# elettrascicomp/witmotion_imu_ros architecture

> Architecture diagram of the GitHub repository elettrascicomp/witmotion_imu_ros, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elettrascicomp/witmotion_imu_ros
- Repository: https://github.com/elettrascicomp/witmotion_imu_ros

## Overview

##### Project type and purpose
- This is a ROS 1 driver package (“witmotion_ros”) that wraps an existing C++/QtSerialPort IMU driver library (`witmotion-uart-qt`) and exposes data as standard ROS messages (`sensor_msgs` & `std_msgs`).
- It reads serial‐TTL data from Witmotion IMU units (e.g. WT31N, WT901) and publishes it on ROS topics.

##### File structure
- Top-level build and meta files:
- CMakeLists.txt & package.xml → ROS build configuration
- rosdoc.yaml → documentation settings
- Directories:
- src/ → ROS node implementation (`witmotion_ros.cpp`, `witmotion_ros_node.cpp`)
- / → public headers (`witmotion_ros.h`)
- witmotion-uart-qt/ → embedded external QtSerialPort driver submodule
- config/ → default YAML configurations for different sensors
- launch/ → ROS launch files to start the node with specific configs
- CI, licensing, changelog under root.

##### README for additional insights
- Underlying library dependency: QtSerialPort
- Only one node instance per serial device (monopolistic port access)
- All measurement‐type publishers are configurable via YAML or `roslaunch` parameters
- Provides a ROS service to restart the connection on timeout or error

##### Main architecture components
a. Hardware & OS layer
- Physical Witmotion IMU sensor → USB‐TTL serial device
- OS virtual device node (`/dev/ttyUSBx`)
b. Native driver library
- witmotion-uart-qt (QtSerialPort) – handles low‐level serial I/O, packet parsing, calibration/bias
c. ROS node
- `witmotion_ros_node` (in src/)
- Subcomponents:
– Parameter loader (reads YAML from config/) via ROS parameter server
– Serial port manager & packet decoder (calls into Qt library)
– Publisher modules for each message type (IMU, temp, mag, baro, alt, orientation, GPS, RTC)
– Restart service server to reinitialize on errors
d. ROS ecosystem
- ROS Master & Parameter Server
- Topics (`/imu`, `/temperature`, `/magnetometer`, etc.)
- Clients & other nodes subscribing to sensor data
e. Configuration & Launch
- YAML files under config/
- launch/*.launch → inject parameters and start the node

##### Relationships and interactions
- Sensor hardware → OS device → QtSerialPort library
- QtSerialPort → C++ driver (`witmotion-uart-qt`) → ROS node logic
- ROS node reads parameters from Parameter Server (populated via YAML or launch file)
- On incoming serial packets: decode → map to ROS messages → publish on corresponding topics
- On error/timeout: client can call restart service → node reopens the port
- Downstream ROS nodes subscribe to topics or call the restart service

##### Architectural patterns & principles
- Single‐responsibility: Separating low‐level I/O (driver lib) from ROS‐specific glue (node code)
- Monolithic ROS node (not nodelets) given exclusive device access
- Parameter‐driven behavior: all measurement publishers and rates are configurable
- Standard ROS pub/sub and service pattern

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        HardwareSensor["Witmotion IMU\n(Physical Sensor)"]:::hardware
        OSDevice["/dev/ttyUSBx\n(OS Virtual Device)"]:::hardware
    end
    HardwareSensor -->|"serial TTL"| OSDevice

    %% Native Driver Library
    subgraph "Native Driver Library"
        NativeDriver["QtSerialPort Driver & Packet Parsing\n(witmotion-uart-qt)"]:::library
    end
    OSDevice -->|"binary IMU packet"| NativeDriver

    %% Configuration & Launch
    subgraph "Configuration & Launch"
        Launch["Launch Files"]:::config
        ConfigYAML["YAML Config\n(config/)"]:::config
    end
    Launch -->|"inject parameters"| ConfigYAML
    ConfigYAML -->|provides params| ParamLoader

    %% ROS Application Layer
    subgraph "ROS Application Layer"
        NodeCore["witmotion_ros_node"]:::app
        ParamLoader["Parameter Loader\n(reads YAML)"]:::app
        SerialMgr["Serial Port Manager & Decoder"]:::app
        Publishers["Publisher Modules\n(IMU, Temp, Mag, Baro, Alt, Orientation, GPS, RTC)"]:::app
        RestartSvc["Restart Service Server"]:::app
    end
    ConfigYAML --> ParamLoader
    Launch -->|starts node| NodeCore
    NativeDriver -->|"API calls"| SerialMgr
    ParamLoader --> NodeCore
    SerialMgr --> NodeCore
    NodeCore --> Publishers
    NodeCore -.-> RestartSvc

    %% ROS Core
    subgraph "ROS Core"
        ROSMaster["ROS Master"]:::core
        ParamServer["Parameter Server"]:::core
    end
    Launch -->|launch populates| ParamServer
    ParamServer --> ParamLoader
    ROSMaster --> Publishers
    ROSMaster --> RestartSvc

    %% ROS Topics & Services
    subgraph "ROS Topics & Services"
        Topics["Published Topics\n(/imu, /temperature, /magnetometer, etc.)"]:::pubsvc
        RestartCall["/restart service"]:::pubsvc
    end
    Publishers -->|"sensor_msgs/... "| Topics
    RestartSvc -->|srv call| RestartCall

    %% External Subscribers
    External["External ROS Nodes/Subscribers"]:::external
    Topics --> External
    RestartCall --> External

    %% Project Files
    subgraph "Project Files"
        CMake["CMakeLists.txt"]:::meta
        Pkg["package.xml"]:::meta
        Doc["rosdoc.yaml"]:::meta
        CI[".github/workflows/main.yml"]:::meta
        Meta["README.md, CHANGELOG.rst, LICENSE"]:::meta
    end

    %% Click Events
    click NativeDriver "https://github.com/elettrascicomp/witmotion_imu_ros/tree/main/witmotion-uart-qt/"
    click NodeCore "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/src/witmotion_ros_node.cpp"
    click NodeCore "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/src/witmotion_ros.cpp"
    click NodeCore "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/include/witmotion_ros.h"
    click ConfigYAML "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/config/config.yml"
    click ConfigYAML "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/config/wt31n.yml"
    click ConfigYAML "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/config/wt901.yml"
    click Launch "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/launch/witmotion.launch"
    click Launch "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/launch/wt31n.launch"
    click Launch "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/launch/wt901.launch"
    click CMake "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/CMakeLists.txt"
    click Pkg "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/package.xml"
    click Doc "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/rosdoc.yaml"
    click CI "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/.github/workflows/main.yml"
    click Meta "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/README.md"
    click Meta "https://github.com/elettrascicomp/witmotion_imu_ros/blob/main/CHANGELOG.rst"
    click Meta "https://github.com/elettrascicomp/witmotion_imu_ros/tree/main/LICENSE"

    %% Styles
    classDef hardware fill:#b3e6b3,stroke:#2d7a2d,color:#2d7a2d;
    classDef library fill:#cce0ff,stroke:#3366cc,color:#3366cc;
    classDef app fill:#ffddb3,stroke:#cc8400,color:#cc8400;
    classDef core fill:#e0ccff,stroke:#9933cc,color:#9933cc;
    classDef pubsvc fill:#f2f2f2,stroke:#999999,color:#333333;
    classDef external fill:#ffffff,stroke:#666666,color:#666666;
    classDef config fill:#ffe6cc,stroke:#cc6600,color:#cc6600;
    classDef meta fill:#d9d9d9,stroke:#666666,color:#333333;
```
