Metadata-Version: 2.4
Name: fprime-fpy
Version: 0.4
Summary: Fpy Advanced Sequencing Language for F Prime
Author-email: Zimri Leisher <zimri.leisher@gmail.com>, Michael Starch <Michael.D.Starch@jpl.nasa.gov>
Project-URL: Homepage, https://fprime.jpl.nasa.gov
Project-URL: Documentation, https://nasa.github.io/fprime/
Project-URL: Repository, https://github.com/fprime-community/fpy
Keywords: fprime,embedded,nasa,flight,software
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest>=6.2.4
Requires-Dist: lark>=1.2.2
Dynamic: license-file

![The letters 'fpy' in monospaced font, under a red planet illuminated by the light of a four pointed star.](fpy_logo.png)

[![Tests](https://github.com/fprime-community/fpy/actions/workflows/fprime-gds-tests.yml/badge.svg)](https://github.com/fprime-community/fpy/actions/workflows/fprime-gds-tests.yml)
[![Python](https://img.shields.io/pypi/pyversions/fprime-fpy)](https://pypi.org/project/fprime-fpy/)
[![License](https://img.shields.io/github/license/fprime-community/fpy)](LICENSE)


Fpy is a user-friendly spacecraft scripting language for the [F Prime](https://nasa.github.io/fprime/) flight software framework.

---

## Principles

Fpy has a few principles:

* Be safe
* Be pragmatic
* Be a joy to work with

>*The art of making a good language is to restrict the user in a good way* 
>
> – Andrey Breslav, creator of Kotlin

## Overview

This repository contains the Fpy compiler, which emits Fpy bytecode. The Fpy bytecode can be run on the `FpySequencer` virtual machine, or with the `fprime-fpy-model` CLI. If you're interested in contributing, see the [Developer's Guide](#developers-guide).

# User's Guide

This guide is a quick overview of the most important features of Fpy. It should be easy to follow for someone who has used Python and F Prime before.

## Compiling and Running a Sequence

First, make sure `fprime-fpy` is installed:

```
$ pip install fprime-fpy
```

Fpy sequences are suffixed with `.fpy`. Let's make a test sequence that dispatches a no-op:
```py
# hash denotes a comment
# assume this file is named "test.fpy"

# use the full name of the no-op command:
CdhCore.cmdDisp.CMD_NO_OP() # empty parentheses indicate no arguments
```

You can compile it with `fprime-fpyc test.fpy --dictionary Ref/build-artifacts/Linux/dict/RefTopologyDictionary.json`

Make sure your deployment topology has an instance of the `Svc.FpySequencer` component. You can run the sequence by passing it in as an argument to the `Svc.FpySequencer.RUN` command.

## Logging

Fpy supports logging F Prime events:
```py
log("hello world!") # creates an ACTIVITY_HI event with the text "hello world!"
```

You can configure the severity of the event:
```py
log("uh oh", Fw.LogSeverity.WARNING_HI)
log("oh no!", Fw.LogSeverity.FATAL)
```

All F Prime severity levels are supported.

At the moment, only constant string arguments are supported. See [Strings](#strings).

## Commands

Fpy supports calling any command in the F Prime dictionary:

```py
CdhCore.cmdDisp.CMD_NO_OP()
# no delay between commands
CdhCore.cmdDisp.CMD_NO_OP_STRING("hello world!")
# the sequence waits until a command response is returned
```

Commands arguments are type checked, and they do not need to be constants. You can pass command arguments by name:
```py
CdhCore.cmdDisp.CMD_NO_OP_STRING(arg1="hello world!")
```

If a command fails and the response isn't handled, the sequence will exit with an error:
```py
CdhCore.exampleComponent.CMD_THAT_WILL_FAIL()
# sequence exits with an error
```

You can suppress errors by handling the return value of the command:
```py
success: Fw.CmdResponse = CdhCore.exampleComponent.CMD_THAT_WILL_FAIL()
# cmd response is handled, sequence proceeds normally

if success == Fw.CmdResponse.EXECUTION_ERROR:
    log("Command failed!")
```

You can configure whether unhandled command failures cause the sequence to exit by setting the `flags.assert_cmd_success` Boolean flag:
```py
flags.assert_cmd_success = False
CdhCore.exampleComponent.CMD_THAT_WILL_FAIL()
# sequence proceeds normally
```

`flags.assert_cmd_success` is kind of like Bash's `set -e` and `set +e` commands. The flag defaults to `True`.

## Variables and Basic Types

Fpy supports statically-typed, mutable local variables. You can change their value, but the type of the variable can't change. 

This is how you declare a variable, and change its value:
```py
unsigned_var: U8 = 0
# this is a variable named unsigned_var with a type of unsigned 8-bit integer and a value of 0

unsigned_var = 123
# now it has a value of 123
```

For types, Fpy has most of the same basic ones that FPP does:
* Signed integers: `I8, I16, I32, I64`
* Unsigned integers: `U8, U16, U32, U64`
* Floats: `F32, F64`
* Boolean: `bool`
* Time: `Fw.Time`

Float literals can include either a decimal point or exponent notation (`5.0`, `.1`, `1e-5`), and Boolean literals have a capitalized first letter: `True`, `False`. There is no way to differentiate between signed and unsigned integer literals.

Note there is currently no built-in `string` type. See [Strings](#strings).

## Type coercion and casting
If you have a lower-bitwidth numerical type and want to turn it into a higher-bitwidth type, this happens automatically:
```py
low_bitwidth_int: U8 = 123
high_bitwidth_int: U32 = low_bitwidth_int
# high_bitwidth_int == 123
low_bitwidth_float: F32 = 123.0
high_bitwidth_float: F64 = low_bitwidth_float
# high_bitwidth_float == 123.0
```

However, the opposite produces a compile error:
```py
high_bitwidth: U32 = 25565
low_bitwidth: U8 = high_bitwidth # compile error
```

If you are sure you want to do this, you can manually cast the type to the lower-bitwidth type:
```py
high_bitwidth: U32 = 16383
low_bitwidth: U8 = U8(high_bitwidth) # no more error!
# low_bitwidth == 255
```
This is called downcasting. It has the following behavior:
* 64-bit floats are downcasted to 32-bit floats as if by `static_cast<F32>(f64_value)` in C++
* Unsigned integers are bitwise truncated to the desired length
* Signed integers are first reinterpreted bitwise as unsigned, then truncated to the desired length. Then, if the sign bit of the resulting number is set, `2 ** dest_type_bits` is subtracted from the resulting number to make it negative. This may have unintended behavior so use it cautiously.

You can turn an int into a float implicitly:
```py
int_value: U8 = 123
float_value: F32 = int_value
```

But the opposite produces a compile error:
```py
float_value: F32 = 123.0
int_value: U8 = float_value # compile error
```

Instead, you have to manually cast:
```py
float_value: F32 = 123.0
int_value: U8 = U8(float_value)
# int_value == 123
```

In addition, you have to cast between signed/unsigned ints:
```py
uint: U32 = 123123
int: I32 = uint # compile error
int: I32 = I32(uint)
# int == 123123
```


## Dictionary Types

Fpy also has access to all structs, arrays and enums in the F Prime dictionary:
```py
# you can access enum constants by name:
enum_var: Fw.Success = Fw.Success.SUCCESS

# you can construct arrays:
array_var: Ref.DpDemo.U32Array = [0, 1, 2, 3, 4]

# you can construct structs:
struct_var: Fw.TimeInterval = {seconds: 0, useconds: 1000}
```

If a struct or array has a default value for a member/element, it will use that default value if you don't provide one.

Trailing commas are allowed in these expressions.

## Math
You can do basic math and store the result in variables in Fpy:
```py
pemdas: F32 = 1 - 2 + 3 * 4 + 10 / 5 * 2 # == 15.0
```

Fpy supports the following math operations:
* Basic arithmetic: `+, -, *, /`
* Modulo: `%`
* Exponentiation: `**`
* Floor division: `//`
* Natural logarithm: `log(F64)`
* Absolute value: `fabs(F64), iabs(I64)`

The behavior of these operators is designed to mimic Python. 
> Note that **division always returns a float**. This means that `5 / 2 == 2.5`, not `2`. This may be confusing coming from C++, but it is consistent with Python. If you want integer division, use the `//` operator.

## Getting Telemetry Channels and Parameters

Fpy supports getting the value of telemetry channels:
```py
cmds_dispatched: U32 = CdhCore.cmdDisp.CommandsDispatched

signal_pair: Ref.SignalPair = Ref.SG1.PairOutput
```

It's important to note that if your component hasn't written telemetry to the telemetry database (`TlmPacketizer` or `TlmChan`) in a while, the value the sequence sees may be old. Make sure to regularly write your telemetry!

Fpy supports getting the value of parameters:
```py
prm_3: U8 = Ref.sendBuffComp.parameter3
```

A significant limitation of this is that it will only return the value most recently saved to the parameter database. This means you must command `_PRM_SAVE` before the sequence will see the new value.

> Note:  If a telemetry channel and parameter have the same fully-qualified name, the fully-qualified name will get the value of the telemetry channel

## Conditionals
Fpy supports comparison operators:
```py
value: bool = 1 > 2 and (3 + 4) != 5
```
* Inequalities: `>, <, >=, <=`
* Equalities: `==, !=`
* Boolean functions: `and, or, not`

Boolean `and` and `or` short-circuit just like Python: the right-hand expression only evaluates when the result is still undecided.


The inequality operators can compare two numbers of any type together. The equality operators, in addition to comparing numbers, can check for equality between two values of the same type:
```py
record1: Svc.DpRecord = Svc.DpRecord(0, 1, 2, 3, 4, 5, Fw.DpState.UNTRANSMITTED)
record2: Svc.DpRecord = Svc.DpRecord(0, 1, 2, 3, 4, 5, Fw.DpState.UNTRANSMITTED)
records_equal: bool = record1 == record2 # == True
```
## If/elif/else

You can branch off of conditionals with `if`, `elif` and `else`:
```py
random_value: I8 = 4 # chosen by fair dice roll. guaranteed to be random

if random_value < 0:
    log("won't happen")
elif random_value > 0 and random_value <= 6:
    log("should happen!")
else:
    log("uh oh...")
```

This is particularly useful for checking telemetry channel values:
```py
# dispatch a no-op
CdhCore.cmdDisp.CMD_NO_OP()
# the commands dispatched count should be >= 1
if CdhCore.cmdDisp.CommandsDispatched >= 1:
    log("should happen")
```

## Check statement

A `check` statement is like an [`if`](#ifelifelse), but its condition has to hold true (or "persist") for some amount of time.
```py
check CdhCore.cmdDisp.CommandsDispatched > 30 persist {seconds: 15}:
    log("more than 30 commands for 15 seconds!")
```

If you don't specify a value for `persist`, the condition only has to be true once.

You can specify an absolute time at which the `check` should time out:
```py
check CdhCore.cmdDisp.CommandsDispatched > 30 timeout now() + {seconds: 60} persist {seconds: 2}:
    log("more than 30 commands for 2 seconds!")
```

You can also specify a `timeout` clause, which executes if the `check` times out:
```py
check CdhCore.cmdDisp.CommandsDispatched > 30 timeout now() + {seconds: 60} persist {seconds: 2}:
    log("more than 30 commands for 2 seconds!")
timeout:
    log("took more than 60 seconds :(")
```

Finally, you can specify a `period` at which the condition should be checked:
```py
check CdhCore.cmdDisp.CommandsDispatched > 30 period {seconds: 1}: # check every 1 second
    log("more than 30 commands!")
```

If you don't specify a value for `period`, the default period is 1 second.

The `timeout`, `persist` and `period` clauses can appear in any order. They can also be spread across multiple lines:
```py
check CdhCore.cmdDisp.CommandsDispatched > 30
    timeout now() + {seconds: 60}
    persist {seconds: 2}
    period {seconds: 1}
    log("more than 30 commands for 2 seconds!")
timeout:
    log("took more than 60 seconds :(")
```

If you just want to wait until a condition is true without running any body, you can omit the colon and body:
```py
check CdhCore.cmdDisp.CommandsDispatched > 30 timeout now() + {seconds: 60}
# execution continues here once the condition is satisfied (or times out)
log("done waiting!")
```

## Getting Struct Members and Array Items

You can access members of structs by name, or array elements by index:
```py
# access struct members with "." syntax
signal_pair_time: F32 = Ref.SG1.PairOutput.time

# access array elements with "[]" syntax
com_queue_depth_0: U32 = ComCcsds.comQueue.comQueueDepth[0]
```

You can also reassign struct members or array elements:
```py
# Ref.SignalPair is a struct type
signal_pair: Ref.SignalPair = Ref.SG1.PairOutput
signal_pair.time = 0.2

# Svc.ComQueueDepth is an array type
com_queue_depth: Svc.ComQueueDepth = ComCcsds.comQueue.comQueueDepth
com_queue_depth[0] = 1
```

## For and while loops
You can loop while a condition is true:
```py
counter: U64 = 0
while counter < 100:
    counter = counter + 1

# counter == 100
```

Keep in mind, a busy-loop will eat up the whole thread of the `Svc.FpySequencer` component. If you do this for long enough, the queue will fill up and the component will assert. You may want to include at least one `sleep` in such a loop:

```py
while True:
    # this will execute one loop body every time checkTimers is called
    sleep()
```

You can also loop over a range of integers:
```py
sum: I64 = 0
# loop i from 0 inclusive to 5 exclusive
for i in 0..5:
    sum = sum + i

# sum == 10
```
The loop variable, in this case `i`, is always of type `I64`. If a variable with the same name as the loop variable already exists, it can be reused as long as it is an `I64`:
```py
i: I64 = 123
for i in 0..5: # okay: reuse of `i`
    sum = sum + i
```

There is currently no support for a step size other than 1.

While inside of a loop, you can break out of the loop:
```py
counter: U64 = 0
while True:
    counter = counter + 1
    if counter == 100:
        break

# counter == 100
```

You can also continue on to the next iteration of the loop, skipping the remainder of the loop body:
```py
odd_numbers_sum: I64 = 0
for i in 0..10:
    if i % 2 == 0:
        continue
    odd_numbers_sum = odd_numbers_sum + i

# odd_numbers_sum == 25
```

## Functions
You can define and call functions:
```py
def foobar():
    if 1 + 2 == 3:
        log("foo")

foobar()
```

Functions can have arguments and return types:
```py
def add_vals(a: U64, b: U64) -> U64:
    return a + b
    
assert add_vals(1, 2) == 3
```

Function arguments are passed by value. Trailing commas are allowed in the argument list.

Functions can have default argument values:
```py
def greet(times: I64 = 3):
    for i in 0..times:
        log("hello")

greet()  # uses default: prints 3 times
greet(1) # prints once
```

Default values must be constant expressions (literals, enum constants, type constructors with const args, etc.). You can't use telemetry, variables, or function calls as defaults.

Functions can access top-level variables:
```py
counter: I64 = 0

def increment():
    counter = counter + 1

increment()
increment()
assert counter == 2
```

Functions can call each other or themselves:
```py
def recurse(limit: U64):
    if limit == 0:
        return
    log("tick")
    recurse(limit - 1)

recurse(5) # prints "tick" 5 times
```

Functions can only be defined at the top level, so not inside loops, conditionals, or other functions.

## Sequence arguments

You can define arguments for a sequence similarly to function arguments:
```py
# in "example.fpy"

# sequence() must be the first statement in the file
sequence(foo: U32, bar: bool)

if foo == 123 and bar:
    log("foobar!")
```
Sequence arguments cannot have default values. They are always passed by value.

There are two ways of calling sequences, each of which supports passing sequence arguments: from another sequence, or from the ground.

When you call a sequence from another sequence, you can provide argument values in the command:
```py
# call the example.bin sequence, in blocking mode, with the argument values 123 and True
# passing args by name is supported
Ref.seqDisp.RUN_ARGS("example.bin", Svc.BlockState.BLOCK, 123, bar=True)
```

To call a sequence from the ground, use the `fprime-fpy-cmd` CLI:
```
# this does the same thing as the previous example
$ fprime-fpy-cmd 'Ref.seqDisp.RUN_ARGS("example.bin", Svc.BlockState.BLOCK, 123, bar=True)' -d TopologyDictionary.json
```
To use this, you must have a running GDS. See [`fprime-fpy-cmd`](#fprime-fpy-cmd) for more info.

In both cases, if `example.bin` is not found, or the argument names and types in `example.bin` are incompatible with the provided ones, the sequence will fail to compile. The compiler will search for `example.bin` by default in the same directory as the input `.fpy` file, but you can tell it to look in a different directory with the `-g/--ground-binary-dir` argument. At runtime, the `FpySequencer` component will resolve the path relative to a configurable flight binary directory.

**Important:** this means that you have to compile the sequence's dependencies into binary files before compiling the sequence itself. This is not handled by the Fpy compiler, so it is up to the build system to order the builds appropriately. You can use the `fprime-fpy-depend` tool to find the dependencies of a sequence.

## Relative and Absolute Sleep
You can pause the execution of a sequence for a relative duration, or until an absolute time:
```py
log("second 0")
# sleep for 1 second
sleep(1)
log("second 1")
# sleep for half a second
sleep(useconds=500_000)

# sleep until the next checkTimers call on the Svc.FpySequencer component
sleep()
log("checkTimers called!")

log("today")
# sleep until 1234567890 seconds and 0 microseconds after the epoch
sleep_until({timeBase: TimeBase.TB_NONE, timeContext: 1, seconds: 1234567890, useconds: 0})
log("much later")
```

You can also use the `time()` function to parse ISO 8601 timestamps:
```py
# Parse an ISO 8601 timestamp (UTC with Z suffix)
sleep_until(time("2025-12-19T14:30:00Z"))

# With microseconds
t: Fw.Time = time("2025-12-19T14:30:00.123456Z")
sleep_until(t)

# Customize timeBase and timeContext (defaults are TimeBase.TB_NONE and 0)
t: Fw.Time = time("2025-12-19T14:30:00Z", timeBase=TimeBase.TB_WORKSTATION_TIME, timeContext=1)
```

Make sure that the `Svc.FpySequencer.checkTimers` port is connected to a rate group. The sequencer only checks if a sleep is done when the port is called, so the more frequently you call it, the more accurate the wakeup time.

## Working with Time

Fpy provides built-in functions and operators for working with `Fw.Time` and `Fw.TimeInterval` types (aliases for `Fw.TimeValue` and `Fw.TimeIntervalValue` respectively).

You can get the current time with `now()`:
```py
current_time: Fw.Time = now()
```

The underlying implementation of `now()` just calls the `getTime` port on the `FpySequencer` component.

You can compare two `Fw.Time` values with comparison operators:
```py
t1: Fw.Time = now()
sleep(seconds=1)
t2: Fw.Time = now()

assert t1 <= t2
```

If the times are incomparable due to having different time bases, the sequence will assert. To safely compare times which may have different time bases, use the `time_cmp` function, in `time.fpy`.

You can also compare two `Fw.TimeInterval` values:
```py
interval1: Fw.TimeInterval = {seconds: 5}
interval2: Fw.TimeInterval = {seconds: 10}

assert interval1 < interval2
```

You can add a `Fw.TimeInterval` to a `Fw.Time`:
```py
current: Fw.Time = {timeBase: TimeBase.TB_PROC_TIME, timeContext: 0, seconds: 100, useconds: 500000}
offset: Fw.TimeInterval = {seconds: 60}
assert (current + offset).seconds == 160
```

You can subtract two `Fw.Time` values to get a `Fw.TimeInterval`:
```py
start: Fw.Time = {timeBase: TimeBase.TB_PROC_TIME, timeContext: 0, seconds: 100, useconds: 0}
end: Fw.Time = {timeBase: TimeBase.TB_PROC_TIME, timeContext: 0, seconds: 105, useconds: 500000}
assert (end - start).seconds == 5
```

Subtraction of two `Fw.Time` values asserts that both times have the same time base and that the first argument is greater than or equal to the second. If these conditions are not met, the sequence will exit with an error.

> If at any point the output value would overflow, the sequence will exit with an error.
> Under the hood, these operators are just calling the built in `time_cmp`, `time_sub`, `time_add`, etc. functions in `time.fpy`.

## Exit Macro
You can end the execution of the sequence early by calling the `exit` macro:
```py
# exit takes a U8 argument
# 0 is the error code meaning "no error"
exit(0)
# anything else means an error occurred, and will show up in telemetry
exit(123)
```

## Assertions
You can assert that a Boolean condition is true:
```py
# won't end the sequence
assert 1 > 0
# will end the sequence
assert 0 > 1
```

You can also specify an error code to be raised if the expression is not true:
```py
# will raise an error code of 123
assert 1 > 2, 123
```

## Strings
Fpy does not support a fully-fledged `string` type yet. You can pass a string literal as an argument to a command or builtin, but you cannot pass a string from a telemetry channel. You also cannot store a string in a variable, or perform any string manipulation, or use any types anywhere which have strings as members or elements. This is due to F Prime strings having a dynamic serialized size. These features will be added in a later Fpy update.

## fprime-fpy-cmd


# Developer's Guide

## Workflow

1. Make a venv
2. `pip install -e .`
3. Make changes to the source
4. `pytest`

## Running on a test F Prime deployment

1. `git clone git@github.com:zimri-leisher/fprime-fpy-testbed`
2. `cd fprime-fpy-testbed`
3. `git submodule update --init --recursive`
4. Make a venv, install fprime requirements
5. `cd Ref`
6. `fprime-util generate -f`
7. `fprime-util build -j16`
8. `fprime-gds`. You should see a green circle in the top right.
9. In the `fpy` repo, `pytest --use-gds --dictionary test/fpy/RefTopologyDictionary.json test/fpy/test_seqs.py` will run all of the test sequences against the live GDS deployment.

## Tools

### `fprime-fpyc` debugging flags
The compiler has an optional `debug` flag. When passed, the compiler will print a stack trace of where each compile error is generated.


The compiler has an optional `bytecode` flag. When passed, the compiler will output human-readable `.fpybc` files instead of `.bin` files.

### `fprime-fpy-model`

`fprime-fpy-model` is a Python model of the `FpySequencer` runtime. 
* Given a sequence binary file, it deserializes and runs the sequence as if it were running on a real `FpySequencer`.
* Commands always return successfully, without blocking.
* Telemetry and parameter access always raise `(PR|TL)M_CHAN_NOT_FOUND`.
* Use `--debug` to print each directive and the stack as it executes.

### `fprime-fpy-asm`

`fprime-fpy-asm` assembles human-readable `.fpybc` bytecode files into binary `.bin` files.

### `fprime-fpy-disasm`

`fprime-fpy-disasm` disassembles binary `.bin` files into human-readable `.fpybc` bytecode.

## Running tests

Use `pytest` to run the test suite:
```sh
pytest test/
```

By default, debug output from the sequencer model is disabled for performance. To enable verbose debug output (prints each directive and stack state), use the `--fpy-debug` flag:
```sh
pytest test/ --fpy-debug
```
