Documentation of Standard Patterns

[LeStarch]

We are considering the idea of publishing standard patterns as part of F´ documentation. Thus far, we have come up with the following list.

Please comment and let us know what you'd like to see documented!

1. Implementation patterns (beginner) - Reference + Example
   1. Get/request pattern
   2. Callback pattern
   3. Memory allocation pattern
   4. Buffer manager pattern
   5. Sync cancel
   6. Internal interfaces
   7. Parallel ports
   8. Health
   9. State machines
2. Component Patterns: (beginner) - Reference + Example
   1. Central store
   2. Hub Pattern
   3. Manager/Worker pattern
   4. Rate group pattern
   5. Mode management patterns
   6. Interrupt handling
   7. Resource manager
3. Interface patterns (intermediate) - How To
   1. Generic interfaces - review guide
   2. Time/Tick
   3. Byte stream driver
   4. I2C
   5. SPI
   6. GPIO
   7. PWM
   8. Watchdog
4. Topology patterns (intermediate) - Decide by Item
   1. Custom configuration
   2. Reused component instances
   3. Sub topology
   4. Application/Driver/Manager pattern
   5. Fault protection
   6. Sequencer pooling
   7. Assert
   8. logger
   9. Security
   10. Simulation deployments
5. Integration patterns (advanced) - How To
   1. OS
   2. Hardware Platform
   3. New GDS
   4. Radio
   5. Framing protocol
   6. Vendor library
   7. Other framework
   8. Ground processing script
6. Modeling and build tool patterns (advanced) - How Guides
   1. Custom autocoder
   2. Custom model validation
   3. Custom model tool

[SterlingPeet]

Command registration and Dispatch as implemented in F Prime is often confusing for newcomers to the framework.

Telemetry handling can be equally confusing, but is generally easier to mimic and thus get it to work.

[SterlingPeet]

BTW, I am excited by the prospect of this documentation becoming available, I have had to explain a lot of it in situ for students. It would be great to be able to index into pattern documentation for learning purposes.

[ReggieMarr]

This is excellent, also fwiw I think the gold standard to strive for is documentation somewhat similar to what's provided by 0mq. Admittedly it's a massive amount of work but worth keeping in mind.

[thomas-bc]

Creating a thread to throw in ideas so as not to spam the main thread 🧵 ⬇️

[thomas-bc]

• FPP Pattern Graph specifiers and how to manually define one, say for a ModeManager component

[ReggieMarr]

speaking of threads, are there any examples of how to utilize thread virtualization or create custom threads os/task

[thomas-bc]

• Stop using PRIVATE: for UTs and use the test Friend class for whitebox testing instead

[SiboVG]

Hey! It would also be great to have an overview of the available built-in FPP types and their use case. I'm referring to something similar to the C++ documentation, but for FPP.

For example, in the Led Blinker workshop, you learn to add some ports to Led.fpp:

@ Port receiving calls from the rate group
async input port run: Svc.Sched

@ Port sending calls to the GPIO driver
output port gpioSet: Drv.GpioWrite

But I have no idea what other FPP port types exist or what their use case is.

[kevin-f-ortega]

Here are some ideas I have

• How to add a new toolchain
• How to integrate C/C++ libraries with F Prime
• How to port to a new operating system
• How to add CI
• How to structure your code to be reusable by other projects
• How to write drivers using the Interface paradigm

[LeStarch]

Some other ideas that came in via PR #3040:

1. Document the bytetreamdriver pattern
2. Document the buffer allocation/ownership pattern.

[SterlingPeet]

@zeroping may have some more recent experience with what would be helpful tutorials or cookbook recipes to help with onboarding developers

[LeStarch]

Recent experience or not, I'd love to hear @zeroping's suggestions!

[zeroping]

I've recently watched a few new students try to wrap their heads around making a manager component that talks to an existing hardware driver component (for example, something that manages configuration of a device connected via UART). Having a guide for things like that would be helpful, since "make the manager component for X" is otherwise a good place to start learning with a real system.

I think the best documentation would be something concrete that someone could follow along with, not just a wall of words that aren't as actionable. Imagine something between demo code and a tutorial, but where the user can follow along the steps, but can apply them to their own use case in parallel with the tutorial.

For example, imagine we had a well-implemented manager for some super common SPI-connected accelerometer, some hardware that anyone could buy from Amazon for $5 if needed. Then have a tutorial that explains:

• How the design decisions were made ("we wanted a queued port here because we may not get a response from this SPI device immediately")
• How the new component is connected to a driver component ("We need a buffer manager here because that's how we get from the driver component")
• How the commands, telemetry, and events, and parameters are chosen ("We want this data to be downlinked through an event rather than a telemetry channel because we very rarely expect it to change at runtime")
• How the FPP was written to support that
• How the code gets written (including some ideas for dealing with places where we need to wait for the hardware to provide data back)
• How to write tests for something that interfaces with real hardware ("To test with without real hardware connected, we can write a mock component that can stand in for the SPI driver, but responds to SPI reads and writes as if it were an accelerometer", or "We have a HITL test to exercise all of the functionality when an accelerometer is connected to a Raspberry Pi")

Maybe also pair with a cookbook recipe for "manager component that interfaces with an SPI device".

So, that new user gets reference code, plus the reasoning behind it, plus links into the rest of the documentation for larger concepts like port types, plus auto-generated code they can start from. Super actionable when they have a device datasheet or user manual and need to get started.

Hopefully that made some sense.

[zeroping]

Another approach to answer your question:

Take any component in the FPrime tree - it's probably there because the core FPrime people needed it to solve a real problem, and made a clean generalized solution. For example, how about BufferLogger? It exists to solve a problem, but I'm not sure that's documented anywhere. Someone looking at what it does might not be able to work that out, and would have a hard time finding it if they needed it. So just a quick "We needed to do X on a project, so this component helped to glue Y to Z. We've also seen it used to solve this other problem A" would be great.

As a concrete example, there was a discussion that is a great motivation for ComSplitter. Reading through the list of components and going "what all is ComSplitter good for?" could yield a list of common patterns that might be obvious in hindsight, but confusing at first.

[zeroping]

One last comment: I think fprime-visual could use some love (I know that's been said elsewhere too).

If you want to document patterns, a good graph could go a long way to quickly explain how the parts are connected, and right now, fprime-visual won't quite give you a pretty graph without lots of effort. Generating readable component interconnection graphs, especially for cookie-cutter-generated recipes, could be powerful for someone trying to figure out what's what in an example.

[LeStarch]

#1844

[LeStarch]

#1688

[LeStarch]

#1487

[LeStarch]

#1251

[LeStarch]

#2689

[elliotfayman]

#3056

[ronaldo-monteiro]

I would like to see the use of AI in code improvements for the project, especially in Python.

[kevin-f-ortega]

Document Patches too?

[Joshua-Anderson]

I'd recommend writing a section on fprime unit and integration testing patterns and best practices. - I'm not sure there's any comprehensive guides to fprime testing outside of the LED example.

[zimri-leisher]

Quick note--could add documentation to explain what the pattern is for a custom decoding plugin to the GDS