UWA Jetski Code

This is the code for both the new and old hydrofoil jetski at UWA.

Directories

• shared_components: Components shared across firmware projects. Each firmware's top-level CMakeLists.txt adds this path with list(APPEND EXTRA_COMPONENT_DIRS ".../shared_components") so main's transitive REQUIRES (with MINIMAL_BUILD) pulls only what's needed — no symlink farm under projects/*/components.

• projects: ESP-IDF projects, each targeting a specific ESP32 with a specific purpose. See each project's README for details.

• scripts: Utility scripts for development. Run directly or via the aliases provided by activate_scripts.sh:

  • build.py: Wrapper for idf.py build.
  • save_defconfig.py: Wrapper for idf.py save-defconfig.
  • clean.py: Removes build artifacts.
  • flash.py: Wrapper for idf.py flash, using the serial port defined in .serial_port.
  • monitor.py: PTY wrapper for idf.py monitor, using the serial port defined in .serial_port.
  • choose_port.py: Interactive serial port selector that saves the choice to a project's .serial_port (also supports non-interactive use).
  • setup_clangd.py: Sets up clangd (LSP) support. Runs idf.py reconfigure with the clang toolchain into build.clang for each project, then merges all compile_commands.json files into the repo root. No compilation is performed — purely for IDE language-server support.
  • activate_scripts.sh: Source this script (do not run it directly) to add the scripts directory to your PATH and create convenient aliases. Use source ./activate_scripts.sh from the repo root. After sourcing, you can use build, save_defconfig, clean, flash, monitor, choose_port, and setup_clangd directly without the .py extension.
  • Shell tab-completion is installed by activate_scripts.sh for all script commands/aliases, including dynamic completion for -p/--project values.
  • All scripts support -p/--project with a project name. Scripts that support multiple projects (build, save_defconfig, clean, flash, setup_clangd) accept repeated flags or comma-separated values.
  • Script target selection rules:
    • From repo root: multi-project scripts run for all projects when -p/--project is omitted.
    • From a project root (projects/<name>): scripts run for that project when -p/--project is omitted.
    • Otherwise: scripts error unless -p/--project is provided.
    • monitor and choose_port are limited to one project at a time.
  • choose_port.py uses -P/--port to specify a serial port (-p is reserved for project selection).
  • Scripts discover project names dynamically from directories under projects that contain CMakeLists.txt.
  • In monitor.py, Ctrl+C exits immediately; all other key input is passed through normally.

Development Guidelines

These are more requirements than guidelines but 🤷‍♂️.

• Use scripts from the scripts directory instead of idf.py where possible.
  • Run from repo root to target all projects, or from a project root to target just that project.
  • Use -p/--project when running from other directories or to select specific projects.
• Always modify sdkconfig, not sdkconfig.defaults. Run save_defconfig before committing — sdkconfig is gitignored.
• Do not modify any components in managed_components; it is autogenerated.
• If a component is used in more than one project, it should be in shared_components.
• For editor/IDE support (clangd LSP), run setup_clangd after initial setup and again after adding/removing components or running clean. This reconfigures all projects with the clang toolchain and merges compile_commands.json files into the repo root — no compilation involved.
• No legacy code or backwards-compatibility shims. When implementing new functionality no need to leave anything "just in case".