harbour-aira/README.md

harbour-aira

Native Sailfish OS app to monitor and control an Aira Home heat pump: plant status, domestic hot water, and the house target temperature per zone.

Versione italiana: README.it.md

What it does

• Home, one screen to look at: a coloured dot with a one-line status ("Everything is fine", "Heating the hot water"), the time of the last update, the two readings that matter (house and domestic hot water, each with its target) side by side and tappable, and three quick actions: boost, away mode and the plant commands. It fits without scrolling — the controls live in their own pages
• Setpoints page: house target and hot water target, each with the value the plant is keeping right now, a slider (the proposal, the plant value does not move), a row of quick values for cold fingers and a confirmation button that only lights up when there is something to change
• Data page: heat produced, electricity used, efficiency (COP) for hot water and heating, savings on the bill, CO₂ avoided and the Smart Tariff Control saving, month by month. These are the numbers Aira computes in the cloud, exactly as in the official app's Data tab
• Plant page: status (connection, mode, away/night/forced heating, manual mode, defrost, signature lights, pump state, allowed modes, outdoor and indoor temperature, zones, last reading), accessories (the wall thermostat with temperature, humidity, signal, battery), software versions, the error count and the plant check. The extended status sentence ("Relax: the heat pump is running smoothly") lives here
• Plant commands page: four switches (away mode, forced heating, heating, hot water active) that show the state of the plant and change it in one tap, plus the buttons for what has no state: legionella cycle and night mode for one hour. The switches follow the plant — they never anticipate it
• Cover page showing the house temperature
• Address and bridge token live in the app settings (QSettings), never in the binary
• Languages: English and Italian. The interface follows the phone language by default and falls back to English when there is no catalogue for it. The language can also be picked in the settings; the app reloads to apply it, and numbers follow the chosen language too (decimal comma in Italian, dot in English)

Layout previews (rendered with the real values the plant returned, not screenshots — see Status):

Home	Setpoints	Data

Plant	Plant commands	Settings	Cover

Why there is a bridge

Aira's cloud API is gRPC over HTTP/2. Qt 5.6 — the toolkit every Sailfish app runs on — has no HTTP/2, so a native client cannot talk to it directly. The alternatives (packaging grpcio for aarch64 with PyOtherSide, or rewriting Cognito + gRPC in C++) are fragile and expensive.

So the logic stays on a server, where Python and the tokens already work, and the app is a thin client speaking HTTP/1.1 + JSON. A side effect worth having: credentials and session tokens never leave that machine.

 Jolla (QML/C++ Qt 5.6)  --HTTP/1.1 + JSON-->  bridge (Linux, LAN)  --gRPC-->  cloud Aira
                                               bridge/aira_bridge.py

Requirements

• a Sailfish OS phone
• an Aira Home heat pump, with an account in the Aira app
• the bridge running on a machine that stays on, in the same LAN (a Raspberry Pi is plenty)

The bridge

Sources, systemd user unit and full instructions: bridge/README.md. Short version:

cd bridge
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
export AIRA_CONFIG_DIR="$HOME/.config/aira"
python setup_creds.py            # Aira email + password, saved in a 600 file
python aira_bridge.py --port 8790

The first start writes a random token to $AIRA_CONFIG_DIR/aira_bridge.json (mode 600): that value goes in the app settings, together with the LAN address of the machine. Full API: docs/PROTOCOL.md.

App settings

Address and token are configured in the Settings page (QSettings in ~/.config/harbour/aira/aira.conf): no personal data in the binary.

Build

Requires the Sailfish SDK (sfdk) and an aarch64 target (Jolla Phone 2026):

sfdk target install SailfishOS-5.0.0.62-aarch64
sfdk target use SailfishOS-5.0.0.62-aarch64
sfdk build           # RPM in RPMS/
sfdk deploy          # to the connected device

From a source tarball (harbour-aira-<version>.tar.gz, if you were handed one): extract it into a new directory (never on top of a previous extraction: the Makefiles stay stale), or simply clone this repository. The app log starts with harbour-aira v<version> build <date>, which tells a fresh build from a stale one without guessing.

Local checks, no SDK needed

cd tests && mkdir -p build && cd build
~/Qt/5.15.2/gcc_64/bin/qmake ../core_test.pro && make && ./core_test

Covers the pure logic (src/airajson.cpp): address normalisation, summary and statistics parsing, mode labels, command payloads, error messages, and the number/currency/month formatting used by the Data page. The Silica UI can only be verified on a device.

A second check compares the keys the QML reads with the keys the bridge really returns (26 from /summary, 15 from /stats). It needs the bridge running, and it exists because the UI cannot be run here: a typo in a key would show up as a permanent “—” on the phone, with nothing in the log.

