pub struct BleAccessory { /* private fields */ }Expand description
A connected BLE accessory: holds the GATT link, the secure session, the cached attribute database, and a map from (aid, iid) to GATT characteristic UUID for issuing PDUs.
Implementations§
Source§impl BleAccessory
impl BleAccessory
Sourcepub fn accessories(&self) -> &[Accessory]
pub fn accessories(&self) -> &[Accessory]
The cached attribute database.
Sourcepub async fn broadcast_state(&self) -> BleBroadcastState
pub async fn broadcast_state(&self) -> BleBroadcastState
The current persistable broadcast material (key + latest GSN). Persist
this so a later connect can resume broadcast decryption.
Sourcepub fn find(
&self,
svc: ServiceType,
chr: CharacteristicType,
) -> Result<(u64, u64)>
pub fn find( &self, svc: ServiceType, chr: CharacteristicType, ) -> Result<(u64, u64)>
Find the (aid, iid) of a characteristic by service + characteristic
type.
§Errors
BleError::CharacteristicNotFound if no match exists.
Sourcepub async fn read(&mut self, aid: u64, iid: u64) -> Result<CharValue>
pub async fn read(&mut self, aid: u64, iid: u64) -> Result<CharValue>
Read a characteristic value, decoded to its declared format.
§Errors
BleError::CharacteristicNotFound if unknown; otherwise GATT/PDU/crypto.
Sourcepub async fn remove_pairing(&mut self, controller_id: &str) -> Result<()>
pub async fn remove_pairing(&mut self, controller_id: &str) -> Result<()>
Remove a pairing by controller pairing id. Pass this controller’s own id to un-pair this controller; pass another controller’s id (this session must hold admin permission) to remove that one.
Runs as an encrypted RemovePairing (State M1, Method 4) write to the accessory’s Pairing-Pairings characteristic; a reconnect-invalidated session is re-verified first.
Removing this controller’s own pairing is a special case: the accessory removes the pairing and tears down the secure session as part of the same operation, so the encrypted M2 response is frequently lost or undecryptable (the link drops, or the reply is no longer sealed under the now-defunct session). Per the HAP self-removal semantics, once the request has been written the removal has taken effect, so a transport/crypto failure reading the response on self-removal is reported as success.
§Errors
BleError::PairingRejected if the accessory rejects the request (PDU
status or a kTLVType_Error in the M2 reply); otherwise GATT/PDU/crypto
errors (except the tolerated self-removal teardown described above).
Sourcepub async fn write(
&mut self,
aid: u64,
iid: u64,
value: CharValue,
) -> Result<()>
pub async fn write( &mut self, aid: u64, iid: u64, value: CharValue, ) -> Result<()>
Write a characteristic value, encoded per its declared format, over the
encrypted session (re-verified after a reconnect, like Self::read).
§Errors
BleError::CharacteristicNotFound if unknown;
BleError::RequestRejected if the accessory returns a non-zero PDU
status; BleError::MalformedPdu if value does not match the
characteristic’s format; otherwise GATT/crypto errors.
Sourcepub async fn thread_provision(&mut self, dataset: &ThreadDataset) -> Result<()>
pub async fn thread_provision(&mut self, dataset: &ThreadDataset) -> Result<()>
Commission this accessory onto the Thread network described by dataset.
HomeKit Thread accessories receive their Thread credentials over HAP-BLE
rather than a joiner flow: over the established secure session this writes
a query and then the operational dataset to the accessory’s Thread
Control Point characteristic (0x0704). After it succeeds the accessory
joins that Thread network and becomes reachable over Thread (e.g. via
hap-thread).
The accessory typically drops the BLE link as it switches networks, so a
transport error on the provision write is expected and treated as
success (mirroring aiohomekit); confirm the outcome by the device
appearing on the mesh, not by this call’s result. The dataset carries a
secret network key — see ThreadDataset, whose
Debug redacts it.
§Errors
BleError::CharacteristicNotFound if the accessory exposes no Thread
Control Point (not a Thread accessory); otherwise a GATT/PDU/crypto error
from the initial query write.
Sourcepub fn pairing_id(&self) -> &str
pub fn pairing_id(&self) -> &str
The accessory’s HAP pairing id (as stored in the pairing record).
Sourcepub async fn enable_broadcasts(&mut self, iids: &[u64]) -> Result<()>
pub async fn enable_broadcasts(&mut self, iids: &[u64]) -> Result<()>
Enable encrypted broadcast notifications for the given characteristic
instance ids (the HAP BLE accessory id is always 1). Each is an encrypted
Characteristic-Configuration write (Properties + Broadcast-Interval). Call
this while connected, before disconnecting to receive sleepy events —
without it the accessory will not emit 0x11 encrypted broadcasts. A
characteristic that does not support broadcasts is skipped; per-write
failures are tolerated (best-effort).
§Errors
Propagates a session re-verify failure.
Sourcepub async fn disconnect(&self)
pub async fn disconnect(&self)
Release the underlying link (so the sleepy accessory advertises again). A no-op on backends without a live link.
Sourcepub async fn subscribe(&mut self, aid: u64, iid: u64) -> Result<()>
pub async fn subscribe(&mut self, aid: u64, iid: u64) -> Result<()>
Subscribe to value-change events for a characteristic. HAP-BLE connected
events use the GATT notification only as a trigger: when it fires we
issue an encrypted Characteristic-Read for the new value and publish it
on BleAccessory::events.
§Errors
BleError::CharacteristicNotFound if unknown; otherwise GATT errors.
Connected events are best-effort: if the link drops, this GATT
subscription ends and is not re-armed (re-arming a sleepy device storms).
Durable updates arrive via BleAccessory::events from the broadcast and
disconnected-event channels.
Sourcepub async fn watch_sleepy_events_with_source(
&mut self,
advert_source: Arc<dyn AdvertSource>,
device_id: [u8; 6],
poll_iids: Vec<(u64, u64)>,
) -> Result<()>
pub async fn watch_sleepy_events_with_source( &mut self, advert_source: Arc<dyn AdvertSource>, device_id: [u8; 6], poll_iids: Vec<(u64, u64)>, ) -> Result<()>
Watch advertisements and deliver disconnected-event updates. Two paths:
- Regular (0x06) advertisements: when the accessory’s GSN bumps, read
each polled characteristic and publish its value on
BleAccessory::events. Events are deduplicated by(iid, gsn). The poll runs on its own task fed by a watch channel, so bumps coalesce. - Encrypted broadcast (0x11) advertisements: decrypt the value directly
from the advertisement using the stored
hap_crypto::BroadcastKeyand publish it — no GATT connection needed.
The advert source is supplied by the caller (the same backend object that provides the GATT connection).
§Errors
BleError if the advert source cannot start.
Sourcepub fn set_advert_source(&mut self, src: Arc<dyn AdvertSource>)
pub fn set_advert_source(&mut self, src: Arc<dyn AdvertSource>)
Provide the advert source (the connection) so the self-sourcing
watch_sleepy_events can use it.
Sourcepub async fn watch_sleepy_events(
&mut self,
poll_iids: Vec<(u64, u64)>,
) -> Result<()>
pub async fn watch_sleepy_events( &mut self, poll_iids: Vec<(u64, u64)>, ) -> Result<()>
Watch for sleepy-device events, self-sourcing the advert source (set via
set_advert_source) and the device id (from
the pairing id). Arms the same machinery as
watch_sleepy_events_with_source.
§Errors
BleError::NoAdvertSource if no source was set; BleError::Backend
if the stored pairing id cannot be parsed as a device id; otherwise
advert/GATT errors.
Sourcepub fn events(&self) -> impl Stream<Item = CharacteristicEvent>
pub fn events(&self) -> impl Stream<Item = CharacteristicEvent>
An async stream of characteristic events. Each call returns a fresh subscriber to the shared event channel.