# Host Protocol Rebuild

## Goal

Use protobuf as the single protocol definition source.

This stage fixes two earlier mistakes:

- payload encode/decode should not be hand-written in COM
- the outer CDC frame should also be part of the schema

## Current schema

Files:

- `KeyBorad/proto/keyboard.proto`
- `KeyBorad/proto/keyboard.options`

## Design

### 1. Outer frame is part of protobuf

The outer CDC frame is described as:

- `CdcFrame`

Fields:

- `head1`
- `head2`
- `payload_length`
- `type`
- `payload`
- `checksum`

### 2. Business body is part of protobuf

The business payload is described as:

- `CdcPacketBody`

Supported messages:

- `HelloReq`
- `HelloRsp`
- `Bitmap`
- `FunctionKeyEvent`
- `LedState`
- `TimeSync`
- `ThemeRgb`
- `Ack`
- `Error`

### 3. Transport split

- CDC sends `CdcFrame`
- GATT sends `CdcPacketBody`

## Why this is the chosen direction

- one full schema instead of half schema
- no repeated hand-written payload parsing
- easier to teach layer responsibilities
- easier to align host and firmware

## Current blocker

`protoc.exe` is not present in `3rdParty`, but the machine has an available
protobuf compiler binary at:

```text
C:\Program Files\Lenovo\AIAgent\Modules\RAG\_internal\torch\bin\protoc.exe
```

## Completed nodes

### Node 1: full schema definition

Files:

- `KeyBorad/proto/keyboard.proto`
- `KeyBorad/proto/keyboard.options`

Implemented behavior:

- outer frame moved into protobuf as `CdcFrame`
- business body moved into protobuf as `CdcPacketBody`
- all current message types included in one schema

### Node 2: generated C++ protobuf code

Files:

- `KeyBorad/generated/cpp/keyboard.pb.h`
- `KeyBorad/generated/cpp/keyboard.pb.cc`

Implemented behavior:

- generated from the full protocol schema
- ready to be used by the later thin COM wrapper

## Next step

Stop expanding hand-written typed payload parsing.

The next COM implementation step should use:

- generated `keyboard.pb.h/.cc`
- a thin wrapper that connects `QByteArray` with generated protobuf messages