lego-protocol

name	lego-protocol
description	LEGO Powered Up protocol context for the Megahub project. Use when working on LEGO device communication, lpfuart library, UART parsing, motor control, sensor modes, device initialization, or debugging UART noise/corruption issues.

LEGO Powered Up Protocol — Megahub ESP32

Hardware Setup

• UART chip: SC16IS752 (I²C-to-dual-UART bridge)
• Ports: 0–3 (physical LEGO connectors)
• Baud rate: negotiated per device during handshake (typically starts at low speed, switches to 115200)
• Library: lib/lpfuart/ — legodevice.cpp, lumpparser.cpp, SC16IS752serialadapter.cpp

---

Device Initialization Sequence

Devices send identification messages on connect. Never skip any step.

1. LUMP_CMD_TYPE — device reports its type ID and name
2. LUMP_CMD_MODES — device reports number of supported modes
3. LUMP_CMD_SPEED — device requests baud rate to switch to
4. LUMP_CMD_VERSION — device reports firmware + hardware versions
5. LUMP_INFO_NAME/RAW/PCT/SI/UNITS/MAPPING/FORMAT — per-mode metadata (repeats for each mode)
6. LUMP_INFO_MODE_COMBOS — supported mode combinations
7. finishHandshake() — switch to negotiated baud rate (e.g., 115200)
8. selectMode() — set default operating mode

Example (BOOST Interactive Motor, device ID 0x26):

• 4 modes: POWER (0), SPEED (1), POS (2), TEST (3)
• Default mode: 2 (POS — position feedback)
• Handshake takes ~3 seconds from connect to ready

---

Protocol Rules

• Command rate limit: ~20ms minimum between commands for most devices
• Device timeout: some devices sleep if no command within ~1 second — send keepalives
• Byte order: LEGO uses little-endian in most messages
• Port cleanup: on disconnect, cancel all pending commands for that port
• Mode selection: always use device type to validate supported modes before CMD_SELECT

---

UART Corruption from Motor Noise

This is a known hardware issue. When motors run, EMI corrupts the UART RX line.

Symptoms

• [WARN] LUMP sync lost after N good frames (checksum expected=0xXX actual=0xYY)
• Repeated 0xD2 bytes in discarded data (spurious detections of LEGO header byte)
• uartOvr=1 in parser stats — SC16IS752 FIFO overflow

Root Cause

Motor control via M1/M2 generates high-frequency switching noise → current spikes → EMI coupling into UART RX trace → SC16IS752 FIFO fills faster than ESP32 reads via I²C.

Software Mitigations (already implemented)

• UART read batch size increased to 64 bytes per call (reduces FIFO overrun probability)
• delayMicroseconds(100) after motor speed changes (allows transients to settle)
• FIFO overrun counter tracked and logged as uartOvr

Hardware Fixes (if software mitigations are insufficient)

Priority	Fix	Expected improvement
1 (best)	68–100pF NP0/C0G ceramic cap on UART RX pin to GND	50–70% error reduction
2	Clip-on ferrite bead on RX wire near PCB	40–60% error reduction
3	100Ω + 100pF RC filter on UART TX	10–20% additional
4	100nF decoupling cap on SC16IS752 VCC pin	standard practice

Target: < 5 sync recoveries per minute with motor at 100% speed.

Parser Recovery

The parser (lumpparser.cpp) handles corruption gracefully:

• Detects checksum mismatch
• Scans forward to find next valid frame header
• Logs discarded bytes
• Recovers without device reset

Good state: Parser: ok=XXX csErr=0 discarded=0 recoveries=0 uartOvr=0

---

Debugging LEGO

Watch parser stats in serial log (logged every ~5 seconds):

[INFO] logParserStats() - Parser: ok=138 csErr=0 discarded=0 recoveries=0 overflow=0 unknownSys=0 invalidSize=0 uartOvr=1

Field	Meaning
ok	Good frames parsed
csErr	Checksum errors
discarded	Bytes thrown away during resync
recoveries	Number of sync-loss recovery events
uartOvr	SC16IS752 FIFO overflow count