Homebridge CO2 RestAPI Sensor


A Homebridge plugin to integrate CO2 sensors with optional temperature and humidity via REST API into Apple HomeKit.

Features

- 🌡️ Multi-Sensor Support - CO2, Temperature, and Humidity in one accessory
- 🔄 Flexible API Integration - Works with any REST API that returns sensor values
- 📊 JSON & Plain Text Support - Handles both JSON responses (with configurable path) and plain numeric values
- 🔗 Separate Endpoints - Configure different URLs for each sensor type
- 🔄 Automatic Updates - Configurable polling interval for real-time data
- 🔐 Authentication Support - HTTP Basic Auth and custom headers
- 🎨 Homebridge Config UI - Easy configuration through the Homebridge UI
- ⚙️ Highly Configurable - All parameters customizable per sensor
- 🔢 Multiple Sensors - Support for unlimited sensors in one platform

Installation

$3

1. Search for homebridge-co2-restapi-sensor in the Homebridge Config UI X plugin screen
2. Click Install
3. Configure your sensors in the plugin settings

$3

``bash
npm install -g homebridge-co2-restapi-sensor
`

Configuration

Configure the plugin via the Homebridge Config UI X or manually edit your config.json:

$3

`json
{
"platforms": [
{
"platform": "CO2RestAPISensor",
"sensors": [
{
"name": "Living Room Sensor",
"url": "http://192.168.1.100/sensor",
"enableTemperature": true,
"enableHumidity": true
}
]
}
]
}
`

$3

`json
{
"platforms": [
{
"platform": "CO2RestAPISensor",
"sensors": [
{
"name": "Living Room Multi-Sensor",
"url": "http://192.168.1.100/api/sensor",
"updateInterval": 30,
"httpMethod": "GET",
"jsonPath": "co2",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
},
"timeout": 5000,
"minCO2": 400,
"maxCO2": 5000,
"abnormalThreshold": 1200,
"enableTemperature": true,
"temperatureJsonPath": "temp",
"minTemperature": -10,
"maxTemperature": 50,
"enableHumidity": true,
"humidityJsonPath": "humidity",
"manufacturer": "Acme Corp",
"model": "Multi-Sensor-Pro",
"serialNumber": "SN-123456"
}
]
}
]
}
`

$3

`json
{
"platforms": [
{
"platform": "CO2RestAPISensor",
"sensors": [
{
"name": "Office Sensors",
"url": "http://192.168.1.100/co2",
"jsonPath": "value",
"enableTemperature": true,
"temperatureUrl": "http://192.168.1.100/temperature",
"temperatureJsonPath": "celsius",
"enableHumidity": true,
"humidityUrl": "http://192.168.1.100/humidity",
"humidityJsonPath": "percent"
}
]
}
]
}
`

Configuration Parameters

$3

| Parameter | Type | Description |
|-----------|------|-------------|
| name | string | Name of the sensor as it appears in HomeKit |
| url | string | REST API endpoint URL to fetch sensor data |

$3

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| updateInterval | number | 60 | Update interval in seconds (5-3600) |
| httpMethod | string | GET | HTTP method (GET or POST) |
| jsonPath | string | co2 | Path to extract CO2 value from JSON (e.g., co2 or sensor.co2) |
| headers | object | {} | Custom HTTP headers |
| body | string | - | Request body for POST requests (JSON string) |
| timeout | number | 5000 | Request timeout in milliseconds (1000-30000) |
| auth.username | string | - | Username for HTTP Basic Authentication |
| auth.password | string | - | Password for HTTP Basic Authentication |
| minCO2 | number | 0 | Minimum CO2 value in ppm (clamping) |
| maxCO2 | number | 5000 | Maximum CO2 value in ppm (clamping) |
| abnormalThreshold | number | 1000 | CO2 level (ppm) above which sensor reports abnormal state |

$3

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| enableTemperature | boolean | false | Enable temperature sensor |
| temperatureUrl | string | - | Separate URL for temperature (uses main URL if not set) |
| temperatureJsonPath | string | temp | Path to extract temperature from JSON |
| temperatureHttpMethod | string | - | HTTP method for temperature endpoint (uses main if not set) |
| temperatureHeaders | object | - | Custom headers for temperature endpoint |
| temperatureBody | string | - | Request body for temperature POST requests |
| temperatureTimeout | number | - | Timeout for temperature endpoint |
| minTemperature | number | -100 | Minimum temperature in °C |
| maxTemperature | number | 100 | Maximum temperature in °C |

$3

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| enableHumidity | boolean | false | Enable humidity sensor |
| humidityUrl | string | - | Separate URL for humidity (uses main URL if not set) |
| humidityJsonPath | string | humidity | Path to extract humidity from JSON |
| humidityHttpMethod | string | - | HTTP method for humidity endpoint (uses main if not set) |
| humidityHeaders | object | - | Custom headers for humidity endpoint |
| humidityBody | string | - | Request body for humidity POST requests |
| humidityTimeout | number | - | Timeout for humidity endpoint |

$3

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| manufacturer | string | Custom | Manufacturer name in HomeKit |
| model | string | CO2 Sensor | Model name in HomeKit |
| serialNumber | string | Default-Serial | Serial number in HomeKit |
| firmwareRevision | string | 1.0.0 | Firmware version in HomeKit |

API Response Formats

$3

The plugin works great with APIs that return all sensor values in one response:

`json
{
"co2": 1420,
"temp": 31.30,
"humidity": 26.00,
"unit_co2": "ppm",
"unit_temp": "C"
}
`

Configuration:
`json
{
"name": "Multi-Sensor",
"url": "http://192.168.1.100/api/sensor",
"jsonPath": "co2",
"enableTemperature": true,
"temperatureJsonPath": "temp",
"enableHumidity": true,
"humidityJsonPath": "humidity"
}
`

$3

You can also use different URLs for each sensor type:

`json
{
"name": "Separate Sensors",
"url": "http://192.168.1.100/co2",
"enableTemperature": true,
"temperatureUrl": "http://192.168.1.100/temperature",
"enableHumidity": true,
"humidityUrl": "http://192.168.1.100/humidity"
}
`

Sensor Values in HomeKit

The plugin reports the following values to HomeKit:

$3

1. CO2 Level - The actual CO2 concentration in ppm
2. CO2 Detected - Normal (0) or Abnormal (1)
- Normal: CO2 ≤ threshold
- Abnormal: CO2 > threshold

> Note: The default threshold is 1000 ppm, following general indoor air quality guidelines. Values above 1000 ppm may indicate inadequate ventilation. You can customize this threshold in the sensor configuration using the abnormalThreshold parameter.

$3

- Current Temperature - Temperature in °C (automatically converted to °F in HomeKit if needed)

$3

- Current Relative Humidity - Humidity in % (0-100)

Examples

$3

`json
{
"name": "Office Sensor",
"url": "http://esphome-sensor.local/sensor/data",
"jsonPath": "co2_sensor.state",
"enableTemperature": true,
"temperatureJsonPath": "temperature.state",
"enableHumidity": true,
"humidityJsonPath": "humidity.state",
"updateInterval": 30
}
`

$3

`json
{
"name": "Garage Sensor",
"url": "http://homeassistant.local:8123/api/states/sensor.co2_garage",
"httpMethod": "GET",
"jsonPath": "state",
"headers": {
"Authorization": "Bearer YOUR_LONG_LIVED_TOKEN"
},
"enableTemperature": true,
"temperatureUrl": "http://homeassistant.local:8123/api/states/sensor.temperature_garage",
"temperatureJsonPath": "state"
}
`

$3

`json
{
"name": "Lab Multi-Sensor",
"url": "http://api.example.com/sensors/lab",
"auth": {
"username": "user",
"password": "pass"
},
"jsonPath": "data.co2.current",
"abnormalThreshold": 1500,
"enableTemperature": true,
"temperatureJsonPath": "data.temp.current",
"enableHumidity": true,
"humidityJsonPath": "data.humidity.current"
}
`

Troubleshooting

$3

1. Check that the API URL is accessible from your Homebridge server
2. Verify the jsonPath is correct for JSON responses
3. Check Homebridge logs for error messages
4. Ensure your API returns a valid numeric value
5. Test the API with curl or browser first

$3

1. Check the updateInterval setting
2. Verify network connectivity to the sensor
3. Check Homebridge logs for API errors
4. Ensure timeout is sufficient for slow APIs

$3

1. Verify the jsonPath extracts the correct value
2. Check minCO2 and maxCO2 settings (values are clamped)
3. Ensure API returns value in ppm (parts per million)

$3

Add to your Homebridge startup command:
`bash
homebridge -D
`

Or set in config.json:
`json
{
"bridge": {
"name": "Homebridge",
"username": "...",
"port": 51826,
"pin": "...",
"logLevel": "debug"
}
}
`

Development

$3

`bash


Clone the repository

git clone https://github.com/jstrauss/homebridge-co2-restapi-sensor.git
cd homebridge-co2-restapi-sensor

Install dependencies

npm install

Build the plugin

npm run build

Link to Homebridge

npm link

Watch for changes

npm run watch
`

$3

`
├── src/
│ ├── index.ts # Plugin entry point
│ ├── platform.ts # Platform implementation
│ ├── co2Accessory.ts # CO2 sensor accessory
│ ├── types.ts # TypeScript type definitions
│ └── settings.ts # Plugin constants
├── config.schema.json # Homebridge Config UI schema
├── package.json
├── tsconfig.json
└── README.md
`

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)
5. Open a Pull Request

License

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

Support

- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📖 Homebridge: Homebridge Documentation

Acknowledgments

- Thanks to the Homebridge team for the amazing platform
- Inspired by the need for flexible CO2 sensor integration in HomeKit

Changelog

$3

- ✨ Added temperature sensor support
- ✨ Added humidity sensor support
- ✨ Support for combined or separate sensor endpoints
- ✨ Flexible JSON path configuration for each sensor type
- 🐛 Improved error handling and validation
- 📝 Updated documentation with new examples

$3

- 🐛 Fixed validation bugs
- 🐛 Improved config error messages

$3

- Initial release
- Support for REST API CO2 sensors
- JSON and plain text response parsing
- Configurable update intervals
- HTTP authentication support
- Multiple sensor support
- Homebridge Config UI X integration