# loco-auv/loco_config architecture

> Architecture diagram of the GitHub repository loco-auv/loco_config, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/loco-auv/loco_config
- Repository: https://github.com/loco-auv/loco_config

## Overview

#### Purpose and Scope
LoCO is a meta-repository for the LoCO autonomous underwater vehicle (AUV). It packages deployable host configuration, hardware/CAD design sources, fabrication exports, and camera reference material; it does not contain the robot’s ROS packages or application logic.

#### Operational Entry Points
Device startup is centered on ROS launch wrapper scripts and system services:
- Raspberry Pi: `rpi_config_files/ros-start.bash`, `rpi_config_files/ros-start.service`
- NVIDIA TX2: `tx2_config_files/ros-start.bash`, `tx2_config_files/ros-start.service`

These are the intended boot-time integration points for the external LoCO software stack. `get_pi_ip.sh` is a host-discovery utility.

#### Multi-Computer Robot Network
The repository defines three network roles:
- Vehicle Raspberry Pi configuration: `rpi_config_files/50-cloud-init.yaml`, `rpi_config_files/rpi.routing`
- Vehicle TX2/Jetson configuration: `tx2_config_files/interfaces`, `tx2_config_files/tx2.routing`
- Operator Control Unit (OCU): `ocu_config_files/interfaces`, `ocu_config_files/ocu.routing`

Persistent NIC naming is established independently on each host through `rpi_config_files/70-persistent-net.rules`, `tx2_config_files/70-persistent-net.rules`, and `ocu_config_files/70-persistent-net.rules`. Hosts files provide local name resolution at this boundary.

#### Vehicle Compute and Device Runtime
The Raspberry Pi and TX2 are separately provisioned runtime nodes. Both include USB filesystem-memory tuning and removable-media mounting services:
- `rpi_config_files/usbfs-memory.service`, `rpi_config_files/mount-usb.service`
- `tx2_config_files/usbfs-memory.service`, `tx2_config_files/mount-microsd.service`

The Pi also includes boot/display/platform settings in `rpi_config_files/config.txt`. Startup services execute the ROS wrapper scripts, making systemd the boundary between OS boot and robot software.

#### Mechanical System Source of Truth
The primary full-system CAD assembly is `models/SolidWorks/LoCO.SLDASM`. It composes vehicle sections and vendor-derived hardware models, including compute mounting, battery packaging, ballast, camera support, pressure enclosure, and thruster mounting. The enclosure-specific assembly is available at `models/LoCO_Shell/LoCO_Shell.SLDASM`.

#### Fabrication Outputs
Manufacturing-ready geometry is separated from editable CAD:
- 3D-printable/exported parts: `models/STLs/LoCO_Jetson_Section.STL`, `models/STLs/LoCO_Battery_Section.STL`, `models/STLs/LoCO_ThrusterMount.STL`
- Laser-cut base patterns: `models/LaserCut/MDFBaseLeft.DXF`, `models/LaserCut/MDFBaseRight.DXF`
- Editable sources: `models/SolidWorks/LoCO_Jetson_Section.SLDPRT`, `models/SolidWorks/LoCO_Battery_Section.SLDPRT`

Unit conventions are explicit in `models/STLs/STL in MILLIMETERS.txt` and `models/LoCO_Shell/STL in METERS.txt`, a material boundary for fabrication workflows.

#### External Hardware and Documentation
Camera integration targets the BFS-U3-31S4, with vendor specifications stored in `camera_reference/BFS-U3-31S4-Datasheet.pdf` and `camera_reference/BFS-U3-31S4-Technical-Reference.pdf`. The CAD inventory also embeds interfaces for Blue Robotics-style enclosure/thruster components and onboard hardware such as Pixhawk, Jetson, Raspberry Pi, batteries, and power distribution.

#### Licensing Boundary
Software/configuration is GPLv3 (`LICENSE_GPLV3`); physical designs are Creative Commons Attribution-ShareAlike (`LICENSE_SHAREALIKE`). Changes to boot/network configuration and changes to fabrication/CAD artifacts should therefore be treated as distinct deliverables and licensing domains.

