Synapse FlatBuffers main

Generated from the FlatBuffers schemas in fbs/. Fixed memory layout is the default for runtime protocol payloads so chip-to-chip shared-memory transports can use the payload layout directly. Coordinate frames follow ROS REP-0103: local/world vectors use ENU and body vectors use FLU.

Motivation

Synapse messages are designed for vehicles that exchange state, sensor, and control data in real time. The schema should be efficient enough for shared-memory message passing between chips, compact enough for constrained over-the-air links, and still straightforward to use from ordinary application code.

• Fixed memory layout first: runtime payloads prefer FlatBuffers struct definitions so producers and consumers can share predictable native layouts without allocation when the transport and language allow it.
• ROS-compatible conventions: frames and units follow ROS REP-0103 by default: ENU for local/world vectors, FLU for body vectors, and SI units unless a field name explicitly declares a scaled integer representation.
• Bit-conscious transport: scaled integer fields preserve needed fidelity without spending unnecessary bytes. Airborne systems pay for latency, range, and reliability, so schemas should avoid waste on high-rate or over-the-air messages.
• Native web and cross-platform use: release artifacts for npm, Python, Rust, C, and C++ let browser tools, cloud services, embedded firmware, and developer scripts consume the same schema source.

Transport Boundaries

Most deployments should publish typed topic payloads directly over transports such as Zenoh, UDP, or TCP and rely on those transports or links for framing, integrity checks, and optional security. The optional Frame envelope exists for links that need an explicit Synapse byte-stream container, especially serial-style transports where message delimiting, sequence tracking, and future opt-in integrity or authentication metadata belong at the frame boundary.

Checksums, authentication tags, or encryption should not be hardcoded into every topic payload. When needed, they should be transport-envelope features so fixed-layout payloads remain compact, inspectable, and reusable across shared memory, local middleware, native web tooling, and constrained radio links.

Zenoh Use

Synapse is intended to be straightforward to use with Zenoh. The canonical encoding publishes each fixed-layout topic’s bare payload struct bytes on a stable key expression: the key identifies the stream and the type, so the same bytes serve shared memory, Zenoh values, radio frames, and log messages with zero re-serialization. Little-endian byte order is a protocol requirement. Variable-size topics and generic bridges use the thin FlatBuffers root tables instead; the catalog encoding field records which applies.

Several parts of the schema support this model:

• Fixed-layout payload structs: every runtime topic payload is a struct with a documented byte size, so consumers can decode by overlay without FlatBuffers machinery.
• Generated topic catalog: release artifacts include TopicId, canonical Zenoh key, root table, payload struct and size, scope, encoding, and helper lookups so applications do not hand-maintain routing tables.
• Stable topic identifiers: TopicId is available for bridges, logs, serial frames, or compact routing tables, while Zenoh deployments can use key expressions as the primary discriminator.
• No transport checksums in payloads: Zenoh, UDP, TCP, and link layers can provide their own integrity behavior, so Synapse payloads stay portable across middleware and shared memory.
• Schema assets in every release: npm, Python, Rust, C, and C++ artifacts carry generated bindings or schema assets so Zenoh tools, web dashboards, firmware bridges, and scripts can decode the same messages.

Canonical keys use synapse/v1/topic/<topic_name>[/<instance>]; the v1 segment is the schema-major compatibility signal, and multi-instance sensor topics append an instance segment so subscribers can select one sensor without decoding payloads. Deployments prepend vehicle, swarm, or site namespaces (for example cub1/synapse/v1/topic/gnss_fix); namespace prefixes come from deployment configuration and are never hardcoded in firmware. The package helpers parse namespaced keys and look up topics by TopicId, name, key, or key suffix. Commands and transfers are Zenoh queryables under synapse/v1/cmd/...; synapse/v1/meta/... and synapse/v1/live/... are reserved for schema metadata and liveliness.

Topic Catalog

The generated topic catalog is included as topics.json in schema-asset archives and as language helpers where the package has a public API. It records TopicId, canonical key expression, FlatBuffers root table, fixed-layout payload type, schema file, and the topic description from the schema comments.

Use the catalog when writing Zenoh publishers/subscribers, serial frame routers, log readers, gateways, and ROS bridge nodes. That keeps topic routing synchronized with the schema instead of duplicating key strings and numeric IDs in application code.

ROS And FlatROS

ROS messages are local integration types, not the Synapse over-the-air format. They are useful for visualization, autonomy stacks, simulation, rosbag tooling, and operator workflows, but they should not replace compact Synapse FlatBuffers payloads on constrained vehicle links.

ROS 2 integration should happen at the edge through bridge nodes that translate selected Synapse topics into ROS concepts only where ROS tooling needs them. The planned flatros2 path is a generated ROS workspace or release archive that consumes the Synapse schemas and topic catalog, depends on flatros2, and provides adapter nodes without making ROS message definitions the protocol source of truth.

Layout Rules

Telemetry, state, command, and control samples should use FlatBuffers struct definitions. Use table, string, or vector fields only for thin root wrappers, transport unions, log records, metadata, text, or naturally variable-size data.

Unit And Scale Rules

Fields encode units and frames in their names. Local/world vectors use _enu_; body vectors use _flu_. Global coordinates use _deg_e7, altitudes use _mm, speeds commonly use _cm_s or _mm_s, temperatures use _cdeg or _c, currents use _da, pack voltages use _cv, magnetic field uses _tesla, and normalized manual-control axes use _milli. The scale column in each entity page is generated from those suffixes, and schema validation fails when a quantitative field has no recognized suffix.

Schema Files

• fbs/all.fbs
• fbs/control.fbs
• fbs/mocap.fbs
• fbs/optical_flow.fbs
• fbs/sensors.fbs
• fbs/sil.fbs
• fbs/state.fbs
• fbs/telemetry.fbs
• fbs/transfer.fbs
• fbs/transport.fbs
• fbs/types.fbs

Version path: main. Generated by cargo run --locked --manifest-path xtask/Cargo.toml -- docs.