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, organised like the official Aira app: outdoor temperature and at home / away at the top, a plain-language status line ("Relax: the heat pump is running smoothly"), then the plant card with the two readings that matter (room temperature and domestic hot water, each with its target). Tapping the card opens the plant page. Below that the controls: house target with a 5–30 °C slider (0.5 °C steps) and a confirmation before the command leaves, domestic hot water target (45–60 °C) and the boost buttons
• 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, outdoor and indoor temperature, zones, last reading), accessories (the wall thermostat with temperature, humidity, signal, battery), software versions and the error count
• Other commands page: away mode, night mode for one hour, force heating, heating function on/off, legionella cycle, DHW heating on/off and a plant check — with the current state at the top, so nothing is pressed blindly
• 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	Data	Plant

Other 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:

• 61/61 core checks (tests/core_test.cpp), compiled with no warnings
• 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
• 170/170 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: status, plant card, heating and water
qml/pages/DataPage.qml          energy, efficiency and savings
qml/pages/PlantPage.qml         status, accessories, versions, errors
qml/pages/CommandsPage.qml      the other commands, current state on top
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/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 + proposal for 0.6.0 (Italian)
docs/ux/                UX study wireframes
docs/anteprima/         layout previews (English; docs/anteprima/it/ Italian)

License

MIT.