schafkop-neu/pico/README_PICO_SERIAL.md

Pico Serial Motor Control — README for Copilot/Developers

Purpose

This file documents the exact serial message contract between the Raspberry Pi Pico firmware and a TypeScript backend. It's written so another Copilot or developer can implement a backend and extend firmware features without guesswork.

Transport modes

The firmware supports two serial transports (selected automatically):

1. USB CDC (preferred)

   • When the Pico is connected over USB and a host opens the port, firmware uses Serial.
   • Typical device name:
     • Windows: COMx
     • Linux (Pi): /dev/ttyACM0
   • Vendor/Product IDs: 0x2E8A / 0x000A (can be used for auto-detection).

2. UART0 on GPIO0/GP0 (TX) and GPIO1/GP1 (RX)

   • Activated if USB CDC is not opened within ~2 seconds at boot; firmware falls back to Serial1.
   • Used for headless integration when the Pico is cabled to a Raspberry Pi's UART pins.

Wiring (Pico UART0 <-> Raspberry Pi UART)

All signals are 3.3V. DO NOT connect 5V to Pico GPIOs.

Function	Pico Pin	Pi (BCM)	Pi Physical Pin
UART0 TX	GP0	RXD0 (15)	10
UART0 RX	GP1	TXD0 (14)	8
GND	GND	GND	(any GND)

Power options:

• Preferred: Power Pico over USB (isolated data + power). Only connect GND and TX/RX for UART logic level link.
• Alternate: Power from Pi 3V3 pin to Pico 3V3 pin (NOT VBUS) plus GND. Never power from USB and Pi 3V3 simultaneously unless you know backfeed protection is in place.

Raspberry Pi configuration (enable UART)

Edit /boot/firmware/config.txt (newer Raspberry Pi OS) or /boot/config.txt (older) and ensure:

enable_uart=1

If the serial console/login is enabled, you may need to disable it (via sudo raspi-config -> Interface Options -> Serial) so /dev/serial0 is free.

After reboot you should see one of:

• /dev/serial0 (symlink to the primary UART)
• /dev/ttyAMA0 or /dev/ttyS0 depending on Pi model.

Docker usage on Raspberry Pi

Expose the UART device inside the container:

docker run \
	--device /dev/serial0:/dev/serial0 \
	-e PICO_SERIAL_PORT=/dev/serial0 \
	your-image:tag

If using USB instead of GPIO UART, expose /dev/ttyACM0 (or appropriate) similarly.

Single combined app container (frontend + backend)

The project Dockerfile now builds both the frontend and backend. To run on a Pi with GPIO UART wiring:

docker build -t schafkop-app .
docker run --rm \
	--device /dev/serial0:/dev/serial0 \
	-e PICO_SERIAL_PORT=/dev/serial0 \
	-p 80:3000 \
	schafkop-app

For USB Pico:

docker run --rm \
	--device /dev/ttyACM0:/dev/ttyACM0 \
	-e PICO_SERIAL_PORT=/dev/ttyACM0 \
	-p 80:3000 \
	schafkop-app

If you omit PICO_SERIAL_PORT the backend will attempt auto-detection (vendorId 2e8a or common paths).

Environment variables (suggested backend behavior):

• PICO_SERIAL_PORT: If set, backend uses this path directly.
• PICO_BAUD: Override baud rate (default 115200).

Backend port auto-detection logic (recommended order):

1. If PICO_SERIAL_PORT env var exists, use it.
2. Else list serial ports; prefer any with vendorId 2e8a (Pico USB).
3. Else probe common paths: /dev/serial0, /dev/ttyACM0, /dev/ttyAMA0, Windows COM ports (highest matching newly added), macOS /dev/tty.usbmodem*.
4. Fallback: error with clear message.

Contract (high-level)

• Commands to Pico: ASCII text lines terminated by LF ("\n") or CRLF ("\r\n").
• Events/logs from Pico: ASCII text lines, one event per line. Backend must split on newlines.
• Baud rate: 115200 (firmware uses Serial.begin(115200)).

Accepted commands (input to Pico)

1. STEP

   • steps: integer (positive number of micro-steps)
   • direction: 1 (forward) or 0 (reverse)
   • Example: STEP 4096 1

2. SPEED <delay_us>

   • delay_us: integer microseconds between internal step micro-operations
   • Example: SPEED 3000

Notes:

• Commands are trimmed for leading/trailing whitespace before parsing.
• Invalid or malformed commands result in an error event emitted by the Pico.

Events/log lines emitted by Pico (output)

The firmware emits structured lines with prefixes so the backend can parse them easily.

• EVENT:RECEIVED <raw-command>

  • Emitted immediately when a command line is received (before execution).
  • Example: EVENT:RECEIVED STEP 4096 1

• EVENT:COMPLETED STEP <steps> <direction>

  • Emitted after a successful STEP command completes.
  • Example: EVENT:COMPLETED STEP 4096 1

• EVENT:COMPLETED SPEED <delay_us>

  • Emitted after the SPEED command is applied.

• EVENT:COMPLETED ERROR: <message>

  • Emitted when a command fails to parse or run.
  • Example: EVENT:COMPLETED ERROR: malformed STEP command

• STATUS: OK or STATUS: ERROR: <message>

  • Short summary always emitted after processing a command.

Parsing guidance for backend:

• Read raw bytes, split on \\n (handle \\r\\n).
• Ignore empty lines.
• Inspect prefixes EVENT:RECEIVED, EVENT:COMPLETED, STATUS: and parse the remainder.

Backend responsibilities (TypeScript)

