README.md

Foxglove Custom Extensions

This monorepo contains our custom Foxglove development tools and extensions.

Setup

For initial setup instructions, follow the root SETUP.md file.

Using foxglove.py

Important

The foxglove.py CLI should be run inside the Docker container. For more details see SETUP.md.

The foxglove.py CLI provides a unified interface to manage our custom extensions. It integrates commands from the foxglove, foxglove-extension, and npm CLIs. Extensions can be installed locally or published to our organization.

To run the CLI you can use python3 foxglove.py (inside of the foxglove directory) or its alias fox (declared in ros_bashrc.sh).

Quick Start

There are two steps in the installation process:

1. Build: Prepares an extension for installation or publishing.
2. Install: Locally installs an extension.

Therefore, to install all extensions, run:

fox build
fox install

To clean up the Foxglove monorepo and uninstall local extensions, run:

fox clean
fox uninstall

Clean and uninstall will revert the changes made by build and install respectively.

User Guide

fox [SUBCOMMAND]

• b, build - Build all necessary dependencies for Foxglove development.
• i, install - Install Foxglove extensions locally.
• w, watch - Automatically reinstall a Foxglove extension after changes.
• l, lint - Lint the Foxglove monorepo.
• p, publish - Publish Foxglove extensions to an organization.
• c, clean - Remove build files from the Foxglove monorepo.
• u, uninstall - Uninstall all local Foxglove extensions.
• d, doctor - Troubleshoot the Foxglove development environment.

You can also run fox [SUBCOMMAND] -h to view a help message.

Build

Important

Building must be performed before local installing or publishing custom extensions. Additionally, building is a prerequisite for fox lint (eslint) and other Foxglove developer tools.

To build, run:

fox build [OPTIONS]

• --skip-ci: Use existing node_modules instead of clean installing external dependencies.

By default, fox build does several things:

1. Install external dependencies to node_modules using npm ci.
2. Patch external dependencies using patch-package.
3. Build local dependencies in foxglove/shared/.
4. Build per-extension dependencies by running npm run build.

Tip

After building once, you only need to rebuild after changes are made to the extension dependencies (e.g., package.json, anything in foxglove/shared/, etc.).

Install

To perform a local install, run:

fox install [extensions ...]

• extensions: A list of extensions to install. If no extensions are given, all extensions are installed.

This will execute the command npm run local-install for each extension specified.

Note

Extensions are installed at ~/.foxglove-studio/extensions/ and will have the prefix dukerobotics.ros-jazzy-.

Watch

To watch an extension for changes, run:

fox watch extension

This will automatically execute npm run local-install upon .ts or .tsx file changes in the src directory.

Lint

To lint the Foxglove monorepo, run:

fox lint [files ...]

• files: A list of files to lint. If no files are given, the entire Foxglove monorepo is linted.
• -f, --fix: Attempt to autofix linting errors by modifying files in place.

Publish

Important

To publish extensions, you must set up the .foxgloverc file. See SETUP.md for more details.

When you are ready to publish custom extensions to your organization, run:

fox publish [extensions ...]

• extensions: A list of extensions to publish. If no extensions are given, all extensions are published.
• -v, --version: Version to publish extensions under. If no version is given, the short (length 7) HEAD commit hash is used. A version is required if the robosub-ros2 git reposititory is dirty.
• -f, --force: Publish extensions even if the repository is dirty.
• --github-action: Append -prod to the publish version (to avoid version collisions).

Clean

To clean up the Foxglove monorepo, run:

fox clean

This launches an interactive session where you can remove files generated during fox build.

Uninstall

To uninstall all Duke Robotics extensions, run:

fox uninstall

This removes all files generated during fox install.

Doctor

To troubleshoot the Foxglove development environment, run:

fox doctor

This command will exit with a non-zero status if any potential problems are found.

Using Foxglove Studio

Note

When testing local extensions, the desktop version of Foxglove Studio must be used.

1. Run the following command to start the Foxglove bridge:

   fg-ws

   • This is an alias that starts the Foxglove bridge, which enables Foxglove Studio to connect to the ROS 2 network.
   • The bridge opens a WebSocket on port 28765. This port is mapped to port 28765 on the host machine, so you can connect to the WebSocket from your host machine.
2. Open Foxglove Studio and connect to the WebSocket at ws://IP_ADDRESS:28765.
   • Replace IP_ADDRESS with the IP address of the host machine. If you are running the Docker container locally, you can use localhost as the IP address.

Monorepo Structure

Extensions

• publish-topic-panel - Panel to publish topics
• toggle-controls-panel - Panel to toggle controls on/off
• system-status-panel - Panel that displays system usage of the onboard computer
• sensors-status-panel - Panel that displays the connected/disconnected status of sensors
• thruster-allocs-panel - Panel that displays the current thruster allocs and publishes desired thruster allocs
• toggle-joystick-panel - Panel to toggle joystick control on/off, as well as publish transformed joystick inputs as a desired power
• toggle-keyboard-panel - Panel to toggle keyboard control on/off, as well as publish transformed keyboard inputs as a desired power
• pid-panel - Panel to read/set PID gains
• discrete-servos-panel - Panel to control discrete servos

Local Dependencies

Local dependencies are located in the shared/ directory.

• defs - Exports Foxglove datatype maps and TypeScript interfaces/enums for both ROS 2 and Duke Robotics message definitions
• theme - Exports the Duke Robotics MUI Theme
• robot-name - Exports the Robot enum and related utilities used for implementing robot-specific behavior
• utils - Exports shared utility functions used across Foxglove extensions

Patches

Patches to external node modules are located in the patches/ directory. Running fox build will automatically apply these patches.

• create-foxglove-extension+1.0.4.patch
  • No longer require README.md or CHANGELOG.md when installing an extension
  • Before installing an extension, only remove dist/extension.js (instead of cleaning the entire dist directory)

Monorepo Root Files

• eslint.config.mjs - Configuration file for ESLint
• .eslintignore - Ignore file for ESLint
• .npmrc - Configuration file for npm
• .prettierrc.yaml - Configuration file for Prettier
• tsconfig.json Configuration file for TypeScript
• package.json - Metadata file for the Foxglove monorepo
• package-lock.json - The npm dependency tree of the Foxglove monorepo, generated using npm i

Contributing

Adding a New Extension

Copy an existing Duke Robotics extension as a starting point. This ensures that all of our extensions have the same code structure and use the same core set of dependencies.

Adding a New Local Dependency

All local dependencies must expose an npm run build command in package.json. During build, foxglove.py will compile each local dependency to node_modules where they can be consumed by an extension.

Additional Documentation

See the Foxglove documentation for more details on extension development.