Advanced Sequence Compiler 0.1

[zimri-leisher]

Related Issue(s)	nasa/fprime#2919
Has Unit Tests (y/n)	y
Documentation Included (y/n)	y

---

FPy Advanced Sequencing Language Version 0.1

The FPy advanced sequencing language is a combination of a high-level scripting language and a low-level bytecode language for running complex command sequences on spacecraft flight software. The initial version only duplicates already existing CmdSequencer and fprime-seqgen functionality.

FPy Syntax

Modules, components, channels, commands and types

You can imagine the FPy syntax as Python with the following mappings:

1. FPrime modules become Python namespaces
2. FPrime components become Python classes
3. FPrime types (structs, arrays and enums) become Python classes
4. FPrime component instances become Python object instances
5. FPrime commands become member functions of Python object instances
6. FPrime telemetry channels become member properties of Python object instances

FPrime declaration:

module Ref {
    passive component ExampleComponent {
        telemetry testChannel: U8
        sync command TEST_COMMAND(arg: string size 40)
    }

    instance exampleInstance: ExampleComponent base id 0x01
}

FPy usage:

# reference a telemetry channel
Ref.exampleInstance.testChannel
# call a command
Ref.exampleInstance.TEST_COMMAND("arg value")

FPrime declaration:

struct ExampleStruct {
    member: F32
}

enum TestEnum {
    ONE
    TWO
    THREE
}

array TestArray = [3] U8

FPy usage:

# construct a struct
ExampleStruct(0.0)
# reference an enum const
TestEnum.THREE
# construct an array
TestArray(1, 2, 3)

Sequence directives

FPy also has sequence directives, which are like commands that control the running sequence itself.

The most common sequence directives are absolute and relative sleep:

sleep_abs(Time(time_base, time_context, seconds, useconds))
sleep_rel(Time(time_base, time_context, seconds, useconds))

Due to the nature of the FPrime CmdSequencer, you can only have zero or one sleep directives before each command.

FPy Compiler Usage

fprime-seq <sequence.fpy> -d <TopologyDictionary.json> [-o <output.bin>]

A compiler for the FPrime advanced sequencing language

positional arguments:
  input                 The path of the input sequence to compile

options:
  -h, --help            show this help message and exit
  -d DICTIONARY, --dictionary DICTIONARY
                        The JSON topology dictionary to compile against
  -o OUTPUT, --output OUTPUT
                        The output .bin file path. Defaults to the input file path

The result is a sequence binary file that works with the FPrime CmdSequencer.

Rationale

This is a good first step towards proving that FPrime dictionaries and Python syntax trees can be linked. It also provides a demonstration of part of the functionality of the end goal.

Testing/Review Recommendations

Try this on any sequences you have. If you translate the sequence from .seq to .fpy, the binary output should be identical to that generated by fprime-seqgen.

Future Work

Start working on custom bytecode. First step for the custom bytecode should again just be to duplicate existing functionality.

[zimri-leisher]

Looks like this is failing to run some builds because I'm using a Python feature from 3.10, type subscripting. I will probably just include
from __future__ import annotations unless you'd rather I remove this syntax entirely.

[Joshua-Anderson]

Just want to jump in and say this is super neat! Seems like a nice and extensible way to build on top of the existing python syntax parser. I wish I had the time to be more involved right now but hopefully as my life gets less crazy in the next few months I'll have time to play around with this.

[LeStarch]

@zimri-leisher yes, if from future import annotations will fix this in python pre 3.10, then yes! If it doesn't, I can help you express these in earlier python syntax.

[LeStarch]

Spelling is failing because of:

bytecode
expr

Both of these are valid, so they need to be added to .github/actions/spelling/expect.txt

[LeStarch]

Python code looks nice. I don't see any major issues. Comments are a bit sparse, but otherwise this is nice!

[LeStarch]

Should we add fpy to this name to distinguish it? The old fprime-seqgen will lose to this in tab-complete and won't process correctly.

[zimri-leisher]

Ah good point. Sure, if you think that's the best idea, we can make a generic "fpy" cmdline tool whose default behavior can be compiling.

[LeStarch]

Eventually we should put this with F´. We typically try to avoid directory-READMEs.

[zimri-leisher]

Happy to move it. Where/when should we move it?

[zimri-leisher]

Just want to jump in and say this is super neat! Seems like a nice and extensible way to build on top of the existing python syntax parser. I wish I had the time to be more involved right now but hopefully as my life gets less crazy in the next few months I'll have time to play around with this.

Thanks! Any feedback you have would be super valuable. Yes, I just realized that any language I was going to make was going to be heavily inspired by Python. This is just skipping the middle man of having to write some EBNF grammar etc etc.

Python code looks nice. I don't see any major issues. Comments are a bit sparse, but otherwise this is nice!

The code is really the first version of this that works. I'll spend some time this week cleaning it up so I would feel comfortable merging it. Either way, most of this will have to be rewritten as the language evolves, but it was a helpful learning experience and proof-of-concept.