{"id":50757677,"url":"https://github.com/jasonjhofmann/aranet-cloud-homeassistant","last_synced_at":"2026-06-11T07:00:17.548Z","repository":{"id":360840611,"uuid":"1251930847","full_name":"jasonjhofmann/aranet-cloud-homeassistant","owner":"jasonjhofmann","description":"Home Assistant custom integration for Aranet Cloud — pulls historical and current readings from Aranet's cloud API for fleets of Aranet4 / Aranet Radon+ sensors. Companion library: github.com/jasonjhofmann/aranet-cloud","archived":false,"fork":false,"pushed_at":"2026-06-09T06:55:26.000Z","size":235,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T08:31:05.464Z","etag":null,"topics":["air-quality","aranet","co2-sensor","hacs","home-assistant","home-assistant-integration","iaq","soil-moisture"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jasonjhofmann.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T03:16:53.000Z","updated_at":"2026-06-09T06:55:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jasonjhofmann/aranet-cloud-homeassistant","commit_stats":null,"previous_names":["jasonjhofmann/aranet-cloud-homeassistant"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jasonjhofmann/aranet-cloud-homeassistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonjhofmann%2Faranet-cloud-homeassistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonjhofmann%2Faranet-cloud-homeassistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonjhofmann%2Faranet-cloud-homeassistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonjhofmann%2Faranet-cloud-homeassistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jasonjhofmann","download_url":"https://codeload.github.com/jasonjhofmann/aranet-cloud-homeassistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonjhofmann%2Faranet-cloud-homeassistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34186385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["air-quality","aranet","co2-sensor","hacs","home-assistant","home-assistant-integration","iaq","soil-moisture"],"created_at":"2026-06-11T07:00:15.151Z","updated_at":"2026-06-11T07:00:17.520Z","avatar_url":"https://github.com/jasonjhofmann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aranet Cloud — Home Assistant integration\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)\n[![release](https://img.shields.io/github/v/release/jasonjhofmann/aranet-cloud-homeassistant?label=release\u0026color=blue)](https://github.com/jasonjhofmann/aranet-cloud-homeassistant/releases)\n\nRead all your [Aranet Cloud](https://aranet.cloud/) sensors into Home\nAssistant via the official REST API. Works alongside (or instead of) the\nbuilt-in Bluetooth Aranet integration — and is the only path for sensors\nthat aren't in BLE range of your HA host.\n\n\u003e **Status:** Pre-release (0.8.x, Platinum quality scale). Functionally complete. v1.0 ships when\n\u003e submitted to the HACS default registry; until then, install as a custom\n\u003e repository.\n\n## What you get\n\n- **One Home Assistant device per Aranet sensor**, grouped under a parent\n  device for each base station — the same hierarchy you see in the Aranet app.\n- **Sensors** for each supported metric your sensors report:\n  temperature, humidity, CO₂, atmospheric pressure, volumetric water\n  content, soil + pore electrical conductivity, soil dielectric permittivity,\n  vapour-pressure deficit, day light integral, RSSI (signal), battery.\n  (See [Supported metrics](#supported-metrics) — unrecognised metrics aren't\n  surfaced yet.)\n- **Binary sensors** for the built-in Aranet alarm rules: per-sensor low\n  battery, per-base-station offline.\n- **Diagnostic entity** per base station showing firmware version.\n- **Unit preservation** — values arrive in whatever units your Aranet\n  account is configured to display (°F vs °C, mmHg vs hPa, etc.). Home\n  Assistant's built-in conversions still work if you prefer something else.\n- **Fixed 60-second poll cadence**, matching Aranet sensors' 60 s sample\n  rate. Not user-configurable per HA Core conventions — the integration\n  owns its cadence.\n- **Reauth flow** on revoked or rotated API keys.\n- **Diagnostics download** with the API key automatically redacted —\n  paste into a GitHub issue if something looks off.\n- **Aranet branding** bundled in the integration (icon + logo in light + dark)\n  via Home Assistant's Brands Proxy API (HA 2026.3+).\n\n## Supported hardware\n\nThe integration is **catalog-driven**: it doesn't hard-code a list of sensor\nmodels. It creates a Home Assistant device for any Aranet sensor on your\naccount that reports at least one metric it knows how to render (see\n[Supported metrics](#supported-metrics) below), so new and Pro/virtual sensor\ntypes appear automatically.\n\n### Verified on real hardware\n\nThese types have been tested end-to-end against physical sensors:\n\n- **Aranet4 (S4V1)** — 4-in-1 air quality (T, RH, CO₂, P)\n- **Aranet legacy (S1V16)** — older 2-metric model\n- **Soil moisture (S6V4)** — capacitive soil + temperature\n- **Soil VWC / EC / T (S6V1)** — Delta-T WET150 multi-parameter probe\n\n### Expected to work — not yet verified\n\nThe Aranet Cloud catalog lists ~53 sensor *types*. Every **metric** they can\nreport is rendered (see [Supported metrics](#supported-metrics)), but the\nfollowing device types haven't been exercised on physical hardware — for\nexample the **Aranet2 (S4V5)**, the **0–10 VDC / 4–20 mA transmitter bridges\n(S5V1 / S5V2)**, the **Radon Plus PRO**, and Pro/virtual sensor types. They\nshould appear and work; if you have one, a\n[diagnostics download](#reporting-issues) on an issue is very welcome.\n\n## Supported metrics\n\nThe integration renders an entity for **every metric class in the Aranet Cloud\ncatalog**. A sensor gets a `sensor` entity for each of these it reports:\n\n- temperature, humidity, CO₂, atmospheric pressure\n- soil moisture (VWC), soil permittivity, soil EC, pore EC\n- vapour-pressure deficit, day-light integral\n- voltage, weight, distance, differential pressure\n- radon, fraction\n- signal strength, battery\n\n(See [Entity reference](#entity-reference) for device classes and units.) Plus\nthe built-in **Low battery** / **Base station offline** binary sensors and a\nper-base firmware diagnostic.\n\nCoverage is complete against the current catalog. A *future* metric Aranet\nadds would be skipped until added here — a one-row change to `METRIC_REGISTRY`\n(see [CONTRIBUTING](CONTRIBUTING.md)). Units follow your Aranet account\npreference (°C vs °F, hPa vs mmHg, …); an unrecognised unit shows the value\nwith no unit label.\n\n## Use cases\n\n- **Whole-home air quality** — pull every Aranet4/Aranet2 CO₂, temperature,\n  humidity, and pressure reading into HA, even for sensors that are nowhere\n  near your HA host's Bluetooth range (the cloud is the transport).\n- **Greenhouse / grow rooms** — VPD and daily-light-integral entities feed\n  climate and lighting automations.\n- **Soil \u0026 irrigation** — soil moisture (VWC), permittivity, and EC from\n  S6V4 / WET150 probes drive watering logic and long-term statistics.\n- **Fleet health at a glance** — per-sensor battery and signal-strength\n  diagnostics plus low-battery and base-offline binary sensors let you\n  alert before a sensor silently drops out.\n\n## Installation\n\n### Via HACS (custom repository)\n\n1. HACS → Integrations → ⋮ menu → **Custom repositories**\n2. URL: `https://github.com/jasonjhofmann/aranet-cloud-homeassistant`\n3. Category: **Integration**\n4. Find \"Aranet Cloud\" in the list → Download\n5. Restart Home Assistant\n6. Settings → Devices \u0026 Services → **+ Add Integration** → Aranet Cloud\n7. Paste your Aranet Cloud API key\n\n### Manually\n\n1. Copy `custom_components/aranet_cloud/` into your HA\n   `/config/custom_components/`\n2. Restart HA (the [`aranet-cloud`](https://pypi.org/project/aranet-cloud/)\n   Python dependency is installed automatically from `manifest.json`)\n3. Add the integration via the UI as above\n\n## Removing the integration\n\nThis integration follows standard Home Assistant removal — no extra steps.\n\n1. Go to **Settings → Devices \u0026 Services**.\n2. Click the **Aranet Cloud** integration entry.\n3. Use the **⋮** (three-dot) menu on the entry and choose **Delete**.\n\nDeleting the config entry removes all of the integration's devices and\nentities and discards the stored API key. To remove the integration's code\nas well, open **HACS → Aranet Cloud → ⋮ → Remove** (or delete\n`custom_components/aranet_cloud/` if you installed manually), then restart\nHome Assistant. Your Aranet Cloud account is untouched — the integration is\nread-only and never modifies it.\n\n## Getting an API key\n\n1. Sign in to [aranet.cloud](https://aranet.cloud/)\n2. Account → API\n3. Generate a key\n4. Paste into the integration setup form\n\nThe integration is **read-only** — it only ever calls `GET` endpoints. No\ndata is written to your Aranet account.\n\n## Entity reference\n\n| Domain | Metric | HA device class | Default unit |\n|---|---|---|---|\n| `sensor` | Temperature | `temperature` | °C or °F (account preference) |\n| `sensor` | Humidity | `humidity` | % |\n| `sensor` | CO₂ | `carbon_dioxide` | ppm |\n| `sensor` | Atmospheric pressure | `atmospheric_pressure` | mmHg / hPa / inHg (account preference) |\n| `sensor` | Soil moisture (VWC) | `moisture` | % |\n| `sensor` | Soil permittivity | — | (unitless) |\n| `sensor` | Soil EC | — | mS/cm |\n| `sensor` | Pore EC | — | mS/cm |\n| `sensor` | Vapour-pressure deficit | `pressure` | kPa / hPa / Pa (account preference) |\n| `sensor` | Day light integral | — | mol/m²/d or µmol/m²/d |\n| `sensor` | Voltage | `voltage` | V or mV (account preference) |\n| `sensor` | Weight | `weight` | kg or lb (account preference) |\n| `sensor` | Distance | — | m / cm / ft / in / mm (account preference) |\n| `sensor` | Differential pressure | — | Pa / mbar / mmH₂O (account preference) |\n| `sensor` | Radon | — | Bq/m³ or pCi/L (account preference) |\n| `sensor` | Fraction | — | (unitless) |\n| `sensor` | Signal strength (RSSI) | `signal_strength` (diagnostic, disabled by default) | dBm |\n| `sensor` | Battery | `battery` (diagnostic) | % |\n| `sensor` | Base firmware | — (diagnostic) | version string |\n| `binary_sensor` | Low battery | `battery` | `on` = low |\n| `binary_sensor` | Base station | `connectivity` | `on` = connected |\n\nAll `unique_id`s use the **device-printed hex serial** (e.g. `0AB12`),\nnot the cloud numeric ID — so entity IDs survive any cloud-side rekeying.\n\n## Example automations\n\nAlert when a room's CO₂ climbs above 1000 ppm:\n\n```yaml\nautomation:\n  - alias: \"High CO₂ — Living Room\"\n    triggers:\n      - trigger: numeric_state\n        entity_id: sensor.living_room_co2\n        above: 1000\n    actions:\n      - action: notify.mobile_app_phone\n        data:\n          message: \"Living Room CO₂ is {{ states('sensor.living_room_co2') }} ppm — ventilate.\"\n```\n\nNotify when a sensor reports low battery, or a base station drops offline:\n\n```yaml\nautomation:\n  - alias: \"Aranet sensor needs attention\"\n    triggers:\n      - trigger: state\n        entity_id: binary_sensor.living_room_low_battery\n        to: \"on\"\n      - trigger: state\n        entity_id: binary_sensor.aranet_1a2b3c_base_station\n        to: \"off\"   # connectivity class: off = disconnected\n    actions:\n      - action: notify.mobile_app_phone\n        data:\n          message: \"An Aranet device needs attention.\"\n```\n\n## How data is updated\n\nThe integration **polls** Aranet Cloud once every **60 seconds** through a\nsingle `DataUpdateCoordinator` shared by all entities — one set of API calls\nper cycle (`measurements/last`, `telemetry/last`, `alarms/actual`, plus the\nsensor and base catalogs), not one per entity. Aranet sensors themselves\nreport to the cloud roughly once a minute, so a faster cadence returns no\nnew data; the interval is fixed and not user-configurable.\n\nWhen a sensor newly appears in your account it gains entities on the next\npoll; when one is removed from the account, its device is pruned\nautomatically. If the API key is rejected mid-run, all entities go\n`unavailable` and a reauthentication prompt appears.\n\n## Configuration\n\nThere is nothing to configure beyond the API key entered at setup. The poll\ncadence is a fixed **60 seconds** (see *How data is updated*) and is\nintentionally not user-tunable, per Home Assistant Core conventions (the\nintegration owns its cadence).\n\nIf your API key is rotated or revoked, the integration triggers a\nreauthentication prompt so you can paste the new key. To change the key\nproactively, use the integration entry's **⋮ → Reconfigure** action.\n\n## Known limitations\n\n- **Cloud-only.** This integration talks to the Aranet *Cloud* REST API; it\n  does not read sensors over Bluetooth. A working internet connection and a\n  cloud-synced Aranet base station are required. For local BLE, use the\n  built-in `aranet` integration instead (the two can run side by side).\n- **Read-only.** Only `GET` endpoints are used — you cannot change sensor or\n  account settings from Home Assistant.\n- **Fixed 60 s cadence.** Sub-minute resolution is not available (and the\n  upstream sample rate wouldn't supply it anyway).\n- **User-defined alarm rules** beyond the built-in low-battery and\n  base-offline rules are not yet surfaced as binary sensors.\n- **Units follow your Aranet account preference** (°C vs °F, hPa vs mmHg,\n  etc.); Home Assistant's own unit conversion can override the display.\n\n## Troubleshooting\n\n### \"Could not connect to Aranet Cloud\" during setup\n\n- Check your internet connection.\n- Verify `https://aranet.cloud/api/v1/sensors` is reachable from your HA\n  host (try `curl -H \"ApiKey: yours\" …`).\n- Some corporate networks block Cloudflare-fronted endpoints — the API\n  sits behind Cloudflare.\n\n### \"The API key was rejected\"\n\n- Make sure you copied the full key without trailing whitespace.\n- Confirm the key wasn't revoked in the Aranet Cloud dashboard.\n- If you recently rotated, the integration shows a reauthentication prompt\n  (Settings → Devices \u0026 Services) so you can paste the new key.\n\n### Entities show `unavailable`\n\n- Check the integration tile for setup errors.\n- Click **Download diagnostics** and inspect the `coordinator.last_update_success`\n  flag and the raw snapshot — the API key is auto-redacted.\n- The Aranet sensors themselves go silent when out of range of their base\n  station. Enable the per-sensor **Signal strength** entity (it's a\n  diagnostic, disabled by default) to watch for a weak signal.\n\n### Enabling debug logs\n\nAdd this to `configuration.yaml` and restart (or call the\n`logger.set_level` service for a no-restart change):\n\n```yaml\nlogger:\n  logs:\n    custom_components.aranet_cloud: debug\n    aranet_cloud: debug   # the underlying REST client library\n```\n\nAt `debug` you'll see, in `Settings → System → Logs`:\n\n- **Setup** — the entry name, sensor/base counts, and poll interval.\n- **Each poll** — `Polled Aranet Cloud: N sensor(s), N base(s), …` once per\n  cycle, so you can confirm data is flowing and how much.\n- **Entity changes** — `Adding N sensor entit…: \u003cunique_id\u003e, …` whenever a\n  new sensor or metric appears.\n- **Unrendered metrics** — `Sensor X reports metric id N … — skipping` (once\n  per sensor/metric) if Aranet ever reports a metric this integration doesn't\n  render yet. That's your cue to [open an issue](#reporting-issues) — adding it\n  is a one-row change.\n- **Device cleanup** — a one-line `INFO` (no debug needed) when a device is\n  removed because the account stopped reporting it.\n\nThe API key is **never** logged at any level. Coordinator failures are\nlogged once when they start and once when they recover (Home Assistant's\nstandard coordinator behaviour), so a flaky connection won't spam the log.\n\n## Reporting issues\n\nUse the GitHub issue tracker linked from this README. Please include the\ndiagnostics download — the API key is redacted before the snapshot is\ngenerated, so it's safe to share.\n\nFor intermittent problems, also enable debug logging (integration page →\n⋮ → **Enable debug logging**, which now covers the `aranet-cloud` client\nlibrary too, or via YAML):\n\n```yaml\nlogger:\n  logs:\n    custom_components.aranet_cloud: debug\n    aranet_cloud: debug\n```\n\nDebug logs include per-poll counts (sensors/bases/readings/alarms) and the\nclient library's retry/timeout attempts; credentials never appear in logs.\n\n## Architecture\n\n- Backed by [`aranet-cloud`](https://github.com/jasonjhofmann/aranet-cloud),\n  a standalone async Python library covering the full 27-endpoint API\n  surface. Reusable outside Home Assistant.\n- Single `DataUpdateCoordinator` polls measurements, telemetry, and\n  alarms each cycle; base + sensor catalogs are refreshed in the same\n  cycle (cheap, stable).\n- Base devices are pre-registered before sensor entities, so the\n  `via_device` device-hierarchy link is set up correctly per HA 2025.12+\n  rules.\n- Brand assets are bundled in `custom_components/aranet_cloud/brand/`\n  via HA's new Brands Proxy API (no PR to home-assistant/brands required).\n\n## License\n\nApache 2.0. Aranet branding is bundled in-repo at\n`custom_components/aranet_cloud/brand/` and served by Home Assistant's Brands\nProxy API (HA 2026.3+); \"Aranet\" is a trademark of SAF Tehnika.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonjhofmann%2Faranet-cloud-homeassistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasonjhofmann%2Faranet-cloud-homeassistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonjhofmann%2Faranet-cloud-homeassistant/lists"}