Add frame format definitions proto file by Copilot · Pull Request #48 · mylonics/struct-frame

Copilot · 2025-11-29T18:50:08Z

Defines message framing formats in a .proto file with documented use cases for each format type.

Frame Format Structure

BasicFrame: 2 start bytes (0x90, 0x91+) - Standard reliable communication
TinyFrame: 1 start byte (0x70+) - Constrained environments
MinimalFrame: 0 start bytes - Minimal framing with just MSG_ID

Recommended Frame Formats

Format	Start Bytes	Length	CRC	Total Overhead	Use Case
BasicFrame	2 (0x90, 0x91)	0	2	5	When all messages are known to both systems
TinyFrame	1 (0x70)	0	2	4	Constrained environments with known messages
BasicFrameWithLen	2 (0x90, 0x92)	1	2	6	When systems may not have matching message definitions
TinyFrameWithLen	1 (0x71)	1	2	5	Constrained environments with variable messages
BasicFrameWithLen16	2 (0x90, 0x93)	2	2	7	Large payloads up to 64KB
BasicFrameWithSysComp	2 (0x90, 0x94)	0	2	7	Multi-system networks with system and component IDs

Extended Frame Formats

NoFormat, MinimalFrame, MinimalFrameNoCrc, MinimalFrameWithLen

Parametric Frame Formats

All NoCrc variants and other combinations for specialized use cases

Third Party Protocols

UBX (u-blox GPS)
MAVLink v1/v2 (drone communication)

Files

examples/frame_formats.proto - Protocol Buffer definitions with hex options for start bytes
docs/framing.md - Updated documentation with frame format tables and examples
Fixes New framing definition file #47

Original prompt

This section details on the original issue you should resolve

<issue_title>New framing definition file</issue_title>
<issue_description>Using a .proto file format create a method of defining frame formats. Document the use case for each frame format in this file as well.

NoFormat - MSG
MSG ID Frame - MSG ID + MSG + 2 CRC
MSG ID Frame No CRC - MSG ID + MSG
Basic Frame - 2 header + MSG ID + MSG + 2 CRC
Basic Frame No CRC - 2 header + MSG ID + MSG
Tiny Frame - 1 header + MSG ID + MSG + 2 CRC
Tiny No CRC - 1 header + MSG ID + MSG

All of the above message formats with a 1 byte length and a 2 byte length field included right after the header.

UBX
MAVLINK V1
MAVLINK V2

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes New framing definition file #47

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

rijesha · 2025-11-29T19:00:53Z

+| BasicFrameNoCrc | 2 | 0 | None | Sync recovery, no CRC |
+| TinyFrame | 1 | 2 | None | Low overhead with CRC |
+| TinyFrameNoCrc | 1 | 0 | None | Minimal overhead |
+| *Len8 variants | +1 | same | 8-bit | Variable length up to 255 bytes |


This should be expanded. and so should the Len 16

Expanded all Len8 and Len16 variants in the table with full columns (Preamble, Header, CRC, Length, Total Overhead). See commit 3fd035f.

rijesha · 2025-11-29T19:01:14Z

+
+## Frame Format Overview
+
+| Format | Header | Footer | Length Field | Use Case |


There should be a crc collumn

We have a preamble which is the number of starting bytes. header should be the number of total header bytes which includes msg id and length as applicable. Another collumn showing total overhead should be listed.

Added CRC column, separated Preamble from Header, and added Total Overhead column. Also reorganized to show recommended frames (NoFormat, BasicFrame, BasicFrameLen8) first in a separate table. See commit 3fd035f.

rijesha · 2025-11-29T19:04:15Z

+
+## Frame Format Overview
+
+| Format | Header | Footer | Length Field | Use Case |


We should have recommended Frame followed by the others that are obscure variations.
The recommended one is the No Format, Basic Frame, and Basic Frame with 1 length byte.

Added "Recommended Frame Formats" section with NoFormat, BasicFrame, and BasicFrameLen8 at the top, followed by "All Frame Formats" table with all variants. See commit 3fd035f.

