Adding New Proto Files

Step-by-Step Guide

1. Create the new .proto file

Create platform_shared/myfeature.proto:

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:

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:

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:

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):

proto_files = [proto_dir / "filesystem.proto", proto_dir / "myfeature.proto", proto_dir / "message.proto"]

TypeScript (app/scripts/compile_protos.js):

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:

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:

// Before #undef DEFINE_MESSAGE_TRAITS
DEFINE_MESSAGE_TRAITS(MyFeatureRequest, my_feature_request)
DEFINE_MESSAGE_TRAITS(MyFeatureResponse, my_feature_response)

9. Build and test

# 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

3.5 KiB Raw Blame History