Merge pull request #3 from jwest115/devel

Sync `fpp/349` with `devel`

.github/workflows/build-test-rpi.yml

@@ -17,7 +17,7 @@ on:
       - '.github/ISSUE_TEMPLATE/**'
 env:
   RPI_TOOLCHAIN_DIR: /tmp/rpi-toolchain
-  DICTIONARY_PATH: build-artifacts/raspberrypi/RPI/dict/RPITopologyAppDictionary.xml
+  DICTIONARY_PATH: build-artifacts/raspberrypi/RPI/dict/RPITopologyDictionary.json
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
   RPI:
@@ -55,12 +55,23 @@ jobs:
     runs-on: self-hosted
     needs: RPI
     steps:
+    - uses: actions/checkout@v4
+      with:
+        sparse-checkout: 'requirements.txt'
+    - name: "Setup environment"
+      run: |
+        python -m venv venv
+        . venv/bin/activate
+        pip install -r requirements.txt
     - name: RPI Build Download
       uses: actions/download-artifact@v3
       with:
         name: rpi-build
     - name: RPI Integration Tests
-      run: chmod +x RPI/build-artifacts/raspberrypi/RPI/bin/RPI; /bin/bash ci/tests/RPI-Ints.bash
+      run: |
+        chmod +x RPI/build-artifacts/raspberrypi/RPI/bin/RPI
+        . venv/bin/activate
+        /bin/bash ci/tests/RPI-Ints.bash
     # Archive the outputs
     - name: 'Archive Logs'
       uses: actions/upload-artifact@v3

.github/workflows/ext-raspberry-led-blinker.yml

@@ -70,11 +70,15 @@ jobs:
     runs-on: self-hosted
     needs: cross-compilation
     steps:
+      - name: "Checkout F´ Repository"
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: 'requirements.txt'
       - name: "Setup environment"
         run: |
           python -m venv venv
           . venv/bin/activate
-          pip install fprime-gds
+          pip install -r requirements.txt
       - name: "Artifacts Download"
         uses: actions/download-artifact@v3
         with:
@@ -86,7 +90,7 @@ jobs:
           chmod +x ./build-artifacts/raspberrypi/LedBlinker/bin/LedBlinker
           fprime-gds --ip-client -d ./build-artifacts/raspberrypi/LedBlinker --logs ./ci-logs &
           sleep 10
-          pytest --dictionary ./build-artifacts/raspberrypi/LedBlinker/dict/LedBlinkerTopologyAppDictionary.xml ./int/led_integration_tests.py
+          pytest --dictionary ./build-artifacts/raspberrypi/LedBlinker/dict/LedBlinkerTopologyDictionary.json ./int/led_integration_tests.py
       - name: 'Archive logs'
         uses: actions/upload-artifact@v3
         if: always()

RPI/README.md

@@ -83,7 +83,7 @@ home network where the pi and the user's computer are connected to the same netw
 
 ```
 cd fprime/RPI
-fprime-gds -n --dictionary ./build-artifacts/raspberrypi/dict/RPITopologyAppDictionary.xml
+fprime-gds -n --dictionary ./build-artifacts/raspberrypi/dict/RPITopologyDictionary.json
 ```
 The ground station should now appear in the user's default browser. Should the user wish to terminate the ground system, return to that terminal
 and press CTRL-C to shut it down. Please allow it a few moments to finalize and exit.  The user may then kill the browser tab displaying the GUI.

ci/tests/fputil.bash

