Niklas Jensen
141 lines
3.5 KiB
Markdown
141 lines
3.5 KiB
Markdown
# Adding New Proto Files
|
|
|
|
## Step-by-Step Guide
|
|
|
|
### 1. Create the new .proto file
|
|
|
|
Create `platform_shared/myfeature.proto`:
|
|
|
|
```protobuf
|
|
syntax = "proto3";
|
|
|
|
package socket_message;
|
|
|
|
message MyFeatureRequest {
|
|
string name = 1;
|
|
}
|
|
|
|
message MyFeatureResponse {
|
|
bool success = 1;
|
|
string error = 2;
|
|
}
|
|
```
|
|
|
|
### 2. Create the .options file (for nanopb size constraints)
|
|
|
|
Create `platform_shared/myfeature.options`:
|
|
|
|
```
|
|
socket_message.MyFeatureRequest.name max_size:64
|
|
socket_message.MyFeatureResponse.error max_size:128
|
|
```
|
|
|
|
### 3. Import in message.proto
|
|
|
|
Add the import at the top of `platform_shared/message.proto`:
|
|
|
|
```protobuf
|
|
import "myfeature.proto";
|
|
```
|
|
|
|
### 4. Add to Message oneof (if needed for streaming/pub-sub)
|
|
|
|
If your message needs to be sent directly (not via correlation request/response), add it to the `Message` oneof in `message.proto`:
|
|
|
|
```protobuf
|
|
message Message {
|
|
oneof message {
|
|
// ... existing fields ...
|
|
MyFeatureRequest my_feature_request = 300; // Pick unused tag number
|
|
MyFeatureResponse my_feature_response = 301;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5. Add to CorrelationRequest/Response (if using request/response pattern)
|
|
|
|
For request/response messages, add to the correlation oneofs in `message.proto`:
|
|
|
|
```protobuf
|
|
message CorrelationRequest {
|
|
oneof request {
|
|
// ... existing fields ...
|
|
MyFeatureRequest my_feature_request = 200; // Pick unused tag number
|
|
}
|
|
}
|
|
|
|
message CorrelationResponse {
|
|
oneof response {
|
|
// ... existing fields ...
|
|
MyFeatureResponse my_feature_response = 200;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 6. Update compile scripts
|
|
|
|
**ESP32 (esp32/scripts/compile_protos.py):**
|
|
|
|
```python
|
|
proto_files = [proto_dir / "filesystem.proto", proto_dir / "myfeature.proto", proto_dir / "message.proto"]
|
|
```
|
|
|
|
**TypeScript (app/scripts/compile_protos.js):**
|
|
|
|
```javascript
|
|
const protoFiles = ['filesystem.proto', 'myfeature.proto', 'message.proto']
|
|
```
|
|
|
|
### 7. Update socket.ts (for TypeScript - only if added to Message oneof)
|
|
|
|
If you added messages to the `Message` oneof, import the protoMetadata in `app/src/lib/stores/socket.ts`:
|
|
|
|
```typescript
|
|
import { protoMetadata as myfeatureProtoMetadata } from '$lib/platform_shared/myfeature'
|
|
|
|
// Add to combinedReferences
|
|
const combinedReferences: Record<string, MessageFns<unknown>> = {
|
|
...protoMetadata.references,
|
|
...filesystemProtoMetadata.references,
|
|
...myfeatureProtoMetadata.references // Add this
|
|
}
|
|
```
|
|
|
|
### 8. Add MessageTraits (for ESP32 - only if added to Message oneof)
|
|
|
|
If you added messages to the `Message` oneof, add traits in `esp32/include/communication/proto_helpers.h`:
|
|
|
|
```cpp
|
|
// Before #undef DEFINE_MESSAGE_TRAITS
|
|
DEFINE_MESSAGE_TRAITS(MyFeatureRequest, my_feature_request)
|
|
DEFINE_MESSAGE_TRAITS(MyFeatureResponse, my_feature_response)
|
|
```
|
|
|
|
### 9. Build and test
|
|
|
|
```bash
|
|
# ESP32
|
|
pio run
|
|
|
|
# TypeScript
|
|
cd app && pnpm proto
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `platform_shared/*.proto` | Protocol definitions |
|
|
| `platform_shared/*.options` | Nanopb size constraints |
|
|
| `esp32/scripts/compile_protos.py` | ESP32 proto compilation |
|
|
| `app/scripts/compile_protos.js` | TypeScript proto compilation |
|
|
| `app/src/lib/stores/socket.ts` | Tag mapping for socket.on/emit |
|
|
| `esp32/include/communication/proto_helpers.h` | MessageTraits for ESP32 emit |
|
|
|
|
## Notes
|
|
|
|
- Messages in `CorrelationRequest/Response` don't need MessageTraits or socket.ts updates
|
|
- Messages in `Message` oneof (for streaming/pub-sub) need both
|
|
- Always use the same `package socket_message;` in all proto files
|
|
- Tag numbers in oneofs must be unique across all fields
|