HAP-python Documentation

When multiple characteristics are updated together (e.g., 'On' and 'Brightness' for a lightbulb), using individual characteristic callbacks can cause race conditions or redundant updates.

To handle these as a single atomic request, use a Service Callback. Instead of setting callbacks on individual characteristics, set the setter_callback on the Service itself. The callback receives a dictionary of all changed characteristic values.

from pyhap.accessory import Accessory
from pyhap.const import Category

class Light(Accessory):
    category = Category.CATEGORY_LIGHTBULB

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        
        serv_light = self.add_preload_service('Lightbulb')
        # Configure characteristics
        self.char_on = serv_light.configure_char('On', value=False)
        self.char_brightness = serv_light.configure_char('Brightness', value=100)

        # Set the callback on the SERVICE, not the characteristic
        serv_light.setter_callback = self._set_chars

    def _set_chars(self, char_values):
        # char_values is a dict containing all changed keys
        if "On" in char_values:
            print('On changed to: ', char_values["On"])
        if "Brightness" in char_values:
            print('Brightness changed to: ', char_values["Brightness"])

    @Accessory.run_at_interval(3)
    def run(self):
        import random
        self.char_on.set_value(random.randint(0, 1))
        self.char_brightness.set_value(random.randint(1, 100))

    def stop(self):
        print('Stopping accessory.')

The Camera accessory handles HomeKit stream negotiation. By default, HAP-python uses ffmpeg to manage streams via the Camera.FFMPEG_CMD command.

Customizing the Stream Command

If the default ffmpeg command doesn't work for your platform, you can provide a custom command via the options dictionary passed to the Camera constructor using the start_stream_cmd key.

Variables like {width}, {height}, and {audio_channels} can be used in your command string and will be replaced by the negotiated values.

Example: start_stream_cmd: 'foo start -width {width}' becomes foo start -width 640.

Implementing Custom Stream Logic

For maximum control, override these Camera methods:

• start(self, width, height, audio_channels, ...): Called when the stream starts.
• stop(self): Called when the stream stops.
• reconfigure(self, width, height, ...): Called when stream parameters change.
• snapshot(self): Override this to provide custom logic for taking snapshots (the default returns a stock photo).

# Example of passing a custom command via options
# options = {'start_stream_cmd': 'my_custom_tool --w {width} --h {height}'}
# camera = Camera(options=options, ...)

To run HAP-python as a background daemon that starts automatically on boot, create a systemd service file at /etc/systemd/system/HAP-python.service.

Prerequisites:

• It is recommended to enable "Wait for network" in raspi-config to ensure network services are available.
• If your implementation depends on pigpiod, include it in the Wants and After directives. Otherwise, remove it.
• Use an unprivileged system user (e.g., lesserdaemon) for the User directive for better security.
• Ensure all paths in ExecStart (for the Python interpreter and your script) and any paths used for state persistence are absolute and correct.

Service Management Commands:

• Start the service: sudo systemctl start HAP-python
• Check status: systemctl status HAP-python
• View logs: sudo journalctl -u HAP-python
• Stop the service: sudo systemctl stop HAP-python
• Enable auto-start at boot: sudo systemctl enable HAP-python
• Disable auto-start at boot: sudo systemctl disable HAP-python

[Unit]
Description = HAP-python daemon
Wants = pigpiod.service
After = local-fs.target network-online.target pigpiod.service

[Service]
User = lesserdaemon
ExecStart = /usr/bin/python3 /home/lesserdaemon/.hap-python/hap-python.py

[Install]
WantedBy = multi-user.target

You can share custom device implementations as subpackages of pyhap.accessories using native Python namespace packages. This allows your accessory to be imported under the pyhap.accessories.<your_accessory> namespace without requiring __init__.py files in the parent pyhap or accessories directories.

Directory Structure

Ensure your project follows this structure (note the absence of __init__.py in the parent directories):

pyhap/
    # NO __init__.py here !!!
    accessories/
        # NO __init__.py here !!!
        bulb/
            __init__.py
            ... the code for the bulb accessory ...

Packaging with setup.py

In your setup.py file, explicitly include the specific subpackage path in the packages list:

setup(
    ...
    packages=['pyhap.accessories.bulb'],
    ...
)

Installation and Usage

Users can install your accessory via pip (if uploaded) or by cloning the repository:

# Via pip
pip install HAP-python-bulb

# Or via git clone
git clone <repository_url>
python3 setup.py install

Once installed, the accessory can be used in Python code via:

import pyhap.accessories.bulb