From c77ca452d72bb7e3c9be629f225f317f643001f0 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 14 Jan 2025 17:00:19 -0800 Subject: [PATCH 01/11] Revise specification --- docs/fpp-spec.html | 190 ++++++++++++++++-- ...Component-Instance-Member-Identifiers.adoc | 94 +++++++++ .../Definitions/Topology-Definitions.adoc | 2 + docs/spec/Port-Instance-Identifiers.adoc | 44 ---- .../Connection-Graph-Specifiers.adoc | 4 +- .../Telemetry-Packet-Group-Specifiers.adoc | 16 ++ .../Telemetry-Packet-Specifiers.adoc | 16 ++ docs/spec/Specifiers/defs.sh | 2 + docs/spec/defs.sh | 2 +- 9 files changed, 301 insertions(+), 69 deletions(-) create mode 100644 docs/spec/Component-Instance-Member-Identifiers.adoc delete mode 100644 docs/spec/Port-Instance-Identifiers.adoc create mode 100644 docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc create mode 100644 docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 3d25c330b..320757479 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -742,20 +742,45 @@

The F Prime Prime (FPP) Language Specification, Unreleased, after v2.2.1

7.15.3. Examples -
  • 7.16. Topology Import Specifiers +
  • 7.16. Telemetry Packet Group Specifiers
    • +
  • 7.17. Telemetry Packet Specifiers + +
    • +
  • 7.18. Topology Import Specifiers +
    • -
  • 8. Port Instance Identifiers + +
    • +
  • 8. Component Instance Member Identifiers
  • 9. Type Names @@ -3341,6 +3366,9 @@

    5.12.1. Syntax

    A connection graph specifier

  • +

    A telemetry packet group specifier

    +
    • +

  • A topology import specifier

  • @@ -5204,14 +5232,14 @@

    7.3.1. Syntax

    [ unmatched ] -port-instance-id +port-instance-id [ [ expression ] ] -> -port-instance-id +port-instance-id [ [ expression @@ -7072,18 +7100,68 @@

    7.15.3. Examples

    -

    7.16. Topology Import Specifiers

    +

    7.16. Telemetry Packet Group Specifiers

    +
    +

    A telemetry packet group specifier specifies a grouping of +telemetry channels into telemetry packets.

    +
    +
    +

    7.16.1. Syntax

    +
    +

    TODO

    +
    +
    +
    +

    7.16.2. Semantics

    +
    +

    TODO

    +
    +
    +
    +

    7.16.3. Examples

    +
    +

    TODO

    +
    +
    +
    +
    +

    7.17. Telemetry Packet Specifiers

    +
    +

    A telemetry packet specifier specifies the format of a packet of +of telemetry channel data that can be sent to the ground.

    +
    +
    +

    7.17.1. Syntax

    +
    +

    TODO

    +
    +
    +
    +

    7.17.2. Semantics

    +
    +

    TODO

    +
    +
    +
    +

    7.17.3. Examples

    +
    +

    TODO

    +
    +
    +
    +
    +

    7.18. Topology Import Specifiers

    A topology import specifier imports one topology into another one.

    -

    7.16.1. Syntax

    +

    7.18.1. Syntax

    import qual-ident

    -

    7.16.2. Semantics

    +

    7.18.2. Semantics

    The qualified identifier must refer to @@ -7174,7 +7252,7 @@

    7.16.2. Semantics

    -

    7.16.3. Example

    +

    7.18.3. Example

    topology A {
@@ -7264,24 +7342,30 @@ 
    7.16.3. Example
    -

    8. Port Instance Identifiers

    +

    8. Component Instance Member Identifiers

    +

    A component instance member identifier refers to a member of a +component instance.

    +
    +
    +

    8.1. Port Instance Identifiers

    +

    A port instance identifier identifies a port instance that is part of a component instance. Port instance identifiers appear in connection graph specifiers.

    -
    -

    8.1. Syntax

    +
    +

    8.1.1. Syntax

    qual-ident . identifier

    -
    -

    8.2. Semantics

    +
    +

    8.1.2. Semantics

    For each port instance identifier Q . P:

    @@ -7309,8 +7393,8 @@

    8.2. Semantics

    -
    -

    8.3. Examples

    +
    +

    8.1.3. Examples

    a.b
@@ -7325,6 +7409,68 @@ 
    8.3. Examples
    +
    +

    8.2. Telemetry Channel Identifiers

    +
    +

    A telemetry channel identifier identifies a telemetry channel +that is part of a component instance. +Telemetry channel identifiers appear in +telemetry packet specifiers.

    +
    +
    +

    8.2.1. Syntax

    +
    +

    qual-ident +. +identifier

    +
    +
    +
    +

    8.2.2. Semantics

    +
    +

    For each telemetry channel identifier Q . T:

    +
    +
    +
      +
    1. +

      The qualified identifier Q must +refer to +a component instance I.

      +
      2. +
    2. +

      I must refer to a component +instance definition I'.

      +
      3. +
    3. +

      I' must refer to a component +definition C.

      +
      4. +
    4. +

      The identifier T +must refer to a +telemetry channel specifier +of C.

      +
      5. +
    +
    +
    +
    +

    8.2.3. Examples

    +
    +
    +
    a.b
+A.b.c
    +
    +
    +
    +

    In the first example, a names a component instance, and b names a +telemetry channel. +In the second example, A.b names a component instance, and c names a +telemetry channel.

    +
    +
    +
    +

    9. Type Names

    @@ -10582,7 +10728,7 @@

    22.4. Translation Tools

    diff --git a/docs/spec/Component-Instance-Member-Identifiers.adoc b/docs/spec/Component-Instance-Member-Identifiers.adoc new file mode 100644 index 000000000..4e7906969 --- /dev/null +++ b/docs/spec/Component-Instance-Member-Identifiers.adoc @@ -0,0 +1,94 @@ +== Component Instance Member Identifiers + +A *component instance member identifier* refers to a member of a +component instance. + +=== Port Instance Identifiers + +A *port instance identifier* identifies a port instance +that is part of a component instance. +Port instance identifiers appear in +<>. + +==== Syntax + +<> +`.` +<> + +==== Semantics + +For each port instance identifier _Q_ `.` _P_: + +. The qualified identifier _Q_ must +<> +a component instance _I_. + +. _I_ must refer to a <>. + +. _I'_ must refer to a <>. + +. The identifier _P_ +must refer to a +<> +of _C_. + +==== Examples + +[source,fpp] +---- +a.b +A.b.c +---- + +In the first example, `a` names a component instance, and `b` names a port +instance. +In the second example, `A.b` names a component instance, and `c` names a +port instance. + +=== Telemetry Channel Identifiers + +A *telemetry channel identifier* identifies a telemetry channel +that is part of a component instance. +Telemetry channel identifiers appear in +<>. + +==== Syntax + +<> +`.` +<> + +==== Semantics + +For each telemetry channel identifier _Q_ `.` _T_: + +. The qualified identifier _Q_ must +<> +a component instance _I_. + +. _I_ must refer to a <>. + +. _I'_ must refer to a <>. + +. The identifier _T_ +must refer to a +<> +of _C_. + +==== Examples + +[source,fpp] +---- +a.b +A.b.c +---- + +In the first example, `a` names a component instance, and `b` names a +telemetry channel. +In the second example, `A.b` names a component instance, and `c` names a +telemetry channel. diff --git a/docs/spec/Definitions/Topology-Definitions.adoc b/docs/spec/Definitions/Topology-Definitions.adoc index a89a6e1e7..1ad5476c9 100644 --- a/docs/spec/Definitions/Topology-Definitions.adoc +++ b/docs/spec/Definitions/Topology-Definitions.adoc @@ -27,6 +27,8 @@ instance specifier>> * A <> +* A <> + * A <> * An <> diff --git a/docs/spec/Port-Instance-Identifiers.adoc b/docs/spec/Port-Instance-Identifiers.adoc deleted file mode 100644 index c67a3a32e..000000000 --- a/docs/spec/Port-Instance-Identifiers.adoc +++ /dev/null @@ -1,44 +0,0 @@ -== Port Instance Identifiers - -A *port instance identifier* identifies a port instance -that is part of a component instance. -Port instance identifiers appear in -<>. - -=== Syntax - -<> -`.` -<> - -=== Semantics - -For each port instance identifier _Q_ `.` _P_: - -. The qualified identifier _Q_ must -<> -a component instance _I_. - -. _I_ must refer to a <>. - -. _I'_ must refer to a <>. - -. The identifier _P_ -must refer to a -<> -of _C_. - -=== Examples - -[source,fpp] ----- -a.b -A.b.c ----- - -In the first example, `a` names a component instance, and `b` names a port -instance. -In the second example, `A.b` names a component instance, and `c` names a -port instance. diff --git a/docs/spec/Specifiers/Connection-Graph-Specifiers.adoc b/docs/spec/Specifiers/Connection-Graph-Specifiers.adoc index 75bb71b8a..252956352 100644 --- a/docs/spec/Specifiers/Connection-Graph-Specifiers.adoc +++ b/docs/spec/Specifiers/Connection-Graph-Specifiers.adoc @@ -37,14 +37,14 @@ A connection is the following: _[_ `unmatched` _]_ -<> +<> _[_ `[` <> `]` _]_ `pass:[->]` -<> +<> _[_ `[` <> diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc new file mode 100644 index 000000000..c7c388ebf --- /dev/null +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -0,0 +1,16 @@ +=== Telemetry Packet Group Specifiers + +A *telemetry packet group specifier* specifies a grouping of +telemetry channels into <>. + +==== Syntax + +TODO + +==== Semantics + +TODO + +==== Examples + +TODO diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc new file mode 100644 index 000000000..deee535dc --- /dev/null +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -0,0 +1,16 @@ +=== Telemetry Packet Specifiers + +A *telemetry packet specifier* specifies the format of a packet of +of telemetry channel data that can be sent to the ground. + +==== Syntax + +TODO + +==== Semantics + +TODO + +==== Examples + +TODO diff --git a/docs/spec/Specifiers/defs.sh b/docs/spec/Specifiers/defs.sh index f5849157d..7e2bbfef7 100644 --- a/docs/spec/Specifiers/defs.sh +++ b/docs/spec/Specifiers/defs.sh @@ -23,5 +23,7 @@ Port-Matching-Specifiers.adoc Record-Specifiers.adoc State-Machine-Instance-Specifiers.adoc Telemetry-Channel-Specifiers.adoc +Telemetry-Packet-Group-Specifiers.adoc +Telemetry-Packet-Specifiers.adoc Topology-Import-Specifiers.adoc " diff --git a/docs/spec/defs.sh b/docs/spec/defs.sh index 3285c6fbf..f8cd896fd 100644 --- a/docs/spec/defs.sh +++ b/docs/spec/defs.sh @@ -17,7 +17,7 @@ Element-Sequences.adoc Definitions/Definitions.adoc State-Machine-Behavior-Elements/State-Machine-Behavior-Elements.adoc Specifiers/Specifiers.adoc -Port-Instance-Identifiers.adoc +Component-Instance-Member-Identifiers.adoc Type-Names.adoc Expressions/Expressions.adoc Formal-Parameter-Lists.adoc From 497edc921a5ff1bde902ab39a60e5abb8f0f04dc Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 14 Jan 2025 18:02:09 -0800 Subject: [PATCH 02/11] Revise specification --- docs/code-prettify/run_prettify.js | 2 + docs/fpp-spec.html | 83 +++++++++++++++++-- docs/spec/Lexical-Elements.adoc | 2 + .../Telemetry-Packet-Group-Specifiers.adoc | 2 + .../Telemetry-Packet-Specifiers.adoc | 66 +++++++++++++-- 5 files changed, 141 insertions(+), 14 deletions(-) diff --git a/docs/code-prettify/run_prettify.js b/docs/code-prettify/run_prettify.js index 014231cd2..ac2e15a7a 100644 --- a/docs/code-prettify/run_prettify.js +++ b/docs/code-prettify/run_prettify.js @@ -449,6 +449,7 @@ var IN_GLOBAL_SCOPE = false; "input," + "instance," + "internal," + + "level," + "locate," + "low," + "machine," + @@ -458,6 +459,7 @@ var IN_GLOBAL_SCOPE = false; "opcode," + "orange," + "output," + + "packet," + "param," + "passive," + "phase," + diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 320757479..d21d37b4e 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -1163,6 +1163,7 @@

    3.1. Reserved Words

    input instance internal +level locate low machine @@ -1172,6 +1173,7 @@

    3.1. Reserved Words

    opcode orange output +packet param passive phase @@ -7103,7 +7105,9 @@

    7.15.3. Examples

    7.16. Telemetry Packet Group Specifiers

    A telemetry packet group specifier specifies a grouping of -telemetry channels into telemetry packets.

    +telemetry channels into telemetry packets. +A telemetry packet group specifier is part of a +topology definition.

    7.16.1. Syntax

    @@ -7127,25 +7131,86 @@

    7.16.3. Examples<

    7.17. Telemetry Packet Specifiers

    -

    A telemetry packet specifier specifies the format of a packet of -of telemetry channel data that can be sent to the ground.

    +

    A telemetry packet specifier specifies the format of a data +packet containing telemetry points that can be sent to the ground. +A telemetry packet specifier is part of a +telemetry packet group +specifier, which is in turn part of a +topology definition.

    7.17.1. Syntax

    -

    TODO

    +

    packet +identifier +[ +id expression +] +level expression +{ telemetry-channel-sequence }

    +
    +
    +

    telemetry-channel-sequence is an +element sequence in +which each element is a +telemetry channel identifier, +and the terminating punctuation is a comma.

    7.17.2. Semantics

    -
    -

    TODO

    +
    +
      +
    • +

      The optional expression e following id specifies the numeric +identifier for the packet. +If e is present, then the type of e must be +convertible to +Integer, and e must evaluate +to a nonnegative integer. +If e is not present, then the default identifier is either zero (for the +first +packet appearing in a packet group) or the previous packet identifier plus one.

      +
      • +
    • +

      The expression e following level specifies the +level of the packet. +The level is a number that governs the sending of the packet. +In the F Prime flight software, sending of packets can be throttled, +so that only packets at or below a specified level are sent. +The type of e must be +convertible to +Integer, and e must evaluate +to a nonnegative integer.

      +
      • +
    • +

      For each telemetry channel identifier I in telemetry-channel-sequence, +the component instance referred to in I must be +available in the enclosing topology, either through +direct specification +or through +import.

      +
      • +

    7.17.3. Examples

    -
    -

    TODO

    +
    +
    +
    # CDH packet has id 0 and level 0
+packet CDH id 0 level 0 {
+  commandDispatcher.commandsDispatched
+  rateGroup1Hz.rgMaxTime
+  fileUplink.filesReceived
+}
+
+# Implicit id of ADCS packet is 1. Its level is 2.
+packet ADCS level 2 {
+  adcs.mode
+  adcs.attitude
+}
    +
    @@ -10728,7 +10793,7 @@

    22.4. Translation Tools

    diff --git a/docs/spec/Lexical-Elements.adoc b/docs/spec/Lexical-Elements.adoc index bd378178a..345170039 100644 --- a/docs/spec/Lexical-Elements.adoc +++ b/docs/spec/Lexical-Elements.adoc @@ -87,6 +87,7 @@ initial input instance internal +level locate low machine @@ -96,6 +97,7 @@ on opcode orange output +packet param passive phase diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index c7c388ebf..1af9edf66 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -2,6 +2,8 @@ A *telemetry packet group specifier* specifies a grouping of telemetry channels into <>. +A telemetry packet group specifier is part of a +<>. ==== Syntax diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index deee535dc..3ad04eb07 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -1,16 +1,72 @@ === Telemetry Packet Specifiers -A *telemetry packet specifier* specifies the format of a packet of -of telemetry channel data that can be sent to the ground. +A *telemetry packet specifier* specifies the format of a data +packet containing telemetry points that can be sent to the ground. +A telemetry packet specifier is part of a +<>, which is in turn part of a +<>. ==== Syntax -TODO +`packet` +<> +_[_ +`id` <> +_]_ +`level` <> +`{` _telemetry-channel-sequence_ `}` + +_telemetry-channel-sequence_ is an +<> in +which each element is a +<>, +and the terminating punctuation is a comma. ==== Semantics -TODO +* The optional expression _e_ following `id` specifies the numeric +identifier for the packet. +If _e_ is present, then the type of _e_ must be +<> +<>, and _e_ must evaluate +to a nonnegative integer. +If _e_ is not present, then the default identifier is either zero (for the +first +packet appearing in a packet group) or the previous packet identifier plus one. + +* The expression _e_ following `level` specifies the +*level* of the packet. +The level is a number that governs the sending of the packet. +In the F Prime flight software, sending of packets can be throttled, +so that only packets at or below a specified level are sent. +The type of _e_ must be +<> +<>, and _e_ must evaluate +to a nonnegative integer. + +* For each telemetry channel identifier _I_ in _telemetry-channel-sequence_, +the component instance referred to in _I_ must be +available in the enclosing topology, either through +<> +or through +<>. ==== Examples -TODO +[source,fpp] +---- +# CDH packet has id 0 and level 0 +packet CDH id 0 level 0 { + commandDispatcher.commandsDispatched + rateGroup1Hz.rgMaxTime + fileUplink.filesReceived +} + +# Implicit id of ADCS packet is 1. Its level is 2. +packet ADCS level 2 { + adcs.mode + adcs.attitude +} +---- From a2b921ba39260346893577acaaa9d63b7a23518a Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 14 Jan 2025 18:35:43 -0800 Subject: [PATCH 03/11] Revise spec --- docs/code-prettify/run_prettify.js | 2 + docs/fpp-spec.html | 103 ++++++++++++++++-- .../Definitions/Topology-Definitions.adoc | 13 +++ docs/spec/Lexical-Elements.adoc | 2 + .../Telemetry-Packet-Group-Specifiers.adoc | 57 +++++++++- .../Telemetry-Packet-Specifiers.adoc | 6 +- 6 files changed, 168 insertions(+), 15 deletions(-) diff --git a/docs/code-prettify/run_prettify.js b/docs/code-prettify/run_prettify.js index ac2e15a7a..a98e5a84f 100644 --- a/docs/code-prettify/run_prettify.js +++ b/docs/code-prettify/run_prettify.js @@ -443,6 +443,7 @@ var IN_GLOBAL_SCOPE = false; "hook," + "id," + "if," + + "ignore," + "import," + "include," + "initial," + @@ -460,6 +461,7 @@ var IN_GLOBAL_SCOPE = false; "orange," + "output," + "packet," + + "packets," + "param," + "passive," + "phase," + diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index d21d37b4e..5a468b3dc 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -1157,6 +1157,7 @@

    3.1. Reserved Words

    hook id if +ignore import include initial @@ -1174,6 +1175,7 @@

    3.1. Reserved Words

    orange output packet +packets param passive phase @@ -3392,6 +3394,9 @@

    5.12.2. Semantics

    partially numbered topology T'.

  • +

    Check telemetry packet group specifiers for T'.

    +
    • +

  • Apply automatic numbering of ports to T'.

    @@ -3480,6 +3485,24 @@
    +
    Checking-Telemetry-Packet-Group-Specifiers
    +
    +

    FPP checks telemetry packet group specifiers as follows:

    +
    +
    +
      +
    1. +

      Check that no two telemetry packet group specifiers have +the same name.

      +
      2. +
    2. +

      Check that each telemetry packet group specifier is +valid.

      +
      3. +
    +
    + +
    Automatic Numbering of Ports

    FPP automatically assigns port numbers as follows.

    @@ -7112,19 +7135,81 @@

    7.16. Telemetry Packet Gro

    7.16.1. Syntax

    -

    TODO

    +

    telemetry packets +identifier +{ telemetry-packet-specifier-sequence } +[ +ignore +{ telemetry-channel-specifier-sequence } +]

    +
    +
    +

    telemetry-packet-specifier-sequence is an +element sequence in +which each element is a telemetry +packet specifier, +and the terminating punctuation is a comma.

    +
    +
    +

    telemetry-channel-sequence is an +element sequence in +which each element is a +telemetry channel identifier, +and the terminating punctuation is a comma.

    7.16.2. Semantics

    -
    -

    TODO

    +
    +
      +
    1. +

      Each telemetry packet specifier in telemetry-packet-specifier-sequence must +be valid, +and it must have a distinct name and a distinct identifier.

      +
      2. +
    2. +

      For every telemetry channel T that is a member of a component +instance available in the enclosing topology, either through +direct specification +or through +import, +exactly one of the following must be true:

      +
      +
        +
      1. +

        T appears in at least one of the packets of +telemetry-packet-specifier-sequence.

        +
        2. +
      2. +

        telemetry-channel-sequence is present, and T appears in it.

        +
        3. +
      +
      +
      3. +

    7.16.3. Examples

    -
    -

    TODO

    +
    +
    +
    packets Packets {
+
+  packet CDH level 0 {
+    commandDispatcher.commandsDispatched
+    rateGroup1Hz.rgMaxTime
+    fileUplink.filesReceived
+  }
+
+  packet ADCS level 2 {
+    adcs.mode
+    adcs.attitude
+  }
+
+} ignore {
+  adcs.extraTelemetry
+}
    +
    @@ -7159,8 +7244,8 @@

    7.17.1. Syntax

    7.17.2. Semantics

    -
    -
      +
      +

      1. The optional expression e following id specifies the numeric identifier for the packet. @@ -7191,7 +7276,7 @@

        7.17.2. Semantics

        or through import.

        2. -
    +
    @@ -10793,7 +10878,7 @@

    22.4. Translation Tools

    diff --git a/docs/spec/Definitions/Topology-Definitions.adoc b/docs/spec/Definitions/Topology-Definitions.adoc index 1ad5476c9..338e1e10a 100644 --- a/docs/spec/Definitions/Topology-Definitions.adoc +++ b/docs/spec/Definitions/Topology-Definitions.adoc @@ -42,6 +42,9 @@ according to the following algorithm: <> _T'_. +. <> for _T'_. + . Apply <> @@ -113,6 +116,16 @@ registration connection between two ports, and there is already a command registration connection between those ports, then do not add the connection. +===== Checking-Telemetry-Packet-Group-Specifiers + +FPP checks telemetry packet group specifiers as follows: + +. Check that no two telemetry packet group specifiers have +the same name. + +. Check that each telemetry packet group specifier is +<>. + ===== Automatic Numbering of Ports FPP automatically assigns port numbers as follows. diff --git a/docs/spec/Lexical-Elements.adoc b/docs/spec/Lexical-Elements.adoc index 345170039..a910d3368 100644 --- a/docs/spec/Lexical-Elements.adoc +++ b/docs/spec/Lexical-Elements.adoc @@ -81,6 +81,7 @@ high hook id if +ignore import include initial @@ -98,6 +99,7 @@ opcode orange output packet +packets param passive phase diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index 1af9edf66..99733db9e 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -7,12 +7,63 @@ A telemetry packet group specifier is part of a ==== Syntax -TODO +`telemetry` `packets` +<> +`{` _telemetry-packet-specifier-sequence_ `}` +_[_ +`ignore` +`{` _telemetry-channel-specifier-sequence_ `}` +_]_ + +_telemetry-packet-specifier-sequence_ is an +<> in +which each element is a <>, +and the terminating punctuation is a comma. + +_telemetry-channel-sequence_ is an +<> in +which each element is a +<>, +and the terminating punctuation is a comma. ==== Semantics -TODO +. Each telemetry packet specifier in _telemetry-packet-specifier-sequence_ must +be <>, +and it must have a distinct name and a distinct identifier. + +. For every telemetry channel _T_ that is a member of a component +instance available in the enclosing topology, either through +<> +or through +<>, +exactly one of the following must be true: + +.. _T_ appears in at least one of the packets of +_telemetry-packet-specifier-sequence_. + +.. _telemetry-channel-sequence_ is present, and _T_ appears in it. ==== Examples -TODO +[source,fpp] +---- +packets Packets { + + packet CDH level 0 { + commandDispatcher.commandsDispatched + rateGroup1Hz.rgMaxTime + fileUplink.filesReceived + } + + packet ADCS level 2 { + adcs.mode + adcs.attitude + } + +} ignore { + adcs.extraTelemetry +} +---- diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index 3ad04eb07..bb6055f8d 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -26,7 +26,7 @@ and the terminating punctuation is a comma. ==== Semantics -* The optional expression _e_ following `id` specifies the numeric +. The optional expression _e_ following `id` specifies the numeric identifier for the packet. If _e_ is present, then the type of _e_ must be <> @@ -36,7 +36,7 @@ If _e_ is not present, then the default identifier is either zero (for the first packet appearing in a packet group) or the previous packet identifier plus one. -* The expression _e_ following `level` specifies the +. The expression _e_ following `level` specifies the *level* of the packet. The level is a number that governs the sending of the packet. In the F Prime flight software, sending of packets can be throttled, @@ -46,7 +46,7 @@ The type of _e_ must be <>, and _e_ must evaluate to a nonnegative integer. -* For each telemetry channel identifier _I_ in _telemetry-channel-sequence_, +. For each telemetry channel identifier _I_ in _telemetry-channel-sequence_, the component instance referred to in _I_ must be available in the enclosing topology, either through <> From 02a9a99fd6a6091d4cffd412027d04ddbe7ae3b0 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 14 Jan 2025 18:37:51 -0800 Subject: [PATCH 04/11] Revise specification --- docs/fpp-spec.html | 8 ++++---- .../Specifiers/Telemetry-Packet-Group-Specifiers.adoc | 4 ++-- docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 5a468b3dc..6f4d2ec6c 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -7127,8 +7127,8 @@

    7.15.3. Examples

    7.16. Telemetry Packet Group Specifiers

    -

    A telemetry packet group specifier specifies a grouping of -telemetry channels into telemetry packets. +

    A telemetry packet group specifier groups the telemetry channels of a +topology into telemetry packets. A telemetry packet group specifier is part of a topology definition.

    @@ -7217,7 +7217,7 @@

    7.16.3. Examples<

    7.17. Telemetry Packet Specifiers

    A telemetry packet specifier specifies the format of a data -packet containing telemetry points that can be sent to the ground. +packet containing telemetry points. A telemetry packet specifier is part of a telemetry packet group specifier, which is in turn part of a @@ -10878,7 +10878,7 @@

    22.4. Translation Tools

    diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index 99733db9e..165ca2657 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -1,7 +1,7 @@ === Telemetry Packet Group Specifiers -A *telemetry packet group specifier* specifies a grouping of -telemetry channels into <>. +A *telemetry packet group specifier* groups the telemetry channels of a +topology into <>. A telemetry packet group specifier is part of a <>. diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index bb6055f8d..39ea136a5 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -1,7 +1,7 @@ === Telemetry Packet Specifiers A *telemetry packet specifier* specifies the format of a data -packet containing telemetry points that can be sent to the ground. +packet containing telemetry points. A telemetry packet specifier is part of a <>, which is in turn part of a From dea65db04ff33a8a479adc395a4c67316a700c8b Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Wed, 15 Jan 2025 10:17:08 -0800 Subject: [PATCH 05/11] Revise spec --- docs/code-prettify/run_prettify.js | 2 +- docs/fpp-spec.html | 34 +++++++++++-------- docs/spec/Lexical-Elements.adoc | 2 +- .../Telemetry-Packet-Group-Specifiers.adoc | 21 +++++++----- .../Telemetry-Packet-Specifiers.adoc | 4 +-- 5 files changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/code-prettify/run_prettify.js b/docs/code-prettify/run_prettify.js index a98e5a84f..4926af255 100644 --- a/docs/code-prettify/run_prettify.js +++ b/docs/code-prettify/run_prettify.js @@ -443,7 +443,6 @@ var IN_GLOBAL_SCOPE = false; "hook," + "id," + "if," + - "ignore," + "import," + "include," + "initial," + @@ -456,6 +455,7 @@ var IN_GLOBAL_SCOPE = false; "machine," + "match," + "module," + + "omit," + "on," + "opcode," + "orange," + diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 6f4d2ec6c..6b3f3a3c0 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -746,7 +746,7 @@

    The F Prime Prime (FPP) Language Specification, Unreleased, after v2.2.1

  • 7.16.1. Syntax
  • 7.16.2. Semantics
    • -
  • 7.16.3. Examples
    • +
  • 7.16.3. Example

  • 7.17. Telemetry Packet Specifiers @@ -1157,7 +1157,6 @@

    3.1. Reserved Words

    hook id if -ignore import include initial @@ -1170,6 +1169,7 @@

    3.1. Reserved Words

    machine match module +omit on opcode orange @@ -7139,7 +7139,7 @@

    7.16.1. Syntax

    identifier { telemetry-packet-specifier-sequence } [ -ignore +omit { telemetry-channel-specifier-sequence } ]

    @@ -7164,15 +7164,18 @@

    7.16.2. Semantic

    1. Each telemetry packet specifier in telemetry-packet-specifier-sequence must -be valid, -and it must have a distinct name and a distinct identifier.

      +be valid,

    2. -

      For every telemetry channel T that is a member of a component -instance available in the enclosing topology, either through +

      Each telemetry packet specifier in telemetry-packet-specifier-sequence must +must have a distinct name and a distinct identifier.

      +
      3. +
    3. +

      For every component instance I available in the enclosing topology, either through direct specification or through import, +for every telemetry channel T that is a member of I, exactly one of the following must be true:

        @@ -7181,7 +7184,8 @@

        7.16.2. Semantic telemetry-packet-specifier-sequence.

      1. -

        telemetry-channel-sequence is present, and T appears in it.

        +

        telemetry-channel-sequence is present, and T appears in +telemetry-channel-sequence.

      @@ -7190,23 +7194,23 @@

      7.16.2. Semantic
      -

      7.16.3. Examples

      +

      7.16.3. Example

      packets Packets {
 
-  packet CDH level 0 {
+  packet CDH id 0 level 0 {
     commandDispatcher.commandsDispatched
     rateGroup1Hz.rgMaxTime
     fileUplink.filesReceived
   }
 
-  packet ADCS level 2 {
+  packet ADCS id 1 level 2 {
     adcs.mode
     adcs.attitude
   }
 
-} ignore {
+} omit {
   adcs.extraTelemetry
 }
      @@ -7261,8 +7265,8 @@

      7.17.2. Semantics

      The expression e following level specifies the level of the packet. The level is a number that governs the sending of the packet. -In the F Prime flight software, sending of packets can be throttled, -so that only packets at or below a specified level are sent. +In the F Prime flight software, sending of packets can be filtered +by level, so that only packets at or below a specified level are sent. The type of e must be convertible to Integer, and e must evaluate @@ -10878,7 +10882,7 @@

      22.4. Translation Tools

      diff --git a/docs/spec/Lexical-Elements.adoc b/docs/spec/Lexical-Elements.adoc index a910d3368..2e8178483 100644 --- a/docs/spec/Lexical-Elements.adoc +++ b/docs/spec/Lexical-Elements.adoc @@ -81,7 +81,6 @@ high hook id if -ignore import include initial @@ -94,6 +93,7 @@ low machine match module +omit on opcode orange diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index 165ca2657..4ad721e58 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -11,7 +11,7 @@ A telemetry packet group specifier is part of a <> `{` _telemetry-packet-specifier-sequence_ `}` _[_ -`ignore` +`omit` `{` _telemetry-channel-specifier-sequence_ `}` _]_ @@ -32,38 +32,41 @@ and the terminating punctuation is a comma. . Each telemetry packet specifier in _telemetry-packet-specifier-sequence_ must be <>, -and it must have a distinct name and a distinct identifier. -. For every telemetry channel _T_ that is a member of a component -instance available in the enclosing topology, either through +. Each telemetry packet specifier in _telemetry-packet-specifier-sequence_ must +must have a distinct name and a distinct identifier. + +. For every component instance _I_ available in the enclosing topology, either through <> or through <>, +for every telemetry channel _T_ that is a member of _I_, exactly one of the following must be true: .. _T_ appears in at least one of the packets of _telemetry-packet-specifier-sequence_. -.. _telemetry-channel-sequence_ is present, and _T_ appears in it. +.. _telemetry-channel-sequence_ is present, and _T_ appears in +_telemetry-channel-sequence_. -==== Examples +==== Example [source,fpp] ---- packets Packets { - packet CDH level 0 { + packet CDH id 0 level 0 { commandDispatcher.commandsDispatched rateGroup1Hz.rgMaxTime fileUplink.filesReceived } - packet ADCS level 2 { + packet ADCS id 1 level 2 { adcs.mode adcs.attitude } -} ignore { +} omit { adcs.extraTelemetry } ---- diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index 39ea136a5..ec37df4d1 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -39,8 +39,8 @@ packet appearing in a packet group) or the previous packet identifier plus one. . The expression _e_ following `level` specifies the *level* of the packet. The level is a number that governs the sending of the packet. -In the F Prime flight software, sending of packets can be throttled, -so that only packets at or below a specified level are sent. +In the F Prime flight software, sending of packets can be filtered +by level, so that only packets at or below a specified level are sent. The type of _e_ must be <> <>, and _e_ must evaluate From 0b888afc0035659da27e60033db2e84df8585a37 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Wed, 15 Jan 2025 10:20:03 -0800 Subject: [PATCH 06/11] Revise editor syntax files --- editors/emacs/fpp-mode.el | 7 ++++--- editors/vim/fpp.vim | 4 ++++ 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/editors/emacs/fpp-mode.el b/editors/emacs/fpp-mode.el index 2a7905a22..74f56f9d1 100644 --- a/editors/emacs/fpp-mode.el +++ b/editors/emacs/fpp-mode.el @@ -35,7 +35,8 @@ (defconst fpp-mode-definition-keywords '("type" "array" "component" "instance" "constant" - "enum" "machine" "module" "port" "state" "struct" "topology") + "enum" "machine" "module" "omit" "packet" "packets" + "port" "state" "struct" "topology") "FPP keywords for definitions.") (defconst fpp-mode-keywords @@ -45,8 +46,8 @@ "drop" "else" "entry" "event" "exit" "false" "fatal" "format" "get" "guard" "guarded" "health" "high" "hook" "id" "if" "import" - "include" "initial" "input" "internal" - "locate" "low" "match" "on" "opcode" "orange" + "include" "initial" "input" "internal" "level" + "locate" "low" "match" "on" "opcode" "orange" "output" "param" "passive" "phase" "priority" "private" "queue" "queued" "raw" "recv" "red" "ref" "reg" "resp" "save" "signal" "serial" "set" "severity" diff --git a/editors/vim/fpp.vim b/editors/vim/fpp.vim index 53f3be206..5dd7e649d 100644 --- a/editors/vim/fpp.vim +++ b/editors/vim/fpp.vim @@ -53,15 +53,19 @@ syn keyword fppKeyword initial syn keyword fppKeyword input syn keyword fppKeyword instance syn keyword fppKeyword internal +syn keyword fppKeyword level syn keyword fppKeyword locate syn keyword fppKeyword low syn keyword fppKeyword machine syn keyword fppKeyword match syn keyword fppKeyword module +syn keyword fppKeyword omit syn keyword fppKeyword on syn keyword fppKeyword opcode syn keyword fppKeyword orange syn keyword fppKeyword output +syn keyword fppKeyword packet +syn keyword fppKeyword packets syn keyword fppKeyword param syn keyword fppKeyword passive syn keyword fppKeyword phase From fd118d5e3309ca11abcf418604d741e3bf62d8b6 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Wed, 15 Jan 2025 13:15:57 -0800 Subject: [PATCH 07/11] Revise spec --- docs/fpp-spec.html | 10 +++++++++- docs/spec/Definitions/Topology-Definitions.adoc | 7 +++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 6b3f3a3c0..64c6e1d67 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -3501,6 +3501,14 @@
      +

      Note that a telemetry packet group specifier is not required. +If there is no specifier, then the topology has no packet definitions. +Note also that two or more telemetry packet group specifiers +are allowed. +Each one specifies a way of assigning the telemetry channels +of the topology to packets.

      +
      Automatic Numbering of Ports
      @@ -10882,7 +10890,7 @@

      22.4. Translation Tools

      diff --git a/docs/spec/Definitions/Topology-Definitions.adoc b/docs/spec/Definitions/Topology-Definitions.adoc index 338e1e10a..d29d3dcb9 100644 --- a/docs/spec/Definitions/Topology-Definitions.adoc +++ b/docs/spec/Definitions/Topology-Definitions.adoc @@ -126,6 +126,13 @@ the same name. . Check that each telemetry packet group specifier is <>. +Note that a telemetry packet group specifier is not required. +If there is no specifier, then the topology has no packet definitions. +Note also that two or more telemetry packet group specifiers +are allowed. +Each one specifies a way of assigning the telemetry channels +of the topology to packets. + ===== Automatic Numbering of Ports FPP automatically assigns port numbers as follows. From d28c406899b689952cad6bacde1c74b7b0c8dbca Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Thu, 16 Jan 2025 17:01:18 -0800 Subject: [PATCH 08/11] Revise fpp spec --- docs/fpp-spec.html | 75 +++++++++++++------ docs/fpp-users-guide.html | 2 +- .../Telemetry-Packet-Group-Specifiers.adoc | 34 ++++++--- .../Telemetry-Packet-Specifiers.adoc | 24 ++++-- 4 files changed, 92 insertions(+), 43 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 64c6e1d67..194d7b60c 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -7145,21 +7145,31 @@

      7.16.1. Syntax

      telemetry packets identifier -{ telemetry-packet-specifier-sequence } +{ telemetry-packet-group-member-sequence } [ omit -{ telemetry-channel-specifier-sequence } +{ telemetry-channel-identifier-sequence } ]

      -

      telemetry-packet-specifier-sequence is an +

      telemetry-packet-group-member-sequence is an element sequence in -which each element is a telemetry -packet specifier, -and the terminating punctuation is a comma.

      +which each element is a telemetry packet group member, +and the terminating punctuation is a comma. +A telemetry packet group member is one of the following:

      +
      +
      +
      -

      telemetry-channel-sequence is an +

      telemetry-channel-identifier-sequence is an element sequence in which each element is a telemetry channel identifier, @@ -7168,14 +7178,20 @@

      7.16.1. Syntax

      7.16.2. Semantics

      +
      +

      FPP resolves any include specifiers in telemetry-packet-specifier-sequence, +generating a list L of telemetry packet specifiers, +each of which is a list of telemetry channel identifiers. +It then checks the following:

      +
      1. -

        Each telemetry packet specifier in telemetry-packet-specifier-sequence must +

        Each telemetry packet specifier in L must be valid,

      2. -

        Each telemetry packet specifier in telemetry-packet-specifier-sequence must +

        Each telemetry packet specifier in L must must have a distinct name and a distinct identifier.

      3. @@ -7188,12 +7204,11 @@

        7.16.2. Semantic
        1. -

          T appears in at least one of the packets of -telemetry-packet-specifier-sequence.

          +

          T appears in at least one of the telemetry packet specifiers of L.

        2. -

          telemetry-channel-sequence is present, and T appears in -telemetry-channel-sequence.

          +

          telemetry-channel-identifier-sequence is present, and T appears in +telemetry-channel-identifier-sequence.

        @@ -7218,6 +7233,8 @@

        7.16.3. Example @@ -7244,14 +7261,24 @@

        7.17.1. Syntax

        id expression ] level expression -{ telemetry-channel-sequence }

        +{ telemetry-packet-member-sequence }

      -

      telemetry-channel-sequence is an +

      telemetry-packet-member-sequence is an element sequence in -which each element is a -telemetry channel identifier, -and the terminating punctuation is a comma.

      +which each element is a telemetry packet member, +and the terminating punctuation is a comma. +A telemetry packet member is one of the following:

      +
      +
      +
      @@ -7281,8 +7308,11 @@

      7.17.2. Semantics

      to a nonnegative integer.

    4. -

      For each telemetry channel identifier I in telemetry-channel-sequence, -the component instance referred to in I must be +

      FPP resolves any include specifiers in telemetry-packet-member-sequence to a +list L +of telemetry channel identifiers. +It then checks that for each telemetry channel identifier I in L, +the component instance referred to in I is available in the enclosing topology, either through direct specification or through @@ -7299,7 +7329,8 @@

      7.17.3. Examples

      packet CDH id 0 level 0 { commandDispatcher.commandsDispatched rateGroup1Hz.rgMaxTime - fileUplink.filesReceived + include "DownlinkTelemetryChannels.fppi" + include "UplinkTelemetryChannels.fppi" } # Implicit id of ADCS packet is 1. Its level is 2. @@ -10890,7 +10921,7 @@

      22.4. Translation Tools

      diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index e9edf6138..eb419357b 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -14817,7 +14817,7 @@

      -Last updated 2024-12-11 16:51:28 -0800 +Last updated 2025-01-16 15:54:49 -0800
      diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index 4ad721e58..1c469b2f4 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -9,19 +9,23 @@ A telemetry packet group specifier is part of a `telemetry` `packets` <> -`{` _telemetry-packet-specifier-sequence_ `}` +`{` _telemetry-packet-group-member-sequence_ `}` _[_ `omit` -`{` _telemetry-channel-specifier-sequence_ `}` +`{` _telemetry-channel-identifier-sequence_ `}` _]_ -_telemetry-packet-specifier-sequence_ is an +_telemetry-packet-group-member-sequence_ is an <> in -which each element is a <>, +which each element is a *telemetry packet group member*, and the terminating punctuation is a comma. +A telemetry packet group member is one of the following: -_telemetry-channel-sequence_ is an +* An <> + +* A <> + +_telemetry-channel-identifier-sequence_ is an <> in which each element is a <>, -. Each telemetry packet specifier in _telemetry-packet-specifier-sequence_ must +. Each telemetry packet specifier in _L_ must must have a distinct name and a distinct identifier. . For every component instance _I_ available in the enclosing topology, either through @@ -43,11 +52,10 @@ or through for every telemetry channel _T_ that is a member of _I_, exactly one of the following must be true: -.. _T_ appears in at least one of the packets of -_telemetry-packet-specifier-sequence_. +.. _T_ appears in at least one of the telemetry packet specifiers of _L_. -.. _telemetry-channel-sequence_ is present, and _T_ appears in -_telemetry-channel-sequence_. +.. _telemetry-channel-identifier-sequence_ is present, and _T_ appears in +_telemetry-channel-identifier-sequence_. ==== Example @@ -66,6 +74,8 @@ packets Packets { adcs.attitude } + include "PowerTelemetryPackets.fppi" + } omit { adcs.extraTelemetry } diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index ec37df4d1..670f9011c 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -15,14 +15,18 @@ _[_ `id` <> _]_ `level` <> -`{` _telemetry-channel-sequence_ `}` +`{` _telemetry-packet-member-sequence_ `}` -_telemetry-channel-sequence_ is an +_telemetry-packet-member-sequence_ is an <> in -which each element is a -<>, +which each element is a *telemetry packet member*, and the terminating punctuation is a comma. +A telemetry packet member is one of the following: + +* An <> + +* A <> ==== Semantics @@ -46,8 +50,11 @@ The type of _e_ must be <>, and _e_ must evaluate to a nonnegative integer. -. For each telemetry channel identifier _I_ in _telemetry-channel-sequence_, -the component instance referred to in _I_ must be +. FPP resolves any include specifiers in _telemetry-packet-member-sequence_ to a +list _L_ +of telemetry channel identifiers. +It then checks that for each telemetry channel identifier _I_ in _L_, +the component instance referred to in _I_ is available in the enclosing topology, either through <> or through @@ -61,7 +68,8 @@ or through packet CDH id 0 level 0 { commandDispatcher.commandsDispatched rateGroup1Hz.rgMaxTime - fileUplink.filesReceived + include "DownlinkTelemetryChannels.fppi" + include "UplinkTelemetryChannels.fppi" } # Implicit id of ADCS packet is 1. Its level is 2. From f47bf7c15c16d59c71bc3e6d8e0ac9eb61413618 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Thu, 16 Jan 2025 17:13:50 -0800 Subject: [PATCH 09/11] Revise spec --- docs/fpp-spec.html | 22 ++++++++++++------- .../Telemetry-Packet-Group-Specifiers.adoc | 8 ++++--- .../Telemetry-Packet-Specifiers.adoc | 11 ++++++---- 3 files changed, 26 insertions(+), 15 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 194d7b60c..9b9ee78c1 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -7179,10 +7179,12 @@

      7.16.1. Syntax

      7.16.2. Semantics

      -

      FPP resolves any include specifiers in telemetry-packet-specifier-sequence, -generating a list L of telemetry packet specifiers, +

      FPP recursively resolves any include specifiers in +telemetry-packet-group-member-sequence. +This action converts telemetry-packet-group-member-sequence to a +list L of telemetry packet specifiers, each of which is a list of telemetry channel identifiers. -It then checks the following:

      +FPP then checks the following:

        @@ -7283,6 +7285,13 @@

        7.17.1. Syntax

      7.17.2. Semantics

      +
      +

      FPP recursively resolves any include specifiers in +telemetry-packet-member-sequence. +This action converts telemetry-packet-member-sequence to a list L of +telemetry channel identifiers. +FPP then checks the following:

      +
      1. @@ -7308,10 +7317,7 @@

        7.17.2. Semantics

        to a nonnegative integer.

      2. -

        FPP resolves any include specifiers in telemetry-packet-member-sequence to a -list L -of telemetry channel identifiers. -It then checks that for each telemetry channel identifier I in L, +

        For each telemetry channel identifier I in L, the component instance referred to in I is available in the enclosing topology, either through direct specification @@ -10921,7 +10927,7 @@

        22.4. Translation Tools

      diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index 1c469b2f4..d98f0abcb 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -34,10 +34,12 @@ and the terminating punctuation is a comma. ==== Semantics -FPP resolves any include specifiers in _telemetry-packet-specifier-sequence_, -generating a list _L_ of telemetry packet specifiers, +FPP recursively resolves any include specifiers in +_telemetry-packet-group-member-sequence_. +This action converts _telemetry-packet-group-member-sequence_ to a +list _L_ of telemetry packet specifiers, each of which is a list of telemetry channel identifiers. -It then checks the following: +FPP then checks the following: . Each telemetry packet specifier in _L_ must be <>, diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index 670f9011c..9633d37fb 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -30,6 +30,12 @@ telemetry channel identifier>> ==== Semantics +FPP recursively resolves any include specifiers in +_telemetry-packet-member-sequence_. +This action converts _telemetry-packet-member-sequence_ to a list _L_ of +telemetry channel identifiers. +FPP then checks the following: + . The optional expression _e_ following `id` specifies the numeric identifier for the packet. If _e_ is present, then the type of _e_ must be @@ -50,10 +56,7 @@ The type of _e_ must be <>, and _e_ must evaluate to a nonnegative integer. -. FPP resolves any include specifiers in _telemetry-packet-member-sequence_ to a -list _L_ -of telemetry channel identifiers. -It then checks that for each telemetry channel identifier _I_ in _L_, +. For each telemetry channel identifier _I_ in _L_, the component instance referred to in _I_ is available in the enclosing topology, either through <> From 96841d573d7dded9fc51ab6099737b60b1b6d0ef Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Thu, 16 Jan 2025 17:27:19 -0800 Subject: [PATCH 10/11] Revise spec --- docs/fpp-spec.html | 27 +++++++++---------- .../Telemetry-Packet-Group-Specifiers.adoc | 10 +++---- .../Telemetry-Packet-Specifiers.adoc | 14 +++++----- 3 files changed, 23 insertions(+), 28 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 9b9ee78c1..50480bba6 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -7189,12 +7189,12 @@

      7.16.2. Semantic
      1. -

        Each telemetry packet specifier in L must -be valid,

        +

        Each telemetry packet specifier in L is +valid,

      2. -

        Each telemetry packet specifier in L must -must have a distinct name and a distinct identifier.

        +

        Each telemetry packet specifier in L has +a distinct name and a distinct identifier.

      3. For every component instance I available in the enclosing topology, either through @@ -7202,7 +7202,7 @@

        7.16.2. Semantic or through import, for every telemetry channel T that is a member of I, -exactly one of the following must be true:

        +exactly one of the following is true:

        1. @@ -7285,13 +7285,6 @@

          7.17.1. Syntax

        7.17.2. Semantics

        -
        -

        FPP recursively resolves any include specifiers in -telemetry-packet-member-sequence. -This action converts telemetry-packet-member-sequence to a list L of -telemetry channel identifiers. -FPP then checks the following:

        -
        1. @@ -7317,8 +7310,12 @@

          7.17.2. Semantics

          to a nonnegative integer.

        2. -

          For each telemetry channel identifier I in L, -the component instance referred to in I is +

          FPP recursively resolves any include specifiers in +telemetry-packet-member-sequence. +This action converts telemetry-packet-member-sequence to a list L of +telemetry channel identifiers. +For each telemetry channel identifier I in L, +the component instance referred to in I must be available in the enclosing topology, either through direct specification or through @@ -10927,7 +10924,7 @@

          22.4. Translation Tools

        diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index d98f0abcb..6ed77e41a 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -41,18 +41,18 @@ list _L_ of telemetry packet specifiers, each of which is a list of telemetry channel identifiers. FPP then checks the following: -. Each telemetry packet specifier in _L_ must -be <>, +. Each telemetry packet specifier in _L_ is +<>, -. Each telemetry packet specifier in _L_ must -must have a distinct name and a distinct identifier. +. Each telemetry packet specifier in _L_ has +a distinct name and a distinct identifier. . For every component instance _I_ available in the enclosing topology, either through <> or through <>, for every telemetry channel _T_ that is a member of _I_, -exactly one of the following must be true: +exactly one of the following is true: .. _T_ appears in at least one of the telemetry packet specifiers of _L_. diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index 9633d37fb..50e36d5b1 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -30,12 +30,6 @@ telemetry channel identifier>> ==== Semantics -FPP recursively resolves any include specifiers in -_telemetry-packet-member-sequence_. -This action converts _telemetry-packet-member-sequence_ to a list _L_ of -telemetry channel identifiers. -FPP then checks the following: - . The optional expression _e_ following `id` specifies the numeric identifier for the packet. If _e_ is present, then the type of _e_ must be @@ -56,8 +50,12 @@ The type of _e_ must be <>, and _e_ must evaluate to a nonnegative integer. -. For each telemetry channel identifier _I_ in _L_, -the component instance referred to in _I_ is +. FPP recursively resolves any include specifiers in +_telemetry-packet-member-sequence_. +This action converts _telemetry-packet-member-sequence_ to a list _L_ of +telemetry channel identifiers. +For each telemetry channel identifier _I_ in _L_, +the component instance referred to in _I_ must be available in the enclosing topology, either through <> or through From 5e7f91fa52853a17c69bdc81c30b84f5313f8b4d Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 21 Jan 2025 09:54:58 -0800 Subject: [PATCH 11/11] Update fpp spec --- docs/fpp-spec.html | 29 ++++++++++++------- docs/fpp-users-guide.html | 2 +- docs/index.html | 2 +- ...Component-Instance-Member-Identifiers.adoc | 9 +++--- .../Telemetry-Packet-Group-Specifiers.adoc | 4 +-- .../Telemetry-Packet-Specifiers.adoc | 21 +++++++++----- 6 files changed, 40 insertions(+), 27 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 50480bba6..4d835ec63 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -7161,10 +7161,10 @@

        7.16.1. Syntax

        @@ -7275,13 +7275,19 @@

        7.17.1. Syntax

        +
        +

        A non-annotatable-include-specifier is identical to an +include specifier, +but it is not an +annotatable element.

        +

        7.17.2. Semantics

        @@ -7328,7 +7334,7 @@

        7.17.2. Semantics

        7.17.3. Examples

        -
        # CDH packet has id 0 and level 0
+
        @ CDH packet has id 0 and level 0
 packet CDH id 0 level 0 {
   commandDispatcher.commandsDispatched
   rateGroup1Hz.rgMaxTime
@@ -7336,7 +7342,7 @@ 
        7.17.3. Examples
        
   include "UplinkTelemetryChannels.fppi"
 }
 
-# Implicit id of ADCS packet is 1. Its level is 2.
+@ Implicit id of ADCS packet is 1. Its level is 2.
 packet ADCS level 2 {
   adcs.mode
   adcs.attitude
@@ -7608,10 +7614,11 @@ 
        
 
        8.2. Telemetry Channel Identifiers
        
 
        
-
        A telemetry channel identifier identifies a telemetry channel
-that is part of a component instance.
-Telemetry channel identifiers appear in
-telemetry packet specifiers.
        
+
        A telemetry channel identifier identifies a telemetry channel that is part of
+a component instance.  Telemetry channel identifiers appear in
+telemetry packet group
+specifiers and telemetry packet
+specifiers.
        
 
        
 
        
 
        8.2.1. Syntax
        
@@ -10924,7 +10931,7 @@ 
        22.4. Translation Tools
        
 
        
 
 
diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html
index eb419357b..f194bfd61 100644
--- a/docs/fpp-users-guide.html
+++ b/docs/fpp-users-guide.html
@@ -14817,7 +14817,7 @@ 
        
 
        
-Last updated 2025-01-16 15:54:49 -0800
+Last updated 2025-01-21 09:54:50 -0800
        diff --git a/docs/index.html b/docs/index.html index 07e30b8d1..9bd7e4b03 100644 --- a/docs/index.html +++ b/docs/index.html @@ -463,7 +463,7 @@

        F Prime Prime (FPP)

        diff --git a/docs/spec/Component-Instance-Member-Identifiers.adoc b/docs/spec/Component-Instance-Member-Identifiers.adoc index 4e7906969..18c61d36d 100644 --- a/docs/spec/Component-Instance-Member-Identifiers.adoc +++ b/docs/spec/Component-Instance-Member-Identifiers.adoc @@ -50,10 +50,11 @@ port instance. === Telemetry Channel Identifiers -A *telemetry channel identifier* identifies a telemetry channel -that is part of a component instance. -Telemetry channel identifiers appear in -<>. +A *telemetry channel identifier* identifies a telemetry channel that is part of +a component instance. Telemetry channel identifiers appear in +<> and <>. ==== Syntax diff --git a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc index 6ed77e41a..6bb2e1e2b 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Group-Specifiers.adoc @@ -21,9 +21,9 @@ which each element is a *telemetry packet group member*, and the terminating punctuation is a comma. A telemetry packet group member is one of the following: -* An <> +* An <>. -* A <> +* A <>. _telemetry-channel-identifier-sequence_ is an <> in diff --git a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc index 50e36d5b1..2c99392db 100644 --- a/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc +++ b/docs/spec/Specifiers/Telemetry-Packet-Specifiers.adoc @@ -3,7 +3,7 @@ A *telemetry packet specifier* specifies the format of a data packet containing telemetry points. A telemetry packet specifier is part of a -<>, which is in turn part of a <>. @@ -23,10 +23,15 @@ which each element is a *telemetry packet member*, and the terminating punctuation is a comma. A telemetry packet member is one of the following: -* An <> +* _non-annotatable-include-specifier_. -* A <> +* _<>_. + +A _non-annotatable-include-specifier_ is identical to an +<>, +but it is not an +<>. ==== Semantics @@ -50,9 +55,9 @@ The type of _e_ must be <>, and _e_ must evaluate to a nonnegative integer. -. FPP recursively resolves any include specifiers in +. FPP recursively resolves any include specifiers in _telemetry-packet-member-sequence_. -This action converts _telemetry-packet-member-sequence_ to a list _L_ of +This action converts _telemetry-packet-member-sequence_ to a list _L_ of telemetry channel identifiers. For each telemetry channel identifier _I_ in _L_, the component instance referred to in _I_ must be @@ -65,7 +70,7 @@ or through [source,fpp] ---- -# CDH packet has id 0 and level 0 +@ CDH packet has id 0 and level 0 packet CDH id 0 level 0 { commandDispatcher.commandsDispatched rateGroup1Hz.rgMaxTime @@ -73,7 +78,7 @@ packet CDH id 0 level 0 { include "UplinkTelemetryChannels.fppi" } -# Implicit id of ADCS packet is 1. Its level is 2. +@ Implicit id of ADCS packet is 1. Its level is 2. packet ADCS level 2 { adcs.mode adcs.attitude