Merge branch 'feature/simcb'

.gitignore

@@ -1,3 +1,3 @@
-.vscode/
+./.vscode/
 core.[0-9]*
-package/
+package/build/

package.sh → changeversion.sh

@@ -1,5 +1,9 @@
 #!/usr/bin/env bash
 
+# Work in same directory as this script
+DIR=$(realpath $(dirname "$0"))
+cd "$DIR"
+
 # Exit if any command errors
 set -e
 trap 'last_command=$current_command; current_command=$BASH_COMMAND' DEBUG
@@ -13,7 +17,7 @@ echo "    a = alpha"
 echo "    b = beta"
 echo "    c = release candidate (rc)"
 echo "    - = full release"
-echo "  If type is specified (not space), also provide a build number."
+echo "  If type is specified (not hyphen), also provide a build number."
 echo "  Nubmers (major, minor, revision, build) must be 0-255 (inclusive)"
 echo ""
 read -p "Major: " VER_MAJOR
@@ -40,24 +44,6 @@ else
 fi
 echo ""
 
-
-# Work in same directory as this script
-DIR=$(realpath $(dirname "$0"))
-cd "$DIR"
-
-# Base directory structure
-rm -rf package/
-mkdir package/
-mkdir package/firmware/
-mkdir package/firmware/tools/
-mkdir package/firmware/build/
-mkdir package/firmware/build/v1/
-mkdir package/firmware/build/v2/
-mkdir package/firmware/source/
-mkdir package/iface/
-mkdir package/iface/scripts/
-mkdir package/iface/example/
-
 # Update version in firmware code
 sed -i "s/#define FW_VER_MAJOR.*/#define FW_VER_MAJOR $VER_MAJOR/g" firmware/include/metadata.h
 sed -i "s/#define FW_VER_MINOR.*/#define FW_VER_MINOR $VER_MINOR/g" firmware/include/metadata.h
@@ -69,51 +55,4 @@ sed -i "s/#define FW_VER_BUILD.*/#define FW_VER_BUILD $VER_BUILD/g" firmware/inc
 sed -i "s/VER_STR = .*/VER_STR = \"$VERSION_SHORT\"/g" iface/control_board.py
 
 # Write version file
