From 8b3f0bc835c654d5d65ab583f2500ca90454f6c4 Mon Sep 17 00:00:00 2001 From: Andrei Tumbar Date: Tue, 21 Oct 2025 13:50:21 -0700 Subject: [PATCH 1/2] Time limited event throttling users guide --- docs/fpp-spec.html | 2 +- docs/fpp-users-guide.html | 65 +++++++++++++++++++++-- docs/users-guide/Defining-Components.adoc | 60 +++++++++++++++++++-- 3 files changed, 117 insertions(+), 10 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index a794e9951..7101bd891 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -11892,7 +11892,7 @@ equivalent.

diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 11ec7c84d..10d13b19a 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -7633,14 +7633,69 @@ passive component EventThrottling {
-

In this example, event E will be throttled after the component +

In this example, event Event1 will be throttled after the component instance has emitted it ten times.

Once an event is throttled, the component instance will no longer -emit the event until the throttling is canceled. -Typically, the canceling happens via a FSW command. -For details, see the +emit the event until the throttling is canceled. Throttle cancellation +can happen after a specified time interval or via a FSW command.

+
+
+

A throttle timeout can be specified using the every keyword and a time interval +after the throttle clause. +Here is an example:

+
+
+
+
@ Component for illustrating event throttling with timeouts
+passive component EventThrottlingWithTimeout {
+
+  # ----------------------------------------------------------------------
+  # Ports
+  # ----------------------------------------------------------------------
+
+  @ Event port
+  event port eventOut
+
+  @ Text event port
+  text event port textEventOut
+
+  @ Time get port
+  time get port timeGetOut
+
+  # ----------------------------------------------------------------------
+  # Events
+  # ----------------------------------------------------------------------
+
+  @ Event 1
+  event Event1 severity warning high \
+    format "Event 1 occurred" \
+    throttle 10 \
+    every {seconds=2}
+
+  @ Event 2
+  event Event2 severity warning high \
+    format "Event 2 occurred" \
+    throttle 10 \
+    every {seconds=2, useconds=500000}
+
+  @ Event 3
+  event Event3 severity warning high \
+    format "Event 3 occurred" \
+    throttle 10 \
+    every {useconds=500000}
+
+}
+
+
+
+

In this example Event1 will emit up to 10 events every 2 seconds, Event2 +will emit up to 10 events every 2.5 seconds and Event3 up to 10 every 0.5 seconds.

+
+
+

If a throttle timeout is not specified via the every clause, the component will not +emit the event until the throttle is cleared through FSW command. For details, see the F Prime User Manual.

@@ -15789,7 +15844,7 @@ serialized according to its diff --git a/docs/users-guide/Defining-Components.adoc b/docs/users-guide/Defining-Components.adoc index 4a0050361..0437786f8 100644 --- a/docs/users-guide/Defining-Components.adoc +++ b/docs/users-guide/Defining-Components.adoc @@ -1541,13 +1541,65 @@ passive component EventThrottling { } ---- -In this example, event `E` will be throttled after the component +In this example, event `Event1` will be throttled after the component instance has emitted it ten times. Once an event is throttled, the component instance will no longer -emit the event until the throttling is canceled. -Typically, the canceling happens via a FSW command. -For details, see the +emit the event until the throttling is canceled. Throttle cancellation +can happen after a specified time interval or via a FSW command. + +A throttle timeout can be specified using the `every` keyword and a time interval +after the throttle clause. +Here is an example: + +[source,fpp] +---- +@ Component for illustrating event throttling with timeouts +passive component EventThrottlingWithTimeout { + + # ---------------------------------------------------------------------- + # Ports + # ---------------------------------------------------------------------- + + @ Event port + event port eventOut + + @ Text event port + text event port textEventOut + + @ Time get port + time get port timeGetOut + + # ---------------------------------------------------------------------- + # Events + # ---------------------------------------------------------------------- + + @ Event 1 + event Event1 severity warning high \ + format "Event 1 occurred" \ + throttle 10 \ + every {seconds=2} + + @ Event 2 + event Event2 severity warning high \ + format "Event 2 occurred" \ + throttle 10 \ + every {seconds=2, useconds=500000} + + @ Event 3 + event Event3 severity warning high \ + format "Event 3 occurred" \ + throttle 10 \ + every {useconds=500000} + +} +---- + +In this example `Event1` will emit up to 10 events every 2 seconds, `Event2` +will emit up to 10 events every 2.5 seconds and `Event3` up to 10 every 0.5 seconds. + +If a throttle timeout is not specified via the `every` clause, the component will not +emit the event until the throttle is cleared through FSW command. For details, see the https://fprime.jpl.nasa.gov/devel/docs/user-manual/[F Prime User Manual]. === Telemetry From 0f82443039867faf8f8a80144dda99c32fadea7e Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 4 Nov 2025 14:38:55 -0800 Subject: [PATCH 2/2] Revise User's Guide --- docs/fpp-users-guide.html | 72 ++++++++++++++++------- docs/users-guide/Defining-Components.adoc | 58 ++++++++++++------ 2 files changed, 93 insertions(+), 37 deletions(-) diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 09febae9e..2a9fc4e65 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -7817,7 +7817,9 @@ or a few warnings.

To achieve this behavior, you can write the keyword throttle and a numeric expression after the format string. -The expression must evaluate to a constant value n. +The expression must evaluate to a constant value n, where n is a number +greater than zero. +n is called the maximum throttle count. After an instance of the component has emitted the event n times, it will stop emitting the event. Here is an example:

@@ -7857,14 +7859,39 @@ passive component EventThrottling { instance has emitted it ten times.

-

Once an event is throttled, the component instance will no longer -emit the event until the throttling is canceled. Throttle cancellation -can happen after a specified time interval or via a FSW command.

+

Once an event is throttled, the component +instance will no longer emit the event until the throttling is reset. +There are two ways to reset the throttling of an event: manually and +automatically.

-

A throttle timeout can be specified using the every keyword and a time interval -after the throttle clause. -Here is an example:

+

Manual reset: +To manually reset throttling for events, +you can use a command. +For example, you can define a command CLEAR_EVENT_THROTTLE +that resets throttling for all throttled events. +You can implement this command by calling functions +that reset the throttle counts to zero. +The auto-generated C++ code provides one such function for +each event with throttling. +For details, see the +F Prime User Manual.

+
+
+

Automatic reset: +You can also specify in FPP that the throttling for an event should be reset +automatically after a specified amount of time. +To do this, you write every and a time interval after the maximum throttle +count. +The time interval is a struct +value expression with two members: seconds and useconds. +useconds is short for “microseconds.” +Each member must evaluate to an integer value. +Either or both of the members can be omitted; an omitted member evaluates to +zero.

+
+
+

Here is an example:

@@ -7891,32 +7918,37 @@ passive component EventThrottlingWithTimeout { @ Event 1 event Event1 severity warning high \ format "Event 1 occurred" \ - throttle 10 \ - every {seconds=2} + throttle 10 every { seconds = 2 } @ Event 2 event Event2 severity warning high \ format "Event 2 occurred" \ - throttle 10 \ - every {seconds=2, useconds=500000} + throttle 10 every { seconds = 2, useconds = 500000 } @ Event 3 event Event3 severity warning high \ format "Event 3 occurred" \ - throttle 10 \ - every {useconds=500000} + throttle 10 every { useconds = 500000 } }
-

In this example Event1 will emit up to 10 events every 2 seconds, Event2 -will emit up to 10 events every 2.5 seconds and Event3 up to 10 every 0.5 seconds.

+

In this example, an instance of EventThrottlingWithTimeout will emit events +at the following rates:

-
-

If a throttle timeout is not specified via the every clause, the component will not -emit the event until the throttle is cleared through FSW command. For details, see the -F Prime User Manual.

+
+
    +
  • +

    Event1: Up to 10 events every 2 seconds.

    +
    • +
  • +

    Event2: Up to 10 events every 2.5 seconds.

    +
    • +
  • +

    Event3: Up to 10 events every 0.5 seconds.

    +
    • +
@@ -16188,7 +16220,7 @@ serialized according to its diff --git a/docs/users-guide/Defining-Components.adoc b/docs/users-guide/Defining-Components.adoc index b40714601..7c19e5761 100644 --- a/docs/users-guide/Defining-Components.adoc +++ b/docs/users-guide/Defining-Components.adoc @@ -1507,7 +1507,9 @@ or a few warnings. To achieve this behavior, you can write the keyword `throttle` and a numeric expression after the format string. -The expression must evaluate to a constant value _n_. +The expression must evaluate to a constant value _n_, where _n_ is a number +greater than zero. +_n_ is called the *maximum throttle count*. After an instance of the component has emitted the event _n_ times, it will stop emitting the event. Here is an example: @@ -1545,12 +1547,35 @@ passive component EventThrottling { In this example, event `Event1` will be throttled after the component instance has emitted it ten times. -Once an event is throttled, the component instance will no longer -emit the event until the throttling is canceled. Throttle cancellation -can happen after a specified time interval or via a FSW command. +Once an event is throttled, the component +instance will no longer emit the event until the throttling is reset. +There are two ways to reset the throttling of an event: manually and +automatically. + +*Manual reset:* +To manually reset throttling for events, +you can use a <>. +For example, you can define a command `CLEAR_EVENT_THROTTLE` +that resets throttling for all throttled events. +You can implement this command by calling functions +that reset the throttle counts to zero. +The auto-generated {cpp} code provides one such function for +each event with throttling. +For details, see the +https://fprime.jpl.nasa.gov/devel/docs/user-manual/[F Prime User Manual]. + +*Automatic reset:* +You can also specify in FPP that the throttling for an event should be reset +automatically after a specified amount of time. +To do this, you write `every` and a time interval after the maximum throttle +count. +The time interval is a <> with two members: `seconds` and `useconds`. +`useconds` is short for "`microseconds.`" +Each member must evaluate to an integer value. +Either or both of the members can be omitted; an omitted member evaluates to +zero. -A throttle timeout can be specified using the `every` keyword and a time interval -after the throttle clause. Here is an example: [source,fpp] @@ -1578,30 +1603,29 @@ passive component EventThrottlingWithTimeout { @ Event 1 event Event1 severity warning high \ format "Event 1 occurred" \ - throttle 10 \ - every {seconds=2} + throttle 10 every { seconds = 2 } @ Event 2 event Event2 severity warning high \ format "Event 2 occurred" \ - throttle 10 \ - every {seconds=2, useconds=500000} + throttle 10 every { seconds = 2, useconds = 500000 } @ Event 3 event Event3 severity warning high \ format "Event 3 occurred" \ - throttle 10 \ - every {useconds=500000} + throttle 10 every { useconds = 500000 } } ---- -In this example `Event1` will emit up to 10 events every 2 seconds, `Event2` -will emit up to 10 events every 2.5 seconds and `Event3` up to 10 every 0.5 seconds. +In this example, an instance of `EventThrottlingWithTimeout` will emit events +at the following rates: -If a throttle timeout is not specified via the `every` clause, the component will not -emit the event until the throttle is cleared through FSW command. For details, see the -https://fprime.jpl.nasa.gov/devel/docs/user-manual/[F Prime User Manual]. +* `Event1`: Up to 10 events every 2 seconds. + +* `Event2`: Up to 10 events every 2.5 seconds. + +* `Event3`: Up to 10 events every 0.5 seconds. === Telemetry