Struct Frame
Struct Frame generates fixed-layout message types and framing code from one schema, for C, C++, Python, TypeScript, JavaScript, C# and Rust (plus a GraphQL schema). It is built for links where bytes arrive in a stream and both ends must agree on every one of them: UART and serial, CAN-style buses, UDP/TCP between a device and a PC, inter-process pipes.
- Fixed, packed layouts. In C and C++ a message is a packed struct, so encoding a fixed
message is a
memcpy. Variable-length strings and arrays are optional per message. - Framing included. Five ready-made frame profiles, from a 1-byte header for trusted links to sequence numbers, system/component IDs and 16-bit lengths for networks. Every runtime has the same writer and a streaming reader that resynchronises after corruption.
- Checked compatibility. On the checksummed profiles each message's checksum is seeded with
bytes derived from its layout, so peers with different schemas reject each other's frames
instead of misreading them. Fields can be appended under
extensions_start, andstruct-frame difftells you whether a schema change is wire-compatible. - Same bytes everywhere. Every runtime is tested against shared known-answer vectors and against each other on clean, corrupt and noisy streams.
Compared with Protocol Buffers, messages have a fixed size and no tag/varint encoding, which suits microcontrollers and hard real-time code. Compared with MAVLink, messages can nest, contain arrays and strings, and be split across packages.
Install
pip install struct-frame
The generator needs Python 3.9 or later. The generated code and its runtime are copied into
your output directory and need nothing beyond each language's standard library (TypeScript and
JavaScript use Node's Buffer; the optional SDK transports have a few dependencies).
Example
robot.sf (.sf is the preferred extension; .proto files with the same syntax also work):
package robot;
enum Mode { IDLE = 0; DRIVE = 1; }
message Status {
option msgid = 1;
uint32 uptime_ms = 1;
float battery_v = 2;
Mode mode = 3;
}
Generate C and Python into gen/:
struct-frame robot.sf --lang c,py --out gen
Send from C:
#include "robot.structframe.h" /* also brings in frame_profiles.h */
uint8_t tx[64];
buffer_writer_t writer;
buffer_writer_init(&writer, &PROFILE_STANDARD_CONFIG, tx, sizeof tx);
RobotStatus status = {.uptime_ms = 1200, .battery_v = 12.4f, .mode = MODE_DRIVE};
RobotStatus_write(&writer, &status); /* frame + checksum */
uart_send(tx, buffer_writer_size(&writer));
Receive in Python, feeding bytes as they arrive:
from structframe.frame_profiles import AccumulatingReader, PROFILE_STANDARD_CONFIG
from structframe.robot import Status, get_message_info
reader = AccumulatingReader(PROFILE_STANDARD_CONFIG, get_message_info=get_message_info)
reader.add_data(serial_port.read(256))
while (frame := reader.try_next()) is not None:
if frame.valid and frame.msg_id == Status.MSG_ID:
print(Status.deserialize(frame).battery_v)
Complete programs for C, Python and TypeScript are in examples/basic/; the
test suite builds and runs them. The Language Examples
page has the same steps for every language.
Languages
| C | C++ | Python | TypeScript | JavaScript | C# | Rust | |
|---|---|---|---|---|---|---|---|
| Messages, enums, nested messages, arrays, strings | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Variable-length messages and oneof |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Frame writer and streaming reader | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SDK (transports, message routing) | Serial, UDP, TCP | Serial, sockets, WebSocket | Serial, UDP, TCP, WebSocket | same as TS | Serial, UDP, TCP, WebSocket |
--build-gql also writes a GraphQL schema of the same types. See the
SDK overview for transports.
Frame profiles
| Profile | Layout | Overhead | Use |
|---|---|---|---|
| Standard | 90 71 LEN ID payload CRC CRC |
6 | Serial links (recommended default) |
| Sensor | 70 ID payload |
2 | Low-bandwidth sensors, fixed-size messages |
| IPC | ID payload |
1 | Trusted in-process or local links |
| Bulk | 90 74 LEN LEN PKG ID payload CRC CRC |
8 | Large payloads, package IDs |
| Network | 90 78 SEQ SYS COMP LEN LEN PKG ID payload CRC CRC |
11 | Multi-node networks |
The checksum is Fletcher-16 over everything after the start bytes, seeded with two per-message
bytes; readers therefore take the generated get_message_info. See
Framing for every header and payload type.
Command line
struct-frame robot.sf --lang c,cpp,py,ts --out gen # several languages under gen/<lang>
struct-frame robot.sf --build-c --c-path firmware/gen # one language, explicit directory
struct-frame robot.sf --validate # check against every language, write nothing
struct-frame diff old.sf new.sf # is the change wire-compatible?
struct-frame # options from ./structframe.toml
Outputs are cached: an unchanged schema is not regenerated (--force overrides). See the
CLI reference for every option and the
structframe.toml format, and Build Integration
for CMake, Make, npm and MSBuild.
Documentation
- Quick start
- Message definitions: types, arrays, strings,
oneof, defaults, wire evolution - Framing and framing details
- Conformance: the wire format, for writing your own implementation
- Wireshark dissector (experimental)
- Changelog
Contributing
See CONTRIBUTING.md. In short: pip install -e ".[test]", npm ci, then
python test_all.py runs generation, compilation and the cross-language tests for every toolchain
on your machine.
License
MIT; see LICENSE.
Metadata
Release files for struct-frame 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| struct_frame-0.11.0.tar.gz | 4.8 MB | With provenance | Details for struct_frame-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| struct_frame-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for struct_frame-0.11.0-py3-none-any.whl |
Total release size: 9.3 MB
Release files / struct_frame-0.11.0.tar.gz
| Download URL | struct_frame-0.11.0.tar.gz |
|---|---|
| Size | 4.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cbc3db94e14cbb038196b8f569128b9650b7493f1e52911f65bea2a7a500160a
|
|
BLAKE2b-256 checksum How to use checksums |
b5460c65c182a3912766a5f08f972c34c08fb3cc0f02f2daeb665b14707e8218
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / struct_frame-0.11.0-py3-none-any.whl
| Download URL | struct_frame-0.11.0-py3-none-any.whl |
|---|---|
| Size | 4.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d7457bcc16e36fb9bdf79d52b5b7222add9719a212b02b6b089fb52cf5163771
|
|
BLAKE2b-256 checksum How to use checksums |
ed47b17e712568d7754119bbc21b7adb8fc85cdccaed7d98adf456ba1cded177
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for struct-frame 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for struct_frame-0.11.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.