KeyBoard_QT/docs/host_com_rebuild.md

Host COM Rebuild

Goal

Keep the COM layer small, explicit, and easy to teach.

The COM layer should:

• define packet types and payload structures
• build full wire frames
• parse full wire frames
• parse typed packet payloads

The COM layer should not:

• enumerate devices
• open ports
• own handshake state
• own UI state

Current file roles

Com_Cdc.h

Owns the packet model:

• packet types
• fixed payload lengths
• payload structs

Com_CdcEncode.h/.cpp

Owns the write direction:

• checksum
• full frame build
• typed payload encode

Com_CdcDecode.h/.cpp

Owns the read direction:

• full frame parse
• stream extraction
• typed payload decode

Completed nodes

Node 1: legacy frame encode baseline

Already present before this step:

• build full frame
• build all typed packets

Node 2: typed packet decode completion

Files updated in this step:

• KeyBorad/KeyBorad/COM/Com_CdcDecode.h
• KeyBorad/KeyBorad/COM/Com_CdcDecode.cpp

Design notes:

• keep decode logic flat and explicit
• one helper for little-endian reads
• one helper for type + length validation
• one decode function per packet type

Implemented behavior:

• parse frame header and checksum
• extract frames from a byte stream
• decode:
  • HelloReq
  • HelloRsp
  • Bitmap
  • FunctionKeyEvent
  • LedState
  • TimeSync
  • ThemeRgb
  • Ack
  • Error

COM done criteria

For the current project stage, COM is considered done when:

1. every supported packet can be built
2. every supported packet can be parsed
3. stream extraction is stable
4. higher layers no longer need to know byte offsets