110 lines
2.0 KiB
Markdown
110 lines
2.0 KiB
Markdown
|
# 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
|