When to Use Parameters, Telemetry, or Just Make It a Variable

[John-P-Cargille]

Hey All,

In making a custom F Prime practice project, I initially approached parameters as something to be actively read and written to from within the implementation code. However, I eventually realized this was an erroneous conception of parameters, given that F' does not support a paramSet() function, but only allows you to update them from the ground. I also planned to use telemetry mostly to track those changing parameters, which also ultimately didn't make very much sense to do--partially because telemetry can only be written to in the implementation and not read. Ultimately, I found that a lot of the pieces of data I wanted to interact with were much easier to integrate into the code as standard C++ data members, rather than with an F-Prime-specific solution.
So my current understanding is something like this: parameters should be used for broad changes in state or goal, such as coordinates of interest (I honestly struggle to thing of more examples, though), which provide additional logic as to how commands and implemented code should behave; telemetry should be things regularly changing in the state of the system or its surroundings, such as temperature, battery power, or velocity, which gives information to the ground team but doesn't impact the implemented code itself; variables should be used for anything that belongs purely to the components as implemented within the code.

Can other people help me understand how these tools generally relate a little better? I'd be curious to hear especially about what people have used as parameters in their missions, because I'm struggling to think of many my team would use in what will likely be a fairly insularly-programmed system. Also, how do people generally handle modes of operation in relation to these tools?

Thanks!

[thomas-bc]

So my current understanding is something like this: [...]

I would say what you described there is pretty accurate. To clarify some things, have you looked at this page in our user guide yet? Data Constructs: Commands, Events, Channels, and Parameters

As for modes of operations, we don't have an F´-provided implementation of it yet. But it could likely be handled by a dedicated component that other components and the ground can talk to? Some people in the community may have implemented this or another approach, I'll let them speak to it.

[SterlingPeet]

Hi @John-P-Cargille, It sounds like you are running into some of the same organizational and conceptual challenges that I noticed when I got started on flight software many years ago.

In general (and F Prime is no exception) with flight software, the better the code is organized and the more rigid and narrow your definitions are for data usage, then the easier it will be to reason about and avoid bugs. Space flight software (and medical device code) is the most conservative about these things, because the cost of small mistakes is wildly high. Unsurprisingly, this drives seasoned developers down paths of rigidity, for better or worse. And don't get started talking about change, thats a whole other can of worms!

That said, F Prime is probably the most forward-thinking FSW framework I have had the pleasure to work with. There are lots of guardrails and tooling support to ensure the best chances of success for your project.

So, lets rehash the link that @thomas-bc posted a little, and see if that helps with understand when to use certain data constructs. For clarity, I will use the term "spacecraft" in place of any particular remote robotic platform, but this could just as easily be something the shape of a roomba vacuum or a kuka arm.

