Frame Profile Calculator¶

Use this interactive tool to select the features you need and discover which frame profile matches your requirements.

**Frame Type**

Basic (2 start bytes) - Better sync recovery, recommended for noisy links Tiny (1 start byte) - Lower overhead, good for clean links None (0 start bytes) - No framing, external sync required

**Features**

CRC Error Detection - Detect corrupted frames (recommended) Length Field - Variable-length messages (recommended) Large Payloads (>255 bytes) - Support up to 64KB messages Package ID - Namespace separation for many message types Sequence Number - Detect packet loss Multi-Node Routing - System ID + Component ID for distributed systems

Selected Frame Format

BasicDefault

Profile: Profile.Standard

Total Overhead: 6 bytes

Maximum Payload: 255 bytes

Start Bytes: 0x90, 0x71

    Frame Structure:

    [0x90] [0x71] [LEN] [MSG_ID] [PAYLOAD] [CRC1] [CRC2]

Understanding the Results¶

Frame Format Names¶

The frame format name tells you exactly what features are included:

Frame Type Prefix: Basic, Tiny, or None
Payload Type Suffix: Default, Extended, MultiSystemStream, etc.

Overhead Calculation¶

The overhead is calculated as:

Overhead = Start Bytes + Header Fields + CRC Bytes

Basic frames: +2 bytes (0x90, 0x7X)
Tiny frames:  +1 byte  (0x7X)
None frames:  +0 bytes

Header fields:
- Length (8-bit):  +1 byte
- Length (16-bit): +2 bytes
- Message ID:      +1 byte (always present)
- Package ID:      +1 byte (if enabled)
- Sequence:        +1 byte (if enabled)
- System ID:       +1 byte (if routing enabled)
- Component ID:    +1 byte (if routing enabled)

Footer:
- CRC:             +2 bytes (if enabled)

Next Steps¶

Use a standard profile if it matches your needs (recommended)
Or create a custom profile alias in a frame_format.proto file
Use it in your code when initializing the frame parser

Using Standard Profiles¶

For most use cases, use one of the 5 standard profiles:

// Use this in your frame_format.proto file or directly in code

// For general serial/UART:
Profile.STANDARD  // Maps to BasicDefault

// For low-bandwidth sensors:
Profile.SENSOR    // Maps to TinyMinimal

// For trusted inter-process communication:
Profile.IPC       // Maps to NoneMinimal

// For large file transfers:
Profile.BULK      // Maps to BasicExtended

// For multi-node mesh networks:
Profile.NETWORK   // Maps to BasicExtendedMultiSystemStream

Creating Custom Profiles¶

If you need a custom combination of features, create a frame_format.proto file with a profile alias:

// frame_format.proto
package frame_formats;

message ProfileAlias {
  string name = 1;
  HeaderType header_type = 2;
  PayloadType payload_type = 3;
  string description = 4;
}

// Example: Tiny header with Default payload (lower overhead than Standard)
message TinyDefaultAlias {
  ProfileAlias profile = 1 [default = {
    name: "TinyDefault",
    header_type: HEADER_TINY,
    payload_type: PAYLOAD_DEFAULT,
    description: "Tiny header with default payload"
  }];
}

Then generate code with:

struct-frame your_messages.proto --frame_formats frame_format.proto --build_py

Contributing New Headers/Payloads¶

If you need a new header or payload type that doesn't exist, please submit a PR to the struct-frame repository.

Example Usage¶

PythonTypeScriptC++

from struct_frame_parser import BasicPacket

# Profile.Standard = BasicDefault
packet = BasicPacket()
frame = packet.encode_msg(my_message)

import { BasicPacket } from './struct_frame_parser';

// Profile.Standard = BasicDefault
const packet = new BasicPacket();
const frame = packet.encodeMsg(myMessage);

#include "struct_frame.hpp"

// Profile.Standard = BasicDefault
StructFrame::BasicPacket format;
encoder.encode(&format, msg_id, &msg, sizeof(msg));