Skip to content

A live bird collage card for your Home Assistant dashboard.

Ship 1.6.1: explain an empty MQTT fallback in the connection error (#80)

Adam Oberleycde1fb87e601
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d3a21e7..52bc1c4b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,15 @@
# Changelog
+## v1.6.1 — 2026-09-29
+
+### Fixed
+- **The connection error now says why the fallback found nothing**
+ ([#73](https://github.com/adamoberley/HABirdDashboard/issues/73)). With
+ `data_source: auto`, when BirdNET-Go can't be reached and Home Assistant
+ has no BirdNET-Go MQTT sensors (`*_scientific_name`) to fall back on, the
+ card says exactly that and points at the MQTT setup, instead of the
+ generic "Can't reach BirdNET-Go" message.
+
## v1.6.0 — 2026-09-29
### Changed
diff --git a/README.md b/README.md
index cfee6dbd..941fed16 100644
--- a/README.md
+++ b/README.md
@@ -685,7 +685,10 @@ ring layout, `?names` (or `?names=scientific` / `?names=both`) plus
- **"Can't reach BirdNET-Go from this browser."** The card gave up on
the API after 15 seconds and had no MQTT history to fall back on. Work
through the two items above; with MQTT enabled the card falls back to
- HA history instead of showing this.
+ HA history instead of showing this. If the message adds that Home
+ Assistant has **no BirdNET-Go MQTT sensors**, the fallback looked for
+ `*_scientific_name` sensors and found none - see
+ [Enabling MQTT](#enabling-mqtt-recommended).
- **The "not it?" flag fails.** The pill shows a short reason: `no path`
means the card couldn't reach HA ingress (writes need it - check
you're an admin user); `err 401/403/405` means BirdNET-Go refused -
diff --git a/addons/birdframe/config.yaml b/addons/birdframe/config.yaml
index c4156edb..1f0ba27a 100644
--- a/addons/birdframe/config.yaml
+++ b/addons/birdframe/config.yaml
@@ -6,7 +6,7 @@
# Frame TV's Art Mode - replacing the previous upload in place so the TV's art
# library never accumulates duplicates.
name: Bird Frame (Samsung Frame TV)
-version: "1.6.0"
+version: "1.6.1"
slug: birdframe
description: >-
Render the live Bird collage and push it to a Samsung Frame TV as Art Mode
diff --git a/addons/birdframe/www/apt.js b/addons/birdframe/www/apt.js
index 4843de0e..8db9a55d 100644
--- a/addons/birdframe/www/apt.js
+++ b/addons/birdframe/www/apt.js
@@ -2924,8 +2924,11 @@
// atlas say so instead of sitting blank (#73).
var apiUnreachable = false;
function apiErrorText() {
- return apiPrivateMode ? tt('error.privateMode')
- : apiUnreachable ? tt('error.unreachable') : '';
+ if (apiPrivateMode) return tt('error.privateMode');
+ if (!apiUnreachable) return '';
+ // 'auto' tried HA history too: say when that found no sensors at all.
+ return fetchJson.haWhy === 'no BirdNET-Go MQTT sensors found'
+ ? tt('error.unreachableNoMqtt') : tt('error.unreachable');
}
// Derived chart arrays, backfilled so 30 buckets always exist.
@@ -2989,7 +2992,10 @@
if (mode === 'ha') return haAvailable() ? ha() : Promise.reject('HA data source needs the card (hass) or a haToken');
if (mode === 'api' || !haAvailable()) return api();
return api().catch(function (apiErr) {
- return ha().catch(function () { return Promise.reject(apiErr); });
+ // Keep the fallback's own reason so the card can explain why
+ // it found nothing (#73) - read by apiErrorText().
+ return ha().then(function (v) { fetchJson.haWhy = ''; return v; },
+ function (haErr) { fetchJson.haWhy = haErr; return Promise.reject(apiErr); });
});
};
var hours, sci2, days2, lim;
diff --git a/addons/birdframe/www/i18n/en.js b/addons/birdframe/www/i18n/en.js
index 69c5ddef..f40d63bd 100644
--- a/addons/birdframe/www/i18n/en.js
+++ b/addons/birdframe/www/i18n/en.js
@@ -96,6 +96,7 @@
// ---- API errors ----
'error.privateMode': 'BirdNET-Go requires sign-in (Private Mode) — set api_token in the card config',
'error.unreachable': "Can't reach BirdNET-Go from this browser. Check birdnet_url, or see Troubleshooting in the README.",
+ 'error.unreachableNoMqtt': "Can't reach BirdNET-Go from this browser, and Home Assistant has no BirdNET-Go MQTT sensors to fall back on. Check birdnet_url, or turn on BirdNET-Go's MQTT (see Data sources in the README).",
// ---- Detail modal: chrome ----
'modal.close': 'Close',
diff --git a/dist/habird-card.js b/dist/habird-card.js
index c98e1416..3e0f88fe 100644
--- a/dist/habird-card.js
+++ b/dist/habird-card.js
@@ -110,6 +110,7 @@ var DIRS = {"acanthagenys-rufogularis-2":208,"acanthis-flammea-2":213,"acanthiza
// ---- API errors ----
'error.privateMode': 'BirdNET-Go requires sign-in (Private Mode) — set api_token in the card config',
'error.unreachable': "Can't reach BirdNET-Go from this browser. Check birdnet_url, or see Troubleshooting in the README.",
+ 'error.unreachableNoMqtt': "Can't reach BirdNET-Go from this browser, and Home Assistant has no BirdNET-Go MQTT sensors to fall back on. Check birdnet_url, or turn on BirdNET-Go's MQTT (see Data sources in the README).",
// ---- Detail modal: chrome ----
'modal.close': 'Close',
@@ -5072,8 +5073,11 @@ function runHABirdApp(__root, __shell, __cardConfig, __imgBase) {
// atlas say so instead of sitting blank (#73).
var apiUnreachable = false;
function apiErrorText() {
- return apiPrivateMode ? tt('error.privateMode')
- : apiUnreachable ? tt('error.unreachable') : '';
+ if (apiPrivateMode) return tt('error.privateMode');
+ if (!apiUnreachable) return '';
+ // 'auto' tried HA history too: say when that found no sensors at all.
+ return fetchJson.haWhy === 'no BirdNET-Go MQTT sensors found'
+ ? tt('error.unreachableNoMqtt') : tt('error.unreachable');
}
// Derived chart arrays, backfilled so 30 buckets always exist.
@@ -5137,7 +5141,10 @@ function runHABirdApp(__root, __shell, __cardConfig, __imgBase) {
if (mode === 'ha') return haAvailable() ? ha() : Promise.reject('HA data source needs the card (hass) or a haToken');
if (mode === 'api' || !haAvailable()) return api();
return api().catch(function (apiErr) {
- return ha().catch(function () { return Promise.reject(apiErr); });
+ // Keep the fallback's own reason so the card can explain why
+ // it found nothing (#73) - read by apiErrorText().
+ return ha().then(function (v) { fetchJson.haWhy = ''; return v; },
+ function (haErr) { fetchJson.haWhy = haErr; return Promise.reject(apiErr); });
});
};
var hours, sci2, days2, lim;
@@ -8169,7 +8176,7 @@ function runHABirdApp(__root, __shell, __cardConfig, __imgBase) {
// you copied the artwork locally (homeassistant/install.sh layout).
var HABIRD_CDN_ASSETS = 'https://cdn.jsdelivr.net/gh/adamoberley/HABirdDashboard@HABirdDashboard/avian/assets/';
-var HABIRD_VERSION = '1.6.0';
+var HABIRD_VERSION = '1.6.1';
var HABIRD_EDITOR_SCHEMA = [
{ name: 'dashboard', type: 'expandable', flatten: true, title: 'Dashboard', expanded: true, schema: [
diff --git a/homeassistant/card/build.js b/homeassistant/card/build.js
index b60b77b2..017804d7 100644
--- a/homeassistant/card/build.js
+++ b/homeassistant/card/build.js
@@ -228,7 +228,7 @@ const wrapper = `
// you copied the artwork locally (homeassistant/install.sh layout).
var HABIRD_CDN_ASSETS = 'https://cdn.jsdelivr.net/gh/adamoberley/HABirdDashboard@HABirdDashboard/avian/assets/';
-var HABIRD_VERSION = '1.6.0';
+var HABIRD_VERSION = '1.6.1';
var HABIRD_EDITOR_SCHEMA = [
{ name: 'dashboard', type: 'expandable', flatten: true, title: 'Dashboard', expanded: true, schema: [
diff --git a/homeassistant/www/apt.js b/homeassistant/www/apt.js
index 4843de0e..8db9a55d 100644
--- a/homeassistant/www/apt.js
+++ b/homeassistant/www/apt.js
@@ -2924,8 +2924,11 @@
// atlas say so instead of sitting blank (#73).
var apiUnreachable = false;
function apiErrorText() {
- return apiPrivateMode ? tt('error.privateMode')
- : apiUnreachable ? tt('error.unreachable') : '';
+ if (apiPrivateMode) return tt('error.privateMode');
+ if (!apiUnreachable) return '';
+ // 'auto' tried HA history too: say when that found no sensors at all.
+ return fetchJson.haWhy === 'no BirdNET-Go MQTT sensors found'
+ ? tt('error.unreachableNoMqtt') : tt('error.unreachable');
}
// Derived chart arrays, backfilled so 30 buckets always exist.
@@ -2989,7 +2992,10 @@
if (mode === 'ha') return haAvailable() ? ha() : Promise.reject('HA data source needs the card (hass) or a haToken');
if (mode === 'api' || !haAvailable()) return api();
return api().catch(function (apiErr) {
- return ha().catch(function () { return Promise.reject(apiErr); });
+ // Keep the fallback's own reason so the card can explain why
+ // it found nothing (#73) - read by apiErrorText().
+ return ha().then(function (v) { fetchJson.haWhy = ''; return v; },
+ function (haErr) { fetchJson.haWhy = haErr; return Promise.reject(apiErr); });
});
};
var hours, sci2, days2, lim;
diff --git a/homeassistant/www/i18n/en.js b/homeassistant/www/i18n/en.js
index 69c5ddef..f40d63bd 100644
--- a/homeassistant/www/i18n/en.js
+++ b/homeassistant/www/i18n/en.js
@@ -96,6 +96,7 @@
// ---- API errors ----
'error.privateMode': 'BirdNET-Go requires sign-in (Private Mode) — set api_token in the card config',
'error.unreachable': "Can't reach BirdNET-Go from this browser. Check birdnet_url, or see Troubleshooting in the README.",
+ 'error.unreachableNoMqtt': "Can't reach BirdNET-Go from this browser, and Home Assistant has no BirdNET-Go MQTT sensors to fall back on. Check birdnet_url, or turn on BirdNET-Go's MQTT (see Data sources in the README).",
// ---- Detail modal: chrome ----
'modal.close': 'Close',
diff --git a/package-lock.json b/package-lock.json
index b74bae67..64827c58 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "habird-dashboard",
- "version": "1.6.0",
+ "version": "1.6.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "habird-dashboard",
- "version": "1.6.0",
+ "version": "1.6.1",
"license": "MIT",
"devDependencies": {
"jsdom": "^24.0.0"
diff --git a/package.json b/package.json
index 5e4ba989..458a18b0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "habird-dashboard",
- "version": "1.6.0",
+ "version": "1.6.1",
"private": true,
"description": "Bird Card - a live bird collage card for Home Assistant, fed by BirdNET-Go",
"license": "MIT",
diff --git a/tests/test-unreachable.js b/tests/test-unreachable.js
index c207d3d2..db23d525 100644
--- a/tests/test-unreachable.js
+++ b/tests/test-unreachable.js
@@ -2,7 +2,8 @@
// DNS, dead LAN route) used to leave the card blank indefinitely, with only
// a console.warn. The API calls must now time out and the collage + atlas
// must say the API can't be reached. A card that simply has no detections
-// yet must stay blank, as before.
+// yet must stay blank, as before. With data_source: auto and a Home
+// Assistant that has no BirdNET-Go MQTT sensors, the message says so.
const path = require('path');
const ROOT = path.resolve(__dirname, '..');
const fs = require('fs');
@@ -10,7 +11,7 @@ const assert = require('assert');
const { JSDOM } = require('jsdom');
const CARD = fs.readFileSync(ROOT + '/dist/habird-card.js', 'utf8');
-function mount(fetchImpl) {
+function mount(fetchImpl, hass) {
const dom = new JSDOM('<!doctype html><html><body></body></html>', {
url: 'http://ha.local:8123/lovelace/birds', runScripts: 'outside-only', pretendToBeVisual: true,
});
@@ -26,7 +27,7 @@ function mount(fetchImpl) {
window.eval(CARD);
const card = window.document.createElement('habird-card');
card.setConfig({ birdnet_url: 'http://birdnet.lan:8080', live: false });
- card.hass = { themes: { darkMode: false }, states: {} };
+ card.hass = hass || { themes: { darkMode: false }, states: {} };
window.document.body.appendChild(card);
return { card, errors };
}
@@ -42,6 +43,14 @@ const quiet = mount((url) => {
return ok({ data: [], total: 0 });
});
+// 3. BirdNET-Go hangs and HA (reachable, via callApi) has no BirdNET-Go sensors.
+const noMqtt = mount((url) => new Promise(() => {}), {
+ themes: { darkMode: false },
+ states: { 'sensor.outdoor_temp': { entity_id: 'sensor.outdoor_temp', state: '12', attributes: {} } },
+ callApi: () => Promise.resolve([]),
+ callWS: () => Promise.resolve([]),
+});
+
setTimeout(() => {
try {
const root = hung.card.shadowRoot;
@@ -49,10 +58,13 @@ setTimeout(() => {
assert.ok(msg, 'collage shows an error instead of staying blank');
assert.ok(/reach BirdNET-Go/.test(msg.textContent), 'collage message: ' + msg.textContent);
assert.ok(/reach BirdNET-Go/.test(root.querySelector('.atlas-empty').textContent), 'atlas message');
+ assert.ok(!/MQTT sensors/.test(msg.textContent), 'no HA fallback -> generic message');
+ const nm = noMqtt.card.shadowRoot.querySelector('#collage .collage-error');
+ assert.ok(nm && /no BirdNET-Go MQTT sensors/.test(nm.textContent), 'no-MQTT reason shown: ' + (nm && nm.textContent));
const q = quiet.card.shadowRoot;
assert.strictEqual(q.getElementById('collage').innerHTML, '', 'no detections yet -> still blank');
assert.ok(!/reach BirdNET-Go/.test(q.querySelector('.atlas-empty').textContent), 'no error when the API answered');
- assert.deepStrictEqual(hung.errors.concat(quiet.errors), [], 'no page errors');
+ assert.deepStrictEqual(hung.errors.concat(quiet.errors, noMqtt.errors), [], 'no page errors');
console.log('unreachable API OK');
process.exit(0);
} catch (e) {