From f55332c6f9cce51ae8275c46b81d66c576ec8020 Mon Sep 17 00:00:00 2001 From: John-P-Cargille <116765885+John-P-Cargille@users.noreply.github.com> Date: Fri, 14 Jul 2023 11:51:06 -0500 Subject: [PATCH 1/9] Update cmd-evt-chn-prm.md Changed "pipes" to "ports" early in the Commands section, because I've never heard pipes used as a term in F Prime and ports make sense in the context of component-to-component communication. --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 1342beed20..c5b241e43b 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -23,7 +23,7 @@ These types will be elaborated within this guide. It contains: ## Commands -Each **Component** defines a set of commands for operations. Unlike pipes, which are intended for component to component communication, commands are designed for user interaction with a component. Commands are defined through a series of +Each **Component** defines a set of commands for operations. Unlike ports, which are intended for component to component communication, commands are designed for user interaction with a component. Commands are defined through a series of properties. Users can send commands to the F´ system and via `Svc::CmdDispatcher` these commands are dispatched to a handling component to invoke some behavior. The handling component handles a command by defining a command handler function to run when the command arrives. @@ -176,4 +176,4 @@ command. ## A Note On Serialized Ports The `Svc` components use serialize ports to generically handle port data of different types to support uplink and -downlink. \ No newline at end of file +downlink. From 0c74c535a74b127199cf63a8710a78e888f9b054 Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Wed, 19 Jul 2023 15:00:10 -0500 Subject: [PATCH 2/9] Update cmd-evt-chn-prm.md Changed the last line two lines of "Command Dispatching" to more clearly reflect the operational flow described in the next section, "Command Sequencing" --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index c5b241e43b..87a900f8b7 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -56,10 +56,10 @@ the command dispatcher connecting the registration, dispatch, and response ports The command opcode is extracted, and a lookup table is used to find the handling component. The argument buffer is then passed to the component, and the command dispatcher waits without blocking for the component to return status.. -In many projects, commands need to be sequenced in order. In order to facilitate this, the framework provides -`Svc::CmdSequencer`. The command sequencer reads a defined sequence of commands and sends each in turn to the command -dispatcher to be dispatched and the command execution status is returned to the sequencer. This is an alternate path to -send command buffers to the command dispatcher than the external path from ground. +In many projects, commands need to be sequenced in order. In order to facilitate this, the framework provides +`Svc::CmdSequencer`. The command sequencer reads a defined sequence of commands and sends each in turn to the command +dispatcher; after each command is dispatched, the status of its execution is returned to the sequencer. Sending command buffers +to the command dispatcher through the command sequencer is an alternate path to sending them externally from the ground. ### Command Sequencing From 1c4e892b0e8af42795169f8154c05b78ec7151ec Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Wed, 19 Jul 2023 15:21:43 -0500 Subject: [PATCH 3/9] Update cmd-evt-chn-prm.md Changed the 3rd sentence under "Events" to say that components defining events, rather than commands, should hook up to the Svc::ActiveLogger. This should maybe actually say "defining events AND commands"--I forget if the system always sends out an event for a completed command--but the log ports are definitely required for events --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 87a900f8b7..57998f6674 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -73,7 +73,7 @@ while a successful response moves to the next command in the sequence. Events represent a log of activities taken by the embedded system. Events can be thought of in the same way as a program execution log in that they enable the ability to trace the execution of the system. Events are sent out of the system via the -`Svc::ActiveLogger` component and components defining commands should hook up the log port to it. If console logging is +`Svc::ActiveLogger` component and components defining events should hook up the log port to it. If console logging is desired, the text log port can be hooked up to the `Svc::PassiveConsoleTextLogger` component. Events are defined per component and are typically used to capture what the component is doing. Events can be sporadic; however, should all be captured for downlink. Events are defined by the following properties: From bb4560cf59f5fe3fb076f4a9e2179437f55c249e Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Thu, 20 Jul 2023 09:27:43 -0500 Subject: [PATCH 4/9] Update cmd-evt-chn-prm.md Changed the sixth sentence under the events header to be more parsable; this may also mean the sentence now communicates incorrect information, but it should definitely should looked at because it doesn't quite make sense right now --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 57998f6674..0da1a8368a 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -72,11 +72,11 @@ while a successful response moves to the next command in the sequence. ## Events Events represent a log of activities taken by the embedded system. Events can be thought of in the same way as a program -execution log in that they enable the ability to trace the execution of the system. Events are sent out of the system via the -`Svc::ActiveLogger` component and components defining events should hook up the log port to it. If console logging is +execution log in that they enable the ability to trace the execution of the system. Events are sent out of the system via +the `Svc::ActiveLogger` component and components defining events should hook up the log port to it. If console logging is desired, the text log port can be hooked up to the `Svc::PassiveConsoleTextLogger` component. Events are defined per -component and are typically used to capture what the component is doing. Events can be sporadic; however, should all be -captured for downlink. Events are defined by the following properties: +component and are typically used to capture what the component is doing. Events can occur sporadically; however, they +should all be captured for downlink. Events are defined by the following properties: 1. id: a numeric id uniquely define this event. It is automatically offset by the component's base id to ensure global uniqueness. From 00cc32e8e6743bdc8932c2e926a2fe95f2136625 Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Thu, 20 Jul 2023 10:03:49 -0500 Subject: [PATCH 5/9] Update cmd-evt-chn-prm.md Changed the last lines under the "Event" to more accurately reflect where the different log output ports store their event logs, assuming that these binary and text log ports line up with the "Fw.Log" and "Fw.TextLog" ports respectively as described in the FPP User's Guide in section 9.3.2 --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 0da1a8368a..6b21cc45a7 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -100,8 +100,8 @@ component. This function expects an argument to be supplied for each argument de automatically adds ports for retrieving a time tag and sending events. There are two independent ports for sending events: -1. binary log output port for sending outside the system -2. a text log output port for on-board consoles +1. binary log output port for on-board consoles +2. a text log output port for sending outside the system ### Event Logging From ffb34563b23166e7b6e7961ce9729a5a3f6f5a1b Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Thu, 20 Jul 2023 10:49:25 -0500 Subject: [PATCH 6/9] Update cmd-evt-chn-prm.md Updated the second property under the header "Telemetry" to say that the name is prepended with the name of the component instance, and not just the component. This is both consistent with the other data constructs on this page, with how telemetry is usually packetized--"channel name="[componentInstance].[TELEMETRY_CHANNEL]""--and how telemetry coming from two different instances of the same component should intuitively be distinguishable. --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 6b21cc45a7..037100fa97 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -123,7 +123,7 @@ current value. Channels are broken up per component and are typically sampled at id, time, and value triples and are defined per component with the following properties: 1. id: the unique id of the channel. This is offset by the base id of the component for global uniqueness. -2. name: the unique text name of the channel. This is prepended with the component name for global uniqueness. +2. name: the unique text name of the channel. This is prepended with the component instance name for global uniqueness. 3. data_type: type of the value of the channel. Can be primitive and complex types. 4. update: "on_change" to update only when the written value changes, and omitted to always downlink From 83da4e508e0923a14ff327b38341cfb202319017 Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Thu, 20 Jul 2023 10:53:31 -0500 Subject: [PATCH 7/9] Update cmd-evt-chn-prm.md Changed the second sentence under the "Telemetry Database" header for grammatical and semantic clarity. --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 037100fa97..595c1d496e 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -134,7 +134,7 @@ The code generator automatically adds ports for retrieving time tags and sending ### Telemetry Database The telemetry database acts as a double-buffered store for telemetry values. Components are free to update channels at -any time, however; at a set rate the current value will be read from the telemetry database and sent to the ground. +any time; however, the current value will be read from the telemetry database and sent to the ground at a set rate. Components using this service should hook up the telemetry port to the telemetry database (`Svc::TlmChan`). ![Telemetry Database](../media/data_model4.png) From 6bbde336159a25b6896f17e1f7ef7b5a0d02e4c1 Mon Sep 17 00:00:00 2001 From: "John P. Cargille" <116765885+John-P-Cargille@users.noreply.github.com> Date: Thu, 20 Jul 2023 11:19:16 -0500 Subject: [PATCH 8/9] Update cmd-evt-chn-prm.md Changed the last sentence in the figure 8 description to reflect how the parameter manager changes parameter values through the auto-generated set and save commands; my details might be a little fuzzy, so feel free to correct the specifics, but I think this section deserves a little more fleshing out. I'm also unsure of if the line before this should be expanded upon? Simply saying "Components can set and retrieve parameters" might appear rather opaque to folks who are newer to F' (like myself), even with the context of the Svc::PrmDb which one can look into further in the official F Prime repository. --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 595c1d496e..9467c38d6a 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -170,7 +170,9 @@ provides ports to get and set parameters, which are stored in a file to persist **Figure 8. Parameter manager.** The parameter manager or database loads the file containing parameters from the file system during initialization. The initialization subsequently calls *loadParameters()* on components with parameters. Components can set and retrieve parameters. The parameter manager saves the updated values to the file system via the -command. +set and save commands auto-generated for every parameter; the set command updates the value of the parameter locally +within the component that owns it, and the save command pushing the current value of the parameter to non-volatile storage, +meaning it will persist within the files of the system across system resets. ## A Note On Serialized Ports From 4ace4167bfc011bf7c3d93c7096201578bfedce8 Mon Sep 17 00:00:00 2001 From: M Starch Date: Tue, 1 Aug 2023 08:44:47 -0700 Subject: [PATCH 9/9] Fixing minor regression --- docs/UsersGuide/user/cmd-evt-chn-prm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UsersGuide/user/cmd-evt-chn-prm.md b/docs/UsersGuide/user/cmd-evt-chn-prm.md index 9467c38d6a..b11c53472b 100644 --- a/docs/UsersGuide/user/cmd-evt-chn-prm.md +++ b/docs/UsersGuide/user/cmd-evt-chn-prm.md @@ -100,8 +100,8 @@ component. This function expects an argument to be supplied for each argument de automatically adds ports for retrieving a time tag and sending events. There are two independent ports for sending events: -1. binary log output port for on-board consoles -2. a text log output port for sending outside the system +1. binary log output port for sending outside the system +2. a text log output port for on-board consoles ### Event Logging