pyhomekit package

Module contents

pyhomekit.ble module

Contains all of the HAP-BLE classes.

class pyhomekit.ble.HapAccessory(address: str, address_type: str = 'static') → None

Bases: object

HAP Accesory.

Parameters:

• address – MAC address of the accessory
• address_type – Type of the address: static or random

charateristic(uuid: str) → sphinx.ext.autodoc.Characteristic

Return the GATT characteristic for the given UUID.

connect() → None

Connect to BLE peripheral.

discover_hap_characteristics() → typing.List[pyhomekit.ble.HapCharacteristic]

Discovers all of the HAP Characteristics and performs a signature read on each one.

get_characteristic(name: str, uuid: str) → pyhomekit.ble.HapCharacteristic

pair() → None

pair_verify() → None

save_key() → None

class pyhomekit.ble.HapAccessoryLock(address: str, address_type: str = 'static') → None

Bases: pyhomekit.ble.HapAccessory

administrator_only_access() → None

audio_feedback() → bytes

current_door_state() → int

lock_control_point() → typing.Any

lock_current_state() → int

lock_last_known_action() → int

lock_management_auto_security_timeout() → None

lock_target_state() → None

logs() → str

motion_detected() → bool

version() → str

class pyhomekit.ble.HapBlePdu(header: pyhomekit.ble.HapBlePduHeader, TLVs: typing.Sequence[typing.Tuple[int, bytes]]) → None

Bases: object

HAP BLE PDU

fragmented

max_len = 512

pdu_fragments() → typing.Iterator[bytes]

raw_data

class pyhomekit.ble.HapBlePduHeader(response: bool, continuation: bool) → None

Bases: object

Interface for HAP-BLE Headers.

This class is not meant to be instantiated. Use the children HapBlePduRequestHeader and HapBlePduResponseHeader.

Parameters:

• continuation – indicates the fragmentation status of the HAP-BLE PDU. False indicates a first fragment or no fragmentation.
• response – indicates whether the PDU is a response (versus a request)

control_field

Get Control Field as int.

control_field_bits

Get Control Field as string of bits.

data

class pyhomekit.ble.HapBlePduRequestHeader(cid_sid: bytes, op_code: int, response: bool = False, continuation: bool = False, transaction_id: int = None) → None

Bases: pyhomekit.ble.HapBlePduHeader

HAP-BLE PDU Request Header.

Parameters:

• continuation – indicates the fragmentation status of the HAP-BLE PDU. False indicates a first fragment or no fragmentation.
• response – indicates whether the PDU is a response (versus a request)
• transation_id – Transaction Identifier
• op_code – HAP Opcode field, which indicates the opcode for the HAP Request PDU.
• cid_sid – Characteristic / Service Instance Identifier is the instance id of the characteristic / service for a particular request.

data

Byte representation of the PDU Header.

Depends on whether it is a continuation header or not.

transaction_id

Get the transaction identifier, or generate a new one if none exists.

The transation ID is an 8 bit number identifying the transaction number of this PDU. The TID is randomly generated by the originator of the request and is used to match a request/response pair.

class pyhomekit.ble.HapBlePduResponseHeader(status_code: int, transaction_id: int, continuation: bool = False, response: bool = True) → None

Bases: pyhomekit.ble.HapBlePduHeader

HAP-BLE PDU Response Header.

Parameters:

• continuation – indicates the fragmentation status of the HAP-BLE PDU. False indicates a first fragment or no fragmentation.
• response – indicates whether the PDU is a response (versus a request)
• transaction_id – Transaction Identifier
• status_code – HAP Status code for the request.

data

Byte representation of the PDU Header.

classmethod from_data(data: bytes) → pyhomekit.ble.HapBlePduResponseHeader

Creates a header from response bytes

class pyhomekit.ble.HapCharacteristic(accessory: pyhomekit.ble.HapAccessory, uuid: str, retry: bool = False, retry_max_attempts: int = 1, retry_wait_time: int = 2) → None

Bases: object

Represents data or an associated behavior of a service.

The characteristic is defined by a universally unique type, and has additional properties that determine how the value of the characteristic can be accessed.

Parameters:

• accessory – The accessory this characteristic belongs to.
• uuid – The UUID of the underlying GATT characteristic
• retry – Attempt to reconnect when error.
• retry_max_attempts – How many times to attempt reconnection.
• retry_wait_time – How long to wait in s between reconnection attempts.

cid

Get the Characteristic ID, reading it from the device if required.

read(request_header: pyhomekit.ble.HapBlePduRequestHeader) → typing.Dict[str, typing.Any]

Perform a HAP Characteristic read.

Fragmented read if required.

signature

Returns the signature, and adds the attributes.

write(request_header: pyhomekit.ble.HapBlePduRequestHeader, TLVs: typing.List[typing.Tuple[int, bytes]]) → typing.Dict[str, typing.Any]

Perform a HAP Characteristic write.

Fragmented read/write if required.

write_ktlvs(request_header: pyhomekit.ble.HapBlePduRequestHeader, kTLVs: typing.Sequence[typing.Tuple[int, bytes]]) → typing.Dict[str, typing.Any]

Perform a HAP Characteristic write for a pairing.

Fragmented read/write if required.