• Commands: When the operator wants to change or adjust the real-time operation of the spacecraft, this is encoded in commands. This doesn't necessarily mean "as it happpens" or "joysticking" the spacecraft, it just means the operator is choosing these things after spacecraft has been launched. F Prime has a component and associated tooling for a Command Sequencer, which allows the operator to send a list of commands and instructions about when they should be executed. Things like, deploy a solar panel, point this direction, activate the payload, and so on. Generally commands are for things that do not require persistent state, should the spacecraft reboot.
• Parameter: Parameters can be changed by command, and then also must be saved by a separated command. Parameters are stored in a database so they can persist across reboots. This is useful for things that are adjustable, but look like configuration. Radio frequency and baud rate, heater set points, maximum wheel speeds, and anything else that is generally not going to change, but may need to be tweaked during flight, or between code re-uses for different spacecraft [e.g. an OS network port number] should be stored in a parameter rather than a magic number or set by command.
• [Telemetry] Channels: This is meant to be time-series data points. The obvious use case is science instruments, temperature sensors and the like. Its also useful for telemetering internal state variables, particularly if they change often. Things like calculated pointing angles, heater output percentage, navigational inertial parameters and so on. This is probably what you wanted when you were attempting to locally update parameters.
• Events: Functionally similar to Channels, but generally describes things that happened (or didn't). These are more like log messages, use the to describe things that happen irregularly, internally F Prime generates an event when a command is received, and when the component completes the command (or not). If your component implements a state machine, you would want to emit an event when the state machine transitions to a new state. You can also provide data along with a print string to help describe the event, which can be quite useful and compact.

There are a few cases where you might want to set the initial value of a variable manually, and then let the FSW update the variable. In this case you probably want to consider using a local variable and using a command to set it, or perhaps you want to go learn about how internal interfaces in F Prime work.

[John-P-Cargille]

Thank you both! I think I had skimmed through the page linked by @thomas-bc a month or so ago--when I was first trying make my way through some of the tutorials--and found it hard to parse, but it makes significantly more sense now. I now understand how F' defines a lot of components and ports as soon as a user-component requires them (e.g. Svc::ActiveLogger for events) but that they're only instantiated through a) the deployment, for the components or b) within each user-defined component which needs that particular functionality.
I'll try to speak to some things I learned reading both the article and your reply, as well as questions I still have. Feel free to link to any other sections of the User Guide or any other resources you think I should look at in particular.

@SterlingPeet, when you talk about rigidity of definitions, are you encouraging as much usage of C++ concepts within C++ implementation code as possible, thus confining the scope of any given piece of data, or are you encouraging as much usage of F' concepts as possible, such that the overall system can operate as coherently as possible, with minimal definitions and translations?

So it sounds like commands are for directly impacting what the spacecraft (or roomba) is doing in terms of specific actions to take. It was quite helpful to explore how the command dispatcher receives buffers containing commands, and how it in turn dispatches those commands to the handling components. However, I am still curious about the sequencing of commands, especially. If our spacecraft needs to enter detumble 30 minutes after launch, would it be helpful to have the change in mode itself be a sequenced command, or a command at all? I know @thomas-bc recommended potentially having a component which handles these changes in operational modes. Also, to what extent do y'all recommend sequencing commands for the sake of a largely autonomous system? The user guide pointed out that sequencing is an alternative to sending commands from the ground--is this something that is commonly used or more for edge-cases? Apologies if this is what @SterlingPeet meant by internal interfaces in F Prime; if it was, where would I find more about those?

"[The functionality of parameters] is useful for things that are adjustable, but look like configuration." This is a really useful perspective on them, thank you! So it sounds like you wouldn't use parameters for (spit-balling) a payload which needed to switch out lenses to take different spectral data about the earth, because that would directly impact its operational behavior and thus be better-suited for a command. However, if, with the same payload, you thought that you might eventually need to decrease the rate at which you got data down (maybe it becomes more power-intensive over time, or something) than that rate of transmission might be a parameter to be changed? That might be a bit of a scuffed example, because I'm new to FSW by-and-large, but I think I get what you're saying. If it changes what the system is doing, it's a command; if it records what's happening, it's a telemetry channel; if it's mostly a system setting but you think you might need to update it, it's a parameter.

Speaking of telemetry, would you mind elaborating on the examples you provided for telemetry, of the changing internal states? And I agree in retrospect I was definitely looking for telemetry when trying to locally update parameters. Is it recommended that telemetry impacts how your code runs at all? Or was I correct in my assessment that, if I start trying to do that, the thing I'm using in my code should be a C++ variable that is perhaps itself tracked by telemetry?

Thanks for the space-tested advice, I'll be sure to include print strings in my events when applicable. This is more curiosity than confusion, but is there any way to have code run in an event call? It seems like the answer is no from everything I've looked at, but I've found a couple of times that I instinctually wanted to have telemetry update or things happen inside of an event call, instead of alongside it.

Thanks again for y'alls advice! I'm really appreciative of it as I'm starting out.