From 0ba1eb0f53ac408a139113f9cc464ea84ed8b603 Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Thu, 4 Jun 2026 09:48:53 -0700 Subject: [PATCH 01/14] Add guide for importing parameters to GDS This document provides a comprehensive guide on how to import parameters into the GDS using the fprime-prm-write tool, detailing methods for generating .dat and .seq files, along with troubleshooting tips. --- docs/how-to/prm-write-howto.md | 267 +++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/how-to/prm-write-howto.md diff --git a/docs/how-to/prm-write-howto.md b/docs/how-to/prm-write-howto.md new file mode 100644 index 00000000000..7e3a98059d9 --- /dev/null +++ b/docs/how-to/prm-write-howto.md @@ -0,0 +1,267 @@ +# How-To: Import Parameters to the GDS + + +## Overview + +This guide assumes you are familiar with the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write tool` using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. + +This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. + +*Contents:* + +1. [Why Import Parameters?](#why-import-parameters) +2. [Creating a Parameters JSON File](#creating-a-parameters-json-file) +3. [Method 1: Generate a .dat File](#method-1-generate-a-dat-file) +4. [Method 2: Generate a .seq File](#method-2-generate-a-seq-file) +5. [Troubleshooting](#troubleshooting) + +## Why Import Parameters? + +The `fprime-prm-write` tool allows you to: +- Set initial parameter values for system startup +- Update multiple parameters at once without manual commanding +- Version-control parameter configurations alongside your code +- Share parameter sets between team members or mission phases + +## Creating a Parameters JSON File + +The `fprime-prm-write` tool accepts parameter values in JSON format. This format is human-readable and supports all F´ parameter types including primitives, enums, arrays, and structs. + +### JSON File Format + +The JSON should consist of a key-value map of component instance names to an inner key-value map. The inner key-value map should consist of parameter name-to-value map entries. In other words, the JSON file should have a **component name → parameter map** structure. + +Create a JSON file (e.g., `params.json`) anywhere in your project directory: + +**Generic Format:** +```json +{ + "ComponentInstance": { + "parameterName": value, + "anotherParameter": value + }, + "AnotherComponent": { + "paramName": value + } +} +``` + +### Example: Ref Project Parameters + + +**`params.json`:** +```json +{ + "Ref.recvBuffComp": { + "parameter1": 20, + "parameter2": -5 + }, + + "Ref.sendBuffComp": { + "parameter3": 25, + "parameter4": 99.99 + }, + "Ref.typeDemo": { + "CHOICE_PRM": "RED", + "CHOICES_PRM": ["ONE", "BLUE"], + "CHOICE_PAIR_PRM": { + "firstChoice": "RED", + "secondChoice": "BLUE" + } + } +} +``` + +> [!NOTE] +> Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). Parameter values support complex F´ types: +> - **Primitives**: Numbers (`20`, `99.99`), booleans, strings +> - **Enums**: String constants (e.g., `"RED"`, `"BLUE"`) +> - **Arrays**: JSON arrays (e.g., `["ONE", "BLUE"]`) +> - **Structs**: Nested objects with field names as keys (e.g., `{"firstChoice": "RED", "secondChoice": "BLUE"}`) + +> [!TIP] +> **Using the `--defaults` flag:** By default, the `fprime-prm-write` tool only includes parameters explicitly listed in your JSON file. If you add the `--defaults` flag, the tool will include all parameters that have default values defined in the dictionary. This effectively resets all parameters to their defaults, except for those you specify in the JSON file. This flag works for both `.dat` and `.seq` file generation. + +All steps from this point on either take place in the terminal or the GDS GUI. + +## Method 1: Generate a `.dat` File + +Use this method to load a binary parameter file into the `PrmDb` component at any time. + +### Step 1: Generate the `.dat` File + +Run the tool in the terminal: + +**General syntax:** +```bash +fprime-prm-write dat --dictionary +``` + +**Example: Ref project:** +```bash +fprime-prm-write dat params.json \ + --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json +``` + +This creates `params.dat` in the same directory as your JSON file. + +> [!NOTE] +> The output file is named based on your input JSON file. If your JSON file is named `my_params.json`, the output will be `my_params.dat`. + +### Step 2: Start the GDS + +**With GUI:** +```bash +fprime-gds +``` + +**Without GUI (Command Line):** +```bash +fprime-gds -g none --log-directly +``` + +### Step 3: Load the Parameter File + +**Using GUI:** +1. Launch the GDS using `fprime-gds` and open up the browser window +2. Navigate to the **Commanding** tab +3. Find and select `FileHandling.prmDb.PRM_LOAD_FILE` +4. Fill in the arguments: + - **fileName**: `"params.dat"` + - **mode**: `MERGE` (merge with existing) or `CLEAR` (replace all) +5. Send the command +6. Check the **Events** tab for `PrmFileLoadComplete` + +**Command Line:** +```bash +# Load the .dat file into staging area +fprime-cli commands send FileHandling.prmDb.PRM_LOAD_FILE "params.dat" MERGE +# Check events for success +fprime-cli events list | grep -E "PrmFileLoadComplete|PrmDbFileLoadFailed|PrmFileBadCrc" +``` + +**Expected events:** + +| Event | Status | Description | +|-------|--------|-------------| +| `PrmFileLoadComplete` | ✓ | File loaded successfully | +| `PrmDbFileLoadFailed` | ✗ | File not found | +| `PrmFileBadCrc` | ✗ | CRC checksum error | + +### Step 4: Commit the Staged Parameters + +After verifying the load succeeded, commit to make parameters active: + +**Using GUI:** + +Send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. + +**Command Line:** +```bash +# Commit staged parameters +fprime-cli commands send FileHandling.prmDb.PRM_COMMIT_STAGED +# Verify the commit operation succeeded +fprime-cli events list | grep "PrmDbCopyAllComplete" +``` + +### Step 5: Verify Parameter Changes + +**Recommended Method: Check telemetry for each parameter** + +Each parameter has a telemetry channel. Check the **Telemetry** tab in the GDS GUI or: + +```bash +fprime-cli telemetry list | grep +``` + +**Alternative Method: Downlink and decode PrmDb.dat** + +If your deployment has file downlink configured (using `Svc.FileDownlink`), you can verify by downloading and decoding the parameter database: + +1. Use your deployment's file downlink commands to retrieve `PrmDb.dat` from the FSW +```bash fileDownlink.FileDownlink_SendFile``` +2. Decode the downloaded file to a JSON file for human readability + + **General syntax:** Using the inverse `fprime-prm-decode` tool + ```bash + fprime-prm-decode PrmDb.dat \ + --dictionary build-fprime-automatic-//dict/TopologyDictionary.json \ + --format json \ + --output downlinked_params.json + ``` + +3. Compare with your input + ```bash + diff params.json downlinked_params.json + ``` + +## Method 2: Generate a `.seq` File + +Sometimes you need to update parameters while F´ is running without loading files. This can be accomplished with a sequence of _PRM_SET commands, which the `fprime-prm-write` tool can automatically create for you. This creates `.seq` which can be compiled and executed by `Svc::CmdSequencer`. + +> [!TIP] +> **Using the `--save` flag:** The generated `.seq` file contains `_PRM_SET` commands that update parameter values in memory. If you want the changes to persist across FSW restarts, add the `--save` flag to include `_PRM_SAVE` commands after each `_PRM_SET`, which writes the parameters to the PrmDb.dat file on the FSW. + +### Step 1: Generate the Sequence File + +**General syntax:** +```bash +fprime-prm-write seq --dictionary +``` + +**Example: Ref project:** +```bash +fprime-prm-write seq params.json \ + --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json +``` + +This creates `params.seq` in the same directory as your JSON file. + +### Step 2: Execute the Sequence + +1. Compile the sequence file to binary format: + ```bash + fprime-seqgen params.seq --dictionary build-fprime-automatic-//dict/TopologyDictionary.json + ``` + This creates `params.bin`. + +2. Load the sequence into `CmdSequencer`: + - **GUI**: Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name + - **Command Line**: + ```bash + fprime-cli commands send FileHandling.cmdSeq.CS_RUN "params.bin" RUN_NOW + ``` + +3. Verify the sequence executed successfully by checking events in the **Events** tab or command line + +For more details, follow the standard [F´ sequencing workflow](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html). + +## Troubleshooting + +### Error: `PrmFileBadCrc` + +**Cause:** CRC checksum mismatch. + +**Fix:** Regenerate with an up-to-date version of `fprime-prm-write`. + +### Error: `PrmDbFileLoadFailed` + +**Cause:** File not found. + +**Fix:** Verify file path and ensure it's accessible to the FSW. + +### Error: `RuntimeError: Unable to find param in dictionary` + +**Cause:** Parameter name doesn't match dictionary. + +**Fix:** +- Use fully qualified component names (e.g., `Ref.recvBuffComp`) +- Check parameter names are exact (case-sensitive) +- Verify dictionary path is correct + +## References + +1. [fprime-prm-write Tool README](https://github.com/nasa/fprime-gds/blob/devel/docs/prm-write-README.md) +2. [Svc::PrmDb Component SDD](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) +3. [Ref Deployment](https://github.com/nasa/fprime/tree/devel/Ref) +4. [F´ Command Sequencing Guide](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html) From 42967cf2adb68dae12e752f42437fcccb98bb828 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Thu, 4 Jun 2026 10:41:28 -0700 Subject: [PATCH 02/14] Changed file name for spell check --- docs/how-to/prm-write-how-to.md | 267 ++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/how-to/prm-write-how-to.md diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md new file mode 100644 index 00000000000..7e3a98059d9 --- /dev/null +++ b/docs/how-to/prm-write-how-to.md @@ -0,0 +1,267 @@ +# How-To: Import Parameters to the GDS + + +## Overview + +This guide assumes you are familiar with the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write tool` using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. + +This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. + +*Contents:* + +1. [Why Import Parameters?](#why-import-parameters) +2. [Creating a Parameters JSON File](#creating-a-parameters-json-file) +3. [Method 1: Generate a .dat File](#method-1-generate-a-dat-file) +4. [Method 2: Generate a .seq File](#method-2-generate-a-seq-file) +5. [Troubleshooting](#troubleshooting) + +## Why Import Parameters? + +The `fprime-prm-write` tool allows you to: +- Set initial parameter values for system startup +- Update multiple parameters at once without manual commanding +- Version-control parameter configurations alongside your code +- Share parameter sets between team members or mission phases + +## Creating a Parameters JSON File + +The `fprime-prm-write` tool accepts parameter values in JSON format. This format is human-readable and supports all F´ parameter types including primitives, enums, arrays, and structs. + +### JSON File Format + +The JSON should consist of a key-value map of component instance names to an inner key-value map. The inner key-value map should consist of parameter name-to-value map entries. In other words, the JSON file should have a **component name → parameter map** structure. + +Create a JSON file (e.g., `params.json`) anywhere in your project directory: + +**Generic Format:** +```json +{ + "ComponentInstance": { + "parameterName": value, + "anotherParameter": value + }, + "AnotherComponent": { + "paramName": value + } +} +``` + +### Example: Ref Project Parameters + + +**`params.json`:** +```json +{ + "Ref.recvBuffComp": { + "parameter1": 20, + "parameter2": -5 + }, + + "Ref.sendBuffComp": { + "parameter3": 25, + "parameter4": 99.99 + }, + "Ref.typeDemo": { + "CHOICE_PRM": "RED", + "CHOICES_PRM": ["ONE", "BLUE"], + "CHOICE_PAIR_PRM": { + "firstChoice": "RED", + "secondChoice": "BLUE" + } + } +} +``` + +> [!NOTE] +> Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). Parameter values support complex F´ types: +> - **Primitives**: Numbers (`20`, `99.99`), booleans, strings +> - **Enums**: String constants (e.g., `"RED"`, `"BLUE"`) +> - **Arrays**: JSON arrays (e.g., `["ONE", "BLUE"]`) +> - **Structs**: Nested objects with field names as keys (e.g., `{"firstChoice": "RED", "secondChoice": "BLUE"}`) + +> [!TIP] +> **Using the `--defaults` flag:** By default, the `fprime-prm-write` tool only includes parameters explicitly listed in your JSON file. If you add the `--defaults` flag, the tool will include all parameters that have default values defined in the dictionary. This effectively resets all parameters to their defaults, except for those you specify in the JSON file. This flag works for both `.dat` and `.seq` file generation. + +All steps from this point on either take place in the terminal or the GDS GUI. + +## Method 1: Generate a `.dat` File + +Use this method to load a binary parameter file into the `PrmDb` component at any time. + +### Step 1: Generate the `.dat` File + +Run the tool in the terminal: + +**General syntax:** +```bash +fprime-prm-write dat --dictionary +``` + +**Example: Ref project:** +```bash +fprime-prm-write dat params.json \ + --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json +``` + +This creates `params.dat` in the same directory as your JSON file. + +> [!NOTE] +> The output file is named based on your input JSON file. If your JSON file is named `my_params.json`, the output will be `my_params.dat`. + +### Step 2: Start the GDS + +**With GUI:** +```bash +fprime-gds +``` + +**Without GUI (Command Line):** +```bash +fprime-gds -g none --log-directly +``` + +### Step 3: Load the Parameter File + +**Using GUI:** +1. Launch the GDS using `fprime-gds` and open up the browser window +2. Navigate to the **Commanding** tab +3. Find and select `FileHandling.prmDb.PRM_LOAD_FILE` +4. Fill in the arguments: + - **fileName**: `"params.dat"` + - **mode**: `MERGE` (merge with existing) or `CLEAR` (replace all) +5. Send the command +6. Check the **Events** tab for `PrmFileLoadComplete` + +**Command Line:** +```bash +# Load the .dat file into staging area +fprime-cli commands send FileHandling.prmDb.PRM_LOAD_FILE "params.dat" MERGE +# Check events for success +fprime-cli events list | grep -E "PrmFileLoadComplete|PrmDbFileLoadFailed|PrmFileBadCrc" +``` + +**Expected events:** + +| Event | Status | Description | +|-------|--------|-------------| +| `PrmFileLoadComplete` | ✓ | File loaded successfully | +| `PrmDbFileLoadFailed` | ✗ | File not found | +| `PrmFileBadCrc` | ✗ | CRC checksum error | + +### Step 4: Commit the Staged Parameters + +After verifying the load succeeded, commit to make parameters active: + +**Using GUI:** + +Send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. + +**Command Line:** +```bash +# Commit staged parameters +fprime-cli commands send FileHandling.prmDb.PRM_COMMIT_STAGED +# Verify the commit operation succeeded +fprime-cli events list | grep "PrmDbCopyAllComplete" +``` + +### Step 5: Verify Parameter Changes + +**Recommended Method: Check telemetry for each parameter** + +Each parameter has a telemetry channel. Check the **Telemetry** tab in the GDS GUI or: + +```bash +fprime-cli telemetry list | grep +``` + +**Alternative Method: Downlink and decode PrmDb.dat** + +If your deployment has file downlink configured (using `Svc.FileDownlink`), you can verify by downloading and decoding the parameter database: + +1. Use your deployment's file downlink commands to retrieve `PrmDb.dat` from the FSW +```bash fileDownlink.FileDownlink_SendFile``` +2. Decode the downloaded file to a JSON file for human readability + + **General syntax:** Using the inverse `fprime-prm-decode` tool + ```bash + fprime-prm-decode PrmDb.dat \ + --dictionary build-fprime-automatic-//dict/TopologyDictionary.json \ + --format json \ + --output downlinked_params.json + ``` + +3. Compare with your input + ```bash + diff params.json downlinked_params.json + ``` + +## Method 2: Generate a `.seq` File + +Sometimes you need to update parameters while F´ is running without loading files. This can be accomplished with a sequence of _PRM_SET commands, which the `fprime-prm-write` tool can automatically create for you. This creates `.seq` which can be compiled and executed by `Svc::CmdSequencer`. + +> [!TIP] +> **Using the `--save` flag:** The generated `.seq` file contains `_PRM_SET` commands that update parameter values in memory. If you want the changes to persist across FSW restarts, add the `--save` flag to include `_PRM_SAVE` commands after each `_PRM_SET`, which writes the parameters to the PrmDb.dat file on the FSW. + +### Step 1: Generate the Sequence File + +**General syntax:** +```bash +fprime-prm-write seq --dictionary +``` + +**Example: Ref project:** +```bash +fprime-prm-write seq params.json \ + --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json +``` + +This creates `params.seq` in the same directory as your JSON file. + +### Step 2: Execute the Sequence + +1. Compile the sequence file to binary format: + ```bash + fprime-seqgen params.seq --dictionary build-fprime-automatic-//dict/TopologyDictionary.json + ``` + This creates `params.bin`. + +2. Load the sequence into `CmdSequencer`: + - **GUI**: Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name + - **Command Line**: + ```bash + fprime-cli commands send FileHandling.cmdSeq.CS_RUN "params.bin" RUN_NOW + ``` + +3. Verify the sequence executed successfully by checking events in the **Events** tab or command line + +For more details, follow the standard [F´ sequencing workflow](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html). + +## Troubleshooting + +### Error: `PrmFileBadCrc` + +**Cause:** CRC checksum mismatch. + +**Fix:** Regenerate with an up-to-date version of `fprime-prm-write`. + +### Error: `PrmDbFileLoadFailed` + +**Cause:** File not found. + +**Fix:** Verify file path and ensure it's accessible to the FSW. + +### Error: `RuntimeError: Unable to find param in dictionary` + +**Cause:** Parameter name doesn't match dictionary. + +**Fix:** +- Use fully qualified component names (e.g., `Ref.recvBuffComp`) +- Check parameter names are exact (case-sensitive) +- Verify dictionary path is correct + +## References + +1. [fprime-prm-write Tool README](https://github.com/nasa/fprime-gds/blob/devel/docs/prm-write-README.md) +2. [Svc::PrmDb Component SDD](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) +3. [Ref Deployment](https://github.com/nasa/fprime/tree/devel/Ref) +4. [F´ Command Sequencing Guide](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html) From 384cfddb14b50596ceea47e9f196f87d369cd1e4 Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Thu, 4 Jun 2026 14:03:20 -0700 Subject: [PATCH 03/14] Delete docs/how-to/prm-write-howto.md --- docs/how-to/prm-write-howto.md | 267 --------------------------------- 1 file changed, 267 deletions(-) delete mode 100644 docs/how-to/prm-write-howto.md diff --git a/docs/how-to/prm-write-howto.md b/docs/how-to/prm-write-howto.md deleted file mode 100644 index 7e3a98059d9..00000000000 --- a/docs/how-to/prm-write-howto.md +++ /dev/null @@ -1,267 +0,0 @@ -# How-To: Import Parameters to the GDS - - -## Overview - -This guide assumes you are familiar with the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write tool` using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. - -This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. - -*Contents:* - -1. [Why Import Parameters?](#why-import-parameters) -2. [Creating a Parameters JSON File](#creating-a-parameters-json-file) -3. [Method 1: Generate a .dat File](#method-1-generate-a-dat-file) -4. [Method 2: Generate a .seq File](#method-2-generate-a-seq-file) -5. [Troubleshooting](#troubleshooting) - -## Why Import Parameters? - -The `fprime-prm-write` tool allows you to: -- Set initial parameter values for system startup -- Update multiple parameters at once without manual commanding -- Version-control parameter configurations alongside your code -- Share parameter sets between team members or mission phases - -## Creating a Parameters JSON File - -The `fprime-prm-write` tool accepts parameter values in JSON format. This format is human-readable and supports all F´ parameter types including primitives, enums, arrays, and structs. - -### JSON File Format - -The JSON should consist of a key-value map of component instance names to an inner key-value map. The inner key-value map should consist of parameter name-to-value map entries. In other words, the JSON file should have a **component name → parameter map** structure. - -Create a JSON file (e.g., `params.json`) anywhere in your project directory: - -**Generic Format:** -```json -{ - "ComponentInstance": { - "parameterName": value, - "anotherParameter": value - }, - "AnotherComponent": { - "paramName": value - } -} -``` - -### Example: Ref Project Parameters - - -**`params.json`:** -```json -{ - "Ref.recvBuffComp": { - "parameter1": 20, - "parameter2": -5 - }, - - "Ref.sendBuffComp": { - "parameter3": 25, - "parameter4": 99.99 - }, - "Ref.typeDemo": { - "CHOICE_PRM": "RED", - "CHOICES_PRM": ["ONE", "BLUE"], - "CHOICE_PAIR_PRM": { - "firstChoice": "RED", - "secondChoice": "BLUE" - } - } -} -``` - -> [!NOTE] -> Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). Parameter values support complex F´ types: -> - **Primitives**: Numbers (`20`, `99.99`), booleans, strings -> - **Enums**: String constants (e.g., `"RED"`, `"BLUE"`) -> - **Arrays**: JSON arrays (e.g., `["ONE", "BLUE"]`) -> - **Structs**: Nested objects with field names as keys (e.g., `{"firstChoice": "RED", "secondChoice": "BLUE"}`) - -> [!TIP] -> **Using the `--defaults` flag:** By default, the `fprime-prm-write` tool only includes parameters explicitly listed in your JSON file. If you add the `--defaults` flag, the tool will include all parameters that have default values defined in the dictionary. This effectively resets all parameters to their defaults, except for those you specify in the JSON file. This flag works for both `.dat` and `.seq` file generation. - -All steps from this point on either take place in the terminal or the GDS GUI. - -## Method 1: Generate a `.dat` File - -Use this method to load a binary parameter file into the `PrmDb` component at any time. - -### Step 1: Generate the `.dat` File - -Run the tool in the terminal: - -**General syntax:** -```bash -fprime-prm-write dat --dictionary -``` - -**Example: Ref project:** -```bash -fprime-prm-write dat params.json \ - --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json -``` - -This creates `params.dat` in the same directory as your JSON file. - -> [!NOTE] -> The output file is named based on your input JSON file. If your JSON file is named `my_params.json`, the output will be `my_params.dat`. - -### Step 2: Start the GDS - -**With GUI:** -```bash -fprime-gds -``` - -**Without GUI (Command Line):** -```bash -fprime-gds -g none --log-directly -``` - -### Step 3: Load the Parameter File - -**Using GUI:** -1. Launch the GDS using `fprime-gds` and open up the browser window -2. Navigate to the **Commanding** tab -3. Find and select `FileHandling.prmDb.PRM_LOAD_FILE` -4. Fill in the arguments: - - **fileName**: `"params.dat"` - - **mode**: `MERGE` (merge with existing) or `CLEAR` (replace all) -5. Send the command -6. Check the **Events** tab for `PrmFileLoadComplete` - -**Command Line:** -```bash -# Load the .dat file into staging area -fprime-cli commands send FileHandling.prmDb.PRM_LOAD_FILE "params.dat" MERGE -# Check events for success -fprime-cli events list | grep -E "PrmFileLoadComplete|PrmDbFileLoadFailed|PrmFileBadCrc" -``` - -**Expected events:** - -| Event | Status | Description | -|-------|--------|-------------| -| `PrmFileLoadComplete` | ✓ | File loaded successfully | -| `PrmDbFileLoadFailed` | ✗ | File not found | -| `PrmFileBadCrc` | ✗ | CRC checksum error | - -### Step 4: Commit the Staged Parameters - -After verifying the load succeeded, commit to make parameters active: - -**Using GUI:** - -Send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. - -**Command Line:** -```bash -# Commit staged parameters -fprime-cli commands send FileHandling.prmDb.PRM_COMMIT_STAGED -# Verify the commit operation succeeded -fprime-cli events list | grep "PrmDbCopyAllComplete" -``` - -### Step 5: Verify Parameter Changes - -**Recommended Method: Check telemetry for each parameter** - -Each parameter has a telemetry channel. Check the **Telemetry** tab in the GDS GUI or: - -```bash -fprime-cli telemetry list | grep -``` - -**Alternative Method: Downlink and decode PrmDb.dat** - -If your deployment has file downlink configured (using `Svc.FileDownlink`), you can verify by downloading and decoding the parameter database: - -1. Use your deployment's file downlink commands to retrieve `PrmDb.dat` from the FSW -```bash fileDownlink.FileDownlink_SendFile``` -2. Decode the downloaded file to a JSON file for human readability - - **General syntax:** Using the inverse `fprime-prm-decode` tool - ```bash - fprime-prm-decode PrmDb.dat \ - --dictionary build-fprime-automatic-//dict/TopologyDictionary.json \ - --format json \ - --output downlinked_params.json - ``` - -3. Compare with your input - ```bash - diff params.json downlinked_params.json - ``` - -## Method 2: Generate a `.seq` File - -Sometimes you need to update parameters while F´ is running without loading files. This can be accomplished with a sequence of _PRM_SET commands, which the `fprime-prm-write` tool can automatically create for you. This creates `.seq` which can be compiled and executed by `Svc::CmdSequencer`. - -> [!TIP] -> **Using the `--save` flag:** The generated `.seq` file contains `_PRM_SET` commands that update parameter values in memory. If you want the changes to persist across FSW restarts, add the `--save` flag to include `_PRM_SAVE` commands after each `_PRM_SET`, which writes the parameters to the PrmDb.dat file on the FSW. - -### Step 1: Generate the Sequence File - -**General syntax:** -```bash -fprime-prm-write seq --dictionary -``` - -**Example: Ref project:** -```bash -fprime-prm-write seq params.json \ - --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json -``` - -This creates `params.seq` in the same directory as your JSON file. - -### Step 2: Execute the Sequence - -1. Compile the sequence file to binary format: - ```bash - fprime-seqgen params.seq --dictionary build-fprime-automatic-//dict/TopologyDictionary.json - ``` - This creates `params.bin`. - -2. Load the sequence into `CmdSequencer`: - - **GUI**: Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name - - **Command Line**: - ```bash - fprime-cli commands send FileHandling.cmdSeq.CS_RUN "params.bin" RUN_NOW - ``` - -3. Verify the sequence executed successfully by checking events in the **Events** tab or command line - -For more details, follow the standard [F´ sequencing workflow](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html). - -## Troubleshooting - -### Error: `PrmFileBadCrc` - -**Cause:** CRC checksum mismatch. - -**Fix:** Regenerate with an up-to-date version of `fprime-prm-write`. - -### Error: `PrmDbFileLoadFailed` - -**Cause:** File not found. - -**Fix:** Verify file path and ensure it's accessible to the FSW. - -### Error: `RuntimeError: Unable to find param in dictionary` - -**Cause:** Parameter name doesn't match dictionary. - -**Fix:** -- Use fully qualified component names (e.g., `Ref.recvBuffComp`) -- Check parameter names are exact (case-sensitive) -- Verify dictionary path is correct - -## References - -1. [fprime-prm-write Tool README](https://github.com/nasa/fprime-gds/blob/devel/docs/prm-write-README.md) -2. [Svc::PrmDb Component SDD](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) -3. [Ref Deployment](https://github.com/nasa/fprime/tree/devel/Ref) -4. [F´ Command Sequencing Guide](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html) From 3c2a897103220b318e1f7b65753df1f35091fc2c Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Thu, 4 Jun 2026 14:12:27 -0700 Subject: [PATCH 04/14] Revise how-to guide for loading parameters in batch Updated title and clarified command line instructions. Adjusted section on verifying parameter changes. --- docs/how-to/prm-write-how-to.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index 7e3a98059d9..2e85bc8520c 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -1,9 +1,9 @@ -# How-To: Import Parameters to the GDS +# How-To: Load Parameters in Batch ## Overview -This guide assumes you are familiar with the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write tool` using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. +Readers of this guide are encouraged to read through the documentation for [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write tool` using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. @@ -135,9 +135,9 @@ fprime-gds -g none --log-directly **Command Line:** ```bash # Load the .dat file into staging area -fprime-cli commands send FileHandling.prmDb.PRM_LOAD_FILE "params.dat" MERGE +fprime-cli command-send FileHandling.prmDb.PRM_LOAD_FILE "params.dat" MERGE # Check events for success -fprime-cli events list | grep -E "PrmFileLoadComplete|PrmDbFileLoadFailed|PrmFileBadCrc" +grep -q "PrmFileLoadComplete" gds.log ``` **Expected events:** @@ -159,22 +159,14 @@ Send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** **Command Line:** ```bash # Commit staged parameters -fprime-cli commands send FileHandling.prmDb.PRM_COMMIT_STAGED +fprime-cli command-send FileHandling.prmDb.PRM_COMMIT_STAGED # Verify the commit operation succeeded -fprime-cli events list | grep "PrmDbCopyAllComplete" +grep -q "PrmDbCopyAllComplete" gds.log ``` -### Step 5: Verify Parameter Changes +### Step 5 (optional): Verify Parameter Changes -**Recommended Method: Check telemetry for each parameter** - -Each parameter has a telemetry channel. Check the **Telemetry** tab in the GDS GUI or: - -```bash -fprime-cli telemetry list | grep -``` - -**Alternative Method: Downlink and decode PrmDb.dat** +**Downlink and decode PrmDb.dat** If your deployment has file downlink configured (using `Svc.FileDownlink`), you can verify by downloading and decoding the parameter database: From be4022fa1bd11904b919a797512fdf10953aa743 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Fri, 5 Jun 2026 10:53:22 -0700 Subject: [PATCH 05/14] Fixed command errors, added some explanations --- docs/how-to/prm-write-how-to.md | 38 +++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index 2e85bc8520c..be8b59db401 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -3,19 +3,19 @@ ## Overview -Readers of this guide are encouraged to read through the documentation for [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write tool` using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. +Readers of this guide are encouraged to read through the documentation for the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write` tool using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. *Contents:* -1. [Why Import Parameters?](#why-import-parameters) +1. [Why Import Parameters in Batch?](#why-import-parameters-in-batch) 2. [Creating a Parameters JSON File](#creating-a-parameters-json-file) 3. [Method 1: Generate a .dat File](#method-1-generate-a-dat-file) 4. [Method 2: Generate a .seq File](#method-2-generate-a-seq-file) 5. [Troubleshooting](#troubleshooting) -## Why Import Parameters? +## Why Import Parameters in Batch? The `fprime-prm-write` tool allows you to: - Set initial parameter values for system startup @@ -71,9 +71,11 @@ Create a JSON file (e.g., `params.json`) anywhere in your project directory: } } ``` +Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). > [!NOTE] -> Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). Parameter values support complex F´ types: +> The .seq method only handles primitives (strings, numbers, booleans, enums). +> Parameter values may be complex F´ types **only when using the .dat method**: > - **Primitives**: Numbers (`20`, `99.99`), booleans, strings > - **Enums**: String constants (e.g., `"RED"`, `"BLUE"`) > - **Arrays**: JSON arrays (e.g., `["ONE", "BLUE"]`) @@ -135,9 +137,9 @@ fprime-gds -g none --log-directly **Command Line:** ```bash # Load the .dat file into staging area -fprime-cli command-send FileHandling.prmDb.PRM_LOAD_FILE "params.dat" MERGE +fprime-cli command-send FileHandling.prmDb.PRM_LOAD_FILE --arguments "params.dat" MERGE # Check events for success -grep -q "PrmFileLoadComplete" gds.log +grep -E "PrmFileLoadComplete|PrmDbCopyAllComplete|PrmDbFileLoadFailed|PrmFileBadCrc" ``` **Expected events:** @@ -164,7 +166,7 @@ fprime-cli command-send FileHandling.prmDb.PRM_COMMIT_STAGED grep -q "PrmDbCopyAllComplete" gds.log ``` -### Step 5 (optional): Verify Parameter Changes +### Step 5 (optional): Verify Individual Parameter Changes **Downlink and decode PrmDb.dat** @@ -221,12 +223,26 @@ This creates `params.seq` in the same directory as your JSON file. - **GUI**: Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name - **Command Line**: ```bash - fprime-cli commands send FileHandling.cmdSeq.CS_RUN "params.bin" RUN_NOW + fprime-cli command-send .cmdSeq.CS_RUN --arguments PrmDb_input.bin BLOCK ``` - + - `BLOCK`: The command waits for the sequence to complete before returning status + - `NO_BLOCK`: The command returns immediately and the sequence runs in the background 3. Verify the sequence executed successfully by checking events in the **Events** tab or command line - -For more details, follow the standard [F´ sequencing workflow](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html). + ```bash + grep -E "CS_Sequence" + ``` + | Event | Status | Description | + |-------|--------|-------------| + | `CS_SequenceLoaded` | ✓ | Sequence file loaded successfully | + | `CS_CommandComplete` | ✓ | Each command in sequence completed | + | `CS_SequenceComplete` | ✓ | Entire sequence finished successfully | + | `CS_FileNotFound` | ✗ | .bin file not found | + | `CS_FileReadError` | ✗ | Error reading the file | + | `CS_FileInvalid` | ✗ | Invalid file format or structure | + | `CS_FileCrcFailure` | ✗ | CRC checksum mismatch | + | `CS_CommandError` | ✗ | A command in the sequence failed | + + For more details, follow the standard [F´ sequencing workflow](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html). ## Troubleshooting From 34a1d5c4b02496021dda005db6c6ccdf3315184e Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Fri, 5 Jun 2026 15:26:36 -0700 Subject: [PATCH 06/14] Edited some steps for sequencing --- docs/how-to/prm-write-how-to.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index be8b59db401..570808eca5d 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -220,7 +220,9 @@ This creates `params.seq` in the same directory as your JSON file. This creates `params.bin`. 2. Load the sequence into `CmdSequencer`: - - **GUI**: Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name + - **GUI**: + 1. Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name + 2. [Stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the params.bin file. - **Command Line**: ```bash fprime-cli command-send .cmdSeq.CS_RUN --arguments PrmDb_input.bin BLOCK From 059a0923ac10ee2b1ed9107c00371665ffd00116 Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Tue, 9 Jun 2026 09:42:51 -0700 Subject: [PATCH 07/14] Apply suggestion from @thomas-bc Co-authored-by: Thomas Boyer-Chammard <49786685+thomas-bc@users.noreply.github.com> --- docs/how-to/prm-write-how-to.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index 570808eca5d..9de8dbf2db0 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -3,7 +3,7 @@ ## Overview -Readers of this guide are encouraged to read through the documentation for the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file or through a `.seq` file. Both types of files are created by the `fprime-prm-write` tool using a JSON file with the parameters. The PrmDb component loads parameters from binary `.dat` files that contain a CRC32 header followed by parameter records. CmdSeq loads parameters from a binary created from a `.seq` file. +Readers of this guide are encouraged to read through the documentation for the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file that PrmDb loads directly, or by generating a command sequence (`.seq` file) to dispatch a series of commands. This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. From b3450a6adb5ce1d6835576772b32f7a4fd19bb96 Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Tue, 9 Jun 2026 09:43:16 -0700 Subject: [PATCH 08/14] Apply suggestion from @thomas-bc Co-authored-by: Thomas Boyer-Chammard <49786685+thomas-bc@users.noreply.github.com> --- docs/how-to/prm-write-how-to.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index 9de8dbf2db0..2e8649e4e3b 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -96,7 +96,7 @@ Run the tool in the terminal: **General syntax:** ```bash -fprime-prm-write dat --dictionary +fprime-prm-write dat --dictionary ``` **Example: Ref project:** From 55807079a3563d6db0dc591c7ca2679d6ff717cc Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 11:13:13 -0700 Subject: [PATCH 09/14] Removed fprime-cli and clarified uplinking --- docs/how-to/prm-write-how-to.md | 96 +++++++++++---------------------- 1 file changed, 30 insertions(+), 66 deletions(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index 2e8649e4e3b..a4e69223383 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -5,7 +5,7 @@ Readers of this guide are encouraged to read through the documentation for the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file that PrmDb loads directly, or by generating a command sequence (`.seq` file) to dispatch a series of commands. -This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/Ref) (reference) F´ project as an example. +This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/TestDeploymentsProject/Ref) (reference) F´ project as an example. *Contents:* @@ -75,11 +75,7 @@ Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). > [!NOTE] > The .seq method only handles primitives (strings, numbers, booleans, enums). -> Parameter values may be complex F´ types **only when using the .dat method**: -> - **Primitives**: Numbers (`20`, `99.99`), booleans, strings -> - **Enums**: String constants (e.g., `"RED"`, `"BLUE"`) -> - **Arrays**: JSON arrays (e.g., `["ONE", "BLUE"]`) -> - **Structs**: Nested objects with field names as keys (e.g., `{"firstChoice": "RED", "secondChoice": "BLUE"}`) +> Parameter values may be complex F´ types **only when using the .dat method**. > [!TIP] > **Using the `--defaults` flag:** By default, the `fprime-prm-write` tool only includes parameters explicitly listed in your JSON file. If you add the `--defaults` flag, the tool will include all parameters that have default values defined in the dictionary. This effectively resets all parameters to their defaults, except for those you specify in the JSON file. This flag works for both `.dat` and `.seq` file generation. @@ -101,7 +97,7 @@ fprime-prm-write dat --dictionary [!NOTE] > The output file is named based on your input JSON file. If your JSON file is named `my_params.json`, the output will be `my_params.dat`. -### Step 2: Start the GDS +### Step 2: Load the Parameter File -**With GUI:** -```bash -fprime-gds -``` - -**Without GUI (Command Line):** -```bash -fprime-gds -g none --log-directly -``` - -### Step 3: Load the Parameter File - -**Using GUI:** 1. Launch the GDS using `fprime-gds` and open up the browser window -2. Navigate to the **Commanding** tab -3. Find and select `FileHandling.prmDb.PRM_LOAD_FILE` -4. Fill in the arguments: - - **fileName**: `"params.dat"` +2. Navigate to the **Uplink** tab to [stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the `params.dat` file. + - Specify an onboard Destination Folder +3. Navigate to the **Commanding** tab +4. Find and select `FileHandling.prmDb.PRM_LOAD_FILE` +5. Fill in the arguments: + - **fileName**: `path/params.dat` - **mode**: `MERGE` (merge with existing) or `CLEAR` (replace all) -5. Send the command -6. Check the **Events** tab for `PrmFileLoadComplete` - -**Command Line:** -```bash -# Load the .dat file into staging area -fprime-cli command-send FileHandling.prmDb.PRM_LOAD_FILE --arguments "params.dat" MERGE -# Check events for success -grep -E "PrmFileLoadComplete|PrmDbCopyAllComplete|PrmDbFileLoadFailed|PrmFileBadCrc" -``` +6. Send the command +7. Check the **Events** tab for `PrmFileLoadComplete` **Expected events:** @@ -150,23 +127,13 @@ grep -E "PrmFileLoadComplete|PrmDbCopyAllComplete|PrmDbFileLoadFailed|PrmFileBad | `PrmDbFileLoadFailed` | ✗ | File not found | | `PrmFileBadCrc` | ✗ | CRC checksum error | -### Step 4: Commit the Staged Parameters +### Step 3: Commit the Staged Parameters After verifying the load succeeded, commit to make parameters active: -**Using GUI:** - -Send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. - -**Command Line:** -```bash -# Commit staged parameters -fprime-cli command-send FileHandling.prmDb.PRM_COMMIT_STAGED -# Verify the commit operation succeeded -grep -q "PrmDbCopyAllComplete" gds.log -``` +Using the GDS GUI, send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. -### Step 5 (optional): Verify Individual Parameter Changes +### Step 4 (optional): Verify Individual Parameter Changes **Downlink and decode PrmDb.dat** @@ -191,7 +158,7 @@ If your deployment has file downlink configured (using `Svc.FileDownlink`), you ## Method 2: Generate a `.seq` File -Sometimes you need to update parameters while F´ is running without loading files. This can be accomplished with a sequence of _PRM_SET commands, which the `fprime-prm-write` tool can automatically create for you. This creates `.seq` which can be compiled and executed by `Svc::CmdSequencer`. +Use this method to load a binary parameter file into the CmdSequencer component at any time. > [!TIP] > **Using the `--save` flag:** The generated `.seq` file contains `_PRM_SET` commands that update parameter values in memory. If you want the changes to persist across FSW restarts, add the `--save` flag to include `_PRM_SAVE` commands after each `_PRM_SET`, which writes the parameters to the PrmDb.dat file on the FSW. @@ -215,20 +182,18 @@ This creates `params.seq` in the same directory as your JSON file. 1. Compile the sequence file to binary format: ```bash - fprime-seqgen params.seq --dictionary build-fprime-automatic-//dict/TopologyDictionary.json + fprime-seqgen params.seq --dictionary ``` This creates `params.bin`. -2. Load the sequence into `CmdSequencer`: - - **GUI**: - 1. Send `FileHandling.cmdSeq.CS_RUN` command with the binary file name - 2. [Stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the params.bin file. - - **Command Line**: - ```bash - fprime-cli command-send .cmdSeq.CS_RUN --arguments PrmDb_input.bin BLOCK - ``` - - `BLOCK`: The command waits for the sequence to complete before returning status - - `NO_BLOCK`: The command returns immediately and the sequence runs in the background +2. Load the sequence into `CmdSequencer` in the GDS GUI: + 1. [Stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the `params.bin` file. + - Specify the Destination Folder onboard, such as `/seq` + 2. Send the `.cmdSeq.CS_RUN` command with the binary file name + - File name should include the path (e.g. `/seq/params.bin`) + - `BLOCK`: The command waits for the sequence to complete before returning status + - `NO_BLOCK`: The command returns immediately and the sequence runs in the background + 3. Verify the sequence executed successfully by checking events in the **Events** tab or command line ```bash grep -E "CS_Sequence" @@ -244,7 +209,7 @@ This creates `params.seq` in the same directory as your JSON file. | `CS_FileCrcFailure` | ✗ | CRC checksum mismatch | | `CS_CommandError` | ✗ | A command in the sequence failed | - For more details, follow the standard [F´ sequencing workflow](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html). + For more details, follow the standard [F´ sequencing workflow](https://fprime.jpl.nasa.gov/devel/docs/user-manual/gds/seqgen/). ## Troubleshooting @@ -270,8 +235,7 @@ This creates `params.seq` in the same directory as your JSON file. - Verify dictionary path is correct ## References - -1. [fprime-prm-write Tool README](https://github.com/nasa/fprime-gds/blob/devel/docs/prm-write-README.md) -2. [Svc::PrmDb Component SDD](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) -3. [Ref Deployment](https://github.com/nasa/fprime/tree/devel/Ref) -4. [F´ Command Sequencing Guide](https://nasa.github.io/fprime/UsersGuide/user/cmd-seq.html) +1. [Svc::PrmDb Component SDD](https://fprime.jpl.nasa.gov/latest/Svc/PrmDb/docs/sdd/) +2. [Svc::CmdSequencer Component SDD](https://fprime.jpl.nasa.gov/latest/Svc/CmdSequencer/docs/sdd/) +3. [Ref Deployment](https://github.com/nasa/fprime/tree/devel/TestDeploymentsProject/Ref) +4. [F´ Command Sequencing Guide](https://fprime.jpl.nasa.gov/latest/docs/user-manual/gds/seqgen/) From cd6923d3b6ec53ab303b6f53c593784ee3910d01 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 11:21:44 -0700 Subject: [PATCH 10/14] Edited intro paragraph --- docs/how-to/prm-write-how-to.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index a4e69223383..a42c0eec7fb 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -3,7 +3,7 @@ ## Overview -Readers of this guide are encouraged to read through the documentation for the [**PrmDb component**](https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md) (F´ framework standard), which stores and manages parameters in F´ deployments. This guide will go over two methods of updating parameters: through a `.dat` file that PrmDb loads directly, or by generating a command sequence (`.seq` file) to dispatch a series of commands. +Readers of this guide are encouraged to read through the documentation for the [PrmDb component](https://fprime.jpl.nasa.gov/latest/Svc/PrmDb/docs/sdd/) and the [CmdSequencer component](https://fprime.jpl.nasa.gov/latest/Svc/CmdSequencer/docs/sdd/). This guide will go over two methods of updating parameters: through a `.dat` file that PrmDb loads directly, or by generating a command sequence (`.seq` file) to dispatch a series of commands. This guide uses the [**Ref**](https://github.com/nasa/fprime/tree/devel/TestDeploymentsProject/Ref) (reference) F´ project as an example. From 49fb688db70ddd79a6e679c6cf4d84ba322a09ed Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 13:31:37 -0700 Subject: [PATCH 11/14] Fixing .dat/.seq descriptions --- docs/how-to/prm-write-how-to.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index a42c0eec7fb..ca3b65543db 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -84,7 +84,7 @@ All steps from this point on either take place in the terminal or the GDS GUI. ## Method 1: Generate a `.dat` File -Use this method to load a binary parameter file into the `PrmDb` component at any time. +With this method, the user uplinks a `.dat` file to the FSW and sends `PRM_LOAD_FILE` followed by `PRM_COMMIT_STAGED` commands to the PrmDb component, which loads parameter values in batch from the file. ### Step 1: Generate the `.dat` File @@ -158,7 +158,7 @@ If your deployment has file downlink configured (using `Svc.FileDownlink`), you ## Method 2: Generate a `.seq` File -Use this method to load a binary parameter file into the CmdSequencer component at any time. +With this method, the user compiles a `.seq` file into a `.bin` and uplinks it to CmdSequencer, which dispatches `_PRM_SET` commands (and `_PRM_SAVE` if `--save` was used) to each component. > [!TIP] > **Using the `--save` flag:** The generated `.seq` file contains `_PRM_SET` commands that update parameter values in memory. If you want the changes to persist across FSW restarts, add the `--save` flag to include `_PRM_SAVE` commands after each `_PRM_SET`, which writes the parameters to the PrmDb.dat file on the FSW. From 7e0fd29ae5488abd129a969b9e9633e9993469ab Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 14:00:44 -0700 Subject: [PATCH 12/14] Multiple small wording updates --- docs/how-to/prm-write-how-to.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index ca3b65543db..d24075d8728 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -78,17 +78,17 @@ Component instance names must be fully qualified (e.g., `Ref.recvBuffComp`). > Parameter values may be complex F´ types **only when using the .dat method**. > [!TIP] -> **Using the `--defaults` flag:** By default, the `fprime-prm-write` tool only includes parameters explicitly listed in your JSON file. If you add the `--defaults` flag, the tool will include all parameters that have default values defined in the dictionary. This effectively resets all parameters to their defaults, except for those you specify in the JSON file. This flag works for both `.dat` and `.seq` file generation. +> **Using the `--defaults` flag:** The `fprime-prm-write` tool only automatically includes parameters explicitly listed in your JSON file. If you add the `--defaults` flag, the tool will include all parameters that have default values defined in the dictionary. This effectively resets all parameters to their defaults, except for those you specify in the JSON file. This flag works for both `.dat` and `.seq` file generation. All steps from this point on either take place in the terminal or the GDS GUI. ## Method 1: Generate a `.dat` File -With this method, the user uplinks a `.dat` file to the FSW and sends `PRM_LOAD_FILE` followed by `PRM_COMMIT_STAGED` commands to the PrmDb component, which loads parameter values in batch from the file. +With this method, the user uplinks a `.dat` file to the FSW and sends the `PRM_LOAD_FILE` and `PRM_COMMIT_STAGED` commands to the PrmDb component, which loads parameter values in batch from the file. ### Step 1: Generate the `.dat` File -Run the tool in the terminal: +Now you will run the `fprime-prm-write` tool in the terminal. **General syntax:** ```bash @@ -110,7 +110,7 @@ This creates `params.dat` in the same directory as your JSON file. 1. Launch the GDS using `fprime-gds` and open up the browser window 2. Navigate to the **Uplink** tab to [stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the `params.dat` file. - - Specify an onboard Destination Folder + - Specify an onboard Destination Folder path 3. Navigate to the **Commanding** tab 4. Find and select `FileHandling.prmDb.PRM_LOAD_FILE` 5. Fill in the arguments: @@ -131,7 +131,7 @@ This creates `params.dat` in the same directory as your JSON file. After verifying the load succeeded, commit to make parameters active: -Using the GDS GUI, send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. +In the **Commanding** tab, send `FileHandling.prmDb.PRM_COMMIT_STAGED` (no arguments). Check the **Events** tab for `PrmDbCopyAllComplete` to confirm the commit succeeded. ### Step 4 (optional): Verify Individual Parameter Changes @@ -145,9 +145,9 @@ If your deployment has file downlink configured (using `Svc.FileDownlink`), you **General syntax:** Using the inverse `fprime-prm-decode` tool ```bash - fprime-prm-decode PrmDb.dat \ - --dictionary build-fprime-automatic-//dict/TopologyDictionary.json \ - --format json \ + fprime-prm-decode PrmDb.dat + --dictionary + --format json --output downlinked_params.json ``` @@ -167,7 +167,7 @@ With this method, the user compiles a `.seq` file into a `.bin` and uplinks it t **General syntax:** ```bash -fprime-prm-write seq --dictionary +fprime-prm-write seq --dictionary ``` **Example: Ref project:** @@ -187,7 +187,7 @@ This creates `params.seq` in the same directory as your JSON file. This creates `params.bin`. 2. Load the sequence into `CmdSequencer` in the GDS GUI: - 1. [Stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the `params.bin` file. + 1. In the **Uplink** tab, [stage and uplink](https://fprime.jpl.nasa.gov/devel/docs/user-manual/overview/gds-introduction/#navigating-the-gds-gui) the `params.bin` file. - Specify the Destination Folder onboard, such as `/seq` 2. Send the `.cmdSeq.CS_RUN` command with the binary file name - File name should include the path (e.g. `/seq/params.bin`) @@ -196,7 +196,7 @@ This creates `params.seq` in the same directory as your JSON file. 3. Verify the sequence executed successfully by checking events in the **Events** tab or command line ```bash - grep -E "CS_Sequence" + grep -E "CS_Sequence" ``` | Event | Status | Description | |-------|--------|-------------| @@ -223,7 +223,7 @@ This creates `params.seq` in the same directory as your JSON file. **Cause:** File not found. -**Fix:** Verify file path and ensure it's accessible to the FSW. +**Fix:** Verify file path and ensure it's accessible to the FSW (uplinked to the spacecraft, providing the onboard file path). ### Error: `RuntimeError: Unable to find param in dictionary` From b6e81be5f475b13aedcbc3f0f611f19781404376 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 14:17:52 -0700 Subject: [PATCH 13/14] Multiple small wording updates --- docs/how-to/prm-write-how-to.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/prm-write-how-to.md b/docs/how-to/prm-write-how-to.md index d24075d8728..2b1e3e02527 100644 --- a/docs/how-to/prm-write-how-to.md +++ b/docs/how-to/prm-write-how-to.md @@ -92,7 +92,7 @@ Now you will run the `fprime-prm-write` tool in the terminal. **General syntax:** ```bash -fprime-prm-write dat --dictionary +fprime-prm-write dat --dictionary ``` **Example: Ref project:** From fb0d97d621ebb58f9cda2c89a42992b10c359b91 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 15:25:28 -0700 Subject: [PATCH 14/14] Change index.md to add a card for this document on the How-To page --- docs/how-to/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 2ea1d961077..356433ee950 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -132,4 +132,12 @@ How-To guides offer step-by-step instructions for specific development tasks in [View Test-Driven Development](test-driven-development.md){ .md-button .md-button--primary } +- __Import Parameters in Batch__ + + --- + + This guide covers two methods of updating parameters: through a `.dat` file that PrmDb loads directly, or by generating a command sequence (`.seq` file) to dispatch a series of commands. + + [View Import Parameters in Batch](prm-write-how-to.md){ .md-button .md-button--primary } + \ No newline at end of file