# inertiallabs/inertiallabs-ros-pkgs architecture

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

- Interactive diagram: https://gitdiagram.com/inertiallabs/inertiallabs-ros-pkgs
- Repository: https://github.com/inertiallabs/inertiallabs-ros-pkgs

## Overview

1. **Overall shape**
   - This repo is a ROS1 driver stack for Inertial Labs navigation sensors.
   - It is split into three real packages plus an umbrella ROS package:
     - `inertiallabs_sdk`: low-level device SDK
     - `inertiallabs_msgs`: custom ROS message definitions
     - `inertiallabs_ins`: ROS node that talks to the sensor and publishes topics
     - `inertiallabs_ros_pkgs`: packaging/aggregation layer

2. **Core runtime data path**
   - The main flow is: sensor hardware → SDK transport → SDK packet parser → ROS driver node → ROS topics.
   - The driver converts Inertial Labs binary output into typed ROS messages for downstream consumers.

3. **SDK boundary**
   - `inertiallabs_sdk` is the non-ROS hardware access layer.
   - It contains transport and parsing code, with platform-specific implementations under `src/platform/linux` and `src/platform/windows`.
   - It abstracts serial and network-style access through classes like `Transport`, `ILDriver`, `NetClient`, `SerialPort`, and packet parsing in `UDDParser`.

4. **ROS driver boundary**
   - `inertiallabs_ins/src/il_ins.cpp` is the executable node.
   - It is configured by ROS parameters such as `ins_url` and `ins_output_format`.
   - This node is the bridge between the SDK and ROS: it opens the configured connection, selects the device packet format, and publishes decoded state.

5. **Custom message model**
   - `inertiallabs_msgs` defines the ROS schema used by the driver.
   - The messages are grouped by data domain:
     - `sensor_data.msg`
     - `ins_data.msg`
     - `gps_data.msg`
     - `gnss_data.msg`
     - `marine_data.msg`
   - These messages represent the sensor outputs that the node publishes.

6. **Published topic groups**
   - The driver publishes onto `/Inertial_Labs/*` topics.
   - Each topic corresponds to a message type and a logical sensor domain:
     - raw IMU / environmental fields in `sensor_data`
     - navigation solution in `ins_data`
     - GNSS state in `gnss_data`
     - GPS kinematics in `gps_data`
     - marine motion metrics in `marine_data`

7. **Packet-format driven behavior**
   - The node supports multiple Inertial Labs packet formats, selected by `ins_output_format`.
   - The README maps these formats to device ICD packet IDs such as `IL_OPVT`, `IL_OPVT2AHR`, `IL_SENSOR_DATA`, and others.
   - This means the same driver can present different subsets of data depending on what the sensor is configured to emit.

8. **Connection and transport layer**
   - Runtime connection is described by `ins_url` strings like `serial:...`, `tcp:...`, and `udp:...`.
   - The README emphasizes serial operation, but the SDK structure shows transport abstractions for both serial and network clients.
   - For architecture purposes, treat transport as a pluggable boundary below the ROS node.

9. **Launch and configuration**
   - `inertiallabs_ins/launch/ins.launch` is the ROS launch entrypoint.
   - It likely wires parameters and starts the driver node in a ROS-native way, while the README also documents direct `rosrun` execution.
   - The node is subscriber-aware: it only needs to publish when there are active topic subscribers.

10. **Build and packaging model**
   - This is a Catkin-based ROS1 repository, tested on Kinetic and Melodic.
   - The README recommends `catkin_make_isolated` because the repo contains multiple packages with shared dependencies.
   - `inertiallabs_sdk` is also built as a standalone C++ library, with example programs and Windows project files, but the ROS driver itself targets Linux.

11. **Deployment assumptions**
   - The driver expects access to the sensor device node or network endpoint, and may require serial permissions and baud-rate alignment.
   - The repository is oriented around direct hardware integration rather than cloud or backend services.
   - The main external dependency is the Inertial Labs sensor itself, plus ROS1/catkin at build and runtime.

