Firmware Documentation

General
1

Hi all,

I am looking for firmware documentation recommendations. The documentation is intended to give insight into the device firmware for our other domain developers and client.

For NodeJS API documentation we use postman API documentation. We are looking for similar documentation but for firmware functions and calls.

Any help is really appreciated.

Rahul G

2

Did you check the… ehm… documentation :see_no_evil:?

2 Likes
3

http://docs.particle.io/

2 Likes
4

I believe he’s looking for recommendations on documenting his own firmware. There are many tools available for self-documenting APIs, but what about for embedded firmware?

4 Likes
5

How important is it for the documentation to be automated? I’d imagine you could get a straightforward win by having engineers have to do documentation as part of a gated software release process with review by others. You could host documentation on something like Read The Docs

For a more automated solution, Doxygen came up in my search. I’ll be curious to see what you end up doing as I probably will do something similar down the line.

1 Like
6

For embedded firmware I would argue that automated documentation should be unnecessary. Your interface should be well-defined and relatively static. That's not even to mention the constrained space we have to work with necessitating small, simple code. Manual documentation of changes should be fine. With a public API however, my thoughts are different. These can (and arguably should) evolve quickly and automatic documentation is a great thing to have in that case.

7

Sorry for the confusion guys. Like @picsil said, I was looking for recommendations on documenting my own firmware. Thanks for the recommendation @justicefreed_amper. Seems like Read The Docs is helpful.
Is there any private tools available so we don’t have to expose our device firmware?

8

@Rahul_G A good starting point is to structure your application code in a way that is consistent and readable. Here is a link to a post from one of the top contributors on this forum that should guide you: Photon offline mode

Additionally, if you are using Workbench / VSC you can include these sorts of documentation tags

/**************************************************************************/
/*!
   @brief    Write a line.  Bresenham's algorithm - thx wikpedia
    @param    x0  Start point x coordinate
    @param    y0  Start point y coordinate
    @param    x1  End point x coordinate
    @param    y1  End point y coordinate
    @param    color 16-bit 5-6-5 Color to draw with
*/
/**************************************************************************/

You could read something like this on stack exchange: https://writing.stackexchange.com/questions/36232/where-do-i-start-with-c-documentation

When you say ‘private tools’ do you mean local and not cloud?

9

The firmware documentation might have some sensitive data of our product which we like to hide from the public. It would be great if we can find applications which won’t publish the documentation publicly.

Thanks for the details @armor, really appreciate the help!

10

Read The Docs for business is a cloud-based but private version.

1 Like