Sensables.IO IAQ Integration for Home Assistant

A Home Assistant custom integration for Sensables.IO air quality monitoring devices. This integration receives webhook data from your IAQ sensors and automatically creates entities with proper units, device classes, and icons.

Features

🎛️ GUI Configuration - Easy setup through Home Assistant's integration interface
📍 Location Support - Optional location field for organizing sensors by room
🌡️ Temperature Conversion - Automatic Celsius to Fahrenheit conversion
🎨 Sensor Icons - Material Design Icons for all sensor types
📊 Device Grouping - All sensors from one device grouped together
⚙️ Configurable - Webhook ID, sensor prefix, and expiration settings
🔄 Auto-Cleanup - Expired sensors automatically removed

Supported Sensors

Temperature (°C/°F) 🌡️
Humidity (%) 💧
Indoor Air Quality Index 🌬️
VOC (ppb) ⚗️
CO2 (ppm) 🌍
Particulate Matter: PM1.0, PM2.5, PM10 (μg/m³) 🌫️
Radon (Bq/m³) ☢️
Carbon Monoxide (ppm) ⚠️
Gas Resistance (Ω)
MQ7 & MQ4 Sensors
Mold Risk 🍄
Smoke Detection 🔥

Installation

HACS (Recommended)

Open HACS in Home Assistant
Click on "Integrations"
Click the three dots in the top right corner
Select "Custom repositories"
Add this repository URL: https://github.com/Madbeefer/sensables-iaq
Select category: "Integration"
Click "Add"
Click "Install" on the Sensables.IO IAQ card
Restart Home Assistant
Go to Settings → Devices & Services → Add Integration
Search for "Sensables.IO IAQ"

Manual Installation

Copy the sensables_iaq folder to your custom_components directory:

   custom_components/
   └── sensables_iaq/
       ├── __init__.py
       ├── config_flow.py
       ├── const.py
       ├── manifest.json
       └── strings.json

Restart Home Assistant
Go to Settings → Devices & Services → Add Integration
Search for "Sensables.IO IAQ"

Configuration

Setup

During initial setup, you'll configure:

Webhook ID: Unique identifier for your webhook endpoint (default: sensables_iaq)
Sensor Prefix: Prefix for all sensor entities (default: sensables)
Location (Optional): Location name to include in sensor IDs (e.g., "Kitchen")
Temperature Unit: Choose Celsius or Fahrenheit (automatic conversion)
Expire After: Time in seconds before inactive sensors are removed (default: 3600)

Webhook Endpoint

Your webhook URL will be:

http://your-home-assistant:8123/api/webhook/[your-webhook-id]

Usage

Webhook Data Format

Your Sensables.IO device should send POST requests with:

Headers:

Content-Type: application/json
device-name: Your Device Name

Example Payload:

{
  "temperature": 25,
  "humidity": 43,
  "iaq": 94,
  "voc": 1,
  "co2": 757,
  "gas": 178087,
  "pm1": 11,
  "pm25": 13,
  "pm10": 13,
  "radon": 0,
  "mq7": 0,
  "mq4": 0,
  "mold": 0,
  "smoke": 0,
  "co": 0
}

Example Sensors Created

With Location: "Kitchen" and Device Name: "Air Monitor"

sensor.sensables_kitchen_air_monitor_temperature - Temperature (77°F)
sensor.sensables_kitchen_air_monitor_humidity - Humidity (43%)
sensor.sensables_kitchen_air_monitor_co2 - CO2 (757 ppm)
sensor.sensables_kitchen_air_monitor_pm25 - PM2.5 (13 μg/m³)

Device Name: "Kitchen Air Monitor"

All sensors grouped under one device in Home Assistant.

Testing the Integration

Manual Test:

curl -X POST http://your-home-assistant:8123/api/webhook/sensables_iaq \
  -H "Content-Type: application/json" \
  -H "device-name: Test Device" \
  -d '{
    "temperature": 22.5,
    "humidity": 45,
    "co2": 687,
    "pm25": 8,
    "voc": 2
  }'

