fprime-gds 4.0.2a2__tar.gz → 4.0.2a4__tar.gz

{fprime_gds-4.0.2a2 → fprime_gds-4.0.2a4}/.github/actions/spelling/expect.txt

@@ -29,6 +29,7 @@ BGR
 Biberstein
 bibtex
 bitmaps
+bitwidth
 breadcrumb
 Btns
 BUGLIST
@@ -84,7 +85,7 @@ deframed
 deframer
 deframing
 DEPRECATEDLIST
-deser
+DESER
 Deserial
 deserializes
 dests
@@ -136,26 +137,27 @@ fastentrypoints
 fbuild
 fd
 FEEDNAME
-FEQ
+feq
 FFCC
 FFFF
-FGE
-FGT
+fge
+fgt
 fileurl
 Firefox
-FLE
+fle
 focusring
-FNE
+fne
 FONTNAME
 FONTPATH
 FONTSIZE
-FPEXT
+fpext
 fpp
+fpow
 fprime
 fptable
-FPTOSI
-FPTOUI
-FPTRUNC
+fptosi
+fptoui
+fptrunc
 fpy
 fpybc
 fqn
@@ -188,11 +190,11 @@ idk
 idl
 idx
 ieeetr
-IEQ
+ieq
 ified
 ifun
 IH
-INE
+ine
 inprogress
 intersphinx
 intlimits
@@ -201,6 +203,7 @@ ipc
 ipp
 issuecomment
 itcl
+itrunc
 ixx
 janamian
 jawest
@@ -228,7 +231,7 @@ logdir
 logpath
 logselect
 luxon
-LVAR
+lvar
 makeindex
 MAKEVAR
 marijnh
@@ -278,6 +281,7 @@ paramdb
 passthrough
 pb
 pdflatex
+pemdas
 PERLMOD
 pkts
 plainnat
@@ -316,6 +320,7 @@ recuring
 recvd
 recvs
 reder
+referenceable
 removeit
 reqparse
 riverbankcomputing
@@ -326,27 +331,31 @@ rst
 saba
 scid
 sdd
+sdiv
 searchdata
 Segoe
 seqfile
 seqgen
 serializables
 serialutil
-SGE
-SGT
+sge
+sgt
 showinitializer
 sideeffect
+siext
 SIGALRM
-SITOFP
+signedness
+sitofp
 sizeb
+sle
 SMAP
 Smath
+smod
 smth
 SNDHWM
 sorttable
 spacepacket
 squashify
-sreg
 sss
 Ssymbols
 stackoverflow
@@ -393,11 +402,13 @@ typedef
 uart
 ucf
 udp
-UGE
+udiv
+uge
 UIs
-UITOFP
+uitofp
 uk
 ul
+umod
 UNINIT
 updown
 upfiles
@@ -416,6 +427,7 @@ viewcode
 vle
 vname
 VRuntime
+vuejs
 vw
 Watney
 webified
@@ -432,4 +444,5 @@ xmlpath
 xy
 zeromq
 zmq
+ziext
 zimri

{fprime_gds-4.0.2a2 → fprime_gds-4.0.2a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fprime-gds
-Version: 4.0.2a2
+Version: 4.0.2a4
 Summary: F Prime Flight Software Ground Data System layer
 Author-email: Michael Starch <Michael.D.Starch@jpl.nasa.gov>, Thomas Boyer-Chammard <Thomas.Boyer.Chammard@jpl.nasa.gov>
 License: 

{fprime_gds-4.0.2a2 → fprime_gds-4.0.2a4}/pyproject.toml

@@ -66,7 +66,8 @@ fprime-seqgen = "fprime_gds.common.tools.seqgen:main"
 fprime-dp-write = "fprime_gds.executables.data_product_writer:main"
 fprime-gds = "fprime_gds.executables.run_deployment:main"
 fprime-prm-write = "fprime_gds.common.tools.params:main"
-fprime-fpyc = "fprime_gds.common.fpy.main:main"
+fprime-fpyc = "fprime_gds.common.fpy.main:compile_main"
+fprime-fpy-model = "fprime_gds.common.fpy.main:model_main"
 fprime-merge-dictionary = "fprime_gds.executables.dictionary_merge:main"
 
 # For Pytest fixtures

{fprime_gds-4.0.2a2 → fprime_gds-4.0.2a4}/src/fprime_gds/common/distributor/distributor.py

@@ -16,6 +16,7 @@ descriptor header will be passed on to the registered objects.
 
 import logging
 
+from fprime.common.models.serialize.type_exceptions import DeserializeException
 from fprime_gds.common.decoders.decoder import DecodingException
 from fprime_gds.common.handlers import DataHandler
 from fprime_gds.common.utils import config_manager, data_desc_type
@@ -147,7 +148,6 @@ class Distributor(DataHandler):
         # | ...                       |      |
         # | ..                        |      |
         #   .                                :
-
         offset = 0
 
         # Parse length
@@ -199,13 +199,16 @@ class Distributor(DataHandler):
         ), "Leftover data is not equivalent to the remaining data in buffer"
 
         for raw_msg in raw_msgs:
