# intelligent-quads/iq_gnc architecture

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

- Interactive diagram: https://gitdiagram.com/intelligent-quads/iq_gnc
- Repository: https://github.com/intelligent-quads/iq_gnc

## Overview

1. **What this repository is**
   - `iq_gnc` is a ROS-oriented drone guidance and control package.
   - Its main purpose is to provide reusable high-level flight-control helpers plus a set of example mission nodes in both C++ and Python.

2. **Primary architectural boundary: ROS node layer vs. control helper layer**
   - The repo is split into:
     - a **core guidance/control helper API** (`include/gnc_functions.hpp` and `src/iq_gnc/py_gnc_functions.py`)
     - **example mission implementations** that call into that API
     - **launch files** that connect the package to the flight stack
   - This makes the reusable control logic distinct from the mission scripts.

3. **C++ control API**
   - `include/gnc_functions.hpp` is the C++ helper interface for common drone actions.
   - The README says it covers things like:
     - interpreting state estimation
     - commanding waypoints
     - changing flight modes
   - C++ example nodes in `src/*.cpp` use this layer to implement missions.

4. **Python control API**
   - `src/iq_gnc/py_gnc_functions.py` is the Python translation of the same helper concepts.
   - The package is installed as a Python module via `setup.py`, and the Python examples import from `src/iq_gnc`.
   - This gives the repo a dual-language architecture with equivalent mission-control primitives.

5. **C++ example mission nodes**
   - `src/gnc_tutorial.cpp` — simple square waypoint mission.
   - `src/avoidance_sol.cpp` — obstacle avoidance using a potential-field approach.
   - `src/sr_sol.cpp` — search-and-rescue mission that flies a pattern until detection triggers landing.
   - `src/subscriber_sol.cpp` — shows how external subscriber input can steer guidance behavior.
   - `src/square.cpp`, `src/set_wp.cpp` appear to be additional mission/demo nodes for waypoint and square-flight behavior.
   - These are not infrastructure; they are the application layer built on top of the helper API.

6. **Python example mission scripts**
   - `scripts/obs_avoid.py`, `scripts/snr.py`, `scripts/square.py`, `scripts/subscriber.py` are the Python equivalents of the C++ examples.
   - They demonstrate the same control patterns but through the Python helper module.
   - This suggests the package is designed for both rapid prototyping and C++-based deployment.

7. **Launch/integration layer**
   - `launch/mavros_node.launch` and `launch/apm.launch` are the integration entry points.
   - They indicate the package is meant to work with:
     - a ROS flight-control bridge (`mavros`)
     - an autopilot stack, specifically APM/ArduPilot
   - In architecture terms, these launch files sit between the mission nodes and the vehicle/autopilot ecosystem.

8. **Main data flow**
   - External vehicle state and commands flow through ROS/MAVROS into the guidance nodes.
   - Mission nodes read state, sensor, or subscriber inputs, then compute:
     - setpoints
     - waypoint targets
     - mode changes
     - landing/mission transitions
   - Output goes back through ROS/MAVROS to the autopilot.

9. **Perception-driven behavior**
   - `sr_sol.cpp` references a search-and-rescue pattern that waits for YOLO-based person detection before landing.
   - That implies a boundary where perception output becomes a mission trigger.
   - The guidance layer does not perform the vision itself; it reacts to detection signals from another subsystem.

10. **Reusable integration pattern**
   - `subscriber_sol.cpp` and `scripts/subscriber.py` show that the package is designed to ingest external ROS messages as mission inputs.
   - This means mission logic can be driven by either onboard autonomy logic or offboard events.

11. **Build and packaging model**
   - `CMakeLists.txt`, `package.xml`, and `.github/workflows/catkin_build.yml` show this is a ROS catkin package with CI support.
   - `setup.py` and `src/iq_gnc/__init__.py` show the Python side is packaged as an installable module.
   - So the repo is a mixed-language ROS package rather than a standalone Python project or pure C++ library.

12. **Documentation and external dependency boundaries**
   - `docs/py_gnc_functions.md` documents the Python API.
   - The README points users to the separate `iq_tutorials` repo for environment setup and drone-programming lessons, and `iq_sim` for simulation worlds.
   - So `iq_gnc` is the control/missions package, while tutorials and simulation live outside the repo.

13. **How to draw the architecture**
   - At the center: the guidance/control helper API.
   - Above it: C++ and Python mission nodes/scripts.
   - To one side: ROS/MAVROS/APM integration via launch files.
   - To the other side: subscriber inputs, state estimation, and perception triggers.
   - Supporting the whole system: ROS/catkin build tooling and Python packaging.

