KeyBoard_QT/docs/host_protocol_rebuild.md

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:

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