rijesha · 2025-11-29T19:04:57Z

 ```

-## Custom Frame Formats
+## Industry Standard Protocols


This can say third party protocols

Changed to "Third Party Protocols" with a separate table showing Preamble/Header/CRC/Length/Total Overhead columns. See commit 3fd035f.

rijesha · 2025-11-29T19:05:21Z

@@ -0,0 +1,840 @@
+// Frame Format Definitions for struct-frame


This file has way too many comments. It should be a lot more succinct.

Significantly simplified the proto file - reduced from 847 lines to 303 lines. Removed verbose use case descriptions and kept only essential format comments. See commit 3fd035f.

rijesha · 2025-11-29T19:05:49Z

+// ============================================================================
+// Frame Format Enumeration
+// ============================================================================
+


Create a BasicMessage message that will be included in every single frame format.

Created BasicMessage with uint8 msg_id field and included it as a payload field in all frame format messages. See commit 3fd035f.

rijesha · 2025-11-29T19:06:21Z

+// Overhead: 0 bytes
+
+message NoFormat {
+  option msgid = 1;


Remove option msgid from all frame formats

Removed option msgid from all frame format messages. See commit 3fd035f.

rijesha · 2025-11-29T19:07:13Z

+  option msgid = 4;
+
+  // Synchronization start byte (default 0x90)
+  uint8 start_byte = 1;


For any start_bytes add an option that puts allows the byte to be defined in hex.

Added [(hex) = 0xNN] option to all start_byte fields to define the default value in hex (e.g., [(hex) = 0x90], [(hex) = 0xB5]). See commit 3fd035f.

rijesha · 2025-11-29T19:08:16Z

@copilot address comments.

…format Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot · 2025-11-29T19:14:24Z

@copilot address comments.

All comments addressed in commit 3fd035f. Changes include: expanded tables with Preamble/Header/CRC/Length/Total Overhead columns, recommended frames section, "Third Party Protocols" rename, simplified proto file (847→303 lines), added BasicMessage, removed msgid options, and added hex options for start bytes.

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

rijesha · 2025-11-29T21:03:49Z

+
+## Recommended Frame Formats
+
+| Format | Preamble | Header | CRC | Length | Total Overhead | Use Case |


Lets remove the header field completely. So we just have preamble, length field, CRC and then total overhead.

The length field should not be 8-bit or 16-bit but just 1,2. It should be clear that this table is showcasing number of bytes.

Removed Header column. Changed Preamble to "Start Bytes" with hex values (e.g., 1 (0x90)). Changed Length field to show byte count (0, 1, 2) instead of 8-bit/16-bit. See commit cd3371e.

rijesha · 2025-11-29T21:05:15Z

+|--------|----------|--------|-----|--------|----------------|----------|
+| NoFormat | 0 | 0 | 0 | None | 0 | Trusted links, nested protocols |
+| BasicFrame | 1 | 2 | 2 | None | 4 | Standard reliable communication |
+| BasicFrameLen8 | 1 | 3 | 2 | 8-bit | 5 | Variable length messages |


BasicFrameWithLen. The use case is when communicating with components where message definitions may not match. Recommended if all systems are not updated at the same time and unknown messages are sent.

Renamed to BasicFrameWithLen. Updated use case: "When systems may not have matching message definitions. Recommended if unknown messages may be sent." See commit cd3371e.

rijesha · 2025-11-29T21:06:04Z

+| Format | Preamble | Header | CRC | Length | Total Overhead | Use Case |
+|--------|----------|--------|-----|--------|----------------|----------|
+| NoFormat | 0 | 0 | 0 | None | 0 | Trusted links, nested protocols |
+| BasicFrame | 1 | 2 | 2 | None | 4 | Standard reliable communication |


The basic frame only works when all messages are known to both systems.

Updated BasicFrame use case to: "When all messages are known to both systems". See commit cd3371e.

rijesha · 2025-11-29T21:06:28Z

+| BasicFrame | 1 | 2 | 2 | None | 4 | Standard reliable communication |
+| BasicFrameLen8 | 1 | 3 | 2 | 8-bit | 5 | Variable length messages |
+
+## All Frame Formats


Additional Formats. Dont repeat the recommended formats.

Renamed section to "Extended Frame Formats" and removed the recommended formats (BasicFrame, BasicFrameWithLen) from it. See commit cd3371e.

rijesha · 2025-11-29T21:40:06Z

+| Format | Preamble | Header | CRC | Length | Total Overhead | Use Case |
+|--------|----------|--------|-----|--------|----------------|----------|
+| NoFormat | 0 | 0 | 0 | None | 0 | Trusted links, nested protocols |
+| BasicFrame | 1 | 2 | 2 | None | 4 | Standard reliable communication |


All Recommended Frame Formats have to include MSG ID. Remove the No Format Frame.

Removed NoFormat from recommended. Recommended now only includes BasicFrame and BasicFrameWithLen which both have MSG ID. See commit cd3371e.

rijesha · 2025-11-29T21:42:17Z

+| BasicFrame | 1 | 2 | 2 | None | 4 | Standard reliable communication |
+| BasicFrameLen8 | 1 | 3 | 2 | 8-bit | 5 | Variable length messages |
+
+## All Frame Formats


Lets have Three Frame format sections in total.

Recommended, Additional recommended (Needs better name) and
Parametric Frame Formats.

Created three sections: "Recommended Frame Formats", "Extended Frame Formats", and "Parametric Frame Formats". See commit cd3371e.

rijesha · 2025-11-29T21:43:12Z

+
+## Recommended Frame Formats
+
+| Format | Preamble | Header | CRC | Length | Total Overhead | Use Case |


Instead of Preamble have start bytes and include the value of the start bytes.

Changed "Preamble" to "Start Bytes" and included the hex values (e.g., 1 (0x90), 2 (0xB5, 0x62)). See commit cd3371e.

rijesha

@copilot please address review comments

…meWithLen Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot · 2025-11-29T21:48:29Z

@copilot please address review comments

All review comments addressed in commit cd3371e.

rijesha · 2025-11-29T22:01:59Z

+- Enumeration of all frame format types
+- Configuration message for runtime format selection
+
+## Recommended Frame Formats


Basic Frame should have 2 start bytes.
Tiny Frame should have 1 start byte.
Minimal Frame should have 0 start bytes.

Recommended formats should be BasicFrame, TinyFrame, BasicFrame With length, Tiny Frame with length, Basic Frame with Length 2.

Then Extended Formats should have NoFrame, MSGIDFrame, MSGIDFrameNoCRC, MSGIDFrameLen8.

The rest should be in parametric format.

The first start byte for each basicframe should be 0x90. the second value should be 0x90 + a unique index.
Each tinyFram start byte should be unique start with 0x70 as the basic one.

The proto file should be updated as well.

Restructured all frame formats. BasicFrame now has 2 start bytes (0x90, 0x91-0x97 for variants), TinyFrame has 1 start byte (0x70-0x75), MinimalFrame (renamed from MsgIdFrame) has 0 start bytes. Added BasicFrameWithSysComp for multi-system networks. Updated both docs/framing.md and examples/frame_formats.proto. See commit d85f467.

rijesha

More changes to framing defines.
We should also add a basic frame format that includes a sys_id and comp_id that takes up another 2 bytes in total. That should be included in the recommended frame formats.

… add SysComp variant Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot · 2025-11-29T22:07:45Z

More changes to framing defines.
We should also add a basic frame format that includes a sys_id and comp_id that takes up another 2 bytes in total. That should be included in the recommended frame for...

Added BasicFrameWithSysComp with sys_id and comp_id (7 bytes overhead total: 2 start bytes + sys_id + comp_id + msg_id + 2 CRC). Included in recommended formats. See commit d85f467.

Initial plan

a1cc931

Copilot AI assigned Copilot and rijesha Nov 29, 2025

Copilot started work on behalf of rijesha November 29, 2025 18:50 View session

Copilot AI and others added 2 commits November 29, 2025 18:57

Add frame_formats.proto with comprehensive framing definitions

5ca1e63

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Fix frame format documentation inconsistencies

d91f8dd

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

rijesha reviewed Nov 29, 2025

View reviewed changes

Copilot AI changed the title ~~[WIP] Add new framing definition file using proto format~~ Add frame format definitions proto file Nov 29, 2025

Copilot AI requested a review from rijesha November 29, 2025 19:02

Copilot finished work on behalf of rijesha November 29, 2025 19:02

rijesha reviewed Nov 29, 2025

View reviewed changes

Copilot started work on behalf of rijesha November 29, 2025 19:08 View session

Address PR feedback: simplify proto, add BasicMessage, improve table …

3fd035f

…format Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Fix third-party protocols to use native message ID fields

eef9e60

Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot AI requested a review from rijesha November 29, 2025 19:17

Copilot finished work on behalf of rijesha November 29, 2025 19:17

rijesha reviewed Nov 29, 2025

View reviewed changes

rijesha requested changes Nov 29, 2025

View reviewed changes

Copilot started work on behalf of rijesha November 29, 2025 21:45 View session

Address review: restructure tables, rename BasicFrameLen8 to BasicFra…

cd3371e

…meWithLen Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot AI requested a review from rijesha November 29, 2025 21:50

Copilot finished work on behalf of rijesha November 29, 2025 21:50

rijesha reviewed Nov 29, 2025

View reviewed changes

rijesha requested changes Nov 29, 2025

View reviewed changes

Copilot started work on behalf of rijesha November 29, 2025 22:03 View session

Restructure frames: BasicFrame 2 start bytes, TinyFrame 1 start byte,…

d85f467

… add SysComp variant Co-authored-by: rijesha <7819200+rijesha@users.noreply.github.com>

Copilot AI requested a review from rijesha November 29, 2025 22:10

Copilot finished work on behalf of rijesha November 29, 2025 22:10

rijesha approved these changes Nov 29, 2025

View reviewed changes

rijesha marked this pull request as ready for review November 29, 2025 22:16

rijesha merged commit 021f7fc into main Nov 29, 2025

rijesha deleted the copilot/create-frame-definition-file branch December 6, 2025 03:20


		## Frame Format Overview

		\| Format \| Header \| Footer \| Length Field \| Use Case \|

		@@ -0,0 +1,840 @@
		// Frame Format Definitions for struct-frame


		## Recommended Frame Formats

		\| Format \| Preamble \| Header \| CRC \| Length \| Total Overhead \| Use Case \|

Uh oh!

Conversation

Copilot AI commented Nov 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Frame Format Structure

Recommended Frame Formats

Extended Frame Formats

Parametric Frame Formats

Third Party Protocols

Files

Comments on the Issue (you are @copilot in this section)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

rijesha commented Nov 29, 2025

Uh oh!

Copilot AI commented Nov 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Nov 29, 2025 •

edited

Loading