eiRadar

Rear vehicle radar extension for Hammerhead Karoo. Reads ANT+ radar data and delivers real-time visual and sound alerts — designed to keep your eyes on the road, not the screen.

<p align="center"> <a href="#features">Features</a> &bull; <a href="#installation">Installation</a> &bull; <a href="#quick-start">Quick Start</a> &bull; <a href="#data-fields">Data Fields</a> &bull; <a href="#alerts">Alerts</a> &bull; <a href="#settings">Settings</a> &bull; <a href="#night-mode">Night Mode</a> &bull; <a href="#fit-recording">FIT Recording</a> &bull; <a href="#ride-statistics">Statistics</a> &bull; <a href="#compatible-radars">Radars</a> &bull; <a href="#development">Development</a> </p>

---

Features

| Feature | Description | |---------|-------------| | 3 Data Fields | Compact, Standard, Full — graphical Glance widgets for any ride screen layout | | Multi-channel Alerts | Visual banner + escalating sound patterns via Karoo speaker | | 4 Sound Sets | Classic, Subtle, Urgent, Bike Bell — choose what fits your riding style | | Threat Levels | Approaching, Warning, Critical — color-coded with configurable distance thresholds | | Night Mode | Automatic threshold increase after sunset (GPS-based detection) | | Closing Speed Detection | Fast-closing vehicles auto-escalate; holding/receding vehicles suppressed | | Traffic Density Adaptation | Sustained heavy traffic silences minor alerts; dangerous vehicles still break through | | Speed Gate | Suppress minor alerts when stopped or slow — critical alerts always fire | | Alert Cooldown | Smart repeat delay prevents alert fatigue without missing new threats | | Escalation Bypass | Higher threat levels fire immediately, ignoring cooldown | | FIT Recording | Threat level, vehicle count, and nearest distance written to ride file at 1 Hz | | Ride Statistics | Per-ride stats: alert counts, closest approach, max vehicles, threat time | | Quick Mute | Toggle alerts via physical button or remote — data fields keep updating | | Screen Wake | Wake Karoo screen on critical threats or any threat | | Imperial / Metric | Automatic unit detection from Karoo profile | | Fully Offline | No accounts, no cloud, no internet, no phone pairing | | Open Source | MIT licensed, free forever |

---

Installation

Download APK

Get the latest release from GitHub Releases or eiradar.com.

# Install via ADB
adb install eiradar.apk

# Or via Hammerhead Companion app:
# 1. Download APK on your phone
# 2. Share to Hammerhead Companion
# 3. Install on Karoo

Build from Source

Prerequisites:

• Android Studio (JDK 17 bundled)
• GitHub PAT with read:packages scope (for Karoo SDK)

Setup:

# Add to ~/.gradle/gradle.properties
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_GITHUB_TOKEN

Build:

./gradlew assembleRelease

Output: app/build/outputs/apk/release/eiradar.apk

---

Quick Start

1. Pair Radar

Connect your ANT+ radar in Karoo Settings > Sensors.

2. Add Data Field

1. Open Profiles on Karoo
2. Edit a profile > Add data page
3. Select More Data > eiRadar
4. Choose a layout: Radar (S), Radar (M), or Radar (L)

3. Ride

Alerts fire automatically when vehicles approach from behind. The first launch shows a quick onboarding guide.

---

Data Fields

Three graphical data types built with Jetpack Glance. Each renders fresh RemoteViews every 1 Hz cycle.

| Data Field | Karoo Name | Content | |------------|:----------:|---------| | Compact | Radar (S) | Vehicle count, colored by threat level | | Standard | Radar (M) | Vehicle count + nearest distance + status label | | Full | Radar (L) | Threat label + vehicle count + distance + status message |

All widgets feature a colored status bar at the top (green / orange / red) and a rounded dark background. When alerts are muted, the status bar turns grey and the label shows "MUTED" — radar data continues to display normally.

Widget States

| State | S display | M / L display | |-------|:---------:|-------------| | Not connected | — grey | "No radar" | | Connecting | ... grey | "Connecting" | | Clear | OK green | "All clear" / "Road is clear" | | Threat | count, colored | count + distance in meters / feet | | Connection lost | ! grey | "Connection lost" |

Threat Colors

| Color | Level | Meaning | |:-----:|-------|---------| | Grey | Disconnected | Radar not paired, connecting, or connection lost | | Green | Clear | No vehicles detected | | Orange | Approaching / Warning | Vehicle detected, closing distance | | Red | Critical | Vehicle very close |

