Wrt. state machines for ROS2, it seems that there’s not a lot of choice (apart from behavior trees):
This post mentions a fork of Smach, but it seems unfinished and unmaintained,
SMACC2 on the other hand seems really good, as it is actively developed, has numerous examples and has a state viewer (albeit closed source),
I am not aware of possible other libraries.
So I looked into SMACC2, but did not find any real documentation.
There are example state machines, but it is hard (impossible?) to learn SMACC2 from these without further background info, as also experienced by others.
So I decided to try to dig through the code and write down some documentation.
It is by far not finished, but as I currently don´t have time to pursue this further I decided to release my notes in their current state anyway, as they might be helpful to anyone wanting to start with SMACC2.
I think the primary need wrt SMACC2 documentation is clarification of the rationale behind each of the functional concepts.
ISmaccUpdatable provides an interface for periodic functionality,
The timer client also implements periodic functionality, but not as an ISmaccUpdatable
So what is the rationale: when to choose one way or the other? Is it equivalent, and just two possible ways to do the same thing, or are there (subtle?) differences?
When to implement functionality in a client as opposed to a client behavior?
The website states:
“Every Orthogonal should contain at least one client, and may contain multiple client behaviors.”
But that’s not strictly true: a functional state machine is possible without clients in the orthogonals, if the states configure client behaviors that post the state transition events.
So I would rather think:
“Use clients for functionality that is needed across multiple states, and/or for functionality that has a high setup cost (e.g. something that you only need in a certain state, but takes a substantial initialization time, so you want it initialized beforehand not on state change).”
But this is just an assumption: it is hard to learn the author’s intention by reading code (except maybe by deducting this from multiple examples, but that is the hard / time consuming way, and prone to misunderstandings).
That’s great, although my advice would be: given the limited amount of resources available, write down the documentation first (even if it is a simple markdown readme file, preliminary, maybe even not well structured yet nor completely finished, etc.), just put it in your github repository for now so people can start using it, and only then focus on the website/sphinx/formatting/etc.