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_PbCodec.h/.cpp

Owns the protobuf-side wrapper:

• full protobuf frame serialize / parse
• checksum validation
• typed helper entry points like hello request / response

keyboard.pb.h/.cc

Own the generated protocol model:

• outer CdcFrame
• business CdcPacketBody
• all message definitions

Completed nodes

Node 1: protobuf thin wrapper

Files added in this step:

• KeyBorad/KeyBorad/COM/Com_PbCodec.h
• KeyBorad/KeyBorad/COM/Com_PbCodec.cpp

Design notes:

• stop expanding hand-written typed payload logic
• let protobuf generated code own message encode/decode
• keep only a thin Qt-friendly wrapper

Implemented behavior:

• serialize a full CdcFrame
• parse and validate a full CdcFrame
• build HelloReq using generated protobuf types
• parse HelloRsp using generated protobuf types

Node 2: remove legacy manual codec

Files removed in this step:

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

Design notes:

• no dual path
• no hand-written payload encode/decode path left behind
• protobuf is now the only packet encode/decode direction

Implemented behavior:

• checksum moved into Com_PbCodec.cpp
• old manual packet structs and old codec files removed

COM done criteria

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

1. the protocol source is the .proto file
2. generated .pb.* files exist
3. Com_PbCodec provides thin project-facing helpers
4. no legacy hand-written packet codec remains