Main entry points: [`inertiallabs_ins/src/il_ins.cpp`](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ins/src/il_ins.cpp) (INS node), [`inertiallabs_sdk/include/inertiallabs_sdk/Transport.h`](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/include/inertiallabs_sdk/Transport.h) (Transport), [`inertiallabs_ros_pkgs/package.xml`](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ros_pkgs/package.xml) (ROS pkgs), [`inertiallabs_sdk/include/inertiallabs_sdk/ILDriver.h`](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/include/inertiallabs_sdk/ILDriver.h) (ILDriver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pkg_driver["ROS driver"]
  node_il_ins_cpp["INS node<br/>ROS executable<br/>[il_ins.cpp]"]
  node_ins_launch["Launch file<br/>ROS launch<br/>[ins.launch]"]
end

subgraph group_pkg_sdk["SDK"]
  node_il_driver["ILDriver<br/>SDK core<br/>[ILDriver.h]"]
  node_transport["Transport<br/>SDK interface<br/>[Transport.h]"]
  node_udd_parser["UDD parser<br/>packet parser<br/>[UDDParser.cpp]"]
  node_linux_net["Linux net<br/>platform impl<br/>[NetClient.cpp]"]
  node_linux_serial["Linux serial<br/>platform impl<br/>[SerialPort.cpp]"]
  node_win_net["Windows net<br/>platform impl<br/>[NetClient.cpp]"]
  node_win_serial["Windows serial<br/>platform impl<br/>[SerialPort.cpp]"]
end

subgraph group_pkg_msgs["Messages"]
  node_sensor_msg["Sensor data<br/>ROS msg<br/>[sensor_data.msg]"]
  node_ins_msg["INS data<br/>ROS msg<br/>[ins_data.msg]"]
  node_gnss_msg["GNSS data<br/>ROS msg<br/>[gnss_data.msg]"]
  node_gps_msg["GPS data<br/>ROS msg<br/>[gps_data.msg]"]
  node_marine_msg["Marine data<br/>ROS msg<br/>[marine_data.msg]"]
end

subgraph group_pkg_umbrella["Umbrella package"]
  node_ros_pkgs["ROS pkgs<br/>package meta<br/>[package.xml]"]
end

node_sensor_hw(("Sensor hardware<br/>external device"))

node_sensor_hw -->|"stream data"| node_transport
node_transport -->|"feeds"| node_il_driver
node_il_driver -->|"parses via"| node_udd_parser
node_udd_parser -->|"decodes for"| node_il_ins_cpp
node_il_ins_cpp -->|"publishes"| node_sensor_msg
node_il_ins_cpp -->|"publishes"| node_ins_msg
node_il_ins_cpp -->|"publishes"| node_gnss_msg
node_il_ins_cpp -->|"publishes"| node_gps_msg
node_il_ins_cpp -->|"publishes"| node_marine_msg
node_ins_launch -->|"starts"| node_il_ins_cpp
node_il_ins_cpp -->|"opens"| node_transport
node_transport -->|"implements"| node_linux_serial
node_transport -->|"implements"| node_linux_net
node_transport -->|"implements"| node_win_serial
node_transport -->|"implements"| node_win_net
node_ros_pkgs -->|"packages"| node_il_ins_cpp
node_ros_pkgs -->|"packages"| node_sensor_msg

click node_il_ins_cpp "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ins/src/il_ins.cpp"
click node_ins_launch "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ins/launch/ins.launch"
click node_il_driver "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/include/inertiallabs_sdk/ILDriver.h"
click node_transport "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/include/inertiallabs_sdk/Transport.h"
click node_udd_parser "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/UDDParser.cpp"
click node_linux_net "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/linux/NetClient.cpp"
click node_linux_serial "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/linux/SerialPort.cpp"
click node_win_net "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/windows/NetClient.cpp"
click node_win_serial "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/windows/SerialPort.cpp"
click node_sensor_msg "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/sensor_data.msg"
click node_ins_msg "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/ins_data.msg"
click node_gnss_msg "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/gnss_data.msg"
click node_gps_msg "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/gps_data.msg"
click node_marine_msg "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/marine_data.msg"
click node_ros_pkgs "https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ros_pkgs/package.xml"

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_il_ins_cpp,node_ins_launch toneBlue
class node_il_driver,node_transport,node_udd_parser,node_linux_net,node_linux_serial,node_win_net,node_win_serial toneAmber
class node_sensor_msg,node_ins_msg,node_gnss_msg,node_gps_msg,node_marine_msg toneMint
class node_ros_pkgs toneRose
class node_sensor_hw toneNeutral
```

## Components

### ROS driver

Executable node and launch entrypoint

- [INS node](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ins/src/il_ins.cpp): ROS executable · Main ROS1 driver that connects to the sensor and publishes topics · `inertiallabs_ins/src/il_ins.cpp`
- [Launch file](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ins/launch/ins.launch): ROS launch · ROS launch entrypoint for starting the INS driver · `inertiallabs_ins/launch/ins.launch`

### SDK

Non-ROS transport and parsing layer

- [ILDriver](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/include/inertiallabs_sdk/ILDriver.h): SDK core · Device-facing SDK entry that coordinates connection and packet flow · `inertiallabs_sdk/include/inertiallabs_sdk/ILDriver.h`
- [Transport](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/include/inertiallabs_sdk/Transport.h): SDK interface · Pluggable access boundary for serial and network communication · `inertiallabs_sdk/include/inertiallabs_sdk/Transport.h`
- [UDD parser](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/UDDParser.cpp): packet parser · Decodes Inertial Labs binary packets into structured data · `inertiallabs_sdk/src/UDDParser.cpp`
- [Linux net](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/linux/NetClient.cpp): platform impl · Linux network transport implementation · `inertiallabs_sdk/src/platform/linux/NetClient.cpp`
- [Linux serial](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/linux/SerialPort.cpp): platform impl · Linux serial transport implementation · `inertiallabs_sdk/src/platform/linux/SerialPort.cpp`
- [Windows net](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/windows/NetClient.cpp): platform impl · Windows network transport implementation · `inertiallabs_sdk/src/platform/windows/NetClient.cpp`
- [Windows serial](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_sdk/src/platform/windows/SerialPort.cpp): platform impl · Windows serial transport implementation · `inertiallabs_sdk/src/platform/windows/SerialPort.cpp`

### Messages

Custom ROS message definitions

- [Sensor data](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/sensor_data.msg): ROS msg · Raw IMU and environmental sensor fields · `inertiallabs_msgs/msg/sensor_data.msg`
- [INS data](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/ins_data.msg): ROS msg · Navigation solution and attitude state · `inertiallabs_msgs/msg/ins_data.msg`
- [GNSS data](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/gnss_data.msg): ROS msg · GNSS status and satellite-state fields · `inertiallabs_msgs/msg/gnss_data.msg`
- [GPS data](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/gps_data.msg): ROS msg · GPS kinematics and position outputs · `inertiallabs_msgs/msg/gps_data.msg`
- [Marine data](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_msgs/msg/marine_data.msg): ROS msg · Marine motion and vessel-related metrics · `inertiallabs_msgs/msg/marine_data.msg`

### Umbrella package

Packaging and aggregation layer

- [ROS pkgs](https://github.com/inertiallabs/inertiallabs-ros-pkgs/blob/master/inertiallabs_ros_pkgs/package.xml): package meta · Umbrella ROS package for aggregation and packaging · `inertiallabs_ros_pkgs/package.xml`

### Other components

- **Sensor hardware**: external device · Inertial Labs navigation sensor or network endpoint

## Connections

- Sensor hardware → Transport: stream data · Sensor output enters the SDK through a transport connection
- Transport → ILDriver: feeds · Transport delivers bytes and packets to the device driver
- ILDriver → UDD parser: parses via · Driver relies on packet parsing to decode device output
- UDD parser → INS node: decodes for · Parsed state is consumed by the ROS driver node
- INS node → Sensor data: publishes · Publishes raw sensor and environmental data
- INS node → INS data: publishes · Publishes navigation solution state
- INS node → GNSS data: publishes · Publishes GNSS-related status and fixes
- INS node → GPS data: publishes · Publishes GPS kinematics and position data
- INS node → Marine data: publishes · Publishes marine motion outputs
- Launch file → INS node: starts · ROS launch entrypoint starts the driver node
- INS node → Transport: opens · Node selects and opens the configured connection URL
- Transport → Linux serial: implements · Linux serial backend for the transport layer
- Transport → Linux net: implements · Linux network backend for the transport layer
- Transport → Windows serial: implements · Windows serial backend for the transport layer
- Transport → Windows net: implements · Windows network backend for the transport layer
- ROS pkgs → INS node: packages · Umbrella package groups the ROS driver package
- ROS pkgs → Sensor data: packages · Umbrella package groups the shared message package