Main entry points: [`models/SolidWorks/LoCO.SLDASM`](https://github.com/loco-auv/loco_config/blob/main/models/SolidWorks/LoCO.SLDASM) (Full vehicle assembly), [`rpi_config_files/50-cloud-init.yaml`](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/50-cloud-init.yaml) (Vehicle Raspberry Pi), [`rpi_config_files/ros-start.service`](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/ros-start.service) (Raspberry Pi startup), [`tx2_config_files/ros-start.service`](https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/ros-start.service) (TX2 startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Host Runtime"]
  node_external_ros{{"External LoCO software<br/>external runtime"}}
  node_rpi_boot["Raspberry Pi startup<br/>systemd + wrapper<br/>[ros-start.service]"]
  node_rpi_wrapper["Pi ROS wrapper<br/>shell entry point<br/>[ros-start.bash]"]
  node_tx2_boot["TX2 startup<br/>systemd + wrapper<br/>[ros-start.service]"]
  node_tx2_wrapper["TX2 ROS wrapper<br/>shell entry point<br/>[ros-start.bash]"]
  node_rpi_device_services["Pi device services<br/>systemd services"]
  node_tx2_device_services["TX2 device services<br/>systemd services"]
  node_rpi_platform["Pi platform settings<br/>boot config<br/>[config.txt]"]
end

subgraph group_network["Robot Network"]
  node_rpi_network["Vehicle Raspberry Pi<br/>network host config<br/>[50-cloud-init.yaml]"]
  node_tx2_network["Vehicle TX2<br/>network host config"]
  node_ocu_network["Operator Control Unit<br/>network host config"]
  node_persistent_nics["Persistent NIC naming<br/>udev rules"]
  node_host_discovery["Pi host discovery<br/>shell utility<br/>[get_pi_ip.sh]"]
end

subgraph group_design["Mechanical &amp; Fabrication"]
  node_full_assembly["Full vehicle assembly<br/>SolidWorks assembly<br/>[LoCO.SLDASM]"]
  node_shell_assembly["Pressure enclosure assembly<br/>SolidWorks assembly<br/>[LoCO_Shell.SLDASM]"]
  node_editable_parts["Editable vehicle sections<br/>SolidWorks parts"]
  node_print_exports["3D-print exports<br/>STL fabrication output"]
  node_laser_exports["Laser-cut base patterns<br/>DXF fabrication output<br/>[MDFBaseLeft.DXF]"]
end

node_camera_docs["BFS-U3-31S4 reference<br/>vendor documentation"]
node_software_license["Software/config license<br/>GPLv3 license"]
node_design_license["Physical design license<br/>CC BY-SA license"]

node_rpi_boot -->|"executes"| node_rpi_wrapper
node_rpi_wrapper -->|"starts"| node_external_ros
node_tx2_boot -->|"executes"| node_tx2_wrapper
node_tx2_wrapper -->|"starts"| node_external_ros
node_rpi_platform -->|"provides boot platform"| node_rpi_boot
node_rpi_device_services -.->|"coexists at OS boot"| node_rpi_boot
node_tx2_device_services -.->|"coexists at OS boot"| node_tx2_boot
node_rpi_network -->|"connects runtime host"| node_rpi_boot
node_tx2_network -->|"connects runtime host"| node_tx2_boot
node_rpi_network -->|"vehicle network"| node_tx2_network
node_ocu_network -->|"operator link"| node_rpi_network
node_ocu_network -->|"operator link"| node_tx2_network
node_persistent_nics -->|"stabilizes interfaces"| node_rpi_network
node_host_discovery -.->|"discovers"| node_rpi_network
node_full_assembly -->|"includes enclosure"| node_shell_assembly
node_full_assembly -->|"composes sections"| node_editable_parts
node_editable_parts -->|"exported as"| node_print_exports
node_full_assembly -->|"drives base patterns"| node_laser_exports
node_camera_docs -.->|"informs camera integration"| node_full_assembly
node_software_license -.->|"licenses"| node_rpi_boot
node_software_license -.->|"licenses"| node_tx2_boot
node_design_license -.->|"licenses"| node_full_assembly
node_design_license -.->|"licenses"| node_print_exports
node_design_license -.->|"licenses"| node_laser_exports

click node_rpi_boot "https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/ros-start.service"
click node_rpi_wrapper "https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/ros-start.bash"
click node_tx2_boot "https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/ros-start.service"
click node_tx2_wrapper "https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/ros-start.bash"
click node_rpi_device_services "https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/usbfs-memory.service"
click node_tx2_device_services "https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/usbfs-memory.service"
click node_rpi_platform "https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/config.txt"
click node_rpi_network "https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/50-cloud-init.yaml"
click node_tx2_network "https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/interfaces"
click node_ocu_network "https://github.com/loco-auv/loco_config/blob/main/ocu_config_files/interfaces"
click node_persistent_nics "https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/70-persistent-net.rules"
click node_host_discovery "https://github.com/loco-auv/loco_config/blob/main/get_pi_ip.sh"
click node_full_assembly "https://github.com/loco-auv/loco_config/blob/main/models/SolidWorks/LoCO.SLDASM"
click node_shell_assembly "https://github.com/loco-auv/loco_config/blob/main/models/LoCO_Shell/LoCO_Shell.SLDASM"
click node_editable_parts "https://github.com/loco-auv/loco_config/blob/main/models/SolidWorks/LoCO_Jetson_Section.SLDPRT"
click node_print_exports "https://github.com/loco-auv/loco_config/blob/main/models/STLs/LoCO_Jetson_Section.STL"
click node_laser_exports "https://github.com/loco-auv/loco_config/blob/main/models/LaserCut/MDFBaseLeft.DXF"
click node_camera_docs "https://github.com/loco-auv/loco_config/blob/main/camera_reference/BFS-U3-31S4-Datasheet.pdf"
click node_software_license "https://github.com/loco-auv/loco_config/blob/main/LICENSE_GPLV3"
click node_design_license "https://github.com/loco-auv/loco_config/blob/main/LICENSE_SHAREALIKE"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_external_ros,node_rpi_boot,node_rpi_wrapper,node_tx2_boot,node_tx2_wrapper,node_rpi_device_services,node_tx2_device_services,node_rpi_platform toneBlue
class node_rpi_network,node_tx2_network,node_ocu_network,node_persistent_nics,node_host_discovery toneAmber
class node_full_assembly,node_shell_assembly,node_editable_parts,node_print_exports,node_laser_exports toneMint
class node_camera_docs,node_software_license,node_design_license toneNeutral
```

## Components

### Host Runtime

Boot-time integration for external robot software.

- **External LoCO software**: external runtime · ROS packages and application logic are outside this repository.
- [Raspberry Pi startup](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/ros-start.service): systemd + wrapper · Boot service invokes the ROS startup wrapper. · `rpi_config_files/ros-start.service`
- [Pi ROS wrapper](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/ros-start.bash): shell entry point · `rpi_config_files/ros-start.bash`
- [TX2 startup](https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/ros-start.service): systemd + wrapper · Boot service invokes the ROS startup wrapper. · `tx2_config_files/ros-start.service`
- [TX2 ROS wrapper](https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/ros-start.bash): shell entry point · `tx2_config_files/ros-start.bash`
- [Pi device services](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/usbfs-memory.service): systemd services · USB filesystem tuning and removable-media mounting. · `rpi_config_files/usbfs-memory.service`
- [TX2 device services](https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/usbfs-memory.service): systemd services · USB filesystem tuning and microSD mounting. · `tx2_config_files/usbfs-memory.service`
- [Pi platform settings](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/config.txt): boot config · Pi boot, display, and platform settings. · `rpi_config_files/config.txt`

### Robot Network

Vehicle and operator network roles.

- [Vehicle Raspberry Pi](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/50-cloud-init.yaml): network host config · Cloud-init addressing and vehicle routing. · `rpi_config_files/50-cloud-init.yaml`
- [Vehicle TX2](https://github.com/loco-auv/loco_config/blob/main/tx2_config_files/interfaces): network host config · Interface addressing and vehicle routing. · `tx2_config_files/interfaces`
- [Operator Control Unit](https://github.com/loco-auv/loco_config/blob/main/ocu_config_files/interfaces): network host config · Operator interface addressing and routing. · `ocu_config_files/interfaces`
- [Persistent NIC naming](https://github.com/loco-auv/loco_config/blob/main/rpi_config_files/70-persistent-net.rules): udev rules · Each host independently fixes network interface names. · `rpi_config_files/70-persistent-net.rules`
- [Pi host discovery](https://github.com/loco-auv/loco_config/blob/main/get_pi_ip.sh): shell utility · `get_pi_ip.sh`

### Mechanical & Fabrication

Editable vehicle design and manufacturing exports.

- [Full vehicle assembly](https://github.com/loco-auv/loco_config/blob/main/models/SolidWorks/LoCO.SLDASM): SolidWorks assembly · Primary system CAD source of truth. · `models/SolidWorks/LoCO.SLDASM`
- [Pressure enclosure assembly](https://github.com/loco-auv/loco_config/blob/main/models/LoCO_Shell/LoCO_Shell.SLDASM): SolidWorks assembly · `models/LoCO_Shell/LoCO_Shell.SLDASM`
- [Editable vehicle sections](https://github.com/loco-auv/loco_config/blob/main/models/SolidWorks/LoCO_Jetson_Section.SLDPRT): SolidWorks parts · Jetson and battery section source parts. · `models/SolidWorks/LoCO_Jetson_Section.SLDPRT`
- [3D-print exports](https://github.com/loco-auv/loco_config/blob/main/models/STLs/LoCO_Jetson_Section.STL): STL fabrication output · Jetson section, battery section, and thruster mount. · `models/STLs/LoCO_Jetson_Section.STL`
- [Laser-cut base patterns](https://github.com/loco-auv/loco_config/blob/main/models/LaserCut/MDFBaseLeft.DXF): DXF fabrication output · Left and right MDF base patterns. · `models/LaserCut/MDFBaseLeft.DXF`

### Other components

- [BFS-U3-31S4 reference](https://github.com/loco-auv/loco_config/blob/main/camera_reference/BFS-U3-31S4-Datasheet.pdf): vendor documentation · Camera datasheet and technical reference. · `camera_reference/BFS-U3-31S4-Datasheet.pdf`
- [Software/config license](https://github.com/loco-auv/loco_config/blob/main/LICENSE_GPLV3): GPLv3 license · Applies to host configuration and scripts. · `LICENSE_GPLV3`
- [Physical design license](https://github.com/loco-auv/loco_config/blob/main/LICENSE_SHAREALIKE): CC BY-SA license · Applies to CAD and fabrication artifacts. · `LICENSE_SHAREALIKE`

## Connections

- Raspberry Pi startup → Pi ROS wrapper: executes
- Pi ROS wrapper → External LoCO software: starts
- TX2 startup → TX2 ROS wrapper: executes
- TX2 ROS wrapper → External LoCO software: starts
- Pi platform settings → Raspberry Pi startup: provides boot platform
- Pi device services → Raspberry Pi startup: coexists at OS boot
- TX2 device services → TX2 startup: coexists at OS boot
- Vehicle Raspberry Pi → Raspberry Pi startup: connects runtime host
- Vehicle TX2 → TX2 startup: connects runtime host
- Vehicle Raspberry Pi → Vehicle TX2: vehicle network
- Operator Control Unit → Vehicle Raspberry Pi: operator link
- Operator Control Unit → Vehicle TX2: operator link
- Persistent NIC naming → Vehicle Raspberry Pi: stabilizes interfaces
- Pi host discovery → Vehicle Raspberry Pi: discovers
- Full vehicle assembly → Pressure enclosure assembly: includes enclosure
- Full vehicle assembly → Editable vehicle sections: composes sections
- Editable vehicle sections → 3D-print exports: exported as
- Full vehicle assembly → Laser-cut base patterns: drives base patterns
- BFS-U3-31S4 reference → Full vehicle assembly: informs camera integration
- Software/config license → Raspberry Pi startup: licenses
- Software/config license → TX2 startup: licenses
- Physical design license → Full vehicle assembly: licenses
- Physical design license → 3D-print exports: licenses
- Physical design license → Laser-cut base patterns: licenses