Home Assistant Integration

aranet-service can publish sensor readings to MQTT and optionally register supported sensors with Home Assistant via MQTT discovery.

Prerequisites

• aranet-service running with MQTT enabled
• A reachable MQTT broker such as Mosquitto or EMQX
• Home Assistant with the MQTT integration configured

Tip

Home Assistant OS users can use the Mosquitto add-on as the broker.

Note

For HTTP-based alerting outside Home Assistant automations, aranet-service also supports webhook notifications.

Quick Setup

1. Configure an MQTT broker.
2. Enable MQTT in server.toml.
3. Turn on mqtt.homeassistant = true.
4. Add the MQTT integration in Home Assistant.
5. Wait for aranet-service to publish its first readings and discovery payloads.

aranet-service Configuration

Edit ~/.config/aranet/server.toml:

[mqtt]
enabled = true
broker = "mqtt://localhost:1883"
topic_prefix = "aranet"
client_id = "aranet-service"
qos = 1
retain = true
homeassistant = true
ha_discovery_prefix = "homeassistant"

# Optional broker auth
# username = "aranet"
# password = "your-password"

[[devices]]
address = "Aranet4 XXXXX"
alias = "office"
poll_interval = 60

Key points:

• topic_prefix controls the reading topics, such as aranet/office/co2.
• ha_discovery_prefix controls the Home Assistant discovery topics, usually homeassistant.
• homeassistant = true enables discovery publishing.

Home Assistant Setup

Add or configure the MQTT integration in Home Assistant:

mqtt:
  broker: localhost
  port: 1883
  # username: aranet
  # password: your-password

You can also add MQTT from the Home Assistant UI at Settings → Devices & Services → Add Integration → MQTT.

Published MQTT Topics

aranet-service publishes readings to these topics:

Topic	Description
{prefix}/{device}/json	Full reading as JSON
{prefix}/{device}/co2	CO₂ concentration
{prefix}/{device}/temperature	Temperature in °C
{prefix}/{device}/humidity	Relative humidity
{prefix}/{device}/pressure	Pressure in hPa
{prefix}/{device}/battery	Battery percentage
{prefix}/{device}/status	Status string: green, yellow, red, error
{prefix}/{device}/radon	Radon value when available
{prefix}/{device}/radon_avg_24h	24-hour radon average when available
{prefix}/{device}/radon_avg_7d	7-day radon average when available
{prefix}/{device}/radon_avg_30d	30-day radon average when available
{prefix}/{device}/radiation_rate	Radiation rate when available
{prefix}/{device}/radiation_total	Radiation total when available

{device} is the configured alias when present, otherwise the device address, sanitized for MQTT topic safety.

Auto-Discovery Behavior

With mqtt.homeassistant = true, aranet-service publishes Home Assistant discovery payloads for the core sensors it can classify from the configured device type:

• CO₂
• Temperature
• Humidity
• Pressure
• Battery

Note

Radon and radiation values are still published to MQTT topics even when they are not auto-registered as Home Assistant entities. You can add those manually if you want them in Home Assistant today.

Manual Sensors

If you want to expose radon or radiation topics manually, add MQTT sensors in configuration.yaml:

mqtt:
  sensor:
    - name: "Basement Radon"
      state_topic: "aranet/basement/radon"
      unit_of_measurement: "Bq/m³"
      state_class: measurement

    - name: "Basement Radon 7d"
      state_topic: "aranet/basement/radon_avg_7d"
      unit_of_measurement: "Bq/m³"
      state_class: measurement

    - name: "Radiation Rate"
      state_topic: "aranet/radiation/radiation_rate"
      unit_of_measurement: "µSv/h"
      state_class: measurement

Automation Example

automation:
  - alias: "High CO2 Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.office_co2
        above: 1000
        for:
          minutes: 5
    action:
      - service: notify.mobile_app
        data:
          title: "High CO₂ Level"
          message: "Office CO₂ is {{ states('sensor.office_co2') }} ppm"

Troubleshooting

Entities do not appear

1. Confirm the broker is reachable.
2. Confirm Home Assistant is connected to the same broker.
3. Check aranet-service logs for MQTT connection errors.
4. Subscribe to both the reading topics and discovery topics:

mosquitto_sub -t 'aranet/#' -v
mosquitto_sub -t 'homeassistant/#' -v

Topic names are unexpected

Device aliases are preferred for topic names. MQTT topic segments are sanitized by replacing spaces, /, #, and + with _.

Discovery is enabled but no sensors appear

1. Make sure mqtt.homeassistant = true.
2. Make sure the service has at least one configured device.
3. Wait for the service to publish readings after startup or config reload.
4. Verify the discovery prefix matches Home Assistant expectations, usually homeassistant.