Main entry points: [`src/iq_gnc/py_gnc_functions.py`](https://github.com/intelligent-quads/iq_gnc/blob/master/src/iq_gnc/py_gnc_functions.py) (Py helpers), [`include/gnc_functions.hpp`](https://github.com/intelligent-quads/iq_gnc/blob/master/include/gnc_functions.hpp) (GNC helpers), [`CMakeLists.txt`](https://github.com/intelligent-quads/iq_gnc/blob/master/CMakeLists.txt) (Catkin build), [`src/sr_sol.cpp`](https://github.com/intelligent-quads/iq_gnc/blob/master/src/sr_sol.cpp) (SR mission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Control API"]
  node_gnc_header["GNC helpers<br/>C++ API<br/>[gnc_functions.hpp]"]
  node_py_gnc["Py helpers<br/>Python API"]
  node_py_init["Package init<br/>Python package<br/>[__init__.py]"]
end

subgraph group_cpp_missions["C++ Missions"]
  node_cpp_tutorial(("Tutorial mission<br/>C++ node<br/>[gnc_tutorial.cpp]"))
  node_cpp_avoid(("Avoidance sol<br/>C++ node<br/>[avoidance_sol.cpp]"))
  node_cpp_sr(("SR mission<br/>C++ node<br/>[sr_sol.cpp]"))
  node_cpp_sub(("Subscriber sol<br/>C++ node<br/>[subscriber_sol.cpp]"))
  node_cpp_square(("Square demo<br/>C++ node<br/>[square.cpp]"))
  node_cpp_setwp(("Set waypoint<br/>C++ node<br/>[set_wp.cpp]"))
end

subgraph group_py_missions["Python Missions"]
  node_py_avoid(("Obs avoid<br/>Python script<br/>[obs_avoid.py]"))
  node_py_snr(("SNR script<br/>Python script<br/>[snr.py]"))
  node_py_square(("Square script<br/>Python script<br/>[square.py]"))
  node_py_sub(("Subscriber script<br/>Python script<br/>[subscriber.py]"))
end

subgraph group_integration["ROS Integration"]
  node_mavros_launch["MAVROS launch<br/>[mavros_node.launch]"]
  node_apm_launch["APM launch<br/>ROS launch<br/>[apm.launch]"]
  node_multi_launch["Multi square<br/>ROS launch"]
  node_mavros{{"MAVROS<br/>ROS bridge"}}
  node_apm{{"APM/ArduPilot<br/>autopilot"}}
  node_vision{{"Perception<br/>external input"}}
end

subgraph group_tooling["Build & Docs"]
  node_catkin["Catkin build<br/>ROS packaging<br/>[CMakeLists.txt]"]
  node_package_xml["Package manifest<br/>ROS metadata<br/>[package.xml]"]
  node_setup_py["Python setup<br/>packaging<br/>[setup.py]"]
  node_docs_py["Python docs"]
  node_ci["CI workflow<br/>automation<br/>[catkin_build.yml]"]
end

node_cpp_tutorial -->|"uses"| node_gnc_header
node_cpp_avoid -->|"uses"| node_gnc_header
node_cpp_sr -->|"uses"| node_gnc_header
node_cpp_sub -->|"uses"| node_gnc_header
node_cpp_square -->|"uses"| node_gnc_header
node_cpp_setwp -->|"uses"| node_gnc_header
node_py_avoid -->|"uses"| node_py_gnc
node_py_snr -->|"uses"| node_py_gnc
node_py_square -->|"uses"| node_py_gnc
node_py_sub -->|"uses"| node_py_gnc
node_py_init -->|"exports"| node_py_gnc
node_mavros_launch -->|"starts"| node_mavros
node_apm_launch -->|"targets"| node_apm
node_multi_launch -->|"launches"| node_cpp_square
node_mavros -->|"feeds"| node_gnc_header
node_mavros -->|"feeds"| node_py_gnc
node_gnc_header -->|"commands"| node_apm
node_py_gnc -->|"commands"| node_apm
node_cpp_sr -->|"triggered by"| node_vision
node_cpp_sub -->|"ingests"| node_vision
node_py_sub -->|"ingests"| node_vision
node_catkin -->|"builds"| node_gnc_header
node_catkin -->|"packages"| node_py_gnc
node_package_xml -->|"declares"| node_catkin
node_setup_py -->|"installs"| node_py_gnc
node_docs_py -->|"documents"| node_py_gnc
node_ci -->|"validates"| node_catkin

click node_gnc_header "https://github.com/intelligent-quads/iq_gnc/blob/master/include/gnc_functions.hpp"
click node_py_gnc "https://github.com/intelligent-quads/iq_gnc/blob/master/src/iq_gnc/py_gnc_functions.py"
click node_py_init "https://github.com/intelligent-quads/iq_gnc/blob/master/src/iq_gnc/__init__.py"
click node_cpp_tutorial "https://github.com/intelligent-quads/iq_gnc/blob/master/src/gnc_tutorial.cpp"
click node_cpp_avoid "https://github.com/intelligent-quads/iq_gnc/blob/master/src/avoidance_sol.cpp"
click node_cpp_sr "https://github.com/intelligent-quads/iq_gnc/blob/master/src/sr_sol.cpp"
click node_cpp_sub "https://github.com/intelligent-quads/iq_gnc/blob/master/src/subscriber_sol.cpp"
click node_cpp_square "https://github.com/intelligent-quads/iq_gnc/blob/master/src/square.cpp"
click node_cpp_setwp "https://github.com/intelligent-quads/iq_gnc/blob/master/src/set_wp.cpp"
click node_py_avoid "https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/obs_avoid.py"
click node_py_snr "https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/snr.py"
click node_py_square "https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/square.py"
click node_py_sub "https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/subscriber.py"
click node_mavros_launch "https://github.com/intelligent-quads/iq_gnc/blob/master/launch/mavros_node.launch"
click node_apm_launch "https://github.com/intelligent-quads/iq_gnc/blob/master/launch/apm.launch"
click node_multi_launch "https://github.com/intelligent-quads/iq_gnc/blob/master/launch/multi_square_sol.launch"
click node_catkin "https://github.com/intelligent-quads/iq_gnc/blob/master/CMakeLists.txt"
click node_package_xml "https://github.com/intelligent-quads/iq_gnc/blob/master/package.xml"
click node_setup_py "https://github.com/intelligent-quads/iq_gnc/blob/master/setup.py"
click node_docs_py "https://github.com/intelligent-quads/iq_gnc/blob/master/docs/py_gnc_functions.md"
click node_ci "https://github.com/intelligent-quads/iq_gnc/blob/master/.github/workflows/catkin_build.yml"

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_gnc_header,node_py_gnc,node_py_init toneBlue
class node_cpp_tutorial,node_cpp_avoid,node_cpp_sr,node_cpp_sub,node_cpp_square,node_cpp_setwp toneAmber
class node_py_avoid,node_py_snr,node_py_square,node_py_sub toneMint
class node_mavros_launch,node_apm_launch,node_multi_launch,node_mavros,node_apm,node_vision toneRose
class node_catkin,node_package_xml,node_setup_py,node_docs_py,node_ci toneIndigo
```

## Components

### Control API

Reusable guidance and control helpers shared by missions.

- [GNC helpers](https://github.com/intelligent-quads/iq_gnc/blob/master/include/gnc_functions.hpp): C++ API · Reusable helper interface for state handling, waypoint control, and flight mode changes. · `include/gnc_functions.hpp`
- [Py helpers](https://github.com/intelligent-quads/iq_gnc/blob/master/src/iq_gnc/py_gnc_functions.py): Python API · Python translation of the guidance/control helper concepts. · `src/iq_gnc/py_gnc_functions.py`
- [Package init](https://github.com/intelligent-quads/iq_gnc/blob/master/src/iq_gnc/__init__.py): Python package · Installable module entry point for the Python side of the package. · `src/iq_gnc/__init__.py`

### C++ Missions

Example flight behaviors implemented in C++ on top of the helper API.

- [Tutorial mission](https://github.com/intelligent-quads/iq_gnc/blob/master/src/gnc_tutorial.cpp): C++ node · Basic square-flight example using the helper API. · `src/gnc_tutorial.cpp`
- [Avoidance sol](https://github.com/intelligent-quads/iq_gnc/blob/master/src/avoidance_sol.cpp): C++ node · Potential-field obstacle avoidance mission example. · `src/avoidance_sol.cpp`
- [SR mission](https://github.com/intelligent-quads/iq_gnc/blob/master/src/sr_sol.cpp): C++ node · Search-and-rescue mission that transitions to landing after detection. · `src/sr_sol.cpp`
- [Subscriber sol](https://github.com/intelligent-quads/iq_gnc/blob/master/src/subscriber_sol.cpp): C++ node · Mission example driven by external subscriber input. · `src/subscriber_sol.cpp`
- [Square demo](https://github.com/intelligent-quads/iq_gnc/blob/master/src/square.cpp): C++ node · Waypoint square-flight example. · `src/square.cpp`
- [Set waypoint](https://github.com/intelligent-quads/iq_gnc/blob/master/src/set_wp.cpp): C++ node · Waypoint-targeting demo node. · `src/set_wp.cpp`

### Python Missions

Example flight behaviors implemented in Python on top of the helper API.

- [Obs avoid](https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/obs_avoid.py): Python script · Python obstacle-avoidance mission example. · `scripts/obs_avoid.py`
- [SNR script](https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/snr.py): Python script · Python search-and-rescue mission example. · `scripts/snr.py`
- [Square script](https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/square.py): Python script · Python square-flight mission example. · `scripts/square.py`
- [Subscriber script](https://github.com/intelligent-quads/iq_gnc/blob/master/scripts/subscriber.py): Python script · Python example that reacts to external messages. · `scripts/subscriber.py`

### ROS Integration

Launch files and external flight-stack boundaries.

- [MAVROS launch](https://github.com/intelligent-quads/iq_gnc/blob/master/launch/mavros_node.launch): ROS launch · Launch entry point for the ROS flight-control bridge. · `launch/mavros_node.launch`
- [APM launch](https://github.com/intelligent-quads/iq_gnc/blob/master/launch/apm.launch): ROS launch · Launch entry point for the ArduPilot/APM flight stack integration. · `launch/apm.launch`
- [Multi square](https://github.com/intelligent-quads/iq_gnc/blob/master/launch/multi_square_sol.launch): ROS launch · Launch file for a multi-node square-flight setup. · `launch/multi_square_sol.launch`
- **MAVROS**: ROS bridge · External ROS bridge between mission logic and vehicle control.
- **APM/ArduPilot**: autopilot · External autopilot stack targeted by the package.
- **Perception**: external input · External detection source used as a mission trigger, such as YOLO person detection.

### Build & Docs

Packaging, build, CI, and documentation support.

- [Catkin build](https://github.com/intelligent-quads/iq_gnc/blob/master/CMakeLists.txt): ROS packaging · CMake/catkin package build and integration metadata. · `CMakeLists.txt`
- [Package manifest](https://github.com/intelligent-quads/iq_gnc/blob/master/package.xml): ROS metadata · ROS package declaration and dependency metadata. · `package.xml`
- [Python setup](https://github.com/intelligent-quads/iq_gnc/blob/master/setup.py): packaging · Python module packaging and install configuration. · `setup.py`
- [Python docs](https://github.com/intelligent-quads/iq_gnc/blob/master/docs/py_gnc_functions.md): docs · Documentation for the Python helper API. · `docs/py_gnc_functions.md`
- [CI workflow](https://github.com/intelligent-quads/iq_gnc/blob/master/.github/workflows/catkin_build.yml): automation · GitHub Actions catkin build workflow. · `.github/workflows/catkin_build.yml`

## Connections

- Tutorial mission → GNC helpers: uses · C++ missions build on the reusable guidance helpers.
- Avoidance sol → GNC helpers: uses · Obstacle avoidance is implemented through the shared helper API.
- SR mission → GNC helpers: uses · Search-and-rescue behavior relies on the helper layer.
- Subscriber sol → GNC helpers: uses · Subscriber-driven guidance uses the shared C++ API.
- Square demo → GNC helpers: uses · Square-flight demo uses waypoint and mode helpers.
- Set waypoint → GNC helpers: uses · Waypoint demo calls into the shared guidance API.
- Obs avoid → Py helpers: uses · Python obstacle avoidance is built on the Python helper module.
- SNR script → Py helpers: uses · Python search-and-rescue behavior uses the Python helper module.
- Square script → Py helpers: uses · Python square-flight demo uses the helper module.
- Subscriber script → Py helpers: uses · Python subscriber demo uses the helper module.
- Package init → Py helpers: exports · Package init exposes the Python helper module.
- MAVROS launch → MAVROS: starts · Launch file brings up the ROS flight bridge.
- APM launch → APM/ArduPilot: targets · Launch file configures the autopilot integration.
- Multi square → Square demo: launches · Composite launch file coordinates the square-flight nodes.
- MAVROS → GNC helpers: feeds · Vehicle state and command exchange passes through the ROS bridge to the C++ control layer.
- MAVROS → Py helpers: feeds · Vehicle state and command exchange passes through the ROS bridge to the Python control layer.
- GNC helpers → APM/ArduPilot: commands · Helper API emits flight commands toward the autopilot stack.
- Py helpers → APM/ArduPilot: commands · Python helper API emits flight commands toward the autopilot stack.
- SR mission → Perception: triggered by · Search-and-rescue mission reacts to external perception results before landing.
- Subscriber sol → Perception: ingests · Subscriber-driven mission accepts external ROS input as a mission signal.
- Subscriber script → Perception: ingests · Python subscriber example accepts external ROS input as a mission signal.
- Catkin build → GNC helpers: builds · Catkin/CMake build covers the C++ helper layer.
- Catkin build → Py helpers: packages · Catkin build also installs the Python module.
- Package manifest → Catkin build: declares · ROS manifest defines package metadata and dependencies.
- Python setup → Py helpers: installs · Python packaging exposes the helper module for import.
- Python docs → Py helpers: documents · Docs explain the Python control helper API.
- CI workflow → Catkin build: validates · GitHub Actions checks the ROS build.