Homebridge File Sensor

A Homebridge plugin that reads numeric values from local files and exposes them as sensors in Apple HomeKit. Built for Raspberry Pi 5.

Why This Plugin?

Existing DHT sensor plugins for Homebridge don't work on Raspberry Pi 5 due to GPIO library incompatibilities. This plugin takes a different approach - instead of reading the sensor directly, it reads values from a file. You can use any external tool or script (like Python with adafruit-circuitpython-dht) to write sensor data to a file, and this plugin will expose it to HomeKit.

Perfect for RPi5 users who want to use DHT11/DHT22 sensors with Homebridge.

Features

• Read numeric values from any local file
• Support for Temperature and Humidity sensor types
• Configurable polling interval
• Real-time updates pushed to HomeKit

Installation

Via Homebridge UI

Search for homebridge-rpi5-file-sensor in the Homebridge UI plugins tab.

Via npm

npm install -g homebridge-rpi5-file-sensor

Configuration

Add the platform to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "FileSensor",
      "name": "My Sensor",
      "filePath": "/path/to/sensor_value.txt",
      "sensorType": "temperature",
      "pollInterval": 60
    }
  ]
}

Options

| Option | Required | Default | Description | |--------|----------|---------|-------------| | platform | Yes | - | Must be "FileSensor" | | name | Yes | - | Display name in HomeKit | | filePath | Yes | - | Absolute path to the file containing the numeric value | | sensorType | No | "humidity" | Type of sensor: "humidity" or "temperature" | | pollInterval | No | 60 | How often to read the file (in seconds) |

Sensor Types

| Type | HomeKit Sensor | Value Range | Unit | |------|----------------|-------------|------| | humidity | Humidity Sensor | 0 - 100 | % | | temperature | Temperature Sensor | -270 - 100 | °C |

File Format

The file should contain a single numeric value:

22.5

• Values are automatically clamped to the valid range for the sensor type
• Non-numeric content will be logged as a warning and ignored
• The file is read at startup and then at every poll interval

Examples

Temperature Sensor

Monitor room temperature from a file updated by an external script or sensor:

{
  "platform": "FileSensor",
  "name": "Room Temperature",
  "filePath": "/tmp/room_temp.txt",
  "sensorType": "temperature",
  "pollInterval": 30
}

Humidity Sensor

Monitor humidity levels:

{
  "platform": "FileSensor",
  "name": "Room Humidity",
  "filePath": "/tmp/room_humidity.txt",
  "sensorType": "humidity",
  "pollInterval": 60
}

Integration with External Scripts

Create a simple script that writes sensor data to a file:

#!/bin/bash
# Example: Read from a USB temperature sensor and write to file
while true; do
  cat /sys/bus/w1/devices/28-*/temperature | awk '{print $1/1000}' > /tmp/temperature.txt
  sleep 30
done

Development

Setup

git clone https://github.com/USERNAME/homebridge-rpi5-file-sensor.git
cd homebridge-rpi5-file-sensor
npm install

Build

npm run build

Watch Mode

Run Homebridge with the plugin in development mode:

npm run watch

This will:

1. Build the TypeScript source
2. Link the plugin locally
3. Start Homebridge with the test configuration

Test Configuration

Edit test/hbConfig/config.json to configure the plugin for local testing:

{
  "platform": "FileSensor",
  "name": "Test Sensor",
  "filePath": "/tmp/sensor_value.txt",
  "sensorType": "temperature",
  "pollInterval": 10
}

Create a test file:

echo "23.5" > /tmp/sensor_value.txt

Lint

npm run lint

Screenshot

Acknowledgments

Big thanks to the Homebridge team for creating the awesome homebridge-plugin-template that this project is built on. You folks made getting started so much easier!

License

Apache-2.0