AccessoryDriver

Accessory Driver class to host an Accessory.

class pyhap.accessory_driver.AccessoryDriver(*, address=None, port=51234, persist_file='accessory.state', pincode=None, encoder=None, loader=None, loop=None, mac=None, listen_address=None, advertised_address=None, interface_choice=None, async_zeroconf_instance=None, zeroconf_server=None)

An AccessoryDriver mediates between incoming requests from the HAPServer and the Accessory.

The driver starts and stops the HAPServer, the mDNS advertisements and responds to events from the HAPServer.

accessories_hash

Hash the get_accessories response to track configuration changes.

add_accessory(accessory)

Add top level accessory to driver.

add_job(target, *args)

Add job to executor pool.

async_add_job(target, *args)

Add job from within the event loop.

async_persist()

Saves the state of the accessory.

Must be run in the event loop.

async_send_event(topic, data, sender_client_addr, immediate)

Send an event to a client.

Must be called in the event loop

async_start()

Starts the accessory.

• Call the accessory’s run method.
• Start handling accessory events.
• Start the HAP server.
• Publish a mDNS advertisement.
• Print the setup QR code if the accessory is not paired.

All of the above are started in separate threads. Accessory thread is set as daemon.

async_stop()

Stops the AccessoryDriver and shutdown all remaining tasks.

async_subscribe_client_topic(client, topic, subscribe=True)

(Un)Subscribe the given client from the given topic.

This method must be run in the event loop.

Parameters:

• client (tuple <str, int>) – A client (address, port) tuple that should be subscribed.
• topic (str) – The topic to which to subscribe.
• subscribe (bool) – Whether to subscribe or unsubscribe the client. Both subscribing an already subscribed client and unsubscribing a client that is not subscribed do nothing.

async_update_advertisement()

Updates the mDNS service info for the accessory from the event loop.

config_changed()

Notify the driver that the accessory’s configuration has changed.

Persists the accessory, so that the new configuration is available on restart. Also, updates the mDNS advertisement, so that iOS clients know they need to fetch new data.

connection_lost(client)

Called when a connection is lost to a client.

This method must be run in the event loop.

Parameters:client (tuple <str, int>) – A client (address, port) tuple that should be unsubscribed.

finish_pair()

Finishing pairing or unpairing.

Updates the accessory and updates the mDNS service.

The mDNS announcement must not be updated until AFTER the final pairing response is sent or homekit will see that the accessory is already paired and assume it should stop pairing.

get_accessories()

Returns the accessory in HAP format.

Returns:An example HAP representation is:

{
   "accessories": [
      "aid": 1,
      "services": [
         "iid": 1,
         "type": ...,
         "characteristics": [{
            "iid": 2,
            "type": ...,
            "description": "CurrentTemperature",
            ...
         }]
      ]
   ]
}

Return type:dict

get_characteristics(char_ids)

Returns values for the required characteristics.

Parameters:char_ids (list<str>) – A list of characteristic “paths”, e.g. “1.2” is aid 1, iid 2. Returns:Status success for each required characteristic. For example:

{
   "characteristics: [{
      "aid": 1,
      "iid": 2,
      "status" 0
   }]
}

Return type:dict

load()

Load the persist file.

Must run in executor.

pair(client_username_bytes: bytes, client_public: bytes, client_permissions: bytes) → bool

Called when a client has paired with the accessory.

Persist the new accessory state.

Parameters:

• client_username_bytes (bytes) – The client username bytes.
• client_public (bytes) – The client’s public key.
• client_permissions (bytes (int)) – The client’s permissions.

Returns:

Whether the pairing is successful.

Return type:

bool

persist()

Saves the state of the accessory.

Must run in executor.

prepare(prepare_query, client_addr)

Called from HAPServerHandler when iOS wants to prepare a write.

Parameters:prepare_query – A prepare query. For example:

{
   "ttl": 10000, # in milliseconds
   "pid": 12345678,
}

publish(data, sender_client_addr=None, immediate=False)

Publishes an event to the client.

The publishing occurs only if the current client is subscribed to the topic for the aid and iid contained in the data.

Parameters:data (dict) – The data to publish. It must at least contain the keys “aid” and “iid”.

set_characteristics(chars_query, client_addr)

Called from HAPServerHandler when iOS configures the characteristics.

Parameters:chars_query – A configuration query. For example:

{
   "characteristics": [{
      "aid": 1,
      "iid": 2,
      "value": False, # Value to set
      "ev": True # (Un)subscribe for events from this characteristics.
   }]
}

setup_srp_verifier()

Create an SRP verifier for the accessory’s info.

signal_handler(_signal, _frame)

Stops the AccessoryDriver for a given signal.

An AccessoryDriver can be registered as a signal handler with this method. For example, you can register it for a KeyboardInterrupt as follows: >>> import signal >>> signal.signal(signal.SIGINT, anAccDriver.signal_handler)

Now, when the user hits Ctrl+C, the driver will stop its accessory, the HAP server and everything else that needs stopping and will exit gracefully.

start()

Start the event loop and call start_service.

Pyhap will be stopped gracefully on a KeyBoardInterrupt.

start_service()

Start the service.

stop()

Method to stop pyhap.

unpair(client_uuid)

Removes the paired client from the accessory.

Persist the new accessory state.

Parameters:client_uuid (uuid.UUID) – The client uuid.

update_advertisement()

Updates the mDNS service info for the accessory.