Skip to content
BranchesTags

Repository files navigation

A.R.G.U.S - "Detect. Decide. Stop."

Overview

A.R.G.U.S. (Adaptive Real-Time Guardian for Unsafe Situations) is a real-time safety supervisor for a small robotic arm.
It watches camera input, decides whether the scene is safe, and routes motion through guardian + interlock logic so unsafe conditions trigger retract + freeze.

ARGUS bench setup view 1 ARGUS bench setup view 2 Validated ARGUS bench setup on Raspberry Pi 5 with Pi Camera, PCA9685 and MeArm platform.

Bill of Materials (BOM)

Controller

Component Quantity Cost (£)
Raspberry Pi 5 1 Free

Sensors & Vision

Component Quantity Cost (£)
Raspberry Pi Camera Module 1 Free

Additional Components

Component Quantity Cost (£)
MeArm Maker Kit V3 1 £47
Adafruit PCA9685 1 £14.40
Raspberry Pi Power Supply 1 £11.50
Tactile Switch Button 1 Free
6V AA Batteries 1 Free
Breadboard 1 Free
Jumper Wires 1 Free
3D Printed Tools 2 Free

Total Cost: £72.90

Current validated bench hardware

Component Quantity Notes
Raspberry Pi 5 1 validated target
Raspberry Pi camera 1 used with libcamerify
Adafruit PCA9685 1 I2C servo driver
MeArm 1 4-servo arm
Servos 4 base / lower / upper / grip
Momentary tactile button 1 active-low physical continue / ACK
External 6V battery pack 1 servo power

What Is Validated

Current validated runtime path:

AppController -> CameraCapture -> VisionProcessor -> GuardianStateMachine -> RobotInterlock -> MotionController

Validated hardware:

  • Raspberry Pi 5
  • Raspberry Pi camera
  • Adafruit PCA9685 (I2C)
  • MeArm (4 servos)
  • one physical operator button (GPIO24, active-low)

Validated behaviour:

  • live camera safety supervision
  • forbidden-layer colour unsafe trigger
  • guardian freeze/recover state flow
  • retract-safe before freeze hold
  • manual operator acknowledge to resume
  • single control contract: space key or physical button

Quick Start (Fresh Pi / Debian)

1) Install prerequisites

sudo apt update
sudo apt install -y \
  build-essential cmake pkg-config \
  libopencv-dev libopencv-contrib-dev \
  libcamera-tools libcamera-dev libturbojpeg0-dev

2) Clone and build

git clone git@github.com:ENG5220-RTEP-Team-ARGUS/ARGUS.git --recursive
cd ARGUS
cmake -S . -B build
cmake --build build -j$(nproc)

3) Run the live demo (recommended)

./scripts/live_test.sh

Notes:

  • live_test.sh self-elevates with sudo for GPIO button access
  • wrapper tries libcamera2opencv first, then falls back to OpenCV/V4L2
  • you can force backend:
    • ARGUS_CAMERA_BACKEND=libcamera2opencv ./scripts/live_test.sh
    • ARGUS_CAMERA_BACKEND=opencv ./scripts/live_test.sh

Live Demo Controls

Global controls:

  • space or physical button: single control action (arm/disarm/ack based on current state)
  • 0: manual mode
  • 1: routine 1 (SURGERY_CUT)
  • 2: routine 2 (BASE_SCAN)
  • 3: routine 3 (GRIP_PULSE)
  • esc: quit
  • +/-: camera focus adjust (Pi Camera Module 3)

Manual mode (0) keys:

  • d/a: base left/right
  • w/s: forward/backward
  • i/k: up/down
  • l/j: gripper open/close

Expected safety flow:

  1. Start in disarmed setup mode.
  2. Wait until scene is safe.
  3. Press space/button to arm and start.
  4. Unsafe trigger occurs -> routine stops -> retract-safe -> freeze hold.
  5. Make scene safe again.
  6. Press space/button to acknowledge and resume.

Common Commands

Camera backend check

./scripts/camera_backend_check.sh

Motion smoke tests

./scripts/smoke_all.sh
./scripts/smoke_base.sh
./scripts/smoke_lower.sh
./scripts/smoke_upper.sh
./scripts/smoke_grip.sh

Home pose

./scripts/set_home.sh

Servo tools

./scripts/servo_console.sh
./scripts/servo_drive.sh
./scripts/servo_calibrate.sh

