135 lines
3.0 KiB
Markdown
135 lines
3.0 KiB
Markdown
# Protocol Generator
|
|
|
|
Generate consistent, idiomatic communication protocol code from a JSON specification.
|
|
Supports communication between embedded systems and host machines (e.g. ESP ↔ PC), with code generation for multiple languages like C and Go.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Define your messages once in a simple JSON format, and generate code to handle:
|
|
- Typed payload structs
|
|
- Message ID enums
|
|
- Dispatcher logic
|
|
- Send & receive helpers
|
|
|
|
---
|
|
|
|
## Message Package Format
|
|
|
|
Currently, the protocol structure is statically defined as:
|
|
- `start_byte`
|
|
- `message_length`
|
|
- `payload`
|
|
- `checksum`
|
|
|
|
---
|
|
|
|
## Message Definition Format (JSON)
|
|
|
|
Each message is described as:
|
|
|
|
```json
|
|
{
|
|
"name": "Status",
|
|
"id": "0xE2",
|
|
"payload": [
|
|
{ "name": "clientid", "type": "uint8_t" },
|
|
{ "name": "mac", "type": "uint8_t[6]" }
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Code Generation
|
|
|
|
### Current: C (ESP → PC)
|
|
- Header file with `MessageID` enums (`ESP_TO_PC`, `PC_TO_ESP`)
|
|
- Typed payload structs
|
|
- Union of all payloads
|
|
- Hook declarations for incoming messages
|
|
- Message dispatcher (switch on `MessageID`)
|
|
- Send functions per message
|
|
|
|
> Uses casting for payloads — fast but not fault-tolerant.
|
|
|
|
---
|
|
|
|
### Planned: Go (PC → ESP)
|
|
- Generate constants for `MessageID`
|
|
- Define structs for payloads (consider endianess!)
|
|
- Dispatcher switch logic
|
|
- Hook functions
|
|
- Send functions
|
|
- Explore alternatives to unions (e.g., interfaces)
|
|
|
|
> Go is less constrained, so performance isn't the top priority.
|
|
|
|
---
|
|
|
|
### Planned: ESP ↔ ESP (C, ESP-NOW)
|
|
- Separate enums for `MasterToSlave`, `SlaveToMaster`
|
|
- Shared payload format
|
|
- Union for all message types
|
|
- Dispatcher on `MessageID`
|
|
- Role-specific send functions
|
|
|
|
---
|
|
|
|
## Implemented
|
|
|
|
- [x] Code-Generierung für C (ESP → PC)
|
|
- [x] Header-Dateien mit Enums
|
|
- [x] Payload-Structs
|
|
- [x] Union-Typen
|
|
- [x] Hook-Funktionen
|
|
- [x] Message-Dispatcher (Switch-Case)
|
|
- [ ] Send-Funktionen
|
|
- [ ] Generate Header and Source File
|
|
---
|
|
|
|
## To-Do
|
|
|
|
### Language Support: Go
|
|
- [ ] MessageID generation (`iota`)
|
|
- [ ] Payload structs
|
|
- [ ] Endianess handling
|
|
- [ ] Dispatcher
|
|
- [ ] Hooks & senders
|
|
- [ ] Union alternative
|
|
|
|
### ESP-to-ESP
|
|
- [ ] Master/Slave Message IDs
|
|
- [ ] Shared payload definitions
|
|
- [ ] Dispatcher & send logic
|
|
|
|
### Generator Features
|
|
- [ ] Direction config (`esp→pc`, etc.)
|
|
- [ ] Configurable package structure (e.g. `start_byte`, `checksum`)
|
|
- [ ] Field type aliases (`u8`, `uint8_t`, etc.)
|
|
- [ ] Support for optional fields / versioning
|
|
|
|
### JSON Format
|
|
- [ ] JSON schema for validation
|
|
- [ ] Field descriptions
|
|
- [ ] Global protocol settings (endianness, direction)
|
|
- [ ] Multi-message support
|
|
|
|
### Tooling
|
|
- [ ] CLI interface (`--input`, `--output`, `--language`, ...)
|
|
- [ ] Logging / verbose mode
|
|
- [ ] Build script / Makefile
|
|
|
|
### Testing
|
|
- [ ] Unit tests for generator
|
|
- [ ] JSON test inputs (esp→pc, pc→esp, etc.)
|
|
- [ ] Golden files for regression testing
|
|
- [ ] Use Generated Code in actual Project
|
|
|
|
---
|
|
|
|
## Roadmap Ideas
|
|
- Add checksum algorithm config
|
|
- Integration with code linters or CI
|