• Open the serial port at 115200 baud.
• Provide a small API:
  • sendStep(steps: number, direction: 0|1): Promise<void>
  • setSpeed(delayUs: number): Promise<void>
  • onEvent(cb: (evt: {type: string; payload: string}) => void)
• Send commands as ASCII lines terminated by \\n.
• Listen for events; map them to higher-level promises if desired.
• Implement reconnect logic with exponential backoff if the device disconnects.
• Add basic validation before sending commands to avoid malformed requests.

Suggested libraries / implementation notes

• Use serialport (npm) and its ReadlineParser or equivalent.
• Keep a small FIFO of pending commands if you want to wait for EVENT:COMPLETED per command.
• For each command you can:
  1. Write the line CMD\\n to the port.
  2. Wait for EVENT:RECEIVED CMD then EVENT:COMPLETED ... and STATUS: ....
• Ensure the backend tolerates duplicate or out-of-order messages (don't assume perfect timing).

Examples

Example sequence for a STEP command:

// backend writes:
STEP 4096 1

// pico emits:
EVENT:RECEIVED STEP 4096 1
EVENT:COMPLETED STEP 4096 1
STATUS: OK

TypeScript example (auto-detect & simple API)

import { SerialPort } from 'serialport';
import { ReadlineParser } from '@serialport/parser-readline';

interface PicoEvent { type: string; payload: string; raw: string; }

async function findPort(): Promise<string> {
	if (process.env.PICO_SERIAL_PORT) return process.env.PICO_SERIAL_PORT;
	const ports = await SerialPort.list();
	// Prefer Pico USB (vendorId 2e8a)
	const pico = ports.find(p => (p.vendorId||'').toLowerCase()==='2e8a');
	if (pico && pico.path) return pico.path;
	const candidates = ['/dev/serial0','/dev/ttyACM0','/dev/ttyAMA0'];
	for (const c of candidates) if (ports.find(p=>p.path===c)) return c;
	if (ports[0]) return ports[0].path; // fallback
	throw new Error('No serial ports detected for Pico');
}

export class PicoClient {
	private port!: SerialPort;
	private parser!: ReadlineParser;
	private listeners: ((e:PicoEvent)=>void)[] = [];
	constructor(private baud = Number(process.env.PICO_BAUD)||115200) {}
	async init() {
		const path = await findPort();
		this.port = new SerialPort({ path, baudRate: this.baud });
		this.parser = this.port.pipe(new ReadlineParser({ delimiter: '\n' }));
		this.parser.on('data', line => {
			const l = line.trim();
			if (!l) return;
			let type='RAW'; let payload=l;
			if (l.startsWith('EVENT:RECEIVED ')) { type='EVENT:RECEIVED'; payload=l.substring(15); }
			else if (l.startsWith('EVENT:COMPLETED ')) { type='EVENT:COMPLETED'; payload=l.substring(17); }
			else if (l.startsWith('STATUS: ')) { type='STATUS'; payload=l.substring(8); }
			this.listeners.forEach(cb=>cb({ type, payload, raw:l }));
		});
		return this;
	}
	onEvent(cb:(e:PicoEvent)=>void){ this.listeners.push(cb); }
	private write(cmd:string){ this.port.write(cmd.endsWith('\n')?cmd:cmd+'\n'); }
	sendStep(steps:number, dir:0|1){ this.write(`STEP ${steps} ${dir}`); }
	setSpeed(delayUs:number){ this.write(`SPEED ${delayUs}`); }
}

// Usage example
// (async () => {
//   const pico = await new PicoClient().init();
//   pico.onEvent(e => console.log('EVENT', e));
//   pico.setSpeed(3000);
//   pico.sendStep(4096,1);
// })();

Manual testing

• Build and upload firmware with PlatformIO (pico environment).
• Open a serial terminal at 115200 and send commands.
• Observe EVENT: and STATUS: lines.

Testing inside Docker (Pi UART example)

1. Connect wiring (see table above) and power Pico.
2. Confirm /dev/serial0 exists on host (ls -l /dev/serial0).
3. Run container with device passed through.
4. Inside container: run a small Node script using the TypeScript example (compiled) or screen /dev/serial0 115200 for manual check.

Troubleshooting

Symptom	Likely Cause	Action
No output on UART	Pi serial console still enabled	Disable login shell on serial via raspi-config
Garbled characters	Baud mismatch	Ensure both sides at 115200
Only EVENT:START appears	Backend not sending newline	Ensure commands end with \n
USB port not found	Missing udev permissions	Add user to dialout (Linux) or run with proper permissions
Command times out	Long step count	Consider splitting into smaller STEP commands

Extending the firmware

• Add new command parsing in src/main.cpp.
• Emit EVENT:RECEIVED <cmd> when a command is received.
• Emit EVENT:COMPLETED <...> once the command finishes (or EVENT:COMPLETED ERROR: ... on failure).
• Update this README with any new event formats.

Files of interest

• src/main.cpp — serial parser, command dispatch, and event emission.
• src/ULN2003Stepper.h, src/Stepper.h — stepper implementation.
• src/schafkopf-bot.cpp — helper logic; references globals via extern.

Notes for a Copilot implementer

• Preserve the exact prefixes (EVENT:RECEIVED, EVENT:COMPLETED, STATUS:).
• Add unit tests for the backend parser to assert the event shapes.
• Keep CLI/manual examples minimal and copyable.
• When adding new commands, document: syntax, EVENT:COMPLETED form, error cases, sample sequence.
• Keep the README as the single source of truth for the serial protocol.

---

This README is intended as the definitive reference for implementing the TypeScript backend and for extending the Pico firmware. Follow the message formats exactly to avoid breaking existing parsers.