---

Alerts

Two independent alert channels. Each can be enabled or disabled separately with a master switch to control all at once.

Channels

| Channel | What it does | Default | |---------|-------------|:-------:| | Banner | Karoo in-ride visual alert overlay with auto-dismiss | On | | Sound | Beep patterns via Karoo speaker (4 sound sets) | On |

Sound Sets

| Set | Character | |-----|-----------| | Classic | Traditional beep patterns — single, double, triple | | Subtle | Quieter, gentler tones for less intrusive alerts | | Urgent | Loud, rapid patterns that demand attention | | Bike Bell | Musical tones using note frequencies |

Alert Escalation

Alerts follow the threat level hierarchy. When a threat escalates (e.g. Approaching → Warning → Critical), the new alert fires immediately — cooldown is bypassed. De-escalation respects the normal cooldown.

Auto-Dismiss Timing

| Level | Banner duration | |-------|:--------------:| | Critical | 5 s | | Warning | 4 s | | Approaching | 2 s | | Clear | 1.5 s |

All-Clear Chime

Optional confirmation sound when all vehicles have passed. Useful as an "all safe" signal before lane changes or turns.

Quick Mute

Assign Toggle Radar Alerts to a physical button or remote in Karoo Settings > Controls. One press mutes all alert channels (sound, banner). Press again to re-enable. Ideal for group rides where nearby cyclists trigger false alerts.

• Data fields continue showing live radar data with a "MUTED" indicator
• FIT recording and statistics continue normally
• Auto-unmutes when the ride ends — the next ride always starts with alerts enabled

Smart Suppression

eiRadar uses closing speed and traffic density to keep the system quiet in normal traffic and loud when actually dangerous. All fully automatic — no settings required.

Closing speed — Smoothed from the last 3 nearest-distance samples at 1 Hz:

• Vehicle closing at ≥36 km/h differential → alert escalated one level (Approaching→Warning, Warning→Critical)
• Vehicle holding distance or receding (≤7 km/h differential) → Approaching alert suppressed
• Large distance jumps (>30 m) reset tracking — different vehicle, fresh calculation

Traffic density — Rolling 30-second average of vehicle count:

• Average ≥2 vehicles sustained for 10+ seconds → Approaching alerts suppressed
• Fast-closing vehicles are escalated to Warning/Critical first, so they bypass density suppression
• Zero-vehicle periods naturally decay the average — alerts return when traffic clears

On a busy road: normal traffic is silent. A fast-closing vehicle gets escalated to Warning → bypasses density suppression AND triggers throttler escalation bypass → immediate alert.

Safety Design

• Critical alerts always fire regardless of speed gate, traffic density, or other suppression
• Repeat delay prevents alert fatigue without missing genuinely new threats
• Escalation bypass ensures worsening situations are immediately communicated
• Quick mute auto-resets on ride end — no risk of starting a ride with alerts off

---

Settings

All settings are accessible from the eiRadar app on Karoo. Tap any value to cycle through options.

Alert Channels

| Setting | Options | Default | |---------|---------|:-------:| | Enable alerts | On / Off | On | | Banner | On / Off | On | | Sound | On / Off | On | | Sound set | Classic / Subtle / Urgent / Bell | Classic | | All-clear sound | On / Off | On |

Detection Thresholds

| Setting | Options | Default | |---------|---------|:-------:| | Approaching | 100 / 125 / 150 / 175 / 200 m | 100 m | | Warning | 30 / 40 / 50 / 60 / 70 m | 50 m | | Critical | 10 / 15 / 20 / 25 / 30 m | 20 m |

The radar detects vehicles up to ~140 m. The default 100 m approaching threshold leaves a 40 m "silent awareness" zone where the widget updates but no alert fires — this reduces alert fatigue on busy roads.

Behavior

| Setting | Options | Default | |---------|---------|:-------:| | Repeat delay | 3 s / 5 s / 8 s / 12 s | 5 s | | Min speed | Off / 3 / 5 / 8 km/h | Off | | Wake screen | Never / Critical only / Always | Critical only |

Min speed (speed gate): Only suppresses Approaching alerts below the set speed. Warning and Critical alerts always fire — a stopped cyclist at a traffic light is the most vulnerable.

Reset to Defaults

Available in the settings screen. Clears all preferences and res