diff --git a/README.md b/README.md index e83d61d..8321771 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,10 @@ ExploringUncertanties/ ├── hardware.md ← hardware specs and purchase links ├── einkaufsliste.md ← shopping list ├── ExploringUncertanties.ino ← MAIN SKETCH — upload this to the Arduino +├── dataLogging/ +│ ├── README.md ← setup instructions for Raspberry Pi auto-logging +│ ├── log_serial.py ← Python script: logs Arduino serial output with timestamps +│ └── arduino-logger.service ← systemd unit file for auto-start on boot ├── LEDStrip/ │ ├── test/ │ │ └── test.ino ← LED strip test / setMirroredLED reference implementation diff --git a/dataLogging/README.md b/dataLogging/README.md new file mode 100644 index 0000000..b10d1b1 --- /dev/null +++ b/dataLogging/README.md @@ -0,0 +1,188 @@ +# Data Logging + +Captures all serial debug output from the Arduino and writes it to a timestamped +log file. Designed to run automatically on a Raspberry Pi with no user interaction. + +--- + +## Files + +| File | Purpose | +|---|---| +| `log_serial.py` | Python logger script | +| `arduino-logger.service` | systemd unit file — runs the script on boot | +| `arduino.log` | Log output (created automatically on first run) | + +--- + +## How it works + +- `log_serial.py` auto-detects the Arduino's USB serial port on startup. +- Every line received from the Arduino is written to `arduino.log` with a + full timestamp (`YYYY-MM-DD HH:MM:SS.mmm`). +- The log file is always **appended**, never overwritten — all sessions are + preserved in one file. +- If the Arduino is restarted or unplugged, the script reconnects automatically + within a few seconds. +- If the Pi is restarted, systemd brings the script back up on boot. + +--- + +## Log file format + +``` +──────────────────────────────────────────────────────────── +Logger started 2026-04-14 19:30:00 +──────────────────────────────────────────────────────────── +[2026-04-14 19:30:01.042] [CONNECT] Opening /dev/ttyACM0 at 9600 baud … +[2026-04-14 19:30:01.108] [CONNECT] Connected to /dev/ttyACM0 +[2026-04-14 19:30:05.210] ---------------------------- +[2026-04-14 19:30:05.212] [BUTTON] Q2 / Button 3 (pin D7) +[2026-04-14 19:30:05.213] [RESULT] HALF-CORRECT +[2026-04-14 19:30:05.215] [TEMP] 4 → 5 sections +[2026-04-14 19:30:05.217] [STATE] Q1:- Q2:HALF Q3:OK Q4:WRONG +[2026-04-14 19:30:12.001] [DISCONNECT] Lost connection to /dev/ttyACM0: … +[2026-04-14 19:30:12.002] [RECONNECT] Retrying in 3s … +[2026-04-14 19:30:15.110] [CONNECT] Connected to /dev/ttyACM0 +``` + +--- + +## Raspberry Pi setup + +### 1. Install Python dependency + +```bash +pip install pyserial +``` + +### 2. Add your user to the `dialout` group + +This allows the script to access serial ports without root. + +```bash +sudo usermod -aG dialout pi +``` + +Log out and back in (or reboot) for the group change to take effect. + +### 3. Copy the repo to the Pi + +```bash +# On the Pi, clone the repo or copy the folder. +# The path used in the service file is /home/pi/ExploringUncertanties — adjust if needed. +git clone /home/pi/ExploringUncertanties +``` + +### 4. Edit the service file + +Open `arduino-logger.service` and update the two lines that reference paths/username: + +```ini +User=pi # ← change if your Pi username is different +ExecStart=/usr/bin/python3 /home/pi/ExploringUncertanties/dataLogging/log_serial.py +``` + +Check where Python 3 lives on your Pi: + +```bash +which python3 # typically /usr/bin/python3 +``` + +### 5. Install and enable the service + +```bash +# Copy the unit file to systemd +sudo cp /home/pi/ExploringUncertanties/dataLogging/arduino-logger.service \ + /etc/systemd/system/arduino-logger.service + +# Reload systemd so it sees the new file +sudo systemctl daemon-reload + +# Enable the service (auto-start on every boot) +sudo systemctl enable arduino-logger + +# Start it now without rebooting +sudo systemctl start arduino-logger +``` + +### 6. Verify it is running + +```bash +sudo systemctl status arduino-logger +``` + +You should see `Active: active (running)`. + +--- + +## Useful commands + +```bash +# Check current status +sudo systemctl status arduino-logger + +# See the last 50 lines of systemd output (useful for debugging startup) +journalctl -u arduino-logger -n 50 + +# Follow live output in the terminal +journalctl -u arduino-logger -f + +# Or tail the log file directly +tail -f /home/pi/ExploringUncertanties/dataLogging/arduino.log + +# Stop the service +sudo systemctl stop arduino-logger + +# Disable auto-start (won't start on next boot) +sudo systemctl disable arduino-logger +``` + +--- + +## Port auto-detection + +The script finds the Arduino port automatically in this order: + +1. Any port whose description contains **"Arduino"** (official boards) +2. Any port whose description contains **"CH340"** or **"CH341"** (common clones) +3. Any **ttyACM\*** or **ttyUSB\*** device (fallback for any USB-serial adapter) + +If no port is found, it retries every 5 seconds and logs a `[WAIT]` message. +Once the Arduino is plugged in it connects without any user action. + +To force a specific port (e.g. if you have two USB serial devices): + +```bash +# Edit the ExecStart line in the service file: +ExecStart=/usr/bin/python3 /home/pi/ExploringUncertanties/dataLogging/log_serial.py --port /dev/ttyACM1 +``` + +--- + +## Reconnection behaviour + +| Event | What happens | +|---|---| +| Arduino restarted (button or power cycle) | Script detects disconnect, waits 3 s, reconnects | +| Arduino unplugged and replugged | Script scans for the port again, reconnects | +| Pi restarted / powered on | systemd starts the script automatically after boot | +| Script crashes | systemd restarts it after 5 s (`Restart=always`) | + +--- + +## Manual usage (without systemd) + +```bash +# Auto-detect port, log to default file +python3 log_serial.py + +# Specific port +python3 log_serial.py --port /dev/ttyACM1 + +# Different log file +python3 log_serial.py --out /home/pi/logs/session.log + +# List available ports +python3 log_serial.py --list-ports +``` diff --git a/dataLogging/arduino-logger.service b/dataLogging/arduino-logger.service new file mode 100644 index 0000000..f035cdb --- /dev/null +++ b/dataLogging/arduino-logger.service @@ -0,0 +1,17 @@ +[Unit] +Description=Arduino Serial Logger (Exploring Uncertainties) +# Start after the system has reached multi-user mode and USB devices are ready. +After=multi-user.target + +[Service] +Type=simple +# Change 'pi' to your actual Raspberry Pi username if different. +User=pi +# Absolute path to the script — update this to match where you cloned the repo. +ExecStart=/usr/bin/python3 /home/pi/ExploringUncertanties/dataLogging/log_serial.py +# Restart the service automatically if it crashes or if the Pi reboots. +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target diff --git a/dataLogging/log_serial.py b/dataLogging/log_serial.py new file mode 100644 index 0000000..2cf2699 --- /dev/null +++ b/dataLogging/log_serial.py @@ -0,0 +1,179 @@ +#!/usr/bin/env python3 +""" +log_serial.py — auto-detects the Arduino serial port, logs timestamped output +to a file (always appending), and reconnects automatically if the Arduino is +restarted or the cable is briefly disconnected. + +Intended to run as a systemd service on a Raspberry Pi so it starts on boot +with no user interaction. See README.md in this folder for setup instructions. + +Usage: + python3 log_serial.py # auto-detect port, log to arduino.log + python3 log_serial.py --port /dev/ttyACM1 # force a specific port + python3 log_serial.py --out /var/log/game.log # write to a different file + python3 log_serial.py --list-ports # show available ports and exit + +Dependencies: + pip install pyserial +""" + +import argparse +import time +import serial +import serial.tools.list_ports +from datetime import datetime +from pathlib import Path + + +# ── Configuration ───────────────────────────────────────────────────────────── +DEFAULT_BAUD = 9600 # must match Serial.begin() in the Arduino sketch +DEFAULT_OUT = "arduino.log" # relative to this script's directory +RECONNECT_DELAY_S = 3 # seconds to wait before reconnecting after a disconnect +PORT_SCAN_DELAY_S = 5 # seconds to wait when no port is found yet +# ────────────────────────────────────────────────────────────────────────────── + + +def find_arduino_port() -> str | None: + """ + Return the device path of the most likely Arduino serial port, or None. + + Search order: + 1. Any port whose description contains 'arduino' (official boards) + 2. Any port whose description contains 'ch340' or 'ch341' (common clones) + 3. Any ttyACM* or ttyUSB* device (generic USB-serial on Linux) + """ + ports = serial.tools.list_ports.comports() + + for p in ports: + desc = p.description.lower() + if "arduino" in desc: + return p.device + + for p in ports: + desc = p.description.lower() + if "ch340" in desc or "ch341" in desc or "ftdi" in desc: + return p.device + + for p in ports: + if "ttyACM" in p.device or "ttyUSB" in p.device: + return p.device + + return None + + +def list_ports(): + ports = serial.tools.list_ports.comports() + if not ports: + print(" (no serial ports found)") + for p in ports: + print(f" {p.device:25s} {p.description}") + + +def log(f, message: str): + """Write a timestamped line to the file and stdout.""" + timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3] + entry = f"[{timestamp}] {message}" + print(entry, flush=True) + f.write(entry + "\n") + f.flush() + + +def run(port_override: str | None, baud: int, out: Path): + print(f"Logging to {out} (Ctrl+C to stop)\n") + + with open(out, "a", encoding="utf-8") as f: + + # ── startup banner ──────────────────────────────────────────────────── + banner = f"\n{'─' * 60}\nLogger started {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n{'─' * 60}" + print(banner, flush=True) + f.write(banner + "\n") + f.flush() + + # ── outer loop: keeps reconnecting forever ──────────────────────────── + try: + while True: + port = port_override or find_arduino_port() + + if port is None: + log(f, f"[WAIT] No Arduino found — retrying in {PORT_SCAN_DELAY_S}s …") + time.sleep(PORT_SCAN_DELAY_S) + continue + + log(f, f"[CONNECT] Opening {port} at {baud} baud …") + + try: + ser = serial.Serial(port, baud, timeout=1) + except serial.SerialException as e: + log(f, f"[ERROR] Could not open {port}: {e}") + time.sleep(RECONNECT_DELAY_S) + continue + + log(f, f"[CONNECT] Connected to {port}") + + # ── inner loop: read lines until disconnect ──────────────────── + try: + while True: + raw = ser.readline() + if not raw: + continue # readline timeout — no data, keep waiting + + try: + line = raw.decode("utf-8", errors="replace").rstrip("\r\n") + except Exception: + line = repr(raw) + + if line: + log(f, line) + + except serial.SerialException as e: + log(f, f"[DISCONNECT] Lost connection to {port}: {e}") + log(f, f"[RECONNECT] Retrying in {RECONNECT_DELAY_S}s …") + + finally: + try: + ser.close() + except Exception: + pass + + time.sleep(RECONNECT_DELAY_S) + + except KeyboardInterrupt: + footer = f"\nLogger stopped {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n" + print(footer, flush=True) + f.write(footer) + + +if __name__ == "__main__": + script_dir = Path(__file__).parent + + parser = argparse.ArgumentParser( + description="Log Arduino serial output with timestamps. Auto-detects the USB port." + ) + parser.add_argument( + "--port", + default=None, + help="Force a specific serial port (default: auto-detect)", + ) + parser.add_argument( + "--baud", + type=int, + default=DEFAULT_BAUD, + help=f"Baud rate (default: {DEFAULT_BAUD})", + ) + parser.add_argument( + "--out", + default=str(script_dir / DEFAULT_OUT), + help=f"Log file path (default: