Add full protobuf schema and generated code

KeyBorad/proto/keyboard.options

@@ -1 +1,2 @@
-BitmapPayload.usage_bitmap max_size:29
+CdcFrame.payload max_size:64
+Bitmap.usage_bitmap max_size:29

KeyBorad/proto/keyboard.proto

@@ -2,10 +2,16 @@ syntax = "proto3";
 
 package keyboard.cdc;
 
-// The AA55 CDC frame still lives outside protobuf:
+// Full protocol schema.
-// [head1][head2][len][type][data][checksum]
+//
-// `data` is the serialized protobuf payload for the matching `type`.
+// CDC uses:
-// Keep the outer `type` field for fast dispatch and debugging.
+//   [AA][55][Len][Type][Payload][Checksum]
+//
+// GATT uses:
+//   protobuf(CdcPacketBody)
+//
+// In this schema, the outer CDC frame is also modeled explicitly so we keep
+// one complete protocol definition.
 
 enum CdcPacketType {
   CDC_PACKET_TYPE_UNKNOWN = 0;
@@ -33,11 +39,34 @@ enum ErrorCode {
   ERROR_CODE_NOT_READY = 4;
 }
 
-message HelloReqPayload {
+message CdcFrame {
+  uint32 head1 = 1;
+  uint32 head2 = 2;
+  uint32 payload_length = 3;
+  CdcPacketType type = 4;
+  bytes payload = 5;
+  uint32 checksum = 6;
+}
+
+message CdcPacketBody {
+  oneof body {
+    HelloReq hello_req = 1;
+    HelloRsp hello_rsp = 2;
+    Bitmap bitmap = 3;
+    FunctionKeyEvent function_key_event = 4;
+    LedState led_state = 5;
+    TimeSync time_sync = 6;
+    ThemeRgb theme_rgb = 7;
+    Ack ack = 8;
+    Error error = 9;
+  }
+}
+
+message HelloReq {
   uint32 protocol_version = 1;
 }
 
-message HelloRspPayload {
+message HelloRsp {
   uint32 protocol_version = 1;
   uint32 vendor_id = 2;
   uint32 product_id = 3;
@@ -46,20 +75,20 @@ message HelloRspPayload {
   uint32 capability_flags = 6;
 }
 
-message BitmapPayload {
+message Bitmap {
   bytes usage_bitmap = 1;
 }
 
-message FunctionKeyEventPayload {
+message FunctionKeyEvent {
   uint32 usage = 1;
   KeyAction action = 2;
 }
 
-message LedStatePayload {
+message LedState {
   uint32 led_mask = 1;
 }
 
-message TimeSyncPayload {
+message TimeSync {
   uint32 version = 1;
   uint32 flags = 2;
   sint32 timezone_min = 3;
@@ -67,17 +96,17 @@ message TimeSyncPayload {
   fixed32 accuracy_ms = 5;
 }
 
-message ThemeRgbPayload {
+message ThemeRgb {
   uint32 red = 1;
   uint32 green = 2;
   uint32 blue = 3;
 }
 
-message AckPayload {
+message Ack {
   uint32 acked_type = 1;
 }
 
-message ErrorPayload {
+message Error {
   uint32 error_type = 1;
   ErrorCode error_code = 2;
 }

docs/host_protocol_rebuild.md

@@ -0,0 +1,109 @@
+# 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