Clarify and improve documentation

Introduction

Greeting F' community. I'm a systems engineer at JPL working on CADRE, which is a tech demo under NASA's Game Changing Development program slated to send three shoebox-sized rovers to the moon in Q2 of 2024. The mission is using F' as it's core for its FSW. As a systems engineer, I'm not a developer, but a user that needs to understand how the code works to figure out how we're going to test and operate it. My C++ skills... let's just say are subject to improvement. So if something is evident in the source code, I might miss it. With that caveat fully stated, I'm starting to identify gaps, shortcomings, and inconsistencies in the documentation that would be great to clarify for the full F' user community. What I'll do is create this issue, then update, comment, or otherwise capture the documentation issues I identify. Anyone in charge, feel free to comment if you want a different approach.

Relative-timing in command sequences

My confusion here is with relative-timed commands in sequences and if they start at an offset from command dispatch or command completion. (This is a big deal for commands that take longer than a sequence-cycle to execute.)

The sample sequence alludes to the relative-timer starting from the completion of the previous command: https://github.com/fprime-community/fprime-gds/blob/7382c8c2c9cd14de7fb8998ba687d245022c6311/examples/simple_sequence.seq#L11-L17

Whereas the documentation does not specify if command timing is relative to the start of the command or end of the command.

This also highlights the need for more detailed timing description in command sequencing. How does sequence timing interact with the execution frequency of the sequence engine?

File packet structure

The binary construction of file packets is ill-defined. I'm used to something a.la CCSDS specifications. For example, see Section 2.2 of the CFDP Implementer's Guide, 720.2-G-4, copied below:

F' should have similar bit-level packet definitions such that there is no confusion in what is being sent when and how it is to be decoded on the ground. Such documentation enables easy V&V, easy troubleshooting, and easy ground interface development.

Absolute time sequence commands

What if an absolute timed command "expires"? e.g. you have this:

A2010-001T12:00:00 CMD1
A2010-001T12:00:10 CMD2

Where CMD1 takes 30s to complete. Does CMD2 clock out at 12:00:10? Or does it clock out at 12:00:30? Or is it just dropped? Or does it trigger a fault and kill everything?

nasa / fprime