@@ -69,7 +69,7 @@ function integration_test_run {
         mkdir -p "${LOG_DIR}/gds-logs"
         # Start the GDS layer and give it time to run
         echo "[INFO] Starting headless GDS layer"
-        fprime-gds -n --dictionary "${ROOTDIR}/"*"/${BINARY}/dict/${BINARY}TopologyAppDictionary.xml" -g none -l "${LOG_DIR}/gds-logs" 1>${LOG_DIR}/gds-logs/fprime-gds.stdout.log 2>${LOG_DIR}/gds-logs/fprime-gds.stderr.log &
+        fprime-gds -n --dictionary "${ROOTDIR}/"*"/${BINARY}/dict/${BINARY}TopologyDictionary.json" -g none -l "${LOG_DIR}/gds-logs" 1>${LOG_DIR}/gds-logs/fprime-gds.stdout.log 2>${LOG_DIR}/gds-logs/fprime-gds.stderr.log &
         GDS_PID=$!
         # run the app with valgrind in the background
         if command -v valgrind &> /dev/null

docs/UsersGuide/gds/gds-cli.md

@@ -152,12 +152,12 @@ Retrieval Options:
 
 As mentioned, these CLI commands let you interact with the GDS through events and commands, and telemetry channels.
 Through a *project F´ dictionary* the CLI can understand what commands, events and telemetry channels are available.
-Every F´ project deployment will have a `*Dictionary.xml` file that's created when the project's deployment is built
-In the `Ref` example project, it'll be the `Ref/Top/RefTopologyAppDictionary.xml` file.  By reading this file, the CLI
+Every F´ project deployment will have a `*Dictionary.json` file that's created when the project's deployment is built
+In the `Ref` example project, it'll be the `Ref/Top/RefTopologyDictionary.json` file.  By reading this file, the CLI
 tool knows what to look for when it's reading or sending data to the GDS. If it doesn't know where the dictionary is,
 then the CLI tool can't do much beyond printing out help messages.
 
-When you run one of the CLI commands, the tool will automatically look for files ending in `Dictionary.xml` in your
+When you run one of the CLI commands, the tool will automatically look for files ending in `Dictionary.json` in your
 current working directory and use the first one it can find. This behavior is similar to how `fprime-gds` searches for
 dictionaries it uses to construct the browser GUI. If it can't find any dictionaries, it will print out an error message
 like this:
@@ -168,7 +168,7 @@ fprime-cli: error: No valid project dictionary found
 
 Running commands from your project folder (e.g. inside `fprime/Ref`) should work to find a dictionary, but if you want
 to run commands for a different deployment or project, you can specify the dictionary file exactly using the
-`--dictionary` option with the file's path. `fprime-cli command-send --dictionary Ref/Top/RefTopologyAppDictionary.xml`.
+`--dictionary` option with the file's path. `fprime-cli command-send --dictionary Ref/Top/RefTopologyDictionary.json`.
 
 ### Using the Tools
 

docs/UsersGuide/gds/seqgen.md

@@ -37,7 +37,7 @@ Below is an example of how to run the sample example sequence with the Ref dicti
 dictionary will not be generated.
 
 ```
-fprime-seqgen fprime/Gds/examples/simple_sequence.seq -d fprime/Ref/build-artifacts/*/dict/RefTopologyAppDictionary.xml
+fprime-seqgen fprime/Gds/examples/simple_sequence.seq -d fprime/Ref/build-artifacts/*/dict/RefTopologyDictionary.json
 ```
 
 Here the output file is not specified, so it will be a new file in the same directory as the sequence but ending with

docs/UsersGuide/guide.md

@@ -40,6 +40,7 @@ This section is divided into four sub-sections:
     - [Data Types and Data Structures: Primitive Types, Enums, Arrays, and Serializables](user/enum-arr-ser.md)
     - [Data Constructs: Commands, Events, Channels, and Parameters](user/cmd-evt-chn-prm.md)
     - [Unit Testing F´ Components](./user/unit-testing.md)
+    - [Troubleshooting FAQ](../troubleshooting.md)
 - F´ Best Practices: helpful patterns when developing F´ software
     - [F´ Development Process](./best/development-practice.md)
     - [Application, Manager, Driver Pattern](./best/app-man-drv.md)

docs/troubleshooting.md

@@ -23,11 +23,26 @@ Some of the F´ Python packages are built in a way that it is recommended to ins
 
 ## fprime-util: command not found
 
-If the user is using a virtual environment and receives the ‘command not found’, the problem is likely caused by the environment not being sourced in a new terminal. Make sure to source the environment before running:
-```
-. <path/to/project>/fprime-venv/bin/activate
-```
-If installing without a virtual environment, PIP occasionally uses `$HOME/.local/bin` as a place to install user tools. Users running without virtual environments should add this directory to the path.
+There are at least three common reasons for this error.
+
+1. If the user is using a virtual environment and receives the ‘command not found’, the problem is likely caused by the environment not being sourced in a new terminal. Make sure to source the environment before running:
+    ```sh
+    # In MyProject
+    . fprime-venv/bin/activate
+    ```
+
+1. If the project folder was moved after the virtual environment was provisioned (e.g. project was originally setup in `/folderA/MyProject` and moved to `/someOtherFolder/MyProject`), various files in the original `fprime-venv` folder will contain references to the original path. The easiest resolution is to remove and reprovision the virtual environment with the following:
+    ```sh
+    # In MyProject
+    rm -rf fprime-venv
+    python -m venv fprime-venv
+    . fprime-venv/bin/activate
+    pip install -r fprime/requirements.txt
+    ```
+
+    > Some projects ship their own `requirements.txt`.  Install using that file if it exists.
+
+1. If installing without a virtual environment, PIP occasionally uses `$HOME/.local/bin` as a place to install user tools. Users running without virtual environments should add this directory to the path.
 
 ## Helper script ‘fpp-redirect-helper’ exited with reason: Permission denied
 This error can occur when the helper-script, (`fprime/cmake/autocoder/fpp-wrapper/fpp-redirect-helper`) loses its execution permission.