# 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`

### Node 3: 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

Current limit:

- not wired into the project yet
- protobuf runtime include and link setup is still pending

## 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