Delsys-Unimore Drone Demo

Plug-and-play Docker workflow for Delsys Trigno, ROS 2, and Godot.
Stream EMG and IMU signals from Delsys hardware, process them through ROS 2, and control a Godot drone visualization from a single launcher.

The project is intended to run as a local hardware product: configure credentials, map sensors, build once, and start the application with make up.

Note

Docker is the recommended workflow. The image includes ROS 2 Humble, Godot 4.3, PyQt dependencies, rosbridge, and the native libraries required by the Delsys bridge.

✨ Features

• 🐳 Dockerized runtime with ROS 2 Humble and Godot 4.3.
• 📡 Delsys Trigno bridge for hardware scanning, channel mapping, and live socket streaming.
• 🧠 EMG processing with MVC calibration and normalized activation topics.
• 🧭 IMU processing with neutral-position calibration and accelerometer/gyroscope topics.
• 🎛️ PyQt control HUD for startup status, calibration, recording, and telemetry.
• 🚁 Godot drone visualization driven by ROS topic /drone/cmd_vel.
• 🔌 Dynamic ROS topic creation based on the configured sensor IDs and roles.

🧱 Repository Layout

docker/          Docker image definition for ROS 2, Godot, PyQt, and Delsys runtime dependencies
delsys_bridge/  Delsys API integration, hardware socket bridge, HUD code, and calibration state
ros2_ws/         ROS 2 workspace with interfaces, EMG processing, IMU processing, and drone control
drone-game/      Godot project, scenes, scripts, and native game assets
public/images/   Images used by the launcher UI and documentation
config/          Tracked config examples only; local hardware config is ignored

Tip

For normal use, you only need to edit .env and config/sensors.json. Everything else is already wired through Docker Compose and the Makefile.

✅ Requirements

• Linux host with Docker and the Docker Compose plugin.
• X11 display access for the PyQt launcher and Godot window.
• Delsys Trigno base connected over USB.
• Paired Delsys sensors for the roles you want to use.
• Valid Delsys API key and license.

Important

The Delsys runtime files required by the bridge are already included in delsys_bridge/resources/. You do not need to extract SDK files during normal setup.

Note

The Docker image downloads the official Godot 4.3 Linux binary during image build. No local Godot installation is required.

🚀 Quick Start

1. Create .env

cp .env.example .env

Edit .env and set your Delsys credentials:

DELSYS_API_KEY=your-api-key
DELSYS_API_LICENSE=your-license

2. Create config/sensors.json

cp config/sensors.example.json config/sensors.json

Edit config/sensors.json with each Delsys sensor GUID prefix, logical sensor ID, and role:

{
  "sensors": [
    {
      "guid_prefix": "replace-with-imu-sensor-guid-prefix",
      "sensor_id": 1,
      "role": "IMU"
    },
    {
      "guid_prefix": "replace-with-emg-sensor-guid-prefix",
      "sensor_id": 2,
      "role": "EMG"
    }
  ]
}

Tip

Use stable sensor_id values. They become part of the ROS topic names, for example /emg2 or /accx1.

3. Build the Docker image

make build

4. Build the ROS 2 workspace

make ros-build

5. Start the application

make up

The launcher opens the PyQt control interface, starts the ROS 2 pipeline, starts rosbridge, connects to the Delsys bridge, and starts the Godot drone visualization.

⚙️ Configuration

.env

The .env file is loaded by Docker Compose and is intentionally ignored by Git.

Required values:

Variable	Purpose
DELSYS_API_KEY	Delsys API key used to validate the Trigno base
DELSYS_API_LICENSE	Delsys API license string

Optional overrides are already listed in .env.example and normally do not need to be changed:

• DELSYS_APP_ROOT
• ROS_WS
• GODOT_BIN
• GODOT_PROJECT_DIR
• PUBLIC_IMAGES_DIR
• SENSOR_CONFIG_PATH

config/sensors.json

The real sensor config is ignored by Git. Copy config/sensors.example.json and edit the local copy.

Field	Purpose
guid_prefix	Prefix of the Delsys sensor GUID matched against discovered hardware
sensor_id	Stable logical numeric ID used in ROS topic names
role	Sensor role: EMG or IMU

Example topic mapping:

Config entry	Generated topics
{"sensor_id": 1, "role": "IMU"}	/accx1, /accy1, /accz1, /gyrox1, /gyroy1, /gyroz1
{"sensor_id": 2, "role": "EMG"}	/emg2

Warning

Do not commit real sensor GUIDs. config/sensors.json is local hardware configuration and must stay private.

🕹️ Daily Workflow

Start the application:

make up

In the launcher:

1. Wait for all startup services to become ready.
2. Calibrate the IMU while holding the sensor in the neutral position.
3. Calibrate EMG with the requested MVC effort.
4. Start the recording/control session from the HUD.
5. Stop the session before recalibrating or shutting down.

Useful commands:

Command	Purpose
make logs	Follow service logs
make shell	Open an interactive shell in the runtime container
make down	Stop the service
make clean	Remove the service and ROS build volumes

Caution

make clean removes Compose volumes, including ROS build outputs. Use it only when you intentionally want a clean rebuild.

🛰️ Runtime Architecture

Docker Compose runs one privileged host-network container with the repository mounted at /workspace/delsys-unimore.

drone_launcher.py starts:

• ROS 2 processing nodes from ros2_ws.
• rosbridge websocket server.
• Delsys socket bridge.
• PyQt launcher/HUD.
• Godot project from drone-game/.

Local ports:

Port	Purpose
9001	IMU processing input
9002	EMG processing input
9003	Drone controller input
9004	GUI-to-Delsys bridge commands
9090	rosbridge websocket

Important ROS topics:

Topic	Purpose
/emg<sensor_id>	Normalized EMG activation for an EMG sensor
/accx<sensor_id> to /gyroz<sensor_id>	IMU accelerometer and gyroscope channels
/drone/cmd_vel	Drone velocity command consumed by Godot
/drone/orientation	Drone orientation telemetry
/recording_trigger	Recording/control session state
/score	Game score telemetry
/sensor_info	Runtime sensor-role announcements

🛠️ Development Notes

Build the image after Dockerfile or dependency changes:

make build

Rebuild the ROS workspace after ROS package or interface changes:

make ros-build

Open a container shell for diagnostics:

make shell

Inside the container, the ROS workspace is available at:

/workspace/delsys-unimore/ros2_ws

The Compose file stores ROS build artifacts in named volumes:

• ros2_build
• ros2_install
• ros2_log

This keeps generated ROS files out of the source tree while preserving build output across normal container restarts.

🔐 Security And Publication

Never commit:

• .env
• config/sensors.json
• Real Delsys API credentials
• Real sensor GUIDs
• Local CSV/session captures
• Hardware-specific private configuration

Important

Treat delsys_bridge/mvc_config.json as calibration data. Do not edit or publish it unless that is intentional.

Warning

Confirm redistribution rights before publishing delsys_bridge/resources/. It contains Delsys SDK runtime binaries that may be subject to Delsys licensing terms.