Supported Devices

Raspberry Pi

Each Raspberry Pi is exposed as a HomeKit accessory, with a Temperature Sensor service, a Lightbulb service, and a Smoke Sensor service. Through the Temperature Sensor service, the Pi's CPU temperature can be monitored. The Lightbulb service provides control for the Pi's power LED. The Smoke Sensor triggers when the CPU frequency is throttled or when the Raspberry Pi experiences under voltage. The Temperature Sensor contains additional characteristics for CPU frequency, CPU voltage, whether the system currently has under voltage or has throttled the CPU frequency, system time, and system load. As Apple's Home app doesn't support custom characteristics, you need to use another HomeKit app to monitor these. Homebridge RPi also exposes a History service, so Eve shows the history for the CPU temperature.

By default, HomeKit will send a push notification when the Smoke Sensor triggers, but these can be configured in the Home app. By setting noSmokeSensor in config.json, you can prevent Homebridge RPi from exposing the smoke sensor. By setting noPowerLed in config.json, the Lightbulb service can be suppressed.

Polling

A Raspberry Pi contains internal sensors for CPU temperature, frequency, voltage. These sensors are read using the vcgencmd command, see Hardware Monitoring. For the local Raspberry Pi, Homebridge RPi simply executes this command periodically. Note that the user running Homebridge needs to be a member of the video group, to be allowed to run vcgencmd.

For a remote Raspberry Pi, Homebridge RPi contains a script that executes these commands, saving the output into a JSON file. Homebridge RPi periodically executes this script, and reads the output file, through the pigpio connection.

The rate for polling can be adjusted through the Heartrate characteristic. To prevent Homebridge RPi from polling the Raspberry Pi altogether, set hidden config.json. With this setting, no Temperature Sensor nor Smoke Sensor service will be exposed. Note that this will result in a Not Supported accessory in Apple's Home app.

USB Power

Raspberry Pi models with four USB 2.0 ports (the B+, 2B, 3B, and 3B+) support cutting power to the USB ports. This might be used to control a USB fan or reading light. Note however, that this works on all four ports at the same time, and that this also cuts the power to the LAN port. Make sure to enable WiFi on the Pi, before trying this. Note that there is no feedback from the Pi to report the actual USB power state.

To control the power to the USB ports from HomeKit, you need to:

• Set usbPower in config.json to expose an Outlet service on the Raspberry Pi accessory;
• Make sure you have enabled and configured the pigpiod service on the local or remote Raspberry Pi, as described in the README under Local Raspberry Pi Configuration or Remote Raspberry Pi Configuration;
• Whitelist the files to control the power to the USB ports, so they can be accessed through pigpiod:

  sudo sh -c 'cat - > /opt/pigpio/access' <<+
  /proc/cpuinfo r
  /tmp/getState.json r
  /sys/class/leds/PWR/brightness w
  /sys/bus/usb/drivers/usb/unbind w
  /sys/bus/usb/drivers/usb/bind w
  +

GPIO Devices

Homebridge RPi supports the following GPIO-connected devices:

Device	State	I/O	HomeKit Service(s)	Description
blinkt	n/a n/a n/a	out out out	Lightbulb ... Lightbulb	Pimoroni Blink! or compatible.
button	push	in	Stateless Programmable Switch	Push button.
carbonmonoxide	push	in	Carbon Monoxide Sensor	CO sensor.
contact	push	in	Contact Sensor	Contact sensor.
dht	pull	in	Temperature Sensor Humidity Sensor	DHTxx temperature/humidity sensor.
doorbell	push	in	Doorbell	Door bell.
fanshim	n/a push push	out in out	Lightbulb Stateless Programmable Switch Switch	Pimoroni FanShim.
garage	push	out	Garage Door Opener	Garage door.
leak	push	in	Leak Sensor	Water leak sensor.
light	poll	out	Lightbulb	Dimmable light (using PWM).
lock	push	out	Lock Mechanism	Lock.
motion	push	in	Motion Sensor	Motion sensor.
p9813	n/a n/a n/a	out out out	Lightbulb ... Lightbulb	Chain of P9813 LED Controllers.
servo	poll	out	Switch*	Servo motor.
smoke	push	in	Smoke Sensor	Smoke sensor.
switch	push	out	Switch	Generic on/off device.
valve	push	out	Valve	Generic valve device.

*) With added Current Tilt Angle and Target Tilt Angle characteristics.

pigpiod monitors the state of the GPIO pins, sending notifications on state changes. For the binary devices, Homebridge RPi subscribes to these notifications. Homebridge RPi polls the state of "level" devices, like light and servo. The state of devices that are controlled using a serial signal cannot be retrieved. For these devices, like the blinkt, Homebridge RPi echoes the state last set. This might not be the actual state, when other programmes change the state as well, bypassing Homebridge RPi.

Device State

For input devices, Homebridge RPi configures the corresponding GPIO pin to use the internal pull-up resistor. This is appropriate in most cases, when the GPIO is connected to ground when the sensor detects something. This means that the GPIO pin is high by default, and low on input. To reverse this logic, set reversed in config.json.
Set pull to down to configure the GPIO pin to use the internal pull-down resistor. This is appropriate when the GPIO is connected to 3.3V when the sensor detects something. Do not ever connect the GPIO to higher voltages, at the pain of frying the GPIO block on the Raspberry Pi. As now the GPIO pin is low by default, and high on input, you might need to set reversed as well.
Set pull to off to configure the GPIO pin without any internal resistor. In this case, you (i.c. your sensor) needs to provide an external pull-up or pull-down resistor, or Homebridge RPi will see the input changing continuously.

For output devices, Homebridge RPi maps the device state to off when the corresponding GPIO pin is low; and to on when the pin is high. To reverse this logic, set reversed in config.json. In this case, you might want to set the pin to high when the Raspberry Pi boots, so the device is off by default. This is best done in through GPIO Control in /boot/config.txt.