pyhomekit.ble.fragment_tlvs(header: pyhomekit.ble.HapBlePduRequestHeader, TLVs: typing.List[typing.Tuple[int, bytes]]) → typing.Iterator[bytes]

Returns the fragmented TLVs to write.

pyhomekit.ble.reconnect_callback_factory(accessory: pyhomekit.ble.HapAccessory) → typing.Callable[[typing.Any, int], NoneType]

Factory for creating tenacity before callbacks to reconnect to a peripheral.

pyhomekit.ble.reconnect_tenacity_retry(reconnect_callback: typing.Callable[[typing.Any, int], typing.Any], max_attempts: int = 2, wait_time: int = 2) → tenacity.Retrying

Build tenacity retry object

pyhomekit.constants module

HAP Constants

class pyhomekit.constants.HapBleOpCodes

Bases: object

HAP Opcode Descriptions.

Characteristic_Execute_Write = 5

Characteristic_Read = 3

Characteristic_Signature_Read = 1

Characteristic_Timed_Write = 4

Characteristic_Write = 2

Service_Signature_Read = 6

class pyhomekit.constants.HapBleStatusCodes

Bases: object

HAP Status code definitions and descriptions.

Insufficient_Authentication = 5

Insufficient_Authorization = 3

Invalid_Instance_ID = 4

Invalid_Request = 6

Max_Procedures = 2

Success = 0

Unsupported_PDU = 1

class pyhomekit.constants.HapParamTypes

Bases: object

Additional_Authorization_Data = 2

Characteristic_Instance_ID = 5

Characteristic_Type = 4

GATT_Presentation_Format_Descriptor = 12

GATT_User_Description_Descriptor = 11

GATT_Valid_Range = 13

HAP_Characteristic_Properties_Descriptor = 10

HAP_Linked_Services = 16

HAP_Service_Properties = 15

HAP_Step_Value_Descriptor = 14

HAP_Valid_Values_Descriptor = 17

HAP_Valid_Values_Range_Descriptor = 18

Origin_local_vs_remote = 3

Return_Response = 9

Service_Instance_ID = 7

Service_Type = 6

TTL = 8

Value = 1

class pyhomekit.constants.PairingKTLVErrorCodes

Bases: object

kTLVError_Authenticatio = 2

kTLVError_Backof = 3

kTLVError_Bus = 7

kTLVError_MaxPeer = 4

kTLVError_MaxTrie = 5

kTLVError_Unavailabl = 6

kTLVError_Unknow = 1

class pyhomekit.constants.PairingKTLVMethodValues

Bases: object

Pairing service kTLV method values

Add_Pairing = 3

List_Pairings = 5

Pair_Setup = 1

Pair_Verify = 2

Remove_Pairing = 4

Reserved = 0

class pyhomekit.constants.PairingKTlvValues

Bases: object

Pairng service TLV Values.

kTLVType_Certificate = 9

kTLVType_EncryptedData = 5

kTLVType_Error = 7

kTLVType_FragmentData = 12

kTLVType_FragmentLast = 13

kTLVType_Identifier = 1

kTLVType_Method = 0

kTLVType_Permissions = 11

kTLVType_Proof = 4

kTLVType_PublicKey = 3

kTLVType_RetryDelay = 8

kTLVType_Salt = 2

kTLVType_Separator = 255

kTLVType_Signature = 10

kTLVType_State = 6

pyhomekit.constants.identity(x: typing.Any) → typing.Any

Identity

pyhomekit.constants.parse_format(b: bytes) → typing.Tuple[int, int]

Parse the bluetooth characteristic presentation format to format and unit code

pyhomekit.constants.to_bool(b: bytes) → bool

Convert to bytes to bool (little endian).

pyhomekit.constants.to_float(b: bytes) → int

Convert to bytes to float (little endian).

pyhomekit.constants.to_int32(b: bytes) → int

Convert to bytes to 32 bit signed int (little endian).

pyhomekit.constants.to_uint16(b: bytes) → int

Convert to bytes to 16 bit unsigned short (little endian).

pyhomekit.constants.to_uint32(b: bytes) → int

Convert to bytes to 32 bit unsigned int (little endian).

pyhomekit.constants.to_uint64(b: bytes) → int

Convert to bytes to 64 bit unsigned int (little endian).

pyhomekit.constants.to_uint8(b: bytes) → int

Convert to bytes to 8 bit unsigned short (little endian).

pyhomekit.constants.to_utf8(b: bytes) → str

Convert bytes to str utf-8 encoded.

pyhomekit.constants.to_uuid(b: bytes) → str

Convert bytes to string representation of uuid.

The bytes are reversed first.

pyhomekit.utils module

Utility functions for BLE

exception pyhomekit.utils.HapBleError(status_code: int = None, name: str = None, message: str = None, *args: str) → None

Bases: Exception

HAP Error.

pyhomekit.utils.iterate_tvl(response: bytes) → typing.Iterator[typing.Tuple[int, int, bytes]]

Iterate through response bytes, 1 tlv at a time.

pyhomekit.utils.parse_ktlvs(data: bytes) → typing.Dict[str, typing.Any]

Parse ktlvs.

pyhomekit.utils.prepare_tlv(param_type: int, value: bytes) → typing.Iterator[bytes]

Formats the TLV into the expected format of the PDU.

Parameters:

• param_type – The name or code for the HAP Parameter type
• value – The value in bytes of the parameter.