Implement emergency safety handling

[jkaflik]

Summary

• add OpenMower-style emergency state handling for HW 0.13.x hall inputs
• publish individual emergency ROS 2 status topics at 10 Hz
• add emergency/command latch/release topic requiring 3 matching commands within 1 second
• add priority blinking red emergency LED status
• safely initialize PIN_ESC_SHUTDOWN LOW without dynamic shutdown logic
• add interactive ROS 2 HIL emergency test for real hardware validation

Verification

• /home/jkaflik/.platformio/penv/bin/pio run
• python3 -m py_compile test/hil/emergency_interactive.py

Closes #5

Summary by CodeRabbit

• New Features

  • Emergency mode system with latching control triggered by stop, lift, and tilt inputs
  • Emergency status LED indicator displaying red blinking with priority over normal status
  • Emergency ROS API including status monitoring topic and software command interface

• Documentation

  • Updated README documenting emergency mode features, LED status behavior, and testing procedures

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1d9e3d5d-18bb-46c7-8c9f-aa4aaa7db393

📥 Commits

Reviewing files that changed from the base of the PR and between e004cdf and ec6b944.

📒 Files selected for processing (15)

• .gitignore
• README.md
• extra_packages/omros2_firmware_msgs/CMakeLists.txt
• extra_packages/omros2_firmware_msgs/msg/EmergencyStatus.msg
• extra_packages/omros2_firmware_msgs/package.xml
• microros.meta
• platformio.ini
• src/emergency.cpp
• src/emergency.h
• src/led_status.hpp
• src/main.cpp
• src/ros.cpp
• src/ros.h
• test/hil/emergency_interactive.py
• utils/remote-openocd.sh

---

📝 Walkthrough

Walkthrough

This PR implements the emergency safety feature for OpenMower firmware: hardware debouncing of three physical emergency inputs (stop, lift, tilt), latching behavior that persists until physical conditions clear, ROS 2 subscription support enabling software-triggered latch/release commands, and LED status indication. The implementation includes comprehensive interactive testing and documentation.

Changes

Emergency Safety Features Implementation

Layer / File(s)	Summary
ROS 2 Subscription Infrastructure src/ros.h, src/ros.cpp	Adds SubscriptionBase abstract class and Subscriber<MessageT> template to receive ROS 2 messages with user callbacks. Manages subscription lifecycle, message-to-user-pointer mapping, executor integration, and resource cleanup. Increases executor capacity from 10 to 16 and refactors timer initialization with explicit error handling.
Emergency Message Schema and Configuration extra_packages/omros2_firmware_msgs/msg/EmergencyStatus.msg, CMakeLists.txt, package.xml, microros.meta, platformio.ini	Defines EmergencyStatus message with seven fields: active status, three physical input flags (stop/lift/tilt), software request flag, release-block flag, and lifted-wheel count. Includes ROS 2 package manifest and micro-ROS configuration for entity timeouts and publisher limits.
Emergency State Machine src/emergency.h, src/emergency.cpp	Implements debounced input reading for three physical emergency inputs with configurable timing thresholds. Maintains a latched emergency state that persists until physical conditions clear and release is approved. Handles software-triggered latch/release commands requiring repeated confirmations within a time window. Exposes state via getState() and updates via mutex-protected update().
LED Status Integration src/led_status.hpp	Adds LED_STATUS_EMERGENCY flag to status bitmask. Implements emergency override in LedStatus::update(): when emergency is active, LED immediately shows red blinking and returns early, interrupting normal status sequencing.
Main Firmware Integration src/main.cpp	Initializes emergency subsystem in setup(), calls emergency::update() in both loop() and dual-core synchronization. Updates LED status flag from emergency::getState().active in loop1(). Refactors ROS power publishing into dedicated publishers (power/charge_voltage, power/charger_present) and consolidated timer. Adds emergency/command subscriber dispatching to emergency::handleCommand and emergency/status publisher driven by timer.
Interactive Hardware-in-the-Loop Testing test/hil/emergency_interactive.py	Comprehensive test script implementing EmergencyProbe ROS 2 node that validates firmware emergency behavior across seven scenarios: initial state, command confirmation/window, software latch, STOP input, single/double lift inputs. Provides PASS/WARN/FAIL reporting with optional ANSI colors, state snapshots, and timeout-based polling.
Project Setup and Documentation .gitignore, README.md, utils/remote-openocd.sh	Adds Python/build artifact ignores, documents emergency mode feature with ROS API description and HIL testing instructions, and enhances OpenOCD build script to detect and enable linuxgpiod adapter support.

Sequence Diagram

sequenceDiagram
  participant Firmware as Firmware Core
  participant Emergency as emergency module
  participant GPIO as Physical Inputs
  participant ROS as ROS 2 I/O
  participant LED as LED Status
  
  Firmware->>Emergency: init() at setup
  loop Every firmware loop iteration
    Firmware->>Emergency: update()
    Emergency->>GPIO: read() stop/lift/tilt inputs
    Emergency->>Emergency: debounce & check timers
    Emergency->>Emergency: manage latch state
  end
  
  ROS->>Emergency: getState()
  Emergency-->>ROS: return EmergencyStatus
  ROS->>ROS: publish to emergency/status topic
  
  ROS->>Emergency: handleCommand(latch_requested)
  Emergency->>Emergency: apply command with confirmation window
  
  Firmware->>LED: set LED_STATUS_EMERGENCY flag
  LED->>LED: override to red blinking if active

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• jkaflik/omros2-firmware#7: Modifies src/led_status.hpp LED status flag logic similarly by adding a new status condition (LED_STATUS_IMU_FAILED) and updating the status color mapping.

Poem

🚨 A rabbit's safety net so bright,
Stops and lifts now glow in red light,
Debounce, latch, and ROS flow—
When danger comes, the firmware will know! 🐰

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch emergency-features

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}