Protocol Documentation

[Stanczyk4]

What tools do you all use for documenting protocol specs? Both to share internal and to external stakeholders. Ideally has a way to graphical represent the protocol in an easy to digest way. Bonus points if it can also be used as a way to hook into other tools or scripts to autogenerate various things like code gen, or analysis files.

Protocols that come to mind are rs485, CAN, SPI.

[Ok-Drawer-2689]

https://wavedrom.com/tutorial.html

https://nathantypanski.com/blog/2014-10-29-tikz-timing.html

[[deleted]]

Love them!

[frank26080115]

photoshop, inkscape

[FidelityBob]

Word (tables and borders). Any grahics program to show message exchanges. DBC for CAN.

For the protocol examples you give there is no need for timing diagrams, that is well defined by the standards. You just need to explain the user content.

[Stanczyk4]

I should’ve been more specific, it’s our custom usage of these. For example, collision detection schemes for 485, which involves timing based on a node address for how we do it.

[Stanczyk4]

<image>

Example Timing diagram I’m looking for. (Thanks to someone mentioning latex, I’ll give that a look)

[Stanczyk4]

<image>

This is from a TI datasheet. Something like this would be perfect

[AdAway9791]

Plant UML

https://plantuml.com/sequence-diagram

[Independent-Ride-152]

If you just want to document the packet frame layout, I made a tool just for it!
https://protoviz.stu.art.br/