docs: Add documentation for F' subtopologies #2743
Conversation
There was a problem hiding this comment.
This document should likely be linked in the documentation's navigation/indexes:
- https://github.com/nasa/fprime/blob/devel/docs/_includes/toc.md
- https://github.com/nasa/fprime/blob/devel/docs/HowTo/general.md.
Also subtopology and subtopologies should be added to spellcheck: https://github.com/nasa/fprime/blob/devel/.github/actions/spelling/expect.txt
There was a problem hiding this comment.
Should the fprime-util new feature (nasa/fprime-tools#203) be documented in this guide?
Up to you. Will that be pushed before the docs? |
|
Finally we pass spell check 😁 |
This comment was marked as off-topic.
This comment was marked as off-topic.
Sorry, something went wrong.
There was a problem hiding this comment.
@mosa11aei this is awesome! I was very much of a noob when it comes to subtopology, and I now feel much more educated!
As a novice, I had a lot of comments/questions. Please just take them as suggestions, this is in no way critical. This is an amazing guide, very clear, the example is really descriptive of the kind of capability subtopologies offers.
Woohoo 🎉
|
|
||
| ## Subtopology Structure | ||
|
|
||
| A subtopology is a folder that contains a `topology.cpp` file, which includes the behavior for setting up your custom topology. It additionally contains a `topology.fpp` file, which is a *unified* topology file. As opposed to having separate files for component instances and the topology itself, the single file encapsulates both. A `topologydefs.hpp` defines a struct that is used when instantiating your subtopology. A `CMakeLists.txt` file links your `topology.cpp` file to the build for your project. |
There was a problem hiding this comment.
topology.cpp etc. could be a little confusing to a new reader as it refers to something named differently. I usually interpret code blocks as literals, idk if that makes sense.
Could consider refactoring into italics: Topology C++, Topology FPP, Topology Defs HPP (or Header). I think this matches the style I've seen in the documentation we have for FPP
| 2. [Individual File Contents](#individual-file-contents) (this is a long section with multiple subsections!) | ||
| 3. [Integration into a "Main" Deployment](#integration-into-a-main-deployment) | ||
| 4. [Conclusion](#conclusion) | ||
|
|
There was a problem hiding this comment.
Would it be good to add a small section about motivation/use case? It is addressed briefly above but I'm thinking a diagram if you have one, or just a few sentence, would clarify a lot.
There was a problem hiding this comment.
Coming back to this, maybe pull up the
### Example Scenario
section up here? And include a quick diagram?
Just an idea, I'm not sure it's a good one. For consideration
| All files will be discussed in more detail in later sections of this guide. Additionally, note that there are optional files that can be included in your subtopology to extend its capability. | ||
|
|
||
| - It is highly recommended to include a `docs` folder to document your subtopology. Simple markdown files work well in this case. | ||
| - `.fppi` files can be included as config files to your subtopology. They can include useful constants or structures that allow users to modify your subtopology. |
There was a problem hiding this comment.
I don't think we document what .fppi is or stands for in our docs. Could be good to clarify that i is just a naming convention for include, or simply say additional .fpp can be included or whatnot
| stack size DEFAULTS.STACK_SIZE \ | ||
| priority 150 | ||
|
|
||
| instance rateGroupDriver: Svc.RateGroupDriver base id 0xFF8FF // to drive the 1Hz rate group |
There was a problem hiding this comment.
Since rateGroupDriver is not going to be in the subtopology but rather hooked from the Main topology, would it be good to remove it from the instance list here? And rather add a note right below to emphasize that this is a feature of subtopologies, leverage components from outside that the user will wire up to their subtopology.
| } // end MySubtopology | ||
| ``` | ||
|
|
||
| ## MySubtopologyTopology.cpp and MySubtopologyTopology.hpp (pt1) |
There was a problem hiding this comment.
Would it read better to name the section
## Subtopology CPP and HPP
or something similar? Might be just a personal preference, let me know
| ... | ||
| ``` | ||
|
|
||
| Head over to `MainDeplomentTopologyDefs.hpp`. We want to not only include our subtopology's definitions header, but also modify `PingEntires` to use `GlobalDefs::PingEntires`. At the end of `namespace MainDeployment`, include: |
There was a problem hiding this comment.
Typo in GlobalDefs::PingEntires Entries
| namespace PingEntries = GlobalDefs::PingEntries; | ||
| ``` | ||
|
|
||
| Then modify the current `PingEntires` namespace call to be surrounded by GlobalDefs: |
| ... | ||
| ``` | ||
|
|
||
| Then, we want to tell our MainDeployment's topology to import and use our unified topology file from our subtopology. While we're here, we should also hook up the `CycleOut` port of our main deployment's rate group driver to the `CycleIn` port of our subtopology's rate group. Ensure that the rate group driver can have enough output wires going from the output port. We head over to the `topology.fpp` file, and include: |
There was a problem hiding this comment.
enough output wires going from the output port
size of the output port array ?
|
|
||
| ... | ||
| // MODIFY this line to include the 4th divider | ||
| // Svc::RateGroupDriver::DividerSet rateGroupDivisorsSet{{{1, 0}, {2, 0}, {4, 0}, {1, 0}}}; |
|
|
||
| This how-to guide has walked through the development of a subtopology. Deployments can include multiple different subtopologies, and thus this feature truly paves the way for making F Prime more accessible to quick prototyping. | ||
|
|
||
| If you'd like to see an example of how subtopologies are used within an actual project, please reference this repository: [RNG Library - An Example of Subtopologies within F'](https://github.com/mosa11aei/fprime-rngLibrary). This project uses the [example scenario](#example-scenario) from this guide. |
There was a problem hiding this comment.
I would advertise this reference project at the very top of the guide so users can follow along with it? Seems very helpful
Also do we want to migrate this repo to e.g. fprime-community/fprime-subtopology-reference or something like this? This is awesome!
Change Description
F' subtopologies are a very powerful tool to allow for breaking out one large topology into smaller, more manageable and reusable ones. This PR provides documentation on this tool.