-echo "$VERSION" > package/version.txt
-
-# Build firmware
-cd firmware
-rm -rf build/
-cmake --preset v1
-cmake --build --preset v1-release
-cmake --preset v2
-cmake --build --preset v2-release
-cd ..
-
-# Copy firmware files
-cp -r firmware/build/v1/Release/ package/firmware/build/v1/
-cp -r firmware/build/v2/Release/ package/firmware/build/v2/
-cp firmware/flash.py package/firmware/
-cp firmware/reboot_bootloader.py package/firmware/
-cp firmware/COPYING package/firmware/
-cp -r firmware/tools/uf2conv/ package/firmware/tools/
-
-cp -r firmware/src/ package/firmware/source/
-cp -r firmware/include/ package/firmware/source/
-cp -r firmware/thirdparty/ package/firmware/source/
-cp -r firmware/toolchains/ package/firmware/source/
-cp firmware/CMakeLists.txt package/firmware/source/
-cp firmware/CMakePresets.json package/firmware/source/
-
-
-
-# Copy Python interface code
-cp iface/*.py package/iface/
-cp iface/scripts/*.py package/iface/scripts/
-cp iface/example/*.py package/iface/example/
-cp iface/COPYING package/iface/COPYING
-
-# Create docs site
-cd docs
-rm -rf site
-SITE_URL="" DIR_URLS=false mkdocs build
-cd ..
-
-# Copy docs site
-cp -r docs/site package/docs/
-
-# Create zip packge
-cd package
-rm -f ./AUVControlBoard_${VERSION}.zip
-zip -r ../AUVControlBoard_${VERSION}.zip .
-mv ../AUVControlBoard_${VERSION}.zip .
+echo "$VERSION" > package/version.txt

docs/docs/firmware/build.md → docs/docs/devs/build.md

@@ -1,4 +1,4 @@
-# Build and Flash
+# Build and Flash Firmware
 
 *Note: Run all commands shown in the `firmware` folder of the repo.*
 
@@ -12,16 +12,14 @@ Install the Required Tools:
 
 *Make sure `cmake`, `ninja`, and `arm-none-eabi-gcc` are in your `PATH`.*
 
-Build the firmware using the commands below. Replace `[preset]` with `v1` or `v2`. Replace `[config]` with `debug`, `release`, `minsizerel`, or `relwithdebinfo`.
+Build the firmware using the commands below. Replace`[preset]` with `v1` or `v2` (depending on which version you are building firmware for). Replace `[config]` with `debug`, `release`, `minsizerel`, or `relwithdebinfo`.
 
 ```sh
 cmake --preset=[preset]
 cmake --build --preset=[preset]-[config]
 ```
 
 
-
-
 ## Flashing
 
 ***Note: Control Board v1 Units must update Adafruit's bootloader before first use. This only needs to be done once, but it must be done. Follow Adafruit's instructions [here](https://learn.adafruit.com/introducing-adafruit-itsybitsy-m4/update-the-uf2-bootloader). DO NOT SKIP THIS!!!***

docs/docs/devs/buildsimcb.md

@@ -0,0 +1,3 @@
+# Build and Run SimCB
+
+TODO

docs/docs/devs/developing.md

@@ -0,0 +1,127 @@
+# Firmware Development
+
+## VSCode Setup
+
+Often, it is useful to have some sort of code editor / IDE setup. The project is already setup to work easily with [Visual Studio Code](https://code.visualstudio.com/) (VSCode), provided a few extensions are installed.
+
+After installing VSCode
+
+- Install the `C/C++` and `CMake Tools`, and `Cortex-Debug` extensions for working with the firmware (`firmware/` subfolder)
+- Install the `Python` extension for working with the interface scripts (`iface/` subfolder)
+
+
+To use, just open one of the folders (eg `firmware/` or `iface/`) in VSCode. The useful extensions should automatically load when you open the folders (you may have to open a source code file in some cases).
+
+For debugging, a `launch.json` file is included in the `firmware/` project (in `.vscode` subfolder). This defines debug configurations both for firmware running on physical hardware and for the supported SimCB configurations.
+
+*Note: Launching a debug session from VSCode will not build the firmware. Make sure to build the "Debug" configuration before launching!*
+
+
+## Debugging Firmware
+
+### Debugging on Physical System
+
+This section discusses debugging of the firmware running on actual hardware (Control Board v1 or v2). Debugging firmware running on a microcontroller requires a "debug probe". The supported probes for each version of the control board are listed in the table below.
+
+| ControlBoard Version | Debugger / Debug Probe | Config Name in `tools/debug` |
+| -------------------- | ---------------------- | ---------------------------- |
+| v1                   | CMSIS-DAP*         | `cb_v1_via_cmsisdap.cfg`     |
+| v2                   | ST-LINK v2             | `cb_v2_via_stlink2.cfg`      |
+
+*The PicoProbe firmware can be used to turn a low cost Raspberry Pi Pico board into a CMSIS-DAP compliant debug probe.
+
+You must wire the debug probe to the microcontroller on the control board correctly. Both v1 and v2 use a SWD debug interface. Examples of wiring the debug probes to each are shown below.
+
+TODO: Wiring diagrams for v1 and v2
+
+***Note: NEVER power the system from both the debug probe and USB at the same time. Generally, power the system over USB and do not connect the power (3.3V) from the debug probe. Signals and GND must be connected from the debug probe.***
+
+
+Make sure that [OpenOCD](https://openocd.org/) must be installed and in the `PATH`. 
+
+On Linux systems, you will likely also need to install `gdb-multiarch` and symlink it to `arm-none-eabi-gdb`. On ubuntu, this is done with the following commands
+
+```sh
+sudo apt install gdb-multiarch
+sudo ln -s `which gdb-multiarch` /usr/local/bin/arm-none-eabi-gdb
+```
+
+Then, use VSCode to run the correct debug session for the hardware version and debug probe you are using. Alternatively, you may use openocd and gdb directly if you are not using vscode. The config files listed in the table above are just OpenOCD configs.
+
+
+### Debugging SimCB
+
+TODO: Instructions for windows, Linux, macOS
+
+
+## Generator Projects
+
+*Note: All paths in this section are relative to the `firmware/` subdirectory.*
+
+
+Each version of ControlBoard has an associated "Generator" project. These are projects used with the chip manufacturer's tools to generate startup / configuration / library code for the chip.
+
+You will only need to modify the generator projects to alter configuration of the chip / components of included libraries from these tools. The firmware copies code generated from these tools into the `thridparty` folder, thus you don't need the generators to modify the firmware, unless you are modifying generated components.
+
+### Running the Generator(s)
+
+#### Control Board v1
+
+Control Board v1 uses an Adafruit ItsyBitsy M4 board (Microchip ATSAMD51G19A chip). The generator used for this project is [MCC Standalone](https://www.microchip.com/en-us/tools-resources/configure/mplab-code-configurator). This tool is available for download on Windows, macOS, and Linux. Tested with v5.2.1 of MCC Standalone.
+
+Once installed
+
+- Launch the application
+- Make sure the Harmony Content Path is set in `Tools` > `Options`. This should only need to be done once per computer. Recommended path is `~/.mcc/harmony/v3`. On windows, use `C:\Users\[YOUR_USERNAME]\.mcc\harmony\v3` (replace `[YOUR_USERNAME]`).
+- `File` > `Load Configuration`
+- Choose `generator_projects/ControlBoard_v1/firmware/ControlBoard_v1/ControlBoard_v1.mc3`
+- You will likely be prompted to install MPLAB Harmony content. Install it.
+- Click "Generate" in the top left.
+
+#### Control Board v2
+
+Control Board v2 uses a WeAct Studio Black Pill board (STMicro STM32F411CEU chip). The generator used for this project is [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html). This tool is available for download on Windows, macOS, and Linux. Tested with v6.6.1 of STM32CubeMX.
+
+Once installed
+
+- Launch the application
+- `File` > `Load Project`
+- Choose `generator_projects/ControlBoard_v2/ControlBoard_v2.ioc`
+- Install any required packs (as prompted)
+- Click "Generate Code" in the top right.
+
+
+### Importing from Generators
+
+After running the generator (as described above) the generated code must be imported to the project. The import process is mostly just copying generated files, however some files are modified slightly. The import process is handled by the `import_from_generator.py` script. If additional components are added in the generator projects, this script may need to be modified to import additional components. When this script is run, it will prompt a version of control board to import generated code for. This script must be run after each time the generator project is modified and code is re-generated.
+
+To run the importer, run `python3 import_from_generator.py` then choose which project your are importing.
+
+
+## Firmware Development using the Simulator
+
+The [simulator](https://github.com/MB3hel/GodotAUVSim) can be very helpful for developing or debugging firmware. The simulator is capable of connecting to a real control board or SimCB binaries. Thus the firmware can be tested in a simulation environment to validate math or behavior of a vehicle. Testing with the simulator can also be done while the control board firmware is running with a debugger attached (true for both a real control board and SimCB).
+
+Testing firmware on a physical control board (v1, v2) with the simulator is fairly simple. It is assumed that you will want the debugger running too:
+
+- Connect the control board to your PC via USB
+- Connect a debug probe to the control board (do **NOT** connect power)
+- Build and run the firmware under debugger
+- In the simulator, choose the UART port for the control board
+- Interface scripts can be run as usual using `launch.py`, but add the `-s` flag so it will connect to the simulator instead of the physical control board.
+
+
+If you want to debug SimCB using the simulated environment
+
+- TODO: Requires more work on simulator UI! NYI!
+
+
+There are a few things to know about running under simulation (these are true when the firmware is hijacked by simulator)
+
+- Sensor drivers are disabled while under simulator control. Additionally, the active sensors will always be reported as the "SIM" sensors. This is true even if a real sensor is connected to a physical control board under simulation.
+- When controlled by the simulator, the control board will not generate PWM signals on thruster pins. The thruster pins will maintain a pulse corresponding to no motion (or no pulse at all if no thruster pwm parameters have been applied).
+
+
+## Developing Python Interface Scripts
+
+TODO

docs/docs/devs/overview.md

@@ -0,0 +1,19 @@
+# Overview
+
+TODO: Project Structure and Build System
+
+TODO: Generator projects
+
+<!--
+## Why Generators
+
+The decision to use generator projects comes down to the following
+
+1. There are multiple versions of Control Board with multiple chips. Using generators to create chip-specific initialization code reduces the chip-specific parts of the firmware that must be written / maintained.
+
+2. The generators are often required to use the manufacturer's HAL (or make using the HAL much easier). Use of the manufacturer's HAL / libraries reduces development time and makes maintenance easier (especially for those less familiar with the codebase).
+
+3. Having a GUI tool (which these generators usually are) to configure the system is an easy way to quickly understand the architecture of the system (clocks, peripheral use, pinout, etc).
+-->
+
+TODO: System architecture

docs/docs/devs/pythoniface.md

@@ -0,0 +1,3 @@
+# Interface Scripts
+
+TODO: Implementation details / architecture

docs/docs/devs/simulation.md

@@ -0,0 +1,39 @@
+# Simulation
+
+TODO: Why simulation
+- Reduce in-water testing time
+- Testing without hardware
+- Unit tests in complex codebases using control board
+
+## SimCB
+
+TODO: SimCB support and FreeRTOS simulation using sockets for USB
+
+TODO: Why? Allow testing comms without hardware and allows end users to easily incorporate a control board into their own simulated environments.
+
+## Simulation Hijack
+
+TODO: Simhijack and support for this in firmware (including multiple sensor stuff)
+
+TODO: Why? Allow a simulated environment to use a control board to actually control a simulated vehicle. Allows motion testing / validation without in-water time (with a real control board). Also allows debugging / testing actual firmware without in-water time with a vehicle.
+
+TODO: By combining with SimCB (which can also be simhijacked), motion can be tested without in-water time and without a real control board.
+
+
+## Simulator Implementation & Development
+
+TODO: Implementation details / tech docs
+
+TODO: Docs on adding vehicles, etc
+
+
+## Control Board Setups
+
+Thus, there are four ways a "control board" can be used
+
+- Real control board over UART
+- SimCB over TCP
+- Simulator models environment and provides inputs to control board and retrieves outputs from control board
+- Can also do this with SimCB! Simulator is a "man in the middle"
+
+TODO: Diagram of four modes.