Author: Zero-MaxV1 License: MIT

For ADS-B enthusiasts using Raspberry Pis or Linux servers, a common point of failure is the USB interface. High-gain antennas often require Active USB Extension Cables or Powered USB Hubs.

During minor power fluctuations (brownouts) or high-load events, these USB controllers can enter a "Zombie State":

• The device remains "connected" to the OS (visible in lsusb).
• The piaware or readsb service remains running.
• BUT: No data is transmitted. The radio is effectively dead.

Standard system reboots are a sledgehammer solution that ruins your uptime stats and interrupts other services.

PiAware USB Watchdog is a lightweight, automated "kill switch" for specific USB buses.

Instead of rebooting the entire server, this tool:

1. Monitors your ADS-B software (piaware) for specific "No Data" error signatures.
2. Identifies the physical USB bus address of your failing hub or active cable.
3. Resets only that specific USB port electrically (toggling power off/on).
4. Restarts the dependent services (readsb, dump1090-fa, piaware).

This restores the radio in seconds without rebooting the machine, preserving your system uptime.

This script is designed to be "Passive" and "Minimally Invasive."

The watchdog runs every few minutes but takes no action if your station is healthy.

• It does not restart services on a schedule.
• It does not touch the USB bus if data is flowing.
• Your logs will remain clean unless a failure is actually detected.

• Linux System Uptime: PRESERVED. The script does not reboot the Raspberry Pi/Server. Your generic server uptime stats will continue to grow.
• Feeder Connection: RESETS. If a failure is detected, the piaware service must be restarted to recognize the USB device again. This will reset your "Connected For" timer on FlightAware/ADSBExchange, but it saves your Data Reliability ranking by minimizing downtime to seconds rather than hours.

• Operating Systems: Debian, Ubuntu, Raspbian (Raspberry Pi OS), DietPi.
• Receivers: RTL-SDR (v3/v4), FlightAware Pro Stick, Nooelec.
• Connection Types: Direct USB, Powered Hubs, Active USB Extension Cables (e.g., Terminus Technology, Genesys Logic).

The script automatically detects and manages:

• piaware (FlightAware)
• dump1090-fa
• readsb (Wiedehopf fork)

This script is a passive observer. It runs piaware-status and checks for specific failure keywords.

• If your station is healthy: The script exits immediately. No services are touched. Your uptime is preserved.
• If your station fails: Only then does it trigger a repair.

To prevent infinite reboot loops if your hardware physically dies:

1. The script tracks consecutive failures.
2. If it attempts to reset the USB 5 times in a row without success, it enters Safety Mode.
3. It stops resetting the device and enters a 90-minute Cool-Down period.
4. After 90 minutes, it will wake up and attempt a reset. This allows the station to "Self-Heal" if the issue was temporary (e.g., a storm or power instability).

1. Clone the repository:

   git clone https://github.com/Zero-MaxV1/PiAware-Active-USB-BrownOut-WatchDog-.git
   cd PiAware-Active-USB-BrownOut-WatchDog-

2. Run the Installer (as root):

   sudo bash install.sh

3. Follow the Interactive Setup: The script will list your USB devices. Find your Hub or Active Cable (e.g., 1a40:0101 Terminus Technology) and enter the ID when prompted.

If you prefer not to use the installer, you must install usbutils:

sudo apt-get install usbutils

This script acts as an automated repairman for your ADS-B station. Here is the exact logic it follows:

Every few minutes (depending on your setting), the script wakes up and asks PiAware: "Are you receiving data?"

• ✅ Yes: The script goes back to sleep immediately. It touches nothing.
• ❌ No: If it sees "No Data," it jumps into action.

If a failure is detected, the script does not reboot your Raspberry Pi. Instead:

1. It identifies your specific radio on the USB bus.
2. It cuts power to only that USB port for 1 second (forcing a hard reset).
3. It restarts the decoder software to reconnect to the radio.

To prevent damage if your hardware is physically broken:

• Loop Protection: If the fix fails 5 times in a row, the script stops trying to avoid an infinite loop.
• Smart Cooldown: It enters a 90-minute hibernation to let the hardware cool down.
• Auto-Resume: After 90 minutes, it wakes up and tries again. This allows your station to recover automatically from storms or power outages without you touching it.

Added

• Smart Cooldown: Watchdog now enters a 90-minute hibernation after 5 failed attempts, allowing for self-healing after storms or power outages.
• Documentation: Added "How It Works" section and clarified Uptime impacts.

Added

• Loop Protection: Prevents infinite reset loops by stopping after 5 consecutive failures.
• Safety Logic: Script now tracks failure counts to protect hardware.

Added

• Service Selection Menu: Installer now asks which decoder you use (dump1090-fa, readsb, etc.).
• Targeted Restarts: Watchdog restarts only the specific service selected.

Added

• Interactive Installation Menu (select USB device).
• Custom Intervals (1 min, 5 min, Daily).

• Initial Release.