How intelligent-quads/iq_gnc works
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: py_gnc_functions.py Py helpers · gnc_functions.hpp GNC helpers · CMakeLists.txt Catkin build · sr_sol.cpp SR mission
Components 24
Control API
Reusable guidance and control helpers shared by missions.
- GNC helpers · Reusable helper interface for state handling, waypoint control, and flight mode changes.
include/gnc_functions.hpp - Py helpers · Python translation of the guidance/control helper concepts.
src/iq_gnc/py_gnc_functions.py - Package init · 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 · Basic square-flight example using the helper API.
src/gnc_tutorial.cpp - Avoidance sol · Potential-field obstacle avoidance mission example.
src/avoidance_sol.cpp - SR mission · Search-and-rescue mission that transitions to landing after detection.
src/sr_sol.cpp - Subscriber sol · Mission example driven by external subscriber input.
src/subscriber_sol.cpp - Square demo · Waypoint square-flight example.
src/square.cpp - Set waypoint · Waypoint-targeting demo node.
src/set_wp.cpp
Python Missions
Example flight behaviors implemented in Python on top of the helper API.
- Obs avoid · Python obstacle-avoidance mission example.
scripts/obs_avoid.py - SNR script · Python search-and-rescue mission example.
scripts/snr.py - Square script · Python square-flight mission example.
scripts/square.py - Subscriber script · Python example that reacts to external messages.
scripts/subscriber.py
ROS Integration
Launch files and external flight-stack boundaries.
- MAVROS launch · Launch entry point for the ROS flight-control bridge.
launch/mavros_node.launch - APM launch · Launch entry point for the ArduPilot/APM flight stack integration.
launch/apm.launch - Multi square · Launch file for a multi-node square-flight setup.
launch/multi_square_sol.launch - MAVROS · External ROS bridge between mission logic and vehicle control.
- APM/ArduPilot · External autopilot stack targeted by the package.
- Perception · External detection source used as a mission trigger, such as YOLO person detection.
Build & Docs
Packaging, build, CI, and documentation support.
- Catkin build · CMake/catkin package build and integration metadata.
CMakeLists.txt - Package manifest · ROS package declaration and dependency metadata.
package.xml - Python setup · Python module packaging and install configuration.
setup.py - Python docs · Documentation for the Python helper API.
docs/py_gnc_functions.md - CI workflow · GitHub Actions catkin build workflow.
.github/workflows/catkin_build.yml
Connections 27
- 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.