# scottmayberry/mur architecture

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

- Interactive diagram: https://gitdiagram.com/scottmayberry/mur
- Repository: https://github.com/scottmayberry/mur

## Overview

##### Project Type and Purpose
- MUR is an open-source underwater robotics platform combining custom hardware (CAD and PCBs), embedded firmware (Teensy controllers), and a ROS­based software stack running on a compute module.
- It targets precise underwater navigation, sensing, modeling, and control.

##### File Structure
- Top-level domains:
- hardware/ (CAD models, BOM, PCBs, assembly videos, firmware)
- software/ (ROS packages: mur, mur_sensors, mur_model, mur_control, BlueBuzz integration)
- images/ (renders, photos)
- hardware/firmware → divides between:
- Teensy embedded code (EthernetManager, SensorManager, ThrusterManager)
- Compute module setup scripts (camera streaming, broadcast IP)
- software/ROS_packages → four core ROS packages plus support tools.

##### Extract Key Architectural Insights from README
- The `mur` ROS package is the orchestrator (roslaunch mur.launch).
- Subpackaging:
- mur_sensors: collects and publishes sensor data over ROS topics.
- mur_model: builds the robot’s physical/dynamic model, publishes transforms and state.
- mur_control: runs manual and PID-based thruster control, subscribes to sensor/model topics and sends commands.
- BlueBuzz and camera streaming nodes provide communication and video feed.
- Communication: ROS topics and services; UDP between compute module and Teensy; acoustic (BlueBuzz), Ethernet, WiFi links.

##### Main Components (Canvas Elements)
- Hardware Layer (physical):
- Structural Frame, Thrusters, IMUs, Pressure Sensors, Leak Detectors, Temperature/Humidity Sensors.
- Communication Modules: BlueBuzz acoustic modem, Ethernet port, WiFi interface.
- Compute Module (e.g., Raspberry Pi/NUC) running Linux + ROS.
- Embedded Microcontroller (Teensy) connected to thrusters and sensors.
- Firmware Layer:
- Teensy Firmware: SensorManager, ThrusterManager, EthernetManager.
- Compute Module Startup & Service Scripts: broadcast_ip_data.py, udp_camera_streamer.py.
- Software Layer (ROS):
- roslaunch orchestrator (`mur.launch`).
- mur_sensors nodes → publish `/imu`, `/depth`, `/leak_status`, etc.
- mur_model nodes → subscribe sensor topics, publish `/tf`, odometry, simulated model state.
- mur_control nodes → subscribe model & manual input topics, publish thruster setpoints.
- BlueBuzz nodes → ros_bluebuzz_udp, ros_bluebuzz_transmit.
- Camera streaming node.
- Configuration Store:
- YAML files: global_config.yaml, environment_info.yaml, control_info.yaml.
- External Interfaces:
- Operator Console (keyboard, GUI).
- Video Monitoring (UDP/MJPEG stream).
- Data Logging (rosbag, onboard file system).

##### Relationships and Data Flows
- Hardware Sensors → Teensy Firmware (I²C/SPI/ADC) → EthernetManager (UDP) → ROS topics.
- Compute Module:
– ROS Master ↔ all ROS nodes (mur_sensors, mur_model, mur_control, BlueBuzz, camera).
– roslaunch loads nodes and YAML params.
- Control loop:
– mur_sensors → mur_model → mur_control → Teensy (thruster commands) → Thrusters.
- Camera Hardware → camera stream script → ROS topic or external video client.
- BlueBuzz modem ↔ ros_bluebuzz_udp ↔ mur package via ROS topics.