Python Test:

import requests

url = "http://your-home-assistant:8123/api/webhook/sensables_iaq"
headers = {
    "Content-Type": "application/json",
    "device-name": "Office Monitor"
}
data = {
    "temperature": 23,
    "humidity": 52,
    "iaq": 87,
    "co2": 723,
    "pm25": 12
}

response = requests.post(url, json=data, headers=headers, timeout=5)
print(f"Status: {response.status_code}")

Configuration Options

You can modify settings after installation:

Go to Settings → Devices & Services
Find "Sensables.IO IAQ"
Click "Configure"
Update your settings
Integration will reload automatically

Multiple Devices

You can set up multiple integration instances with different webhook IDs for:

Different device types
Different locations
Development vs production

Automation Examples

High CO2 Alert

automation:
  - alias: "High CO2 Alert"
    trigger:
      platform: numeric_state
      entity_id: sensor.sensables_kitchen_air_monitor_co2
      above: 1000
    action:
      service: notify.mobile_app
      data:
        message: "High CO2 in Kitchen: {{ states('sensor.sensables_kitchen_air_monitor_co2') }} ppm"

Poor Air Quality Notification

automation:
  - alias: "Poor Air Quality"
    trigger:
      platform: numeric_state
      entity_id: sensor.sensables_bedroom_air_monitor_iaq
      above: 150
    action:
      service: notify.home_assistant
      data:
        title: "Air Quality Alert"
        message: "Air quality in bedroom is poor. Consider ventilation."

Daily Air Quality Report

automation:
  - alias: "Daily Air Quality Report"
    trigger:
      platform: time
      at: "09:00:00"
    action:
      service: notify.mobile_app
      data:
        title: "Morning Air Quality"
        message: >
          Kitchen:
          Temp: {{ states('sensor.sensables_kitchen_air_monitor_temperature') }}°F
          CO2: {{ states('sensor.sensables_kitchen_air_monitor_co2') }} ppm
          PM2.5: {{ states('sensor.sensables_kitchen_air_monitor_pm25') }} μg/m³

Troubleshooting

Integration Not Showing

Ensure all files are in custom_components/sensables_iaq/
Check manifest.json has "config_flow": true
Restart Home Assistant
Clear browser cache

Webhook Returns 401

Webhook should not require authentication
Check reverse proxy settings
Verify URL format

Sensors Not Appearing

Check Home Assistant logs (Settings → System → Logs)
Verify device-name header is being sent
Test with curl command above

Sensors Disappearing

Check "Expire After" setting
Verify device is sending data regularly
Review logs for expiration messages

Temperature Not Converting

Check temperature unit setting in integration config
Verify incoming data is numeric
Check logs for conversion errors

Development

Running Locally

# Clone repository
git clone https://github.com/Madbeefer/sensables-iaq.git

# Copy to Home Assistant
cp -r sensables-iaq/custom_components/sensables_iaq ~/.homeassistant/custom_components/

# Restart Home Assistant

Debug Logging

# configuration.yaml
logger:
  default: info
  logs:
    custom_components.sensables_iaq: debug

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

Version 1.0.0 (2025-02-22)

Initial release
GUI configuration flow
Temperature unit conversion (C/F)
Optional location field
Sensor icons (MDI)
Device grouping
Auto-cleanup of expired sensors
Support for 15+ air quality sensor types

Credits

Created by @Madbeefer
Designed for Sensables.IO air quality monitors
Built for Home Assistant

Disclaimer

This is a third-party integration and is not officially affiliated with or endorsed by Sensables.IO.

Made with ❤️ for the Home Assistant community

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github/workflows		.github/workflows
custom_components/sensables_io_iaq		custom_components/sensables_io_iaq
README.md		README.md
hacs.json		hacs.json

Folders and files

Latest commit

History

Repository files navigation