Skip to content

docs: Add serial transport message framing documentation#544

Open
SiddhantOfficial wants to merge 1 commit intoZeroCM:masterfrom
SiddhantOfficial:docs/serial-framing-documentation
Open

docs: Add serial transport message framing documentation#544
SiddhantOfficial wants to merge 1 commit intoZeroCM:masterfrom
SiddhantOfficial:docs/serial-framing-documentation

Conversation

@SiddhantOfficial
Copy link

Fixes #502

Summary

This PR adds documentation for the serial transport's message framing protocol to help users understand how ZCM handles message identification and parsing when transmitting multiple message types over a serial link.

Changes

Added a new section 'Serial Transport Message Framing' to docs/transports.md that documents:

  • The frame structure with sync bytes (0xCC 0x00)
  • Channel name length and data length fields
  • Channel name and data payload locations
  • Checksum bytes for integrity verification

This documentation was based on the existing implementation in generic_serial_transport.{h,c} as referenced in issue #502.

Why

Users needed clarity on how to identify which bytes correlate with which message types in a serial stream. This information was already implemented in the codebase but not documented, making it difficult for users to parse ZCM messages independently.

Copy link
Member

@jbendes jbendes left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey is there a reason you're deep in the inner workings of the generic serial transport? We actually made a decision to not document these details originally because we were hoping people wouldn't have to go that deep. Can you give us just a few sentences on how you found yourself here? I'm hoping you're not finding yourself coding a receiver for this (as generic serial transport is intended to be used on both ends)

@SiddhantOfficial
Copy link
Author

Thanks for the context, that makes sense.
I ended up here while working with ZCM over a constrained serial link where I needed to inspect and debug the raw byte stream coming off the wire. In my case, I was validating interoperability and diagnosing framing issues using external tools and lightweight environments where pulling in the full generic serial transport stack was not always practical.
I am not reimplementing a full alternative receiver, but I did need to understand how messages are framed at the byte level in order to reason about synchronization, corruption, and message boundaries during bring-up and debugging. Since this behavior is already part of the public implementation, I felt documenting it would help others in similar debugging or integration scenarios without requiring them to reverse-engineer the code.
Happy to clarify or adjust the documentation language if you feel it should be framed more explicitly as implementation detail for debugging and inspection, rather than something users are expected to build against.

@jbendes
Copy link
Member

jbendes commented Dec 29, 2025

Ahh understood. Yeah can you just clarify the use case? Essentially, "I'm a user who just showed up to this new 'doc' page. Why is this here and why do i care?"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Message framing for zcm?

2 participants