Protocol

Helix is a protocol and framework for typed communication between clients and devices. The core wire packet is small and transport-neutral; routing, auth, device IDs, MQTT topics, and connection ownership all live outside the packet.

Goals

• Keep the core wire packet small and transport-neutral.
• Keep gateway routing, auth, device IDs, and topics outside the packet.
• Make service contracts easy to write by hand, with codegen as an optional convenience.
• Use one communication model for direct links, BLE, WebSocket, MQTT, and Serial.
• Support TypeScript, Python, Go, and C++ consumers as independent packages.

Layers

Helix is split into small layers that install independently.

Core protocol

The core only defines the packet shape, request correlation, encoding, and timeout handling. It knows nothing about services, transports, or auth.

type HelixPacket<TMessage = unknown> = {
  requestId?: string;
  message: TMessage;
};

requestId is generated by the caller runtime when a response is expected. It is protocol metadata and must never be part of a method payload.

Service / method protocol

The service layer sits over the core packet and defines the message carried inside packet.message.

type HelixMessage<TPayload = unknown> = {
  service: string;
  method: string;
  payload?: TPayload;
};

The device broker dispatches by message.service and message.method. Clients subscribe by matching the same fields.

Transport providers

Transports move HelixPacket values over a concrete medium — WebSocket, MQTT, BLE, Serial, or a custom transport. Their connection state and framing rules are not part of the packet.

Gateway

Gateway state is connection context, not protocol data.

1. A client connects to a gateway using a connection string.
2. The connection string carries auth material and the target deviceId.
3. The gateway validates the connection and stores { connection, authContext, deviceId }.
4. When the client sends a packet, the gateway already knows the target device.
5. The gateway forwards the packet using its own transport details (e.g. MQTT topics).