Skip to content

mirkosertic/Megahub / .claude/skills/lego-protocol

lego-protocol

Verified

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)

PriorityFixExpected improvement
1 (best)68–100pF NP0/C0G ceramic cap on UART RX pin to GND50–70% error reduction
2Clip-on ferrite bead on RX wire near PCB40–60% error reduction
3100Ω + 100pF RC filter on UART TX10–20% additional
4100nF decoupling cap on SC16IS752 VCC pinstandard 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
FieldMeaning
okGood frames parsed
csErrChecksum errors
discardedBytes thrown away during resync
recoveriesNumber of sync-loss recovery events
uartOvrSC16IS752 FIFO overflow count
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall