Skip to main content

Struct Frame

Tests Coverage Fuzz PyPI

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, and struct-frame diff tells 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

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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for struct-frame 0.11.1
File Size Uploaded Provenance Actions
struct_frame-0.11.1.tar.gz 4.8 MB With provenance Details for struct_frame-0.11.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for struct-frame 0.11.1
File Interpreter ABI Platform Actions
struct_frame-0.11.1-py3-none-any.whl Python 3 none any Details for struct_frame-0.11.1-py3-none-any.whl

Total release size: 9.3 MB

Release files / struct_frame-0.11.1.tar.gz

Download URL struct_frame-0.11.1.tar.gz
Size 4.8 MB
Tags Source
SHA-256 checksum
How to use checksums
427fe203e6f26aa1eb1dc61fae327f480f3b409791b5963b1fc16c0e2ff7374b
BLAKE2b-256 checksum
How to use checksums
cbf71237e748a1b7985199bcc0a58f469643ee9b32eb7e028059ecc638e697a8
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 13, 2026.

Transparency log

Release files / struct_frame-0.11.1-py3-none-any.whl

Download URL struct_frame-0.11.1-py3-none-any.whl
Size 4.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
6806d6265d7152131dadc01e92c51f79143cf1ef7e47ede9b78411785f55a7a1
BLAKE2b-256 checksum
How to use checksums
9e8c6e4c6758dc9d4c30486bcb5ff8889745b014da964146745e11f58214e875
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 13, 2026.

Transparency log

Security for struct-frame 0.11.1

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.

Select from 2 files

Attestation for struct_frame-0.11.1.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 13, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

0.11.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page