# mike4192/spotmicro architecture

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

- Interactive diagram: https://gitdiagram.com/mike4192/spotmicro
- Repository: https://github.com/mike4192/spotmicro

## Overview

##### Project type and purpose
- This is a ROS-based robotics control system for the Spot Micro quadruped robot.
- It runs on a Raspberry Pi 3B (Ubuntu 16.04, ROS Kinetic) and on a remote PC.
- It implements a finite-state machine gait controller (sit, stand, walk, angle control), hardware interface to a PCA9685 servo board, sensor integration (RPLidar for SLAM), TF2/odometry, and several visualization and input nodes (RVIZ, matplotlib plots, keyboard, joystick, LCD).

##### File structure
Top-level organization:
- catkin workspace style, each subdirectory under `src/` (in the user’s workspace) is a ROS package.
- Key packages:
– spot_micro_motion_cmd: C++ control node + YAML config + state machine & kinematics
– ros-i2cpwmboard (submodule): C++ hardware driver for PCA9685 via I²C
– spot_micro_keyboard_command & spot_micro_joy: Python input nodes (keyboard/joystick → motion commands)
– lcd_monitor: Python node to drive a 16×2 I²C LCD for real­time state output
– servo_move_keyboard: Python node for manual servo calibration
– spot_micro_plot: Python matplotlib visualization of robot body state
– spot_micro_rviz: URDF (xacro + STLs), RViz launch files, mapping/SLAM integration
– spot_micro_launch: aggregate launch files for complex workflows (e.g., motion+RViz, SLAM)
- `launch/` directories contain `.launch` files wiring together nodes and parameters
- `scripts/` / `src/` hold Python or C++ node code
- `config/` holds the `spot_micro_motion_cmd.yaml` with gait parameters, TF2 toggles, odom, etc.

##### README for additional insights
- Describes hardware: Raspberry Pi, PCA9685, 12 servos, optional LCD, RPLidar
- Node descriptions and interconnections (state machine, topics, TF2 frames)
- URDF used for RViz visualization, not for control
- SLAM uses hector_slam, RPLidar driver, and publishes maps
- Launch sequences:
- On Pi: i2cpwm_board + motion_cmd
- On PC: keyboard_command or joy + (optional RViz or plot)
- Optional SLAM launch for mapping

##### Detail
- Every ROS package and its role
- Submodule libraries only if they introduce unique runtime behavior (e.g., spot_micro_kinematics_cpp used inside motion_cmd)
- Note about the YAML config feeding parameters to the motion_cmd node
- TF frame hierarchy: odom → base_footprint → base_link → lidar_link

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "PC Input Layer"
        KeyboardNode["spot_micro_keyboard_command"]:::input
        JoystickNode["spot_micro_joy"]:::input
    end

    RosBus["ROS Topic Bus"]:::bus

    subgraph "RPi Control Layer"
        MotionCmd["spot_micro_motion_cmd"]:::control
        HardwareInterface["i2cpwm_board"]:::hardware
    end

    subgraph "Sensors & Localization"
        RPLidar["RPLidar Driver"]:::sensor
        SLAM["hector_slam SLAM"]:::sensor
        TFBus["TF2 Transforms"]:::bus
    end

    subgraph "Visualization Layer"
        RViz["RViz"]:::viz
        Plot["spot_micro_plot"]:::viz
        LCD["lcd_monitor"]:::viz
    end

    ParamServer["Parameter Server"]:::config

    KeyboardNode -->|"/spot_micro/event /cmd_vel"| RosBus
    JoystickNode -->|"/spot_micro/event /cmd_vel"| RosBus
    RosBus -->|"/spot_micro/event /cmd_vel"| MotionCmd
    MotionCmd -->|"/servo_commands"| HardwareInterface
    MotionCmd -->|"TF2 frames"| TFBus
    RPLidar -->|"/scan"| SLAM
    SLAM -->|"/map"| RosBus
    MotionCmd -->|"/robot_state"| RosBus
    RosBus -->|"/robot_state"| Plot
    RosBus -->|"/robot_state"| RViz
    RosBus -->|"/robot_state"| LCD
    ParamServer -->|"Parameters"| MotionCmd

    click KeyboardNode "https://github.com/mike4192/spotmicro/blob/master/spot_micro_keyboard_command/launch/keyboard_command.launch"
    click JoystickNode "https://github.com/mike4192/spotmicro/blob/master/spot_micro_joy/launch/everything.launch"
    click MotionCmd "https://github.com/mike4192/spotmicro/blob/master/spot_micro_motion_cmd/launch/motion_cmd.launch"
    click HardwareInterface "https://github.com/mike4192/spotmicro/tree/master/ros-i2cpwmboard/"
    click RViz "https://github.com/mike4192/spotmicro/blob/master/spot_micro_rviz/launch/show_model.launch"
    click Plot "https://github.com/mike4192/spotmicro/blob/master/spot_micro_plot/launch/start_plotting.launch"
    click LCD "https://github.com/mike4192/spotmicro/blob/master/lcd_monitor/launch/lcd_monitor.launch"
    click ParamServer "https://github.com/mike4192/spotmicro/blob/master/spot_micro_motion_cmd/config/spot_micro_motion_cmd.yaml"

    classDef input fill:#b2f5b2,stroke:#333,stroke-width:1px
    classDef control fill:#b2dfff,stroke:#333,stroke-width:1px
    classDef sensor fill:#ffd59e,stroke:#333,stroke-width:1px
    classDef viz fill:#e3b3ff,stroke:#333,stroke-width:1px
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef bus fill:#fffacd,stroke-dasharray:5 5,stroke:#333
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px
```
