👋 DexTrace

DexTrace is an integrated hardware-software system designed to train and rehabilitate hand fine motor coordination and dexterity. By combining a Raspberry Pi Pico controller with a Python-based GUI, the system evaluates user performance across three progressive difficulty levels, monitoring spatial precision and tremor intensity in real-time.

See the project presentation for further details.

🎯 Key Features

• Real-Time Architecture: Bidirectional communication based on ROS2 (micro-ROS) between the microcontroller and PC;
• Tremor Analysis: Integrated MPU6050 IMU for calculating real-time tremor variance and intensity;
• Multimodal Feedback: Hardware-managed acoustic alarms and visual feedback on screen;
• Clinical Evaluation Protocol:
  • Level 1 (Reaching): Path efficiency and target acquisition assessment;
  • Level 2 (Tracking): Smooth circular target following;
  • Level 3 (Chasing): Non-linear dynamics to simulate complex scenarios.

📋 System Requirements

Hardware:

• Raspberry PI Pico;
• MPU6050 IMU Sensor;
• Analog Joystick (2-axis + integrated button);
• Active Buzzer;
• Led (with 220 Ω resistor).

Software:

• ROS2 (Humble or later - check compatibility with your Ubuntu version);
• Micro-ROS Agent;
• Python 3.10+;
• Python Libraries: pygame, rclpy, math, geometry_msgs, std_msgs.

🏗️ System Architecture

The project utilizes a Finite State Machine (FSM) to ensure safety and smooth operation:

• WAITING: System idle;
• LOADED: Gain and threshold parameters sent from PC to Pico + Alarm reset;
• ACTIVE: Data streaming and watchdog monitoring;
• RESULTS: Statistical processing of the session and score calculation.

📊 Evaluation Metrics (Dex-Metrics)

The system calculates the quality of motor gestures using weighted algorithms:

Metric	Description	Formula	Level
Tremor Intensity	Calculated based on the variance of 3-axis acceleration from the MPU6050	$Var(Mag_{accel})$	All
Dex-Efficiency	Ratio between real and optimal path + tremor penalty	$Path_{eff} + (Tremor_{avg} \cdot 0.5)$	1
Dex-Accuracy	RMSE weighted by tremor intensity	$RMSE + (Tremor_{avg} \cdot 10)$	2 & 3

🛠️ Prototype

Wiring table

Pico pin	Components pin
38	Joystick GND, IMU GND
36	Joystick VCC, IMU VCC
31 - GP26	Joystick VRx
32 - GP27	Joystick VRy
27 - GP21	Joystick SW
7 - GP5	IMU SCL
6 - GP4	IMU SDA
20 - GP15	Buzzer
21 - GP16	Led

🔧 Installation & Setup

micro-ROS workspace with FreeRTOS for Raspberry PI Pico SDK

Dependencies

0. Configure Groups

# add user to groups
sudo usermod -a -G plugdev $USER
sudo usermod -a -G dialout $USER

# To mount PICO without sudo
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2e8a", ATTR{idProduct}=="0003", MODE="0660", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-rpi-pico.rules > /dev/null

(reboot your system after)

1. Install Pico SDK

First, make sure the Pico SDK is properly installed and configured:

# Install dependencies
sudo apt install cmake g++ gcc-arm-none-eabi doxygen libnewlib-arm-none-eabi git python3
git clone --recurse-submodules https://github.com/raspberrypi/pico-sdk.git $HOME/pico-sdk

# Configure environment
echo "export PICO_SDK_PATH=$HOME/pico-sdk" >> ~/.bashrc
source ~/.bashrc

2. Build micro-ROS agent (first time only)

micro-ROS follows the client-server architecture, so you need to start the micro-ROS Agent.

# Create a workspace and download the micro-ROS tools
mkdir microros_ws
cd microros_ws
git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup

# Update dependencies using rosdep
sudo apt update && rosdep update
rosdep install --from-paths src --ignore-src -y

# Install pip
sudo apt-get install python3-pip

# Build micro-ROS tools and source them
colcon build
source install/local_setup.bash

# Download micro-ROS agent packages
ros2 run micro_ros_setup create_agent_ws.sh

# Build step
ros2 run micro_ros_setup build_agent.sh

3. Clone this repository

Recursively clone the repo (working for Ubuntu v22.04 with ROS2 humble).

git clone --recursive https://github.com/alexveronese/DexTrace

4. Package configuration

Move the dextrace_rehab ROS2 package to the workspace.

cd <your_project_dir>
mv DexTrace/dextrace_rehab microros_ws/src/dextrace_rehab

# Moving to the workspace
cd microros_ws

# Build the package
colcon build --packages-select dextrace_rehab

# Source the setup and run:
source install/setup.bash

⚙️ Running

Build

cd DexTrace
mkdir build
cd build
cmake ..
make

Flash the rehab app

To flash hold the boot button, plug the USB and run:

cp rehab.uf2 $(findmnt -rn -o TARGET -S LABEL=RPI-RP2)/

Run micro-ROS agent

Open a new terminal.

# Source workspace
cd microros_ws
source install/local_setup.bash

# Run microros agent
ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyACM0

Launch DexTrace

Open a new terminal and run the rehapp node.

# Source workspace
cd microros_ws
source install/local_setup.bash

ros2 run dextrace_rehab rehab_app

License

This repository is open-sourced under the Apache-2.0 license. See the LICENSE file for details. The content of this repository is derived from micro_ros_raspberrypi_pico_sdk and RTES_freertos_PICO.

For a list of other open-source components included in this repository, see the file 3rd-party-licenses.txt.