Button test

./scripts/test_button.sh

Test Commands

Unit/integration tests configured in CMake:

cmake -S . -B build
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure

Latency Metrics (Runtime)

Runtime logs and dashboards expose:

  • vision_us
  • unsafe_detect_ms
  • freeze_pipeline_ms
  • freeze_cmd_ms
  • total_stop_ms
  • ack_to_resume_ms

Current guardian thresholds in live mode:

  • freeze after 15 consecutive bad frames
  • recover after 3 consecutive good frames

Safety & Performance Metrics Justification

Benchmarked against published literature and IEC 80601-2-77.

Metric Measured Target Status Justification
Frame Processing 706 µs — Good Well below the 75 ms achieved by NVIDIA Holoscan [1] and 15–20 ms AI pipelines in MIS [2].
Detect Unsafe 4 ms ≤ 30 ms Good Delays >100 ms risk tissue damage [3]. Meets IEC 80601-2-77 protective stop requirements [4].
Issue Freeze 458 ms ≤ 900 ms Good Telesurgery validated up to 500 ms latency [5]; 320 ms confirmed safe over 3000 km [6].
Stop Motion 7206 ms ≤ 8000 ms Good Controlled deceleration prevents secondary tissue injury per IEC 80601-2-77 [4].

References

  1. NVIDIA, "Real-Time Surgical Guidance with Holoscan," 2025. Link
  2. "AI-Based Sensorless Force Feedback in Robot-Assisted MIS," MDPI, 2025. Link
  3. Leung, "Engineering precision in surgical robotics," Medical Design & Outsourcing, 2025. Link
  4. IEC 80601-2-77:2019; Chinzei, "Safety of Surgical Robots," Acta Polytechnica Hungarica, 2019. PDF
  5. Korte et al., "Impact of latency on surgical precision," Computer Aided Surgery, 2005. Link
  6. Xu et al., "Latency in robot-assisted telesurgery," PMC, 2024. Link

Architecture and Compliance

Key docs:

Wiki

Project wiki:

Documentation

Doxygen API Reference

Full API documentation is generated from source comments:

🔗 Browse Doxygen Docs

To regenerate locally:

doxygen Doxyfile
open docs/doxygen/html/index.html

Repository Layout

config/                Runtime configuration and calibration files
docs/architecture/     Architecture and wiring diagrams
docs/adr/              Architecture decision records
docs/doxygen/          Generated Doxygen HTML output
docs/compliance_matrix.md
include/               Headers
src/                   C++ implementation
scripts/               Pi run/test helper scripts
tests/                 CTest targets
third_party/           Vendored third-party dependencies

Promotion

ARGUS public channels for demos, build updates, and outreach:

Authors & Contributions

Name Component Ownership Key Contributions
Nathan Sidi Bakari MotionController, AppController Servo output path, PCA9685 driver integration, run modes, CLI interface, hardware wiring, social media content
Patricia Munginga VisionProcessor Vision safety pipeline, colour detection, Doxygen documentation, PR reviews, social media content
Jui Ning Chin GuardianStateMachine FSM design and implementation, state transitions, freeze/recovery logic, social media content
Liyue Tian CameraCapture Camera acquisition pipeline, libcamera2opencv integration, V4L2 fallback, social media content
Nigar Baghirova RobotInterlock Interlock gate logic, atomic state management, motion enable/disable, social media content

Project management

This project is tracked using GitHub Projects. The project board tracks all issues, bugs and tasks with clear ownership per team member.

Acknowledgements

  • Dr Bernd Porr and Dr Chongfeng Wei - course lecturers, ENG5220 Real-Time Embedded Programming
  • Teaching assistants — lab support and coding standard guidance
  • Bernd Porr's open-source libraries - cppTimer and libcamera2opencv, vendored under third_party/ with GPL licensing
  • University of Glasgow, School of Engineering - lab facilities and hardware budget

License

Mixed license model:

  • original ARGUS code outside third_party/: MIT
  • vendored third-party code in third_party/: original upstream licenses

See:

About

A.R.G.U.S. is a real-time, vision-based safety supervision layer for robotic manipulators. It continuously monitors the workspace, evaluates collision or interference risk under strict latency constraints, and triggers fail-safe interventions (e.g. hard stop) via event-driven control, prioritising deterministic response and safe interruption.

thewebbutbeyond.github.io/argus/

Resources

Readme
License
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages