A comprehensive Home Assistant integration for tracking aircraft using ADSB data from dump1090/tar1090 feeders, with built-in dashboard cards, voice queries and military aircraft alerts.
1.11.0 — Quiet hours, snooze, alert events and a wider watchlist.
- Quiet hours. Pick a start and end time and which alerts stay silent in between, in CONFIGURE → Quiet Hours & Snooze. Emergency squawks and your watched aircraft still come through unless you say otherwise.
- Snooze. Every alert notification has a Snooze 1 h button that silences that kind of alert only; the time is adjustable. See Quiet hours and snooze.
- Alert events. Every alert fires an
adsb_aircraft_tracker_alertevent with the aircraft's details, so an automation can flash a light or announce it on a speaker. See Alert events. - Watch types and operators. Put ICAO type codes (
B52, C17, B74*) or operator names (NASA, Air Force) on your watchlist, for aircraft you want to know about without knowing the tail number. See Watched aircraft.
1.10.0 — Watched aircraft. Get an alert whenever an aircraft on your own list of tail numbers, ICAO hex codes or callsigns comes into range; set it in CONFIGURE → Notifications → Watched Aircraft, see Watched aircraft. Thanks to @Dtrieb for the suggestion.
1.9.0 — Choose your units. Aeronautical, imperial or metric, in CONFIGURE → Units; see Units. Thanks to @medivb for the request.
1.8.3 — Plainer cards. The dashboard cards no longer color aircraft by altitude: the colored strip on small photos is gone and airplane icons use your theme's primary color. Rows without a photo now line up with the rest.
1.8.2 — Overhead alerts, and your own alert wording. A new alert for
aircraft almost straight above you at any altitude, with an adjustable angle
(default 15° from straight up); off by default, see Overhead.
And every alert's title and message can now be reworded in CONFIGURE →
Alert Wording, with tokens like {name} and {altitude}; see
Your own wording.
1.8.1 — Older dump1090 feeders. Altitude, speed and vertical rate now
show for feeders that use the legacy aircraft.json field names (altitude,
speed, vert_rate), including the dump1090 bundled in the Flightradar24
feeder image. They showed 0 before.
1.8.0 — Alerts to several devices, and alerts that open the aircraft.
"Devices for alerts" is now a multi-select that also lists notify groups, and
the external URL takes {hex}, {flight} or {registration} so tapping an
alert opens that aircraft on tar1090, adsb-3d or a public tracker.
1.7.0 — Aircraft photos. The cards now show a picture of the airframe from planespotters.net: a photo banner on the closest-aircraft card, a thumbnail per row on the nearest-aircraft and military cards, and the picture in military, low-overhead and emergency notifications. It's on by default with nothing to configure; each card has a Photo style in its editor. See Photos on the cards.
Every release lists its changes in CHANGELOG.md, newest first. The same notes appear on the GitHub release and in HACS when it offers you the update, so you can see what changed before you install it.
📊 Dashboard Cards (built in, nothing to install)
- Four ready-made cards in the dashboard Add card picker (live preview, one click): nearest aircraft, closest aircraft detail, military alert, receiver stats
- Routes, climb/descent and heading at a glance
- A photo of the airframe from planespotters.net on the closest-aircraft card, thumbnails in the list, and the picture in notifications (nearest and military aircraft, cached a day, credited)
- Find your tracker's entities automatically, with a visual editor, and work with multiple feeders
🛩️ Aircraft Tracking
- Real-time aircraft monitoring within configurable distance
- Detailed aircraft information (tail number, flight, altitude, speed, type)
- Top 5 closest aircraft with comprehensive details
- Aircraft type database with 85,000+ aircraft models
- Distance and bearing measured from your Home Assistant home location
- Your choice of units: aeronautical (nm, ft, kts), imperial (mi, ft, mph) or metric (km, m, km/h)
- Registration and aircraft type filled in from the tar1090-db database when the feeder doesn't send them (PiAware/dump1090-fa, bridges)
- Flight route (origin/destination) for every aircraft with a callsign, as sensor attributes
- Works with any readsb-style
aircraft.jsonsource (tar1090, readsb, dump1090-fa/SkyAware, or bridges from other receivers); the data path is auto-detected
📱 Smart Notifications
- Mobile app notifications for specific aircraft types, to one phone, several, or a notify group
- Low altitude aircraft alerts
- Overhead alerts when an aircraft is almost straight above you, at any altitude (off by default)
- Your own wording for every alert title and message
- Emergency squawk code notifications (7700/7600/7500)
- Watched aircraft: alerts for your own list of tail numbers, hex codes or callsigns, aircraft types and operators
- Quiet hours, and a Snooze button on every alert
- An event for every alert, to trigger your own automations
- Customizable external ADSB URL links
🗣️ Voice / Assist Support
- 7 voice intents with 77 sentence variations
- TTS-friendly output: colloquial model names, airline code expansion, no mispronounced hyphens
- Flight route lookup (origin/destination) via adsb.im
- Filter by type: helicopters, jets, turboprops, military
- Works with Home Assistant Assist and voice pipelines
- Exposed as LLM tools for AI conversation agents (Home Assistant 2026.8+)
🔧 Advanced Features
- Runtime configuration changes (no restart required)
- Custom services for testing and manual control
- Developer tools for debugging detection logic
- Comprehensive error handling and logging
- Home Assistant 2023.7 or newer (service response support)
- ADSB Feeder (dump1090/tar1090) running on your network
- Mobile App (optional, for notifications)
- Open HACS in Home Assistant
- Click on "Integrations"
- Click the three dots in the top right corner
- Select "Custom repositories"
- Add this repository URL:
https://github.com/hook-365/adsb-aircraft-tracker - Select "Integration" as the category
- Click "Add"
- Find "ADSB Aircraft Tracker" in the integration list and install
- Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration
- Search for "ADSB Aircraft Tracker" and follow the setup
- Download the latest release from GitHub
- Extract the files to your
custom_components/adsb_aircraft_tracker/directory - Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration
- Search for "ADSB Aircraft Tracker"
- ADSB Host: IP address of your dump1090/tar1090 feeder (e.g.,
192.168.1.100) - ADSB Port: Port number (default:
8085) - Data Path (optional): Leave blank to auto-detect. Setup tries
/data/aircraft.json(tar1090/readsb),/tar1090/data/aircraft.json,/skyaware/data/aircraft.json,/dump1090-fa/data/aircraft.json,/dump1090/data/aircraft.json,/aircraft.json, then/, and keeps the first one that returns aircraft JSON. Set it explicitly for adapters that serve data somewhere else. - Update Interval: How often to fetch data (default:
10seconds) - Distance Limit: Aircraft range in miles, or kilometers if Home Assistant is set to metric (
0= unlimited)
Any source that returns readsb-style JSON (a top-level "aircraft" list with hex, lat/lon, alt_baro, gs, track, flight) works, including bridges from other services. Older dump1090 builds that use the legacy field names altitude, speed and vert_rate (such as the dump1090 bundled in the Flightradar24 feeder image) are read too. The content type doesn't matter; text/plain is accepted.
Go to CONFIGURE → Units to choose how distance, altitude and speed are shown:
| Setting | Distance | Altitude | Speed |
|---|---|---|---|
| Automatic (default) | miles or kilometers, following Home Assistant | feet | knots |
| Aeronautical | nautical miles | feet | knots |
| Imperial | miles | feet | miles per hour |
| Metric | kilometers | meters | kilometers per hour |
The choice applies to the dashboard cards, notifications, voice answers, and the range and alert thresholds in the options (they are shown and entered in your units).
The sensor attributes distance_mi, altitude_ft and speed_kts always stay in miles, feet and knots, so automations that compare them keep working whatever you pick. For text in your units, use distance_display, altitude_display and speed_display.
A local Flightradar24 receiver doesn't serve aircraft.json itself. Brian O'Hern's FR24 dump1090 Bridge is a Home Assistant app that polls the receiver's local /flights.js feed and republishes it at /data/aircraft.json. Position, altitude, speed, heading, callsign and Mode-S hex are translated conservatively, and aircraft without a position stay in the feed (they count toward totals but not closest/nearest).
- Settings → Apps → Install app, open the repository menu and add
https://github.com/brian-r-ohern/fr24-dump1090-bridge - Install FR24 dump1090 Bridge, enter your receiver's host, port, username and password, and start it
- Set up this integration with ADSB Host = the hostname on the bridge's Info page, Port =
8085, and leave Data Path blank
After initial setup, click CONFIGURE on your integration to access advanced options:
- Devices for alerts: one or more notify services. Phones with the Home Assistant mobile app and any notify groups you have defined are listed; every alert goes to all of them
- External URL: website an alert opens when tapped. Defaults to your feeder. Put
{hex},{flight}or{registration}in it to open that aircraft, e.g.https://my-tar1090/?icao={hex} - Overhead alerts (default off), Overhead angle (default 15°) and Overhead maximum altitude (default no limit):: see Overhead
- Watched Aircraft (default empty): your own list of tail numbers, ICAO hex codes or callsigns to be alerted about; see Watched aircraft
- Update Interval: Adjust data refresh frequency
- Distance Limit: Set maximum tracking range
- Aircraft photos (default on): look up a photo of each nearby or military airframe on planespotters.net for the cards and notifications. One request per newly seen airframe, nearest five plus military only, cached 24 hours either way; photographer credit and a link to the photo page are shown, as their API terms ask. The route lookup contact below is sent in the User-Agent here too.
- Route lookup contact (optional): email or URL sent to adsb.im in the User-Agent of flight-route lookups (
adsb-aircraft-tracker/<version> (+repo; contact)). adsb.im is a one-person hobby service and asks callers to identify themselves; empty sends only the project URL.
The integration ships four dashboard cards. There's nothing to install: they load automatically with the integration. Edit a dashboard → Add card → By card tab → search ADSB. The picker previews each card with your live traffic, photos included; pick one and it's done.
| Card | Shows |
|---|---|
ADSB Aircraft Tracker (custom:adsb-aircraft-tracker-card) |
The nearest 1–5 aircraft: callsign, tail, route, distance, altitude, speed, with a military flag |
ADSB Closest Aircraft (custom:adsb-closest-aircraft-card) |
The closest aircraft in detail: photo, type, operator, route with city names, distance, altitude with climb/descent, speed, heading, emergency squawks |
ADSB Military Alert (custom:adsb-military-card) |
A green "all clear", or a red alert listing each military aircraft detected |
ADSB Stats (custom:adsb-stats-card) |
Tracked aircraft, closest distance, military count and military-database health |
Every card finds your tracker's entities by itself, so they work whatever your entity IDs are. If you have more than one feeder, pick which tracker in the card editor. Tap any card or row for details.
type: custom:adsb-aircraft-tracker-card # or any of the card types above
title: Aircraft # optional
count: 5 # optional, nearest-aircraft card only (1-5)
photos: thumbnail # optional, see below
device_id: ... # optional; the editor fills this in when you pick a trackerWith Aircraft photos on (the default, see Configuration), each card can
show the airframe's photo from planespotters.net.
Pick the style in the card editor or with photos::
| Card | photos values |
Default |
|---|---|---|
| ADSB Closest Aircraft | banner (large photo above the details, with credit), thumbnail (small photo next to the callsign), none |
banner |
| ADSB Aircraft Tracker | thumbnail (small photo per row), none |
thumbnail |
| ADSB Military Alert | thumbnail (small photo per row), none |
thumbnail |
Aircraft without a photo (most GA traffic) fall back to the airplane icon, so mixed lists stay aligned. Every photo credits the photographer and links to its planespotters.net page.
To add one from the UI: edit a dashboard → Add card → By card → search ADSB → pick a card. The preview already shows the photo, and the Photo dropdown in the editor switches the style. In YAML, this is the whole "photo dashboard" from the picture above (a closest-aircraft banner with the nearest five under it):
type: vertical-stack
cards:
- type: custom:adsb-closest-aircraft-card
photos: banner
- type: custom:adsb-aircraft-tracker-card
count: 5
photos: thumbnailPhotos are also available to your own cards and automations as sensor
attributes (photo_thumbnail, photo_large, photo_link,
photo_photographer). A plain Markdown card, no extras needed:
type: markdown
content: >-
{% set a = states.sensor.adsb_closest_aircraft.attributes %}
{% if a.photo_large %}

[Photo © {{ a.photo_photographer }} · planespotters.net]({{ a.photo_link }})
{% else %}No photo for {{ a.flight or a.registration or 'the closest aircraft' }}.{% endif %}Ask your Home Assistant voice assistant about aircraft overhead and get natural, TTS-friendly spoken responses.
- Go to Developer Tools → Services
- Call
adsb_aircraft_tracker.install_sentences - Restart Home Assistant
That's it — the custom sentences are installed and the intent handlers register automatically.
"What plane is that?" · "What's flying overhead?" · "What's up there?" · "What kind of plane is that?" · "Identify that aircraft"
Response: "That's United 1 2 3, a Boeing 738, flying from Chicago to Denver, about 4 miles away, climbing through 12,000 feet, heading southwest, cruising at 450 knots."
"What planes are nearby?" · "Any planes around?" · "What do you see flying?" · "What planes can you see?"
Response: "I'm tracking 47 aircraft. The nearest are: United 1 2 3, 4 miles away, at 32,000 feet, heading southwest; Delta 4 5 6, 8 miles away, descending through 15,000 feet; and SkyWest 7 8 9, 12 miles away, at 24,000 feet."
"Any military planes nearby?" · "Are there any military aircraft?" · "Military aircraft status"
Response: "I'm detecting 2 military aircraft. The closest is a Boeing K C 135 Stratotanker, 15 miles away, at 24,000 feet, heading northeast."
"How many planes?" · "How many aircraft are you tracking?" · "How many planes are out there?"
Response: "I'm currently tracking 47 aircraft. The closest is 4 miles away."
"Where is that plane going?" · "What's the flight route?" · "Where did that plane come from?"
Response: "The closest aircraft, United 1 2 3, is flying from Chicago to Denver, about 4 miles away, at 32,000 feet."
"Any helicopter aircraft nearby?" · "Do you see any jet planes?" · "Any prop planes flying?"
Sentences require an "aircraft"/"planes" anchor word after the type (e.g. "military planes", "jet aircraft") — bare wildcards like "any helicopters nearby" over-matched unrelated queries in hassil.
Supported types: helicopters, choppers, jets, airliners, turboprops, props, cessna, military
Response: "I can see 3 helicopters nearby. The closest is 2 miles away, at 1,500 feet."
"What is the fastest aircraft?" · "What plane is the highest?" · "Find the closest plane" · "Which aircraft is the slowest?"
Supported queries: fastest, quickest, speediest, slowest, highest, lowest, closest, nearest, farthest, furthest
Response: "The fastest aircraft is United 1 2 3, a Boeing 738, cruising at 520 knots, about 8 miles away, at 36,000 feet, heading southwest."
All voice responses are formatted for natural text-to-speech pronunciation:
| Raw Data | Spoken As | Why |
|---|---|---|
BOEING 737-800 |
Boeing 738 | Title case, colloquial name, no hyphen |
BOEING 777-300ER |
Boeing triple seven E R | Colloquial spoken name, letters spelled out |
EMBRAER ERJ-190 |
Embraer E190 | Colloquial designation |
UAL123 |
United 1 2 3 | Airline code expanded, digits spelled out |
DAL45 |
Delta 4 5 | Same pattern |
Piper PA-28 Cherokee |
Piper P A 28 Cherokee | Hyphen removed, letter groups spelled out (no "minus", no "pah") |
heading 225° |
heading southwest | 8-point cardinal compass |
climbing +1500 fpm |
climbing through 12,000 feet | Altitude phrased with vertical context |
speed 450 kts |
cruising at 450 knots | "cruising" for faster aircraft |
- 7 intent handlers are registered with Home Assistant's Assist pipeline (hassil)
- Voice queries that match a sentence go directly through intent recognition, without the LLM conversation agent
- With an LLM conversation agent (Home Assistant 2026.8+), the same intents are also offered to the model as Assist API tools, with descriptions written to help it pick the right one. Answers are identical to the sentence path. HA stopped exposing intents to LLMs automatically in 2026.8, so this needs version 1.5.0 or newer of this integration
- Flight route data (origin/destination) is fetched from adsb.im and cached for 4 hours
- Aircraft photos are fetched from planespotters.net (nearest five + military) and cached for 24 hours
- Aircraft type filtering uses ICAO engine type, category, and description keyword matching
- Military detection uses the tar1090-db verified database (same as notification system)
- Can also be triggered from Developer Tools → Conversation for testing
The integration creates the following entities:
- Value: Total aircraft count (e.g., "5 aircraft" or "12 aircraft (closest: 2.1 mi)")
- Attributes: Complete details for all tracked aircraft with distance, altitude, speed, type, etc. These are live only: they are excluded from the recorder (history), since a per-poll list of every aircraft would exceed Home Assistant's attribute size limit at ~30 aircraft. Templates, cards and voice tools read them normally.
- Use: Overview of all aircraft in range
- Value: Closest aircraft identifier (flight number, tail, or hex)
- Attributes: Complete details of the nearest aircraft (distance, altitude, speed, heading, type, operator, etc.), plus its route (
route_origin,route_origin_name,route_destination,route_destination_name) when adsb.im knows it, and its photo (photo_thumbnail,photo_large,photo_link,photo_photographer) when planespotters.net has one. Routes are looked up for every aircraft with a callsign: new callsigns are batched into one request per poll and cached for 4 hours. Private/GA flights usually have no route - Use: Track the aircraft closest to your location
- Value: Summary count (e.g., "5 aircraft detected")
- Attributes:
aircraft_1throughaircraft_5with full details for each, including route and photo fields - Use: Display the closest aircraft in cards/dashboards
- Note: installs that predate the top-5 expansion keep their original entity id (e.g.
sensor.adsb_nearest_3_aircraft) — Home Assistant never renames existing entities
- Value: Military detection summary (e.g., "Military aircraft detected: 2 aircraft")
- Attributes: Details of detected military aircraft with detection reasons
- Use: Monitor military aircraft activity
- Value: Number of military aircraft in database (e.g., "16543")
- Attributes: Database health, last update time, load status
- Use: Monitor military detection database
- Value:
onwhen military aircraft detected,offotherwise - Attributes: Count and details of military aircraft detected
- Use: Trigger automations for military aircraft alerts
# Refresh aircraft data immediately
service: adsb_aircraft_tracker.refresh_data
# Test military detection with current data
service: adsb_aircraft_tracker.test_military_detection
# Get details for specific aircraft
service: adsb_aircraft_tracker.get_aircraft_details
data:
hex_code: "abc123"
# Install voice assistant sentence triggers
service: adsb_aircraft_tracker.install_sentences
# Force a fresh military database download
service: adsb_aircraft_tracker.load_military_database
# Silence alert notifications for a while (see "Quiet hours and snooze")
service: adsb_aircraft_tracker.snooze_alerts
data:
duration: 120 # minutes; 0 turns the alerts back on
alerts: [close_aircraft, overhead] # leave out for all except emergency
# Update the aircraft types database from tar1090-db
service: adsb_aircraft_tracker.update_aircraft_types_databaseThe integration automatically sends mobile notifications for:
- Trigger: Military aircraft detected on radar
- Message: Aircraft details, distance, detection reasons
- Action: Tap to open ADSB tracker
- Trigger: Aircraft within 2 miles and below 3,000 ft (both thresholds configurable in options, in your chosen units)
- Message: Aircraft type, altitude, distance
- Action: Tap to open ADSB tracker
- Trigger: an aircraft is inside a cone around straight up, at any altitude. Off by default; turn it on in CONFIGURE → Notifications
- Message: aircraft, altitude, how many degrees from straight up, type, speed and direction of travel
- Action: Tap to open ADSB tracker
The Overhead angle is how far from straight up still counts, in degrees. The default is 15°, about 3% of the sky. For scale, a fist held at arm's length covers about 10°.
| Angle | Share of the sky | Circle at 3,000 ft | at 10,000 ft | at 35,000 ft |
|---|---|---|---|---|
| 5° | 0.4% | 0.1 mi across | 0.3 mi | 1.2 mi |
| 15° (default) | 3% | 0.3 mi | 1.0 mi | 3.6 mi |
| 30° | 13% | 0.7 mi | 2.2 mi | 7.7 mi |
| 45° | 29% | 1.1 mi | 3.8 mi | 13.3 mi |
Details:
- Height is measured above your home, using the elevation set in Home Assistant (Settings → System → General). Geometric altitude is used when the feeder sends it, barometric otherwise.
- A narrow cone is crossed in less than one update at low altitude, so the aircraft's straight-line path until the next update is checked as well. The alert usually arrives just before the pass.
- Each aircraft alerts once per pass: not again until it has been out of the cone for 5 minutes, so a circling aircraft or hovering helicopter alerts once.
- An aircraft that matches both this and the Low Aircraft alert is announced once, by whichever fires first.
- Overhead maximum altitude ignores aircraft above that altitude, if you only want ones low enough to see or hear. 0 = no limit.
- Trigger: Aircraft broadcasting 7700, 7600, or 7500 codes
- Message: Emergency type and aircraft details
- Action: Tap to open ADSB tracker
- Trigger: an aircraft on your own list comes into range. Empty by default; fill it in under CONFIGURE → Notifications → Watched Aircraft
- Message: aircraft, altitude, distance, type, speed, tail number and operator
- Action: Tap to open ADSB tracker
The list takes tail numbers (registrations), ICAO hex codes and callsigns, separated by commas:
N628TS, 3C6444, RCH285
Details:
- Upper or lower case and dashes don't matter:
d-aima,D-AIMAandDAIMAare the same. - A tail number or hex code follows one airframe. A callsign follows a flight number, whichever airframe flies it. Entries must match in full;
N628does not matchN628TS. - Tail numbers need a feeder that sends registrations (readsb, tar1090) or the downloaded aircraft database, which the integration uses automatically. The hex code always works.
- Each aircraft alerts once per visit: not again until it has been out of range for 15 minutes.
- Only aircraft inside your Distance Limit count, like every other alert.
- A watched aircraft that is also military, low or overhead gets those alerts too.
Two more fields catch aircraft you can't list one by one:
- Watched Aircraft Types takes ICAO type codes, e.g.
B52, C17, A388. Every aircraft of that type alerts, whichever tail number it has. End a code with a star for everything that starts that way:B74*is every 747. The type code is what your feeder's map shows as the aircraft type. - Watched Operators takes owner or operator names, e.g.
NASA, Air Force. An entry matches when it is part of the operator name, in any case:air forcematchesUnited States Air Force. This needs a feeder that sends operators (readsb or tar1090 with the extended aircraft database); without one the field does nothing.
A common type or a big airline alerts for every one of them, once per visit each. Start narrow.
Go to CONFIGURE → Quiet Hours & Snooze.
Quiet hours silence the alerts you tick between two times of day, e.g. 22:00 to 07:00 (the end may be the next morning). By default military, low aircraft and overhead alerts go quiet, and emergency squawks and your watched aircraft still come through. Quiet hours are off until you turn them on.
Snooze: every alert notification has a 🔕 Snooze 1 h button. It silences that kind of alert only, so snoozing the low-aircraft alerts during a busy afternoon does not hide a military one. Every configured device gets a short note saying what is off and until when. Change the time under Snooze time; 0 removes the button. Emergency squawk alerts have no snooze button.
Details:
- A silenced alert is not sent later. It still fires its alert event, with
notified: false. - A snooze is kept across an options change but not across a Home Assistant restart.
- The
adsb_aircraft_tracker.snooze_alertsservice snoozes from an automation or a dashboard button:durationin minutes (0 = back on),alertsto pick the kinds (default: all except emergency),confirm: trueto send the note to the devices.
Every alert also fires an adsb_aircraft_tracker_alert event, so automations can react to an alert directly. It fires whether or not a notify device is configured, and also while the alert is silenced by quiet hours or a snooze.
| Field | Content |
|---|---|
kind |
military, close_aircraft, overhead, emergency or watchlist |
title, message |
the notification text, with your own wording if you set one |
notified |
true when a notification was sent |
muted_by |
quiet_hours or snooze when it was silenced, otherwise empty |
matched |
watchlist alerts only: hex, tail, flight, type or operator |
hex, tail, flight, aircraft_type, description, operator |
the aircraft |
altitude_ft, speed_kts, vertical_rate_fpm, squawk |
flight data, always in feet and knots |
distance_mi, direction, heading, latitude, longitude |
position: miles and bearing from home, and where it is going |
route_origin, route_destination |
airport codes, when the route is known |
url, photo |
the tap-through link and the photo, when there is one |
entry_id |
which feeder, if you have more than one |
Values that are not known are empty.
Every alert has a built-in title and message. To change them, go to CONFIGURE → Alert Wording and edit the title and/or message of the alerts you want to reword.
Put these in curly braces and they are filled in for each aircraft:
| Token | Becomes |
|---|---|
{name} |
callsign, or the tail number when there is no callsign |
{flight} |
callsign |
{tail} |
tail number / registration |
{hex} |
ICAO hex code |
{type} |
aircraft type, e.g. Boeing 737-800 |
{operator} |
owner or operator |
{altitude} |
altitude as a number in your chosen units, e.g. 3,000 |
{altitude_unit} |
unit of the altitude: ft or m |
{speed} |
ground speed as a number in your chosen units |
{speed_unit} |
unit of the speed: kts, mph or km/h |
{distance} |
distance from home with its unit, e.g. 1.4 mi |
{direction} |
where it is from home, e.g. northwest |
{heading} |
where it is going, e.g. south |
{trend} |
|
{emoji} |
icon for the alert or aircraft (🚁 🛫 🛬 🛩️ |
{angle} |
degrees from straight up (overhead alert) |
{where} |
e.g. "13° from straight up" (overhead alert) |
{squawk} |
squawk code (emergency alert) |
{emergency} |
GENERAL EMERGENCY, RADIO FAILURE or HIJACK (emergency alert) |
{reasons} |
why it was flagged (military alert) |
For example, a close aircraft message of
{emoji} {name} is {distance} to the {direction} at {altitude} ft
{type}, heading {heading}
Operator: {operator}
sends "🛬 UAL12 is 1.4 mi to the northwest at 2,500 ft / Boeing 737-800, heading south / Operator: United Airlines". A line whose values are all unknown is left out, so the operator line disappears when the operator isn't known. The fields start out filled with the built-in wording, so you can edit it in place. To go back to the built-in wording, clear the field, or tick the alert under Restore built-in wording at the bottom of the page and press Submit.
automation:
- alias: "Military Aircraft Detection"
trigger:
- platform: state
entity_id: binary_sensor.adsb_military_aircraft_present
from: 'off'
to: 'on'
action:
- service: notify.persistent_notification
data:
title: "Military Aircraft Detected"
message: "{{ state_attr('sensor.adsb_military_aircraft_details', 'summary') }}"Uses the alert event, so it follows your alert settings and wording:
automation:
- alias: "Announce military aircraft"
trigger:
- platform: event
event_type: adsb_aircraft_tracker_alert
event_data:
kind: military
action:
- service: tts.speak
target:
entity_id: tts.home_assistant_cloud
data:
media_player_entity_id: media_player.living_room
message: >
Military aircraft: {{ trigger.event.data.description }},
{{ trigger.event.data.distance_mi }} miles away.automation:
- alias: "No aircraft alerts during nap time"
trigger:
- platform: state
entity_id: input_boolean.nap_time
action:
- service: adsb_aircraft_tracker.snooze_alerts
data:
duration: "{{ 180 if trigger.to_state.state == 'on' else 0 }}"automation:
- alias: "Aircraft Overhead Announcement"
trigger:
- platform: numeric_state
entity_id: sensor.adsb_closest_aircraft
attribute: distance_mi
below: 2
condition:
- condition: numeric_state
entity_id: sensor.adsb_closest_aircraft
attribute: altitude_ft
below: 3000
action:
- service: tts.speak
data:
message: "Aircraft {{ state_attr('sensor.adsb_closest_aircraft', 'tail') }} overhead at {{ state_attr('sensor.adsb_closest_aircraft', 'altitude_ft') }} feet"Prefer to build your own instead of using the built-in cards? The YAML examples below use the default entity IDs. New installs (1.6.1+) get exactly these IDs. Installs set up earlier on Home Assistant 2026.x may have longer IDs with the device name in them (e.g. sensor.adsb_tracker_192_168_1_100_adsb_all_aircraft), a second feeder gets a _2 suffix, and very old installs may have sensor.adsb_nearest_3_aircraft. Check Settings → Entities and swap in your own; Home Assistant never renames existing entities. You can also rename them there to match the examples. Each YAML block is one card.
Perfect for a comprehensive aircraft tracking dashboard using Mushroom cards:
type: custom:stack-in-card
mode: vertical
cards:
- type: custom:mushroom-template-card
primary: Aircraft Tracker
secondary: |
{% set count = states('sensor.adsb_all_aircraft') %}
{{ count }}
icon: mdi:airplane
icon_color: orange
tap_action:
action: url
url_path: http://192.168.1.100:8080
- type: markdown
content: |
{% set a1 = state_attr('sensor.adsb_nearest_5_aircraft', 'aircraft_1') %}
{% set a2 = state_attr('sensor.adsb_nearest_5_aircraft', 'aircraft_2') %}
{% set a3 = state_attr('sensor.adsb_nearest_5_aircraft', 'aircraft_3') %}
## Aircraft Details
{% if a1 %}
**1. {{ a1.tail }}** {% if a1.flight and a1.flight != a1.tail %}({{ a1.flight }}){% endif %}
- {{ a1.description }}
{%- if a1.route_origin %}
- Route: {{ a1.route_origin_name }} ({{ a1.route_origin }}) → {{ a1.route_destination_name }} ({{ a1.route_destination }})
{%- endif %}
- Distance: {{ a1.distance_display }}
- Altitude: {{ a1.altitude_ft }}ft
- Speed: {{ a1.speed_kts }}kts
{%- if a1.operator %}
- Operator: {{ a1.operator }}
{%- endif %}
{% endif %}
{% if a2 %}
**2. {{ a2.tail }}** {% if a2.flight and a2.flight != a2.tail %}({{ a2.flight }}){% endif %}
- {{ a2.description }}
{%- if a2.route_origin %}
- Route: {{ a2.route_origin_name }} ({{ a2.route_origin }}) → {{ a2.route_destination_name }} ({{ a2.route_destination }})
{%- endif %}
- Distance: {{ a2.distance_display }}
- Altitude: {{ a2.altitude_ft }}ft
- Speed: {{ a2.speed_kts }}kts
{%- if a2.operator %}
- Operator: {{ a2.operator }}
{%- endif %}
{% endif %}
{% if a3 %}
**3. {{ a3.tail }}** {% if a3.flight and a3.flight != a3.tail %}({{ a3.flight }}){% endif %}
- {{ a3.description }}
{%- if a3.route_origin %}
- Route: {{ a3.route_origin_name }} ({{ a3.route_origin }}) → {{ a3.route_destination_name }} ({{ a3.route_destination }})
{%- endif %}
- Distance: {{ a3.distance_display }}
- Altitude: {{ a3.altitude_ft }}ft
- Speed: {{ a3.speed_kts }}kts
{%- if a3.operator %}
- Operator: {{ a3.operator }}
{%- endif %}
{% endif %}
- type: custom:mushroom-chips-card
chips:
- type: template
content: >-
Closest: {{ state_attr('sensor.adsb_closest_aircraft', 'distance_display') }}
icon: mdi:map-marker-distance
- type: template
content: "{{ state_attr('sensor.adsb_closest_aircraft', 'altitude_ft') }}ft"
icon: mdi:altimeter
- type: template
content: View Map
icon: mdi:radar
tap_action:
action: url
url_path: http://192.168.1.100:8080For monitoring military aircraft activity:
type: custom:mushroom-template-card
primary: Military Aircraft
secondary: |
{% if is_state('binary_sensor.adsb_military_aircraft_present', 'on') %}
{{ state_attr('sensor.adsb_military_aircraft_details', 'summary') }}
{% else %}
No military aircraft detected
{% endif %}
icon: mdi:shield-airplane
icon_color: >-
{{ 'red' if is_state('binary_sensor.adsb_military_aircraft_present', 'on') else 'green' }}
badge_icon: >-
{{ 'mdi:alert' if is_state('binary_sensor.adsb_military_aircraft_present', 'on') else '' }}
badge_color: red
tap_action:
action: more-info
entity: sensor.adsb_military_aircraft_detailsMinimal aircraft count display:
type: custom:mushroom-template-card
entity: sensor.adsb_all_aircraft
primary: Aircraft Nearby
secondary: >-
{{ states('sensor.adsb_all_aircraft') }} ·
{{ state_attr('sensor.adsb_closest_aircraft', 'distance_display') }} closest
icon: mdi:airplane
icon_color: blue
tap_action:
action: url
url_path: http://192.168.1.100:8080Monitor the military aircraft database health:
type: custom:mushroom-template-card
entity: sensor.adsb_military_database_status
primary: Military Database
secondary: >-
{{ states('sensor.adsb_military_database_status') }} aircraft ·
{{ state_attr('sensor.adsb_military_database_status', 'last_updated_friendly') }}
icon: mdi:database-check
icon_color: >-
{{ 'green' if state_attr('sensor.adsb_military_database_status', 'database_loaded') else 'red' }}
tap_action:
action: more-infoYAML using only Home Assistant's standard cards, no Mushroom or other custom cards needed:
type: vertical-stack
cards:
- type: glance
title: Aircraft Tracker
entities:
- entity: sensor.adsb_all_aircraft
name: Total Aircraft
icon: mdi:airplane
- entity: sensor.adsb_closest_aircraft
name: Closest Aircraft
icon: mdi:airplane-marker
- entity: binary_sensor.adsb_military_aircraft_present
name: Military Present
icon: mdi:shield-airplane
- type: entities
title: Closest Aircraft Details
entities:
- entity: sensor.adsb_closest_aircraft
name: Aircraft
- type: attribute
entity: sensor.adsb_closest_aircraft
attribute: description
name: Type
icon: mdi:airplane-search
- type: attribute
entity: sensor.adsb_closest_aircraft
attribute: distance_display
name: Distance
icon: mdi:map-marker-distance
- type: attribute
entity: sensor.adsb_closest_aircraft
attribute: altitude_ft
name: Altitude
icon: mdi:altimeter
suffix: ft
- type: attribute
entity: sensor.adsb_closest_aircraft
attribute: speed_kts
name: Speed
icon: mdi:speedometer
suffix: kts
- type: markdown
content: |
{% set a1 = state_attr('sensor.adsb_nearest_5_aircraft', 'aircraft_1') %}
{% set a2 = state_attr('sensor.adsb_nearest_5_aircraft', 'aircraft_2') %}
{% set a3 = state_attr('sensor.adsb_nearest_5_aircraft', 'aircraft_3') %}
### Top 3 Aircraft
{% if a1 %}
**1. {{ a1.tail }}** {% if a1.flight and a1.flight != a1.tail %}({{ a1.flight }}){% endif %}
📍 {{ a1.distance_display }} • ⬆️ {{ a1.altitude_ft }}ft • 🚀 {{ a1.speed_kts }}kts
{{ a1.description }}
{%- if a1.route_origin %}
✈️ {{ a1.route_origin }} → {{ a1.route_destination }}
{%- endif %}
{% endif %}
{% if a2 %}
**2. {{ a2.tail }}** {% if a2.flight and a2.flight != a2.tail %}({{ a2.flight }}){% endif %}
📍 {{ a2.distance_display }} • ⬆️ {{ a2.altitude_ft }}ft • 🚀 {{ a2.speed_kts }}kts
{{ a2.description }}
{%- if a2.route_origin %}
✈️ {{ a2.route_origin }} → {{ a2.route_destination }}
{%- endif %}
{% endif %}
{% if a3 %}
**3. {{ a3.tail }}** {% if a3.flight and a3.flight != a3.tail %}({{ a3.flight }}){% endif %}
📍 {{ a3.distance_display }} • ⬆️ {{ a3.altitude_ft }}ft • 🚀 {{ a3.speed_kts }}kts
{{ a3.description }}
{%- if a3.route_origin %}
✈️ {{ a3.route_origin }} → {{ a3.route_destination }}
{%- endif %}
{% endif %}
{% if not a1 %}
*No aircraft currently detected*
{% endif %}Individual cards for each sensor. Each block is a separate card.
Basic aircraft count:
type: entity
entity: sensor.adsb_all_aircraft
name: Aircraft Nearby
icon: mdi:airplaneMilitary aircraft alert:
type: entity
entity: binary_sensor.adsb_military_aircraft_present
name: Military Aircraft
icon: mdi:shield-airplane
state_color: trueClosest aircraft with distance and altitude:
type: tile
entity: sensor.adsb_closest_aircraft
name: Closest Aircraft
icon: mdi:airplane-marker
state_content:
- state
- distance_display
- altitude_ftBuilt-in conditional card for military alerts:
type: conditional
conditions:
- entity: binary_sensor.adsb_military_aircraft_present
state: "on"
card:
type: markdown
content: |
## 🚨 MILITARY AIRCRAFT DETECTED
{{ state_attr('sensor.adsb_military_aircraft_details', 'summary') }}
{% set military = state_attr('sensor.adsb_military_aircraft_details', 'military_1') %}
{% if military %}
**Aircraft:** {{ military.tail }}
**Distance:** {{ military.distance_display }}
**Altitude:** {{ military.altitude_ft }}ft
**Type:** {{ military.description }}
{% endif %}Visual gauges for aircraft metrics:
type: horizontal-stack
cards:
- type: gauge
entity: sensor.adsb_all_aircraft
attribute: total_aircraft
name: Aircraft Count
min: 0
max: 50
severity:
green: 0
yellow: 10
red: 25
- type: gauge
entity: sensor.adsb_closest_aircraft
attribute: distance_mi
name: Closest Distance
min: 0
max: 20
unit: mi
severity:
red: 0
yellow: 5
green: 10
- type: gauge
entity: sensor.adsb_closest_aircraft
attribute: altitude_ft
name: Closest Altitude
min: 0
max: 10000
unit: ft- Verify your ADSB feeder is accessible at the configured IP/port
- Test the URL manually:
http://YOUR_IP:8085/data/aircraft.json(or wherever your source serves its JSON; see Data Path above) - "None of the data paths returned aircraft data" means the host answered but not at any standard path. Enter your source's path in the Data Path field
- Check Home Assistant logs for connection errors
- Verify mobile app device is selected in options
- Check notification permissions on your mobile device
- Test notifications with other Home Assistant integrations
- Check
sensor.adsb_military_database_statusfor database health - Use the
load_military_databaseservice to force a fresh database download - The database also refreshes automatically every 24 hours
This integration uses the following open-source databases and APIs:
- tar1090-db by Mictronics - Military aircraft database with 16,896+ verified military aircraft ICAO hex codes
- ICAO Aircraft Types Database - Comprehensive aircraft type information for 85,000+ aircraft models
- adsb.im - Flight route API for origin/destination airport lookups
Voice/Assist support was inspired by @nwithan8's tutorial and concept.
Special thanks to the ADSB community for maintaining these valuable resources.
Contributions are welcome! Please check the contribution guidelines.
This project is under the MIT License.