##### Architectural Patterns & Principles
- Modular ROS nodes—each package encapsulates one concern (sensors, model, control, comms).
- Publish/Subscribe decoupling.
- Configuration‐driven (YAML) for environment and control parameters.
- Embedded real‐time firmware offloads critical I/O and timing from compute module.
- Single entrypoint orchestration (`mur.launch`) for ease of deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Physical Hardware Layer
    subgraph "Physical Hardware" 
        direction TB
        Frame["Structural Frame"]:::hardware
        Thrusters["Thrusters"]:::hardware
        IMU["IMUs, Pressure, Leak, Temp Sensors"]:::hardware
        Comms["Communication Modules\n(Ethernet, WiFi, BlueBuzz)"]:::hardware
        CM_HW["Compute Module (Raspberry Pi/NUC)"]:::hardware
        TM_HW["Teensy Microcontroller"]:::hardware
    end

    %% Firmware Layer
    subgraph "Embedded Firmware (Teensy)" 
        direction TB
        EM["EthernetManager"]:::firmware
        SM["SensorManager"]:::firmware
        TM["ThrusterManager"]:::firmware
        MF["mur_embedded.ino & config.h"]:::firmware
    end

    %% Compute Module Startup & Services
    subgraph "Compute Module Services" 
        direction TB
        BI["broadcast_ip_data.py"]:::firmware
        CS["udp_camera_streamer.py"]:::firmware
    end

    %% Software Layer (ROS)
    subgraph "ROS Software Stack" 
        direction TB
        MUR_LAUNCH["mur.launch\n(Orchestrator)"]:::ros
        subgraph "mur_sensors" 
            direction TB
            S_LAUNCH["mur_sensors.launch"]:::ros
            S_CONF["sensor_config.yaml"]:::config
            S_PUB["ros_sensor_udp_server_dyn.py\nros_imu_sensor_fusion_dyn.py\nsensor_publisher_constructor.py"]:::ros
        end
        subgraph "mur_model" 
            direction TB
            M_LAUNCH["mur_model.launch"]:::ros
            M_CONF["model_info.yaml\naruco_info.yaml"]:::config
            M_TF["static_tf2_broadcaster.py"]:::ros
            M_LOC["imu_baselink_updater.py\npressure_to_depth.py"]:::ros
            M_THR["ros_thruster_command_conversion.py\nros_thruster_microsecond_udp.py"]:::ros
            subgraph "Camera Bridge"
                direction TB
                C_BOOT["camera_boot_server_udp.py"]:::ros
                C_BRIDGE["camera_udp_to_ros.py"]:::ros
            end
        end
        subgraph "mur_control"
            direction TB
            C_LAUNCH["mur_control.launch"]:::ros
            C_CONF["control_info.yaml"]:::config
            C_CTRL["blended_manual_and_pid_setpoint_controller.py\nmanual_with_PID_setpoint_generator.py\nros_pid_setpoint_control.py"]:::ros
        end
        subgraph "bluebuzz"
            direction TB
            B_LAUNCH["bluebuzz.launch"]:::ros
            B_CONF["bluebuzz_config.yaml"]:::config
            B_NODES["ros_bluebuzz_udp.py\nros_bluebuzz_transmit.py"]:::ros
        end
    end

    %% Configuration Store
    ConfigStore["YAML Config Store\n(global, environment, control)"]:::config

    %% External Interfaces
    Operator["Operator Console\n(Keyboard, GUI)"]:::external
    Video["Video Monitoring\n(UDP/MJPEG)"]:::external
    Logging["Data Logging\n(rosbag, FS)"]:::external

    %% Connections
    IMU -->|"I2C/SPI/ADC"| SM
    Thrusters -->|"PWM"| TM
    SM -->|"UDP JSON"| EM
    TM -->|"UDP JSON"| EM
    EM -->|"UDP"| MUR_LAUNCH
    CM_HW -->|runs| MUR_LAUNCH
    BI -->|broadcast IP| CM_HW
    CS -->|camera stream| CM_HW

    MUR_LAUNCH -->|"roslaunch loads params"| S_LAUNCH
    S_LAUNCH -->|"ROS topics: /imu, /depth, /leak"| S_PUB
    S_PUB -->|"publishes"| M_TF
    M_TF -->|"pub /tf, odom"| M_LOC
    M_LOC -->|"updates"| M_THR
    M_THR -->|"publishes setpoints"| C_CTRL
    C_LAUNCH -->|"loads control"| C_CTRL
    C_CTRL -->|"thruster commands"| EM
    MUR_LAUNCH -->|"loads"| B_LAUNCH
    B_LAUNCH -->|"ROS topics"| B_NODES
    B_NODES -->|"communicates"| Comms
    C_BOOT -->|"bridge"| MUR_LAUNCH
    C_BRIDGE -->|"ROS image topic"| Video

    Operator -->|"manual input"| C_CTRL
    Video -->|"view stream"| CS
    Logging -->|"record topics"| MUR_LAUNCH

    %% Click Events
    click EM "https://github.com/scottmayberry/mur/blob/main/hardware/firmware/Teensy/mur_embedded/EthernetManager.cpp"
    click SM "https://github.com/scottmayberry/mur/blob/main/hardware/firmware/Teensy/mur_embedded/SensorManager.cpp"
    click TM "https://github.com/scottmayberry/mur/blob/main/hardware/firmware/Teensy/mur_embedded/ThrusterManager.cpp"
    click MF "https://github.com/scottmayberry/mur/blob/main/hardware/firmware/Teensy/mur_embedded/mur_embedded.ino"
    click BI "https://github.com/scottmayberry/mur/blob/main/hardware/firmware/compute_module/service_setup/broadcast_ip/broadcast_ip_data.py"
    click CS "https://github.com/scottmayberry/mur/blob/main/hardware/firmware/compute_module/service_setup/camera_streaming/udp_camera_streamer.py"
    click MUR_LAUNCH "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur/launch/mur.launch"
    click S_LAUNCH "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_sensors/launch/mur_sensors.launch"
    click S_CONF "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_sensors/config/sensor_config.yaml"
    click S_PUB "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_sensors/src/ros_sensor_udp_server_dyn.py"
    click M_LAUNCH "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_model/launch/mur_model.launch"
    click M_CONF "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_model/config/model_info.yaml"
    click M_TF "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_model/src/static_tf2_broadcaster.py"
    click M_LOC "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_model/src/localization/imu_baselink_updater.py"
    click M_THR "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_model/src/thruster/ros_thruster_command_conversion.py"
    click C_LAUNCH "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_control/launch/mur_control.launch"
    click C_CONF "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_control/config/control_info.yaml"
    click C_CTRL "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/mur_control/src/ros_pid_setpoint_control.py"
    click B_LAUNCH "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/bluebuzz/launch/bluebuzz.launch"
    click B_CONF "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/bluebuzz/config/bluebuzz_config.yaml"
    click B_NODES "https://github.com/scottmayberry/mur/blob/main/software/ROS_packages/src/bluebuzz/src/ros_bluebuzz_udp.py"

    %% Styles
    classDef hardware fill:#dddddd,stroke:#888,stroke-width:1px
    classDef firmware fill:#bbdefb,stroke:#888,stroke-width:1px
    classDef ros fill:#c8e6c9,stroke:#888,stroke-width:1px
    classDef config fill:#f3e5f5,stroke:#888,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#888,stroke-width:1px
```