python3 tests/ui_contract_check.py        # bridge on 127.0.0.1:8790
python3 tests/ui_contract_check.py http://192.168.3.21:8790

Status

Verified so far:

• 79/79 core checks (tests/core_test.cpp), compiled with no warnings — including the one-line and extended status sentences, so what the home says about the plant is verified without a phone
• 48/48 bridge checks, offline (bridge/test_bridge_commands.py) — including that a zone command always carries every zone, that absurd values are refused (40 °C, zone 3, text), and the Wh→kWh / money conversions of the statistics
• 190/190 strings translated in the Italian catalogue, checked by loading the compiled .qm in the test the same way main.cpp does: source English in, Italian out, and back to English when the catalogue is removed
• numbers, amounts and month names formatted through QLocale, so the decimal separator and the currency position follow the language (verified for both)
• qmllint clean on every QML file. Note it validates syntax only: without the Silica module an invalid Silica property passes silently
• read-only queries against one real Aira Home unit, through the bridge — including the cloud statistics, which match what the official app shows for the same period (heat produced 70.8 kWh, electricity 29.3 kWh, hot-water COP 4.42, Smart Tariff Control saving €2.71)
• the bridge runs as a systemd user unit and comes back by itself after a kill

Not verified: the app has not been built or run on a phone yet — the first build is up to whoever has the Sailfish SDK. The images in docs/anteprima/ are layout previews built from the real plant values, not screenshots.

A Qt 5.6 note on the language switch: QQmlEngine::retranslate() only exists from Qt 5.10, so installing a translator is not enough to re-translate what is already on screen. The app therefore reloads the QML root when the language changes: the setting applies immediately, at the cost of landing back on the home page.

Caveats:

• Unofficial client, not in the Jolla Store: it talks to Aira's API with your own account. Terms of service and trademarks remain Aira's business — use it at your own risk, on your own pump
• tested against one unit so far (firmware: outdoor unit 1.30.0, system 6.10.0, climate control 3.9.12); other units and other countries may expose different fields
• cooling is reachable from the bridge but has no UI yet; schedules/curves are not implemented, and firmware versions are shown read-only
• the Data page depends on Aira's own statistics service: on a very new installation some months have no data yet (the app then writes no data instead of a number)
• only a whitelist of commands is exposed: factory reset, firmware updates, reboots and Wi-Fi provisioning are deliberately unreachable
• no command is ever sent to the plant by the tests

Looking for testers

If you own an Aira heat pump and a Sailfish phone, and you are willing to run the bridge on a machine at home, I would like to hear how it behaves on your unit:

• pump model and firmware versions (visible in the Aira app)
• how many heating zones you have (1 or 2), and whether cooling is configured
• the output of python aira_probe.py --json (it contains no credentials)
• anything that looks wrong next to what the Aira app shows at the same moment
• your country, since Aira may not expose the same fields in every market

Layout

harbour-aira.pro        qmake project (icons, qml, docs)
src/airajson.{h,cpp}    pure logic, testable without the SDK
src/apiclient.{h,cpp}   QNetworkAccessManager + timeout watchdog
src/settings.{h,cpp}    QSettings in AppConfigLocation (SailJail sandbox)
src/translator.{h,cpp}  UI language: system locale, English fallback, reload
src/main.cpp            context properties: appSettings, api, translator
qml/harbour-aira.qml    ApplicationWindow + cover
qml/pages/MainPage.qml          home: one-line status, two readings, quick actions
qml/pages/SetpointsPage.qml     house and water targets, quick values, boost
qml/pages/DataPage.qml          energy, efficiency and savings
qml/pages/PlantPage.qml         status, accessories, versions, errors, diagnostics
qml/pages/CommandsPage.qml      the plant commands, state shown by switches
qml/pages/SettingsPage.qml
qml/components/InfoRow.qml      label on the left, value on the right
qml/components/ValueRow.qml     title + subtitle left, big value right
qml/components/ReadingCell.qml  tappable reading: title, big value, charge bar
qml/components/NoticeBar.qml    command messages, anchored to the bottom edge
qml/components/ActionButton.qml command button, optional confirmation
tests/core_test.cpp     core checks (headless)
tests/ui_contract_check.py  QML keys vs bridge keys (bridge must be running)
bridge/                 local HTTP bridge -> see bridge/README.md
translations/           harbour-aira-it.ts (English is the source language)
docs/PIANO.md           project plan and decisions (Italian)
docs/PROTOCOL.md        bridge API
docs/UX-STUDIO.md       UX review and what changed in 0.6.0 (Italian)
docs/ux/                UX study wireframes
docs/anteprima/         layout previews (English; docs/anteprima/it/ Italian)

License

MIT.