A lightweight module system for small remotely operated underwater vehicles, native
to Linux and small enough for the vehicle's own Raspberry Pi. Every function of the
vehicle is its own process; one manager, hangard, starts, watches and restarts them;
they exchange fixed-size messages through shared-memory topics in which every message
records, by identifier, the input messages it was computed from. That record is what
makes the learning loop possible: training samples defined once and streamed live
to a trainer on the topside, weights sent back and checked by the vehicle before they
run, and any thruster command traceable to the model that produced it, the rows that
trained the model, and the sensor readings behind the rows.
It descends from electric-eye, whose camera, image operators and video transport it carries forward, and it is built for one vehicle and its topside, not a fleet: no DDS, no runtime type system, no daemon between publisher and subscriber.
- Topics (
lib/hg): fixed-size messages in shared memory, a wake-up without polling, calls and parameters on the same mechanism, and in every message the identifiers of the inputs it was computed from. - A manager (
hangard) that starts each module from a manifest, wires it to exactly the topics it declares, restarts it with back-off, runs an actuator's neutral command whenever the actuator's module exits, and adopts the running modules again after its own restart.hangaris its command-line tool. - Vehicle control through ArduSub:
safety(arming, failsafes, the gate every actuator command passes),mux(pilot, controller and bounded policy output per axis),mavlink(its own MAVLink 2 over UDP or the autopilot's serial line),joystick,navanddepth_hold. - Video without a transcoder on the vehicle:
encodersends the camera's own H.264 over RTP;video_relay,visionandtopside_encoderdecode, process and re-encode on the topside. - Recording and learning:
recorderand its.hgrfiles, dataset specifications, thepairerthat turns provenance into training rows as they happen,policyfor inference on the vehicle with checked weights, and a Python package for reading recordings, training and exporting. - A tether bridge (
bridge): topics and calls between the vehicle and the topside over an authenticated UDP link, with the two clocks reconciled. - Dawn Patrol (
console): a web console for the pilot and the operator. - A simulator:
sim_vehicle, a 6-DOF model that runs alone or as the physics of ArduSub's SITL (tools/sim/).
It has been run on a BlueROV2 (Raspberry Pi 5, ArduSub 4.5 on a Pixhawk); the procedure and the measurements are in tools/rov/README.md.
| Directory | |
|---|---|
docs/ |
the design, one document per part; start at 00-overview.md |
lib/hg/ |
the module library: topics, provenance, waiting, calls, parameters, recordings (LGPL) |
hangard/, hangar/ |
the manager and the command-line tool |
modules/ |
the modules, one directory each with its own README, and common/ for what they share |
msg/ |
message types (.msg) and their generated headers |
profiles/ |
manifest sets: the simulation roots, the lab's BlueROV2 and its topside |
lib/sim/, lib/nn/ |
the simulator's physics; the inference runtime and the .hgw weights file |
lib/vision/, lib/camera/, lib/net/, lib/video/, lib/proc/, lib/common/ |
image operators, camera, network and video code, much of it carried over from electric-eye |
python/ |
the topside package: schemas, .hgr and dataset readers, live topics, training and export |
tools/ |
the message and MAVLink generators, the release and cross builds, the simulator container, and tools/rov/ for a session on a real vehicle |
bench/ |
the benchmark harness and its results |
legacy/ |
electric-eye's eeye and hellion, kept until the native video modules have replaced them |
proposal/ |
the research proposal |
C11, GNU make, and gcc, clang or zig cc; libjpeg-turbo for the camera code. The video
modules that decode and encode need libavcodec and libx264 and are left out where
those are missing.
make -j"$(nproc)" all # the manager, the tool and every module
make -j"$(nproc)" check # every test suite
make check-tsan check-asan # the library's suites under the sanitizers
make equivalence # image operators hashed against electric-eye v0.3.1
tools/release.sh # the static aarch64 release tarball (zig cc, musl)Static release binaries are built with zig cc for aarch64-linux-musl and
arm-linux-musleabihf; see tools/cross/README.md. CI runs
the suites with gcc, clang and zig cc on x86-64 and natively on arm64, the sanitizers,
the equivalence check, and the cross builds.
- In simulation, with Gazebo and ArduSub's SITL in a container: tools/sim/SETUP.md.
- On a vehicle, from the topside laptop over the tether: tools/rov/QUICKSTART.md. A session saves the autopilot's parameters before it changes any and puts them back at the end.
- The command-line tool and the console: docs/12-tools.md.
If you use hangar in your research, please cite it. The metadata is in CITATION.cff (GitHub's "Cite this repository" gives it as APA and BibTeX). Each release is archived on Zenodo: 10.5281/zenodo.24084277 names all versions and resolves to the latest; version 0.1.2 is 10.5281/zenodo.24395921.
H. Oğuz Bolat (Department of Geomatics Engineering, Yıldız Technical University; ORCID 0009-0000-8522-7746) and Hakan Ersoy (Department of Electronics and Communications Engineering, Yıldız Technical University; ORCID 0009-0006-0495-6589). hangar: a lightweight module system for small underwater vehicles, with a provenance-recorded learning loop. Software, version 0.1.2, 2026. https://doi.org/10.5281/zenodo.24395921
@software{bolat_ersoy_hangar_2026,
author = {Bolat, H. O{\u{g}}uz and Ersoy, Hakan},
title = {hangar: a lightweight module system for small underwater vehicles,
with a provenance-recorded learning loop},
version = {0.1.2},
year = {2026},
doi = {10.5281/zenodo.24395921},
url = {https://github.com/hogib/hangar},
license = {GPL-3.0-or-later}
}GNU GPL v3.0 or later for the system; GNU LGPL v3.0 or later for the module library
(lib/hg) and the Python package, so that a module may be written in any language
under any licence. electric-eye's code keeps its MIT notices. See
LICENSING.md.