-            (length, data_desc, msg) = self.parse_raw_msg_api(raw_msg)
-
-            data_desc_key = data_desc_type.DataDescType(data_desc).name
-            decoders = self.__decoders[data_desc_key]
-
+            try:
+                (length, data_desc, msg) = self.parse_raw_msg_api(raw_msg)
+                data_desc_key = data_desc_type.DataDescType(data_desc).name
+            except DeserializeException as deserialize_exception:
+                LOGGER.warning(f"Invalid message: {deserialize_exception}")
+                return
+            decoders = self.__decoders.get(data_desc_key, None)
             if not decoders:
                 LOGGER.warning(f"No decoder registered for: {data_desc_key}")
+                return
 
             for d in decoders:
                 try:

fprime_gds-4.0.2a4/src/fprime_gds/common/fpy/README.md

@@ -0,0 +1,204 @@
+# Fpy Guide
+
+Fpy is an easy to learn, powerful spacecraft scripting language backed by decades of JPL heritage. It is designed to work with the FPrime flight software framework. The syntax is inspired by Python, and it compiles to an efficient binary format.
+
+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 FPrime before.
+
+## 1. Compiling and Running a Sequence
+
+First, make sure `fprime-gds` is installed.
+
+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.
+
+## 2. 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`
+
+Float literals are denoted with a decimal point (`5.0`, `0.123`) and Boolean literals have a capitalized first letter: `True`, `False`. There is no way to differentiate between signed and unsigned integer literals, so the compiler looks at where the literal is used to determine the signedness.
+
+Note there is currently no built-in `string` type. See [Strings](#13-strings).
+
+## 3. Dictionary Types
+
+Fpy also has access to all structs, arrays and enums in the FPrime 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 = Ref.DpDemo.U32Array(0, 1, 2, 3, 4)
+
+# you can construct structs:
+struct_var: Ref.SignalPair = Ref.SignalPair(0.0, 1.0)
+```
+
+In general, the syntax for instantiating a struct or array type is `Full.Type.Name(arg, ..., arg)`.
+
+## 4. 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(x)`
+
+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.
+
+## 5. Variable Arguments to Commands
+
+Where this really gets interesting is when you pass variables or expressions into commands:
+```py
+# this is a command that takes an F32
+Ref.recvBuffComp.PARAMETER4_PRM_SET(1 - 2 + 3 * 4 + 10 / 5 * 2)
+# alternatively:
+param4: F32 = 15.0
+Ref.recvBuffComp.PARAMETER4_PRM_SET(param4)
+```
+
+The same syntax works with the [`sleep`](#11-relative-and-absolute-sleep), [`exit`](#12-exit-macro), and `log` macros.
+
+There are some restrictions on passing string values, or complex types containing string values, to commands. See [Strings](#13-strings).
+
+## 6. Getting Telemetry Channels
+
+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!
+
+## 7. Getting Parameters
+
+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.
+
+## 8. Conditionals
+Fpy supports comparison operators:
+```py
+value: bool = 1 > 2 and (3 + 4) != 5
+```
+* Inequalities: `>, <, >=, <=`
+* Equalities: `==, !=`
+* Boolean functions: `and, or, not`
+
+
+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 of the same complex 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
+```
+## 9. 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:
+    CdhCore.cmdDisp.CMD_NO_OP_STRING("won't happen")
+elif random_value > 0 and random_value <= 6:
+    CdhCore.cmdDisp.CMD_NO_OP_STRING("should happen!")
+else:
+    CdhCore.cmdDisp.CMD_NO_OP_STRING("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:
+    CdhCore.cmdDisp.CMD_NO_OP_STRING("should happen")
+```
+
+## 10. 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 cannot reassign struct members or array elements however:
+```py
+# Ref.SignalPair is a struct type
+signal_pair: Ref.SignalPair = Ref.SG1.PairOutput
+# compiler error:
+signal_pair.time = 0.2
+
+# Svc.ComQueueDepth is an array type
+com_queue_depth: Svc.ComQueueDepth = ComCcsds.comQueue.comQueueDepth
+# compiler error:
+com_queue_depth[0] = 1
+```
+
+## 11. Relative and Absolute Sleep
+You can pause the execution of a sequence for a relative duration, or until an absolute time:
+```py
+CdhCore.cmdDisp.CMD_NO_OP_STRING("second 0")
+# sleep for 1 second and 0 microseconds
+sleep(1, 0)
+CdhCore.cmdDisp.CMD_NO_OP_STRING("second 1")
+
+
+CdhCore.cmdDisp.CMD_NO_OP_STRING("today")
+# sleep until 12345678900 seconds and 0 microseconds after the epoch
+sleep_until(0, 0, 12345678900, 0)
+CdhCore.cmdDisp.CMD_NO_OP_STRING("much later")
+```
+
+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.
+
+## 12. Exit Macro
+You can end the execution of the sequence early by calling the `exit` macro:
+```py
+# exit takes a boolean argument
+# True means "end the sequence without an error"
+exit(True)
+# False means "end the sequence and raise an error"
+exit(False)
+```
+
+## 13. Strings
+Fpy does not support a fully-fledged `string` type yet. You can pass a string literal as an argument to a command, but you cannot pass a string from a telemetry channel. You also cannot store a string in a variable, or perform any string manipulation. These features will be added in a later Fpy update.

fprime_gds-4.0.2a4/src/fprime_gds/common/fpy/SPEC.md

@@ -0,0 +1,183 @@
+Nothing type is a type whose set of values is an empty set
+Unit type is a type whose set of values is a set with one element
+BIG question: what if we made an arbitrary precision int type? and float type?
+
+# Types
+
+The following types are built into Fpy, and the developer can directly refer to them by name:
+* Numeric types: `U8, U16, U32, U64, I8, I16, I32, I64, F32, F64`
+* Boolean type: `bool`
+* Time type: `Fw.Time`
+
+In addition, the developer can directly refer to any displayable type defined in FPP via its fully-qualified name. This includes user-defined structs, arrays and enums.
+
+There are some types which exist in Fpy but cannot be directly referenced by name by the developer. These are the internal *Int*, and *String* types. See [literals](#literals).
+
+## Structs
+You can instantiate a new struct at runtime by calling its constructor. A struct's constructor is a function with the same name as the type, with arguments corresponding to the type and position of the struct's members. For example, a struct defined as:
+```
+module Fw {
+    struct Example {
+        intValue: U8
+        boolValue: bool
+    }
+}
+```
+can be constructed in Fpy like:
+```
+Fw.Example(0, True)
+```
+
+
+# Literals
+The following literals are supported by Fpy:
+* Integer literals: `123`, `-456_879`
+* Float literals: `0.123`, `1e-5`
+* String literals: `"hello world"`, `'example string'`
+* Boolean literals: `True` and `False`
+
+## Integer literals
+Integer literals are strings matching:
+```
+DEC_NUMBER:   "1".."9" ("_"?  "0".."9" )*
+          |   "0"      ("_"?  "0"      )* /(?![1-9])/
+```
+
+The first rule of this syntax allows for integers without leading zeroes, separated by underscores. So this is okay:
+```
+123_456
+```
+but this is not:
+```
+0123_456
+```
+
+The second rule allows you to write any number of zeroes, separated by underscores:
+```
+00_000_0
+```
+
+Integer literals have a internal type *Int*, which is not directly referenceable by the user. The *Int* type supports integers of arbitrary size.
+
+## Float literals
+Float literals are strings matching:
+```
+FLOAT_NUMBER: _SPECIAL_DEC _EXP | DECIMAL _EXP?
+```
+where `_SPECIAL_DEC`, `_EXP` and `DECIMAL` are defined as:
+
+```
+_SPECIAL_DEC: "0".."9" ("_"?  "0".."9")*
+_EXP: ("e"|"E") ["+" | "-"] _SPECIAL_DEC
+DECIMAL: "." _SPECIAL_DEC | _SPECIAL_DEC "." _SPECIAL_DEC?
+```
+
+A `FLOAT_NUMBER` can be any string of digits suffixed with an exponent, like these:
+```
+1e-5
+100_200e10
+```
+
+or it can be a `DECIMAL` optionally suffixed by an exponent, like these:
+```
+1.
+2.123
+100.5e+10
+```
+
+Float literals are of type `F64`.
+
+## String literals
+String literals are strings matching:
+```
+STRING: /("(?!"").*?(?<!\\)(\\\\)*?"|'(?!'').*?(?<!\\)(\\\\)*?')/i
+```
+
+They have a internal type *String*, which is not directly referenceable by the user. The *String* type supports strings of arbitrary length.
+
+# Functions
+Functions have arguments and a return type. You can call a function like:
+```
+function_name(arg_1, arg_2, arg_3)
+```
+
+## Commands
+
+
+# Type conversion
+
+Type conversion is the process of converting an expression from one type to another. It can either be implicit, in which case it is called coercion, or explicit, in which case it is called casting.
+
+## Coercion
+Coercion happens when an expression of type *A* is used in a syntactic element which requires an expression of type *B*. For example, functions, operators and variable assignments all require specific input types, so type coercion happens in each of these.
+
+When type coercion happens, the following type conversion rules are applied:
+
+1. Expressions of any integer type can be converted to any signed or unsigned integer or float type.
+2. Expressions of any float type can be converted to any float type.
+3. Expressions of internal type *String* can be converted to any string type.
+
+TODO try out with forcing type casting--see what the FF's think
+TODO require explicit narrowing casts? or have a compiler warning?
+TODO consider float to int conversion?
+TODO consider adding constants
+
+If no rule matches, then the compiler raises an error.
+
+There is currently no support for converting non-internal string expressions to other string expressions.
+
+# Operators
+
+Fpy supports the following operators:
+* Basic arithmetic: `+, -, *, /`
+* Modulo: `%`
+* Exponentiation: `**`
+* Floor division: `//`
+* Boolean: `and, or, not`
+* Comparison: `<, >, <=, >=, ==, !=`
+
+Each time an operator is used, an intermediate type must be picked and both args must be converted to that type.
+
+## Behavior of operators
+
+### Addition (`+`)
+### Subtraction (`-`)
+### Multiplication (`*`)
+### Division (`/`)
+### Modulo (`%`)
+### Exponentiation (`**`)
+### Floor division (`//`)
+### And (`and`)
+### Or (`or`)
+### Not (`not`)
+
+
+## Intermediate types
+
+Intermediate types are picked via the following rules:
+
+1. The intermediate type of Boolean operators is always `bool`.
+2. The intermediate type of `==` and `!=` may be any type, so long as the left and right hand sides are the same type. If both are numeric then continue.
+3. If either argument is non-numeric, raise an error.
+4. If the operator is `/` or `**`, the intermediate type is always `F64`.
+5. If either argument is a float, the intermediate type is `F64`.
+6. If either argument is an unsigned integer, the intermediate type is `U64`.
+7. Otherwise, the intermediate type is `I64`.
+
+If the expressions given to the operator are not of the intermediate type, type coercion rules are applied.
+
+## Result type
+
+The result type is the type of the value produced by the operator.
+1. For numeric operators, the result type is the intermediate type.
+2. For boolean and comparison operators, the result type is `bool`.
+
+Normal type coercion rules apply to the result, of course. Once the operator has produced a value, it may be coerced into some other type depending on context.
+
+
+# Macros
+
+## exit
+## log
+## sleep
+## sleep_until

fprime_gds-4.0.2a4/src/fprime_gds/common/fpy/bytecode/assembler.py

@@ -0,0 +1,62 @@
+from dataclasses import astuple, dataclass
+import struct
+import zlib
+from fprime_gds.common.fpy.bytecode.directives import Directive
+from pathlib import Path
+
+HEADER_FORMAT = "!BBBBBHI"
+HEADER_SIZE = struct.calcsize(HEADER_FORMAT)
+
+
+@dataclass
+class Header:
+    majorVersion: int
+    minorVersion: int
+    patchVersion: int
+    schemaVersion: int
+    argumentCount: int
+    statementCount: int
+    bodySize: int
+
+
+FOOTER_FORMAT = "!I"
+FOOTER_SIZE = struct.calcsize(FOOTER_FORMAT)
+
+SCHEMA_VERSION = 2
+
+
+@dataclass
+class Footer:
+    crc: int
+
+
+def serialize_directives(dirs: list[Directive], output: Path):
+    output_bytes = bytes()
+
+    for dir in dirs:
+        output_bytes += dir.serialize()
+
+    header = Header(0, 0, 0, SCHEMA_VERSION, 0, len(dirs), len(output_bytes))
+    output_bytes = struct.pack(HEADER_FORMAT, *astuple(header)) + output_bytes
+
+    crc = zlib.crc32(output_bytes) % (1 << 32)
+    footer = Footer(crc)
+    output_bytes += struct.pack(FOOTER_FORMAT, *astuple(footer))
+    output.write_bytes(output_bytes)
+
+
+def deserialize_directives(bytes: bytes) -> list[Directive]:
+    header = Header(*struct.unpack_from(HEADER_FORMAT, bytes))
+
+    dirs = []
+    idx = 0
+    offset = HEADER_SIZE
+    while idx < header.statementCount:
+        offset_and_dir = Directive.deserialize(bytes, offset)
+        if offset_and_dir is None:
+            raise RuntimeError("Unable to deserialize sequence")
+        offset, dir = offset_and_dir
+        dirs.append(dir)
+        idx += 1
+
+    return dirs