Diagnostics and the Nerd screen - monikapurpl3/breeze GitHub Wiki
Two different tools. Diagnostics answers "is this working, and if not, where?". The Nerd screen answers "what exactly am I talking to?".
A full battery mirroring the server's own breeze-core diag:
- Connectivity, plus the server's build and advertised features β and the app's own version.
- Authentication and security posture β that the server rejects a missing or wrong key, and which endpoints are token-gated.
- This device's credential β auth version, and a warning as expiry approaches.
- Your device clock offset. A phone whose clock has drifted past the server's signature window fails every signed request, and this identifies it in one tap.
- Config secret-sanitisation β that the server does not hand back the API key or per-unit V3 secrets.
- Input validation β unknown unit β 404, out-of-range value β 422.
- Batch state and a live-stream check.
- Per-unit state, latency and hardware capabilities.
One deliberate omission: it does not probe the LAN-only admin endpoint
/api/auth/devices when you are remote. A single 403 there could get your address
banned by the server's fail2ban β and behind NAT, that takes everyone on your
connection with it.
The About row in Settings is just a version number. Tap it seven times β the gesture Android uses for developer options, with a countdown for the last three β and you get two tabs: System, everything the app knows about itself and the server, and Internal, settings nothing else shows.
The System tab:
-
This app β version, package, platform, Dart runtime, and the resolved
version of every dependency, read from the shipped
pubspec.lockso it cannot drift from what is actually running. -
This connection β measured round-trip latency, auth version, and how the
server sees you: your IP, whether that reads as private, the Host header,
scheme,
X-Forwarded-For, proxy state. This is the fastest way to diagnose a reverse proxy that is not forwarding the real client address. - The server β version and build commit, OS, init system, CPU and architecture, every component version, install date, uptime, time zone, memory, the store paths and their file modes, the effective settings.
- Your air conditioners β addresses, credentials, cached capabilities, history depth.
- Everyone's devices β each enrolled client with its auth version, enrolment date, last use and expiry.
One button copies the lot as JSON, for pasting into a bug report.
The System tab needs Breeze Core β₯ 3.0.5, which is where GET /api/system
arrived. Against anything older there is no partial version worth rendering, so
it says womp womp update your server and leaves it at that. The Internal tab
works with any server.
Breeze 2.4.0. Settings that change how the app looks and connects rather than what it does. Nothing here is needed to use Breeze; it is for an unusual setup, or for seeing what the app is doing.
- Material You, the default: the wallpaper's palette on Android 12 and newer, teal everywhere else.
- My colour: one of twelve swatches, or any colour as a hex code, used everywhere whatever the wallpaper. On iOS, which has no wallpaper palette, this is how to get a colour other than teal. A style decides how the colour is spread across the app, from Calm (the default) and Vibrant through Faithful to the colour and Rainbow to Monochrome.
A row of chips previews the scheme as it changes. The mode colours on the control screen keep their meaning; they are blended slightly towards whatever the main colour is, as they always were.
These belong to the server in use and are kept with its pairing, so each saved server has its own.
-
Fallback addresses: other addresses for the same server, tried in the
order you set when the main address can't be reached at all. "Can't be
reached" means a timeout or a refused connection, never an error from a
server that answered. The address that answers is used from then on, and
every two minutes the main address gets one short try, three seconds, to
come back. This device's pairing works at all of them: a v2 signature covers
the request's method, path and body, not the host. As with the main address,
plain
http://is only allowed for private addresses. -
Then try the server's LAN addresses: the app asks the server
(
/api/system, Breeze Core 3.0.5 or newer) for its address on its network and the port it listens on, and tries those after your fallbacks. It asks again at every launch, because an address from DHCP can change. For a main address that is public, at home. A server listening only on 127.0.0.1, behind a reverse proxy on the same machine, has nothing to offer the LAN, and the tab says so. - Give up on a request after 3 to 60 seconds; 15 by default. Per address: with fallbacks, a shorter timeout reaches the next one sooner.
- Live updates: on by default, the server pushing changes as they happen. Off, the app asks every 5 seconds instead, as with a server older than 3.0.
The tab shows this device's name and how it signs in: v2, requests signed with an Ed25519 key that never leaves the phone, or v1, a bearer token.
Pair again⦠asks for a new pairing code, under a name you choose and as v2
or v1. This device keeps working as it is until an admin approves the new
code; its old entry stays in the server's device list until revoked there
(breeze-core revoke). Choosing v1 also stops the app upgrading itself to v2
in the background, as it otherwise does at every launch. A server that only
accepts v2 refuses a v1 pairing, and the tab says so.
- Show each unit's IP address, under its name on the control screen.
-
Show latency at the top: beside Breeze, the round-trip time to the
server, and the address in use whenever a fallback is answering. Measured
only while this is on: a request to
/api/healthevery 15 seconds, plus the time the app's own requests take. Off, nothing is timed. - Vibration: the haptics, on or off.
The programs (favourites, schedules and curves, with a chip to show one kind) and the pending timers (sleep timers and scheduled starts), as the JSON the server sends. Read-only, with a button to copy it.
Your own facts, one per line, shown while the app waits on the server, mixed in with the 40 built-in ones or instead of them. With none of your own, the built-in ones stay.
Reset these settings puts colours, display, vibration, the timeout, live updates and cat facts back. Fallback addresses and pairing belong to the server and stay.