From 2ed071a2818bac1be01b0b2ac7bc772c45318530 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 2 Jun 2026 17:56:25 -0700 Subject: [PATCH 1/8] CI test for PrmDb dat file creation --- .github/workflows/prmdb-integration-test.yml | 156 +++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 .github/workflows/prmdb-integration-test.yml diff --git a/.github/workflows/prmdb-integration-test.yml b/.github/workflows/prmdb-integration-test.yml new file mode 100644 index 00000000000..84bb0c61ac2 --- /dev/null +++ b/.github/workflows/prmdb-integration-test.yml @@ -0,0 +1,156 @@ +name: PrmDb Integration Test + +on: + pull_request: + branches: [ devel ] + paths: + - 'Svc/PrmDb/**' + - 'Ref/**' + - '.github/workflows/prmdb-integration-test.yml' # Test changes to this workflow itself + +# Cancel in-progress runs if a newer run is started on the same PR +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + prmdb-test: + runs-on: ubuntu-latest + + steps: + # Step 1: Get the code + - name: "Checkout F Prime Repository" + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: true + + # Step 2: Setup Python + - name: "Set up Python" + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + # Step 3: Setup F´ tools + - name: "Setup F Prime Tools" + uses: ./.github/actions/setup + + # Step 4: Build Ref deployment + - name: "Build Ref Deployment" + working-directory: ./Ref + run: | + fprime-util generate -f + fprime-util build + + # Step 5: Create test parameter file + - name: "Create Test Parameter JSON" + working-directory: ./Ref + run: | + # TODO: Create a simple JSON file with test parameters + # Example: {"Ref.recvBuffComp": {"parameter1": 42}} + cat > test_params.json << 'EOF' + { + "Ref.recvBuffComp": { + "parameter1": 42 + }, + "Ref.typeDemo": { + "CHOICES_PRM": ["ONE", "BLUE"] + } + } + EOF + + # Step 6: Generate .dat file + - name: "Generate Parameter .dat File" + working-directory: ./Ref + run: | + # TODO: Use fprime-prm-write to convert JSON to .dat + # Hint: You need the dictionary and the JSON input + fprime-prm-write dat test_params.json \ + --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json \ + --output test_params.dat + + # Step 7: Start GDS in background + - name: "Start F Prime GDS" + working-directory: ./Ref + run: | + # Start GDS in the background + fprime-gds -g none --log-directly > gds.log 2>&1 & + + # save the PID to stop it later + echo $! > gds.pid + + # Wait for GDS to be ready (with timeout) + for i in {1..30}; do + if nc -z localhost 5000 2>/dev/null; then + echo "GDS is ready!" + break + fi + if [ $i -eq 30 ]; then + echo "GDS failed to start within 30 seconds" + cat gds.log + exit 1 + fi + sleep 1 + done + + # Verify GDS started successfully + if ! kill -0 $(cat gds.pid) 2>/dev/null; then + echo "GDS failed to start" + exit 1 + fi + + # Step 8: Load parameters into PrmDb + - name: "Load Parameters via GDS" + working-directory: ./Ref + run: | + # Sending GDS fprime-cli commands + fprime-cli commands send FileHandling.prmDb.PRM_LOAD_FILE "test_params.dat" MERGE + fprime-cli commands send FileHandling.prmDb.PRM_COMMIT_STAGED + + # Step 9: Verify parameters loaded + - name: "Verify Parameters" + working-directory: ./Ref + run: | + # Check GDS logs for success events, if not found, exit 1 + if ! grep -q "PrmFileLoadComplete" gds.log; then + echo "ERROR: Missing PrmFileLoadComplete event" + cat gds.log # Show log for debugging + exit 1 + fi + if ! grep -q "PrmDbCopyAllComplete" gds.log; then + echo "ERROR: Missing PrmDbCopyAllComplete event" + cat gds.log # Show log for debugging + exit 1 + fi + + # - Query parameter values + + # Check for error events, if found, then exit 1 + if grep -q "PrmDbFileLoadFailed" gds.log; then + echo "ERROR: Found PrmDbFileLoadFailed" + cat gds.log + exit 1 + fi + if grep -q "PrmFileBadCrc" gds.log; then + echo "ERROR: Found PrmFileBadCrc" + cat gds.log + exit 1 + fi + + # Step 10: Cleanup + - name: "Stop GDS" + working-directory: ./Ref + if: always() # Run even if previous steps failed + run: | + # Check if PID file exists + if [ -f gds.pid ]; then + # Read the PID + GDS_PID=$(cat gds.pid) + + # Try graceful shutdown + kill $GDS_PID || true + + # Wait for shutdown + sleep 2 + fi + From 2489debfb15682a44979995ae8675b8bf791e454 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Tue, 9 Jun 2026 18:08:41 -0700 Subject: [PATCH 2/8] Reorganize How-To guides into four topical categories --- .../data-products.md | 0 .../define-state-machines.md | 0 .../develop-device-driver.md | 0 .../develop-fprime-libraries.md | 0 .../develop-subtopologies.md | 0 .../implement-radio-manager.md | 0 .../python-development.md | 0 .../derive-channels-on-ground.md | 0 .../develop-gds-plugins.md | 0 .../gds-and-operations/prm-write-how-to.md | 241 ++++++++++++++++++ docs/how-to/index.md | 38 +-- .../custom-framing.md | 0 .../implement-osal.md | 0 .../integrate-external-libraries.md | 0 .../porting-guide.md | 0 .../rule-based-testing.md | 0 .../test-driven-development.md | 0 17 files changed, 264 insertions(+), 15 deletions(-) rename docs/how-to/{ => develop-your-project}/data-products.md (100%) rename docs/how-to/{ => develop-your-project}/define-state-machines.md (100%) rename docs/how-to/{ => develop-your-project}/develop-device-driver.md (100%) rename docs/how-to/{ => develop-your-project}/develop-fprime-libraries.md (100%) rename docs/how-to/{ => develop-your-project}/develop-subtopologies.md (100%) rename docs/how-to/{ => develop-your-project}/implement-radio-manager.md (100%) rename docs/how-to/{ => develop-your-project}/python-development.md (100%) rename docs/how-to/{ => gds-and-operations}/derive-channels-on-ground.md (100%) rename docs/how-to/{ => gds-and-operations}/develop-gds-plugins.md (100%) create mode 100644 docs/how-to/gds-and-operations/prm-write-how-to.md rename docs/how-to/{ => integrate-libraries-and-platforms}/custom-framing.md (100%) rename docs/how-to/{ => integrate-libraries-and-platforms}/implement-osal.md (100%) rename docs/how-to/{ => integrate-libraries-and-platforms}/integrate-external-libraries.md (100%) rename docs/how-to/{ => integrate-libraries-and-platforms}/porting-guide.md (100%) rename docs/how-to/{ => test-your-project}/rule-based-testing.md (100%) rename docs/how-to/{ => test-your-project}/test-driven-development.md (100%) diff --git a/docs/how-to/data-products.md b/docs/how-to/develop-your-project/data-products.md similarity index 100% rename from docs/how-to/data-products.md rename to docs/how-to/develop-your-project/data-products.md diff --git a/docs/how-to/define-state-machines.md b/docs/how-to/develop-your-project/define-state-machines.md similarity index 100% rename from docs/how-to/define-state-machines.md rename to docs/how-to/develop-your-project/define-state-machines.md diff --git a/docs/how-to/develop-device-driver.md b/docs/how-to/develop-your-project/develop-device-driver.md similarity index 100% rename from docs/how-to/develop-device-driver.md rename to docs/how-to/develop-your-project/develop-device-driver.md diff --git a/docs/how-to/develop-fprime-libraries.md b/docs/how-to/develop-your-project/develop-fprime-libraries.md similarity index 100% rename from docs/how-to/develop-fprime-libraries.md rename to docs/how-to/develop-your-project/develop-fprime-libraries.md diff --git a/docs/how-to/develop-subtopologies.md b/docs/how-to/develop-your-project/develop-subtopologies.md similarity index 100% rename from docs/how-to/develop-subtopologies.md rename to docs/how-to/develop-your-project/develop-subtopologies.md diff --git a/docs/how-to/implement-radio-manager.md b/docs/how-to/develop-your-project/implement-radio-manager.md similarity index 100% rename from docs/how-to/implement-radio-manager.md rename to docs/how-to/develop-your-project/implement-radio-manager.md diff --git a/docs/how-to/python-development.md b/docs/how-to/develop-your-project/python-development.md similarity index 100% rename from docs/how-to/python-development.md rename to docs/how-to/develop-your-project/python-development.md diff --git a/docs/how-to/derive-channels-on-ground.md b/docs/how-to/gds-and-operations/derive-channels-on-ground.md similarity index 100% rename from docs/how-to/derive-channels-on-ground.md rename to docs/how-to/gds-and-operations/derive-channels-on-ground.md diff --git a/docs/how-to/develop-gds-plugins.md b/docs/how-to/gds-and-operations/develop-gds-plugins.md similarity index 100% rename from docs/how-to/develop-gds-plugins.md rename to docs/how-to/gds-and-operations/develop-gds-plugins.md diff --git a/docs/how-to/gds-and-operations/prm-write-how-to.md b/docs/how-to/gds-and-operations/prm-write-how-to.md new file mode 100644 index 00000000000..2b1e3e02527 --- /dev/null +++ b/docs/how-to/gds-and-operations/prm-write-how-to.md @@ -0,0 +1,241 @@ +# How-To: Load Parameters in Batch + + +## Overview + +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. + +*Contents:* + +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 in Batch? + +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" + } + } +} +``` +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**. + +> [!TIP] +> **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 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 + +Now you will run the `fprime-prm-write` 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: Load the Parameter 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 path +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) +6. Send the command +7. Check the **Events** tab for `PrmFileLoadComplete` + +**Expected events:** + +| Event | Status | Description | +|-------|--------|-------------| +| `PrmFileLoadComplete` | ✓ | File loaded successfully | +| `PrmDbFileLoadFailed` | ✗ | File not found | +| `PrmFileBadCrc` | ✗ | CRC checksum error | + +### Step 3: Commit the Staged Parameters + +After verifying the load succeeded, commit to make parameters active: + +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 + +**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 + --format json + --output downlinked_params.json + ``` + +3. Compare with your input + ```bash + diff params.json downlinked_params.json + ``` + +## Method 2: Generate a `.seq` File + +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. + +### 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 + ``` + This creates `params.bin`. + +2. Load the sequence into `CmdSequencer` in the GDS GUI: + 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`) + - `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" + ``` + | 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://fprime.jpl.nasa.gov/devel/docs/user-manual/gds/seqgen/). + +## 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 (uplinked to the spacecraft, providing the onboard file path). + +### 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. [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/) diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 2ea1d961077..b536dd897fd 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -16,7 +16,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide will walk you through the process of developing GDS plugins. - [View Develop F´ GDS Plugins](develop-gds-plugins.md){ .md-button .md-button--primary } + [View Develop F´ GDS Plugins](gds-and-operations/develop-gds-plugins.md){ .md-button .md-button--primary } - __F´ Library Development__ @@ -24,7 +24,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This how to will walk you through the structure and best practices in developing an F´ library. - [View Develop F´ Libraries](develop-fprime-libraries.md){ .md-button .md-button--primary } + [View Develop F´ Libraries](develop-your-project/develop-fprime-libraries.md){ .md-button .md-button--primary } - __Integrating Third-Party Libraries__ @@ -33,7 +33,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This how to will walk you through how to integrate non-F´ libraries into your F´ project. It will cover multiple approaches based on examples with [OpenCV](https://github.com/opencv/opencv), [OpenSSL](https://github.com/openssl/openssl) and [ETL](https://github.com/etlcpp/etl). - [View Integrating Third-Party Libraries](integrate-external-libraries.md){ .md-button .md-button--primary } + [View Integrating Third-Party Libraries](integrate-libraries-and-platforms/integrate-external-libraries.md){ .md-button .md-button--primary } - __Porting F´ To a New Platform__ @@ -41,7 +41,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This how to will walk you through porting F´ to a new platform. - [View Porting Guide](porting-guide.md){ .md-button .md-button--primary } + [View Porting Guide](integrate-libraries-and-platforms/implement-osal.md){ .md-button .md-button--primary } - __Implement a Framing Protocol__ @@ -50,7 +50,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to implement a custom framing protocol in F Prime flight software and integrate it with the F Prime GDS. - [View Implement a Framing Protocol](custom-framing.md){ .md-button .md-button--primary } + [View Implement a Framing Protocol](integrate-libraries-and-platforms/custom-framing.md){ .md-button .md-button--primary } - __Generate Data Products__ @@ -58,7 +58,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you when to use data products, how to generate them, how to test them, and how to integrate them into your topology and ground system. - [View Generate Data Products](data-products.md){ .md-button .md-button--primary } + [View Generate Data Products](develop-your-project/data-products.md){ .md-button .md-button--primary } - __Define State Machines__ @@ -66,7 +66,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to define and use state machines in F Prime with FPP so complex component behavior is explicit, testable, and maintainable. - [View Define State Machines](define-state-machines.md){ .md-button .md-button--primary } + [View Define State Machines](develop-your-project/define-state-machines.md){ .md-button .md-button--primary } - __Create Ground-Derived Channels__ @@ -74,7 +74,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to compute telemetry-derived values on the ground and publish them through the F Prime GDS plugin system. - [View Create Ground-Derived Channels](derive-channels-on-ground.md){ .md-button .md-button--primary } + [View Create Ground-Derived Channels](gds-and-operations/derive-channels-on-ground.md){ .md-button .md-button--primary } - __Develop a Device Driver__ @@ -82,7 +82,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to build a new device driver in F Prime using the application-manager-driver pattern. - [View Develop a Device Driver](develop-device-driver.md){ .md-button .md-button--primary } + [View Develop a Device Driver](develop-your-project/develop-device-driver.md){ .md-button .md-button--primary } - __Develop a Subtopology__ @@ -90,7 +90,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to organize reusable topology architecture into subtopologies that can be imported into deployments. - [View Develop a Subtopology](develop-subtopologies.md){ .md-button .md-button--primary } + [View Develop a Subtopology](develop-your-project/develop-subtopologies.md){ .md-button .md-button--primary } - __Implement an OS Abstraction Layer__ @@ -98,7 +98,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to implement a new OS Abstraction Layer for F´ so the framework can run on another operating system. - [View Implement an OS Abstraction Layer](implement-osal.md){ .md-button .md-button--primary } + [View Implement an OS Abstraction Layer](integrate-libraries-and-platforms/implement-osal.md){ .md-button .md-button--primary } - __Implement a Radio Manager Component__ @@ -106,7 +106,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to implement a radio manager component using the communications adapter interface. - [View Implement a Radio Manager Component](implement-radio-manager.md){ .md-button .md-button--primary } + [View Implement a Radio Manager Component](develop-your-project/implement-radio-manager.md){ .md-button .md-button--primary } - __Develop Components in Python__ @@ -114,7 +114,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to develop Python-based F Prime applications and integrate Python components into a larger system. - [View Develop Components in Python](python-development.md){ .md-button .md-button--primary } + [View Develop Components in Python](develop-your-project/python-development.md){ .md-button .md-button--primary } - __Write Rule-Based Tests__ @@ -122,7 +122,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to write rule-based unit tests for F Prime components using the RuleDemo example component. - [View Write Rule-Based Tests](rule-based-testing.md){ .md-button .md-button--primary } + [View Write Rule-Based Tests](test-your-project/rule-based-testing.md){ .md-button .md-button--primary } - __Test-Driven Development__ @@ -130,6 +130,14 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you a practical test-driven development loop for building an F´ component from model to implementation. - [View Test-Driven Development](test-driven-development.md){ .md-button .md-button--primary } + [View Test-Driven Development](test-your-project/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 diff --git a/docs/how-to/custom-framing.md b/docs/how-to/integrate-libraries-and-platforms/custom-framing.md similarity index 100% rename from docs/how-to/custom-framing.md rename to docs/how-to/integrate-libraries-and-platforms/custom-framing.md diff --git a/docs/how-to/implement-osal.md b/docs/how-to/integrate-libraries-and-platforms/implement-osal.md similarity index 100% rename from docs/how-to/implement-osal.md rename to docs/how-to/integrate-libraries-and-platforms/implement-osal.md diff --git a/docs/how-to/integrate-external-libraries.md b/docs/how-to/integrate-libraries-and-platforms/integrate-external-libraries.md similarity index 100% rename from docs/how-to/integrate-external-libraries.md rename to docs/how-to/integrate-libraries-and-platforms/integrate-external-libraries.md diff --git a/docs/how-to/porting-guide.md b/docs/how-to/integrate-libraries-and-platforms/porting-guide.md similarity index 100% rename from docs/how-to/porting-guide.md rename to docs/how-to/integrate-libraries-and-platforms/porting-guide.md diff --git a/docs/how-to/rule-based-testing.md b/docs/how-to/test-your-project/rule-based-testing.md similarity index 100% rename from docs/how-to/rule-based-testing.md rename to docs/how-to/test-your-project/rule-based-testing.md diff --git a/docs/how-to/test-driven-development.md b/docs/how-to/test-your-project/test-driven-development.md similarity index 100% rename from docs/how-to/test-driven-development.md rename to docs/how-to/test-your-project/test-driven-development.md From 4718ebe3a3a8e084056d9fd2f6a21bcf4e98e4f1 Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Tue, 9 Jun 2026 18:14:49 -0700 Subject: [PATCH 3/8] Delete .github/workflows/prmdb-integration-test.yml --- .github/workflows/prmdb-integration-test.yml | 156 ------------------- 1 file changed, 156 deletions(-) delete mode 100644 .github/workflows/prmdb-integration-test.yml diff --git a/.github/workflows/prmdb-integration-test.yml b/.github/workflows/prmdb-integration-test.yml deleted file mode 100644 index 84bb0c61ac2..00000000000 --- a/.github/workflows/prmdb-integration-test.yml +++ /dev/null @@ -1,156 +0,0 @@ -name: PrmDb Integration Test - -on: - pull_request: - branches: [ devel ] - paths: - - 'Svc/PrmDb/**' - - 'Ref/**' - - '.github/workflows/prmdb-integration-test.yml' # Test changes to this workflow itself - -# Cancel in-progress runs if a newer run is started on the same PR -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} - cancel-in-progress: true - -jobs: - prmdb-test: - runs-on: ubuntu-latest - - steps: - # Step 1: Get the code - - name: "Checkout F Prime Repository" - uses: actions/checkout@v4 - with: - fetch-depth: 0 - submodules: true - - # Step 2: Setup Python - - name: "Set up Python" - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - # Step 3: Setup F´ tools - - name: "Setup F Prime Tools" - uses: ./.github/actions/setup - - # Step 4: Build Ref deployment - - name: "Build Ref Deployment" - working-directory: ./Ref - run: | - fprime-util generate -f - fprime-util build - - # Step 5: Create test parameter file - - name: "Create Test Parameter JSON" - working-directory: ./Ref - run: | - # TODO: Create a simple JSON file with test parameters - # Example: {"Ref.recvBuffComp": {"parameter1": 42}} - cat > test_params.json << 'EOF' - { - "Ref.recvBuffComp": { - "parameter1": 42 - }, - "Ref.typeDemo": { - "CHOICES_PRM": ["ONE", "BLUE"] - } - } - EOF - - # Step 6: Generate .dat file - - name: "Generate Parameter .dat File" - working-directory: ./Ref - run: | - # TODO: Use fprime-prm-write to convert JSON to .dat - # Hint: You need the dictionary and the JSON input - fprime-prm-write dat test_params.json \ - --dictionary build-artifacts/Linux/Ref/dict/RefTopologyDictionary.json \ - --output test_params.dat - - # Step 7: Start GDS in background - - name: "Start F Prime GDS" - working-directory: ./Ref - run: | - # Start GDS in the background - fprime-gds -g none --log-directly > gds.log 2>&1 & - - # save the PID to stop it later - echo $! > gds.pid - - # Wait for GDS to be ready (with timeout) - for i in {1..30}; do - if nc -z localhost 5000 2>/dev/null; then - echo "GDS is ready!" - break - fi - if [ $i -eq 30 ]; then - echo "GDS failed to start within 30 seconds" - cat gds.log - exit 1 - fi - sleep 1 - done - - # Verify GDS started successfully - if ! kill -0 $(cat gds.pid) 2>/dev/null; then - echo "GDS failed to start" - exit 1 - fi - - # Step 8: Load parameters into PrmDb - - name: "Load Parameters via GDS" - working-directory: ./Ref - run: | - # Sending GDS fprime-cli commands - fprime-cli commands send FileHandling.prmDb.PRM_LOAD_FILE "test_params.dat" MERGE - fprime-cli commands send FileHandling.prmDb.PRM_COMMIT_STAGED - - # Step 9: Verify parameters loaded - - name: "Verify Parameters" - working-directory: ./Ref - run: | - # Check GDS logs for success events, if not found, exit 1 - if ! grep -q "PrmFileLoadComplete" gds.log; then - echo "ERROR: Missing PrmFileLoadComplete event" - cat gds.log # Show log for debugging - exit 1 - fi - if ! grep -q "PrmDbCopyAllComplete" gds.log; then - echo "ERROR: Missing PrmDbCopyAllComplete event" - cat gds.log # Show log for debugging - exit 1 - fi - - # - Query parameter values - - # Check for error events, if found, then exit 1 - if grep -q "PrmDbFileLoadFailed" gds.log; then - echo "ERROR: Found PrmDbFileLoadFailed" - cat gds.log - exit 1 - fi - if grep -q "PrmFileBadCrc" gds.log; then - echo "ERROR: Found PrmFileBadCrc" - cat gds.log - exit 1 - fi - - # Step 10: Cleanup - - name: "Stop GDS" - working-directory: ./Ref - if: always() # Run even if previous steps failed - run: | - # Check if PID file exists - if [ -f gds.pid ]; then - # Read the PID - GDS_PID=$(cat gds.pid) - - # Try graceful shutdown - kill $GDS_PID || true - - # Wait for shutdown - sleep 2 - fi - From e5cf560b068f3d99cfdf54bc1fd6fbb7f257498e Mon Sep 17 00:00:00 2001 From: Laura Fernandes <77582937+Specky26846@users.noreply.github.com> Date: Tue, 9 Jun 2026 18:15:03 -0700 Subject: [PATCH 4/8] Delete docs/how-to/gds-and-operations/prm-write-how-to.md --- .../gds-and-operations/prm-write-how-to.md | 241 ------------------ 1 file changed, 241 deletions(-) delete mode 100644 docs/how-to/gds-and-operations/prm-write-how-to.md diff --git a/docs/how-to/gds-and-operations/prm-write-how-to.md b/docs/how-to/gds-and-operations/prm-write-how-to.md deleted file mode 100644 index 2b1e3e02527..00000000000 --- a/docs/how-to/gds-and-operations/prm-write-how-to.md +++ /dev/null @@ -1,241 +0,0 @@ -# How-To: Load Parameters in Batch - - -## Overview - -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. - -*Contents:* - -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 in Batch? - -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" - } - } -} -``` -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**. - -> [!TIP] -> **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 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 - -Now you will run the `fprime-prm-write` 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: Load the Parameter 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 path -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) -6. Send the command -7. Check the **Events** tab for `PrmFileLoadComplete` - -**Expected events:** - -| Event | Status | Description | -|-------|--------|-------------| -| `PrmFileLoadComplete` | ✓ | File loaded successfully | -| `PrmDbFileLoadFailed` | ✗ | File not found | -| `PrmFileBadCrc` | ✗ | CRC checksum error | - -### Step 3: Commit the Staged Parameters - -After verifying the load succeeded, commit to make parameters active: - -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 - -**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 - --format json - --output downlinked_params.json - ``` - -3. Compare with your input - ```bash - diff params.json downlinked_params.json - ``` - -## Method 2: Generate a `.seq` File - -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. - -### 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 - ``` - This creates `params.bin`. - -2. Load the sequence into `CmdSequencer` in the GDS GUI: - 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`) - - `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" - ``` - | 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://fprime.jpl.nasa.gov/devel/docs/user-manual/gds/seqgen/). - -## 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 (uplinked to the spacecraft, providing the onboard file path). - -### 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. [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 8fb4fcadb0a86e213f6abeb549d5ded0d557e4aa Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Wed, 10 Jun 2026 10:49:08 -0700 Subject: [PATCH 5/8] Consistent naming for guides --- .nav.yml | 7 ++++++- docs/how-to/develop-your-project/data-products.md | 2 +- docs/how-to/develop-your-project/define-state-machines.md | 2 +- .../how-to/develop-your-project/implement-radio-manager.md | 2 +- docs/how-to/develop-your-project/python-development.md | 2 +- .../integrate-libraries-and-platforms/implement-osal.md | 2 +- docs/how-to/test-your-project/rule-based-testing.md | 2 +- docs/how-to/test-your-project/test-driven-development.md | 2 +- docs/mkdocs.yml | 5 ++++- 9 files changed, 17 insertions(+), 9 deletions(-) diff --git a/.nav.yml b/.nav.yml index eae26346d34..7134d8ca6fd 100644 --- a/.nav.yml +++ b/.nav.yml @@ -28,7 +28,12 @@ nav: - Design Patterns: docs/user-manual/design-patterns/ - Build System: docs/user-manual/build-system/ - Security: docs/user-manual/security/ - - How To: docs/how-to + - How-To: + - How-To Index: docs/how-to/index.md + - Develop your Project: docs/how-to/develop-your-project/ + - Test your Project: docs/how-to/test-your-project/ + - Integrate Libraries and Platforms: docs/how-to/integrate-libraries-and-platforms/ + - GDS and Operations: docs/how-to/gds-and-operations/ - Reference: - docs/reference/index.md - APIs: diff --git a/docs/how-to/develop-your-project/data-products.md b/docs/how-to/develop-your-project/data-products.md index 35dd6b97414..6041a40dfe6 100644 --- a/docs/how-to/develop-your-project/data-products.md +++ b/docs/how-to/develop-your-project/data-products.md @@ -1,4 +1,4 @@ -# How-To: Generate Data Products +# Generate Data Products This How-To describes **when to use data products**, **how to generate them in flight software**, **how to test them**, and provides guidance for **topology integration** and **ground decoding**. It is intended for engineers who are comfortable with F Prime components and want to add structured, store-and-forward mission data to their system. diff --git a/docs/how-to/develop-your-project/define-state-machines.md b/docs/how-to/develop-your-project/define-state-machines.md index 00febacb6f4..a2c0df5e82b 100644 --- a/docs/how-to/develop-your-project/define-state-machines.md +++ b/docs/how-to/develop-your-project/define-state-machines.md @@ -1,4 +1,4 @@ -# How-To: Define State Machines in F Prime +# Define State Machines in F Prime This guide shows how to define and use state machines in F Prime using the F Prime Modeling Language (FPP). State machines help capture component behavior by modeling modes (states) and transitions explicitly, making complex logic easier to implement, test, and maintain. FPP provides autocoding capabilities to allow users to quickly implement state-defined behavior. diff --git a/docs/how-to/develop-your-project/implement-radio-manager.md b/docs/how-to/develop-your-project/implement-radio-manager.md index 1da1e3a3db5..da3d88ccd71 100644 --- a/docs/how-to/develop-your-project/implement-radio-manager.md +++ b/docs/how-to/develop-your-project/implement-radio-manager.md @@ -1,4 +1,4 @@ -# How-To: Implement a Radio Manager Component +# Implement a Radio Manager Component This guide provides step-by-step instructions for implementing a radio manager component using the [Svc.Com Communications Adapter Interface](../reference/communication-adapter-interface.md). A radio manager handles communication with radio hardware, managing both outgoing transmissions (downlink) and incoming receptions (uplink). diff --git a/docs/how-to/develop-your-project/python-development.md b/docs/how-to/develop-your-project/python-development.md index 900a7b05d95..157e1021e75 100644 --- a/docs/how-to/develop-your-project/python-development.md +++ b/docs/how-to/develop-your-project/python-development.md @@ -1,4 +1,4 @@ -# How-To: Develop Components in Python +# Develop Components in Python This guide is a starting point for developing Python-based F Prime applications by constructing select components using Python. diff --git a/docs/how-to/integrate-libraries-and-platforms/implement-osal.md b/docs/how-to/integrate-libraries-and-platforms/implement-osal.md index 0f47a672f0b..8a252d34c7f 100644 --- a/docs/how-to/integrate-libraries-and-platforms/implement-osal.md +++ b/docs/how-to/integrate-libraries-and-platforms/implement-osal.md @@ -1,4 +1,4 @@ -# How-To: Implement an OS Abstraction Layer +# Implement an OS Abstraction Layer This guide provides step-by-step instructions for implementing a new OS Abstraction Layer (OSAL) for F´. The F´ OSAL provides a uniform interface to operating system services, allowing F´ to run on multiple operating systems without modification to the source code. For more information on the architecture and design of the OSAL, refer to the [OSAL Software Design Document](../../Os/docs/sdd.md). diff --git a/docs/how-to/test-your-project/rule-based-testing.md b/docs/how-to/test-your-project/rule-based-testing.md index 144515230bc..89843a140e1 100644 --- a/docs/how-to/test-your-project/rule-based-testing.md +++ b/docs/how-to/test-your-project/rule-based-testing.md @@ -1,4 +1,4 @@ -# How-To: Write Rule-Based Tests for F Prime Components +# Write Rule-Based Tests for F Prime Components This guide shows how to write Rule-Based Testing (RBT) unit tests for an F Prime component. diff --git a/docs/how-to/test-your-project/test-driven-development.md b/docs/how-to/test-your-project/test-driven-development.md index 2f71ad067df..16d15f4db59 100644 --- a/docs/how-to/test-your-project/test-driven-development.md +++ b/docs/how-to/test-your-project/test-driven-development.md @@ -1,4 +1,4 @@ -# How-To: Test-Driven Development in F Prime (F´) +# Test-Driven Development in F Prime (F´) This guide shows a practical, repeatable test-driven development loop for building an F´ component. You’ll model behavior first in FPP, stub the implementation, write tests that fail, then implement the component until the tests pass—iterating as needed. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 47e4c86a63b..fe70ed0a7c5 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -16,7 +16,7 @@ theme: language: en logo: assets/images/logo-fprime-jpl.svg favicon: assets/images/favicon.svg - custom_dir: ../../overrides # external directory + #custom_dir: ../../overrides # external directory icon: annotation: material/information-slab-circle # custom icon for annotations @@ -72,6 +72,9 @@ extra_css: plugins: - search # enables search - awesome-nav + - gen-files: + scripts: + - how-to/scripts/gen_how_to.py - mike: # symlink are not allowed in GH Pages so if website needs to be deployed on GH Pages, use `copy` instead # see https://github.blog/changelog/2023-02-21-github-pages-deprecating-symlinks-in-non-actions-builds/ From 589a6ffc9e7af94d6ced3d6c2039469b30f2ccf7 Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Wed, 10 Jun 2026 11:33:40 -0700 Subject: [PATCH 6/8] Adding theme back in --- docs/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fe70ed0a7c5..24533536416 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -16,7 +16,7 @@ theme: language: en logo: assets/images/logo-fprime-jpl.svg favicon: assets/images/favicon.svg - #custom_dir: ../../overrides # external directory + custom_dir: ../../overrides # external directory icon: annotation: material/information-slab-circle # custom icon for annotations From d245e7203104e5e9c36ba950dc5ff323941f283c Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Thu, 11 Jun 2026 10:09:19 -0700 Subject: [PATCH 7/8] PrmDb move --- .../gds-and-operations/prm-write-how-to.md | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 docs/how-to/gds-and-operations/prm-write-how-to.md diff --git a/docs/how-to/gds-and-operations/prm-write-how-to.md b/docs/how-to/gds-and-operations/prm-write-how-to.md new file mode 100644 index 00000000000..8fceb74996a --- /dev/null +++ b/docs/how-to/gds-and-operations/prm-write-how-to.md @@ -0,0 +1,241 @@ +# Load Parameters in Batch + + +## Overview + +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. + +*Contents:* + +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 in Batch? + +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" + } + } +} +``` +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**. + +> [!TIP] +> **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 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 + +Now you will run the `fprime-prm-write` 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: Load the Parameter 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 path +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) +6. Send the command +7. Check the **Events** tab for `PrmFileLoadComplete` + +**Expected events:** + +| Event | Status | Description | +|-------|--------|-------------| +| `PrmFileLoadComplete` | ✓ | File loaded successfully | +| `PrmDbFileLoadFailed` | ✗ | File not found | +| `PrmFileBadCrc` | ✗ | CRC checksum error | + +### Step 3: Commit the Staged Parameters + +After verifying the load succeeded, commit to make parameters active: + +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 + +**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 + --format json + --output downlinked_params.json + ``` + +3. Compare with your input + ```bash + diff params.json downlinked_params.json + ``` + +## Method 2: Generate a `.seq` File + +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. + +### 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 + ``` + This creates `params.bin`. + +2. Load the sequence into `CmdSequencer` in the GDS GUI: + 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`) + - `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" + ``` +| 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://fprime.jpl.nasa.gov/devel/docs/user-manual/gds/seqgen/). + +## 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 (uplinked to the spacecraft, providing the onboard file path). + +### 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. [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 b2bdc2676b7472cef768194ceb14a478c46baacf Mon Sep 17 00:00:00 2001 From: Specky26826 Date: Mon, 15 Jun 2026 09:38:25 -0700 Subject: [PATCH 8/8] rename how-to folders --- .../data-products.md | 0 .../define-state-machines.md | 0 .../develop-device-driver.md | 0 .../develop-fprime-libraries.md | 0 .../develop-subtopologies.md | 0 .../implement-radio-manager.md | 0 .../python-development.md | 0 docs/how-to/index.md | 40 ++- .../custom-framing.md | 0 .../implement-osal.md | 0 .../integrate-external-libraries.md | 0 .../porting-guide.md | 0 .../derive-channels-on-ground.md | 0 .../develop-gds-plugins.md | 0 .../prm-write-how-to.md | 0 docs/how-to/prm-write-how-to.md | 241 ------------------ .../rule-based-testing.md | 0 .../test-driven-development.md | 0 18 files changed, 16 insertions(+), 265 deletions(-) rename docs/how-to/{develop-your-project => dev}/data-products.md (100%) rename docs/how-to/{develop-your-project => dev}/define-state-machines.md (100%) rename docs/how-to/{develop-your-project => dev}/develop-device-driver.md (100%) rename docs/how-to/{develop-your-project => dev}/develop-fprime-libraries.md (100%) rename docs/how-to/{develop-your-project => dev}/develop-subtopologies.md (100%) rename docs/how-to/{develop-your-project => dev}/implement-radio-manager.md (100%) rename docs/how-to/{develop-your-project => dev}/python-development.md (100%) rename docs/how-to/{integrate-libraries-and-platforms => integrate}/custom-framing.md (100%) rename docs/how-to/{integrate-libraries-and-platforms => integrate}/implement-osal.md (100%) rename docs/how-to/{integrate-libraries-and-platforms => integrate}/integrate-external-libraries.md (100%) rename docs/how-to/{integrate-libraries-and-platforms => integrate}/porting-guide.md (100%) rename docs/how-to/{gds-and-operations => ops}/derive-channels-on-ground.md (100%) rename docs/how-to/{gds-and-operations => ops}/develop-gds-plugins.md (100%) rename docs/how-to/{gds-and-operations => ops}/prm-write-how-to.md (100%) delete mode 100644 docs/how-to/prm-write-how-to.md rename docs/how-to/{test-your-project => test}/rule-based-testing.md (100%) rename docs/how-to/{test-your-project => test}/test-driven-development.md (100%) diff --git a/docs/how-to/develop-your-project/data-products.md b/docs/how-to/dev/data-products.md similarity index 100% rename from docs/how-to/develop-your-project/data-products.md rename to docs/how-to/dev/data-products.md diff --git a/docs/how-to/develop-your-project/define-state-machines.md b/docs/how-to/dev/define-state-machines.md similarity index 100% rename from docs/how-to/develop-your-project/define-state-machines.md rename to docs/how-to/dev/define-state-machines.md diff --git a/docs/how-to/develop-your-project/develop-device-driver.md b/docs/how-to/dev/develop-device-driver.md similarity index 100% rename from docs/how-to/develop-your-project/develop-device-driver.md rename to docs/how-to/dev/develop-device-driver.md diff --git a/docs/how-to/develop-your-project/develop-fprime-libraries.md b/docs/how-to/dev/develop-fprime-libraries.md similarity index 100% rename from docs/how-to/develop-your-project/develop-fprime-libraries.md rename to docs/how-to/dev/develop-fprime-libraries.md diff --git a/docs/how-to/develop-your-project/develop-subtopologies.md b/docs/how-to/dev/develop-subtopologies.md similarity index 100% rename from docs/how-to/develop-your-project/develop-subtopologies.md rename to docs/how-to/dev/develop-subtopologies.md diff --git a/docs/how-to/develop-your-project/implement-radio-manager.md b/docs/how-to/dev/implement-radio-manager.md similarity index 100% rename from docs/how-to/develop-your-project/implement-radio-manager.md rename to docs/how-to/dev/implement-radio-manager.md diff --git a/docs/how-to/develop-your-project/python-development.md b/docs/how-to/dev/python-development.md similarity index 100% rename from docs/how-to/develop-your-project/python-development.md rename to docs/how-to/dev/python-development.md diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 3be79cf56cb..6f4ec929966 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -16,7 +16,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide will walk you through the process of developing GDS plugins. - [View Develop F´ GDS Plugins](gds-and-operations/develop-gds-plugins.md){ .md-button .md-button--primary } + [View Develop F´ GDS Plugins](ops/develop-gds-plugins.md){ .md-button .md-button--primary } - __F´ Library Development__ @@ -24,7 +24,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This how to will walk you through the structure and best practices in developing an F´ library. - [View Develop F´ Libraries](develop-your-project/develop-fprime-libraries.md){ .md-button .md-button--primary } + [View Develop F´ Libraries](dev/develop-fprime-libraries.md){ .md-button .md-button--primary } - __Integrating Third-Party Libraries__ @@ -33,7 +33,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This how to will walk you through how to integrate non-F´ libraries into your F´ project. It will cover multiple approaches based on examples with [OpenCV](https://github.com/opencv/opencv), [OpenSSL](https://github.com/openssl/openssl) and [ETL](https://github.com/etlcpp/etl). - [View Integrating Third-Party Libraries](integrate-libraries-and-platforms/integrate-external-libraries.md){ .md-button .md-button--primary } + [View Integrating Third-Party Libraries](integrate/integrate-external-libraries.md){ .md-button .md-button--primary } - __Porting F´ To a New Platform__ @@ -41,7 +41,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This how to will walk you through porting F´ to a new platform. - [View Porting Guide](integrate-libraries-and-platforms/implement-osal.md){ .md-button .md-button--primary } + [View Porting Guide](integrate/implement-osal.md){ .md-button .md-button--primary } - __Implement a Framing Protocol__ @@ -50,7 +50,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to implement a custom framing protocol in F Prime flight software and integrate it with the F Prime GDS. - [View Implement a Framing Protocol](integrate-libraries-and-platforms/custom-framing.md){ .md-button .md-button--primary } + [View Implement a Framing Protocol](integrate/custom-framing.md){ .md-button .md-button--primary } - __Generate Data Products__ @@ -58,7 +58,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you when to use data products, how to generate them, how to test them, and how to integrate them into your topology and ground system. - [View Generate Data Products](develop-your-project/data-products.md){ .md-button .md-button--primary } + [View Generate Data Products](dev/data-products.md){ .md-button .md-button--primary } - __Define State Machines__ @@ -66,7 +66,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to define and use state machines in F Prime with FPP so complex component behavior is explicit, testable, and maintainable. - [View Define State Machines](develop-your-project/define-state-machines.md){ .md-button .md-button--primary } + [View Define State Machines](dev/define-state-machines.md){ .md-button .md-button--primary } - __Create Ground-Derived Channels__ @@ -74,7 +74,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to compute telemetry-derived values on the ground and publish them through the F Prime GDS plugin system. - [View Create Ground-Derived Channels](gds-and-operations/derive-channels-on-ground.md){ .md-button .md-button--primary } + [View Create Ground-Derived Channels](ops/derive-channels-on-ground.md){ .md-button .md-button--primary } - __Develop a Device Driver__ @@ -82,7 +82,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to build a new device driver in F Prime using the application-manager-driver pattern. - [View Develop a Device Driver](develop-your-project/develop-device-driver.md){ .md-button .md-button--primary } + [View Develop a Device Driver](dev/develop-device-driver.md){ .md-button .md-button--primary } - __Develop a Subtopology__ @@ -90,7 +90,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to organize reusable topology architecture into subtopologies that can be imported into deployments. - [View Develop a Subtopology](develop-your-project/develop-subtopologies.md){ .md-button .md-button--primary } + [View Develop a Subtopology](dev/develop-subtopologies.md){ .md-button .md-button--primary } - __Implement an OS Abstraction Layer__ @@ -98,7 +98,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to implement a new OS Abstraction Layer for F´ so the framework can run on another operating system. - [View Implement an OS Abstraction Layer](integrate-libraries-and-platforms/implement-osal.md){ .md-button .md-button--primary } + [View Implement an OS Abstraction Layer](integrate/implement-osal.md){ .md-button .md-button--primary } - __Implement a Radio Manager Component__ @@ -106,7 +106,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to implement a radio manager component using the communications adapter interface. - [View Implement a Radio Manager Component](develop-your-project/implement-radio-manager.md){ .md-button .md-button--primary } + [View Implement a Radio Manager Component](dev/implement-radio-manager.md){ .md-button .md-button--primary } - __Develop Components in Python__ @@ -114,7 +114,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to develop Python-based F Prime applications and integrate Python components into a larger system. - [View Develop Components in Python](develop-your-project/python-development.md){ .md-button .md-button--primary } + [View Develop Components in Python](dev/python-development.md){ .md-button .md-button--primary } - __Write Rule-Based Tests__ @@ -122,7 +122,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you how to write rule-based unit tests for F Prime components using the RuleDemo example component. - [View Write Rule-Based Tests](test-your-project/rule-based-testing.md){ .md-button .md-button--primary } + [View Write Rule-Based Tests](test/rule-based-testing.md){ .md-button .md-button--primary } - __Test-Driven Development__ @@ -130,7 +130,7 @@ How-To guides offer step-by-step instructions for specific development tasks in This guide shows you a practical test-driven development loop for building an F´ component from model to implementation. - [View Test-Driven Development](test-your-project/test-driven-development.md){ .md-button .md-button--primary } + [View Test-Driven Development](test/test-driven-development.md){ .md-button .md-button--primary } - __Import Parameters in Batch__ @@ -138,14 +138,6 @@ How-To guides offer step-by-step instructions for specific development tasks in 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 } - -- __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 } + [View Import Parameters in Batch](ops/prm-write-how-to.md){ .md-button .md-button--primary } \ No newline at end of file diff --git a/docs/how-to/integrate-libraries-and-platforms/custom-framing.md b/docs/how-to/integrate/custom-framing.md similarity index 100% rename from docs/how-to/integrate-libraries-and-platforms/custom-framing.md rename to docs/how-to/integrate/custom-framing.md diff --git a/docs/how-to/integrate-libraries-and-platforms/implement-osal.md b/docs/how-to/integrate/implement-osal.md similarity index 100% rename from docs/how-to/integrate-libraries-and-platforms/implement-osal.md rename to docs/how-to/integrate/implement-osal.md diff --git a/docs/how-to/integrate-libraries-and-platforms/integrate-external-libraries.md b/docs/how-to/integrate/integrate-external-libraries.md similarity index 100% rename from docs/how-to/integrate-libraries-and-platforms/integrate-external-libraries.md rename to docs/how-to/integrate/integrate-external-libraries.md diff --git a/docs/how-to/integrate-libraries-and-platforms/porting-guide.md b/docs/how-to/integrate/porting-guide.md similarity index 100% rename from docs/how-to/integrate-libraries-and-platforms/porting-guide.md rename to docs/how-to/integrate/porting-guide.md diff --git a/docs/how-to/gds-and-operations/derive-channels-on-ground.md b/docs/how-to/ops/derive-channels-on-ground.md similarity index 100% rename from docs/how-to/gds-and-operations/derive-channels-on-ground.md rename to docs/how-to/ops/derive-channels-on-ground.md diff --git a/docs/how-to/gds-and-operations/develop-gds-plugins.md b/docs/how-to/ops/develop-gds-plugins.md similarity index 100% rename from docs/how-to/gds-and-operations/develop-gds-plugins.md rename to docs/how-to/ops/develop-gds-plugins.md diff --git a/docs/how-to/gds-and-operations/prm-write-how-to.md b/docs/how-to/ops/prm-write-how-to.md similarity index 100% rename from docs/how-to/gds-and-operations/prm-write-how-to.md rename to docs/how-to/ops/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 deleted file mode 100644 index 2b1e3e02527..00000000000 --- a/docs/how-to/prm-write-how-to.md +++ /dev/null @@ -1,241 +0,0 @@ -# How-To: Load Parameters in Batch - - -## Overview - -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. - -*Contents:* - -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 in Batch? - -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" - } - } -} -``` -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**. - -> [!TIP] -> **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 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 - -Now you will run the `fprime-prm-write` 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: Load the Parameter 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 path -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) -6. Send the command -7. Check the **Events** tab for `PrmFileLoadComplete` - -**Expected events:** - -| Event | Status | Description | -|-------|--------|-------------| -| `PrmFileLoadComplete` | ✓ | File loaded successfully | -| `PrmDbFileLoadFailed` | ✗ | File not found | -| `PrmFileBadCrc` | ✗ | CRC checksum error | - -### Step 3: Commit the Staged Parameters - -After verifying the load succeeded, commit to make parameters active: - -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 - -**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 - --format json - --output downlinked_params.json - ``` - -3. Compare with your input - ```bash - diff params.json downlinked_params.json - ``` - -## Method 2: Generate a `.seq` File - -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. - -### 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 - ``` - This creates `params.bin`. - -2. Load the sequence into `CmdSequencer` in the GDS GUI: - 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`) - - `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" - ``` - | 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://fprime.jpl.nasa.gov/devel/docs/user-manual/gds/seqgen/). - -## 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 (uplinked to the spacecraft, providing the onboard file path). - -### 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. [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/) diff --git a/docs/how-to/test-your-project/rule-based-testing.md b/docs/how-to/test/rule-based-testing.md similarity index 100% rename from docs/how-to/test-your-project/rule-based-testing.md rename to docs/how-to/test/rule-based-testing.md diff --git a/docs/how-to/test-your-project/test-driven-development.md b/docs/how-to/test/test-driven-development.md similarity index 100% rename from docs/how-to/test-your-project/test-driven-development.md rename to docs/how-to/test/test-driven-development.md