hap-controller/lib/transport/ble/gatt-client.d.ts

Library to implement a HAP (HomeKit) controller

/**
 * Controller class for interacting with a HAP device over GATT.
 */
import * as Characteristic from '../../model/characteristic';
import { EventEmitter } from 'events';
import GattConnection from './gatt-connection';
import { PairingData } from '../../protocol/pairing-protocol';
import { TLV } from '../../model/tlv';
import { Characteristic as NobleCharacteristic, Peripheral as NoblePeripheral } from '@stoprocent/noble';
import { Accessories } from '../../model/accessory';
export interface GetCharacteristicsOptions {
    meta?: boolean;
    perms?: boolean;
    type?: boolean;
    ev?: boolean;
    extra?: boolean;
}
interface GattSubscriptionCharacteristicData {
    characteristicUuid: string;
    serviceUuid: string;
    iid: number;
    format: string;
}
export default class GattClient extends EventEmitter {
    deviceId: string;
    private peripheral;
    private pairingProtocol;
    private gattProtocol;
    private tid;
    private queue;
    private pairingQueue;
    private _pairingConnection?;
    private subscriptionConnection?;
    private subscribedCharacteristics;
    /**
     * Initialize the GattClient object.
     *
     * @param {string} deviceId - ID of the device
     * @param {NoblePeripheral} peripheral - Peripheral object from noble
     * @param {PairingData?} pairingData - existing pairing data
     */
    constructor(deviceId: string, peripheral: NoblePeripheral, pairingData?: PairingData);
    /**
     * Queue an operation for the client.
     *
     * @param {function} op - Function to add to the queue
     * @returns {Promise} Promise which resolves when the function is called.
     */
    private _queueOperation;
    /**
     * Queue an operation for the pairing.
     *
     * @param {function} op - Function to add to the queue
     * @returns {Promise} Promise which resolves when the function is called.
     */
    private _queuePairingOperation;
    /**
     * Get the next transaction ID.
     *
     * @returns {number} Transaction ID.
     */
    getNextTransactionId(): number;
    /**
     * Get the data (keys) that needs to be stored long-term.
     *
     * @returns {PairingData} Object containing the keys that should be stored.
     */
    getLongTermData(): PairingData | null;
    /**
     * Verify the provided PIN
     *
     * @param pin {string} PIN
     */
    verifyPin(pin: string): void;
    /**
     * Run the identify routine on a device.
     *
     * @returns {Promise} Promise which resolves if identify succeeded.
     */
    identify(): Promise<void>;
    /**
     * Read the instance ID descriptor for a characteristic. The peripheral must
     * already be connected.
     *
     * @param {Object} characteristic - The characteristic to read from
     * @returns {Promise} Promise which resolves to the IID.
     */
    private _readInstanceId;
    getPairingMethod(): Promise<number>;
    /**
     * Begins the pairing process. For devices with random pins, this
     * will cause it to show the pin on the screen.
     *
     * @param {PairMethods} [pairMethod] - Method to use for pairing, default is PairSetupWithAuth
     * @param {PairingTypeFlags} [pairFlags] - Flags to use for Pairing for PairSetup
     *                                         * No provided flags is equivalent to providing
     *                                           kPairingFlag_Transient and kPairingFlag_Split and in this case a new
     *                                           code is generated randomly by the device (if supported) or the
     *                                           pre-defined code is used
     *                                         * If only the flag kPairingFlag_Split is provided the code which
     *                                           was created on the device from last transient+split call is reused
     *                                           and needs to be provided in finishPairing by user of this library
     *                                         * If only the flag kPairingFlag_Transient is provided the session
     *                                           security is enabled but no final pairing is done
     * @returns {Promise} Promise which resolves to opaque
     * pairing data when complete.
     */
    startPairing(pairMethod?: number, pairFlags?: number): Promise<{
        tlv: TLV;
        iid: number;
        characteristic: NobleCharacteristic;
    }>;
    /**
     * Finishes a pairing process that began with startPairing()
     *
     * @param {PairingData} pairingData - The pairing data returned from startPairing()
     * @param {string} pin - The pairing PIN, needs to be formatted as XXX-XX-XXX
     * @returns {Promise} Promise which resolves when pairing is complete.
     */
    finishPairing(pairingData: {
        tlv: TLV;
        iid: number;
        characteristic: NobleCharacteristic;
    }, pin: string): Promise<void>;
    /**
     * Attempt to pair with a device.
     *
     * @param {string} pin - The pairing PIN, needs to be formatted as XXX-XX-XXX
     * @param {PairMethods} [pairMethod] - Method to use for pairing, default is PairSetupWithAuth
     * @param {PairingTypeFlags} [pairFlags] - Flags to use for Pairing for PairSetup
     * @returns {Promise} Promise which resolves when pairing is complete.
     */
    pairSetup(pin: string, pairMethod?: number, pairFlags?: number): Promise<void>;
    /**
     * Method used internally to generate session keys for a connection.
     *
     * @private
     * @param {GattConnection} connection - Existing GattConnection object
     * @returns {Promise} Promise which resolves when the pairing has been verified.
     */
    private _pairVerify;
    /**
     * Unpair the controller from a device.
     *
     * @param {string|Buffer} identifier - Identifier of the controller to remove
     * @returns {Promise} Promise which resolves when the process completes.
     */
    removePairing(identifier: string | Buffer): Promise<void>;
    /**
     * Add a pairing to a device.
     *
     * @param {string} identifier - Identifier of new controller
     * @param {Buffer} ltpk - Long-term public key of the new controller
     * @param {boolean} isAdmin - Whether or not the new controller is an admin
     * @returns {Promise} Promise which resolves when the process is complete.
     */
    addPairing(identifier: string, ltpk: Buffer, isAdmin: boolean): Promise<void>;
    /**
     * List the pairings on a device.
     *
     * @returns {Promise} Promise which resolves to the final TLV when the process
     *                    is complete.
     */
    listPairings(): Promise<TLV>;
    /**
     * Get the accessory attribute database from a device.
     *
     * @returns {Promise} Promise which resolves to the JSON document.
     */
    getAccessories(): Promise<Accessories>;
    /**
     * Read a set of characteristics.
     *
     * @param {Object[]} characteristics - Characteristics to get, as a list of
     *                   objects: {characteristicUuid, serviceUuid, iid, format}
     * @param {Object?} options - Options dictating what metadata to fetch
     * @param {Object?} connection - Existing GattConnection object, must already
     *                  be paired and verified
     * @returns {Promise} Promise which resolves to the JSON document.
     */
    getCharacteristics(characteristics: {
        characteristicUuid: string;
        serviceUuid: string;
        iid: number;
        format?: string;
    }[], options?: GetCharacteristicsOptions, connection?: GattConnection | null): Promise<{
        characteristics: Characteristic.CharacteristicObject[];
    }>;
    /**
     * Modify a set of characteristics.
     *
     * @param {Object[]} values - Characteristics to set, as a list of objects:
     *                   {characteristicUuid, serviceUuid, iid, value}
     * @returns {Promise} Promise which resolves when the characteristics have been set.
     */
    setCharacteristics(values: {
        characteristicUuid: string;
        serviceUuid: string;
        iid: number;
        value: unknown;
    }[]): Promise<void>;
    /**
     * Subscribe to events for a set of characteristics.
     *
     * @fires HttpClient#event
     * @fires HttpClient#event-disconnect
     * @param {Object[]} characteristics - Characteristics to subscribe to, as a
     *                   list of objects:
     *                   {characteristicUuid, serviceUuid, iid, format}
     * @returns {Promise} Promise which resolves to the GattConnection object.
     */
    subscribeCharacteristics(characteristics: GattSubscriptionCharacteristicData[]): Promise<void>;
    /**
     * Get the list of subscribed characteristics
     *
     * @returns {Object[]} Array with subscribed entries as objects with characteristics and service UUIDs and such
     */
    getSubscribedCharacteristics(): {
        characteristicUuid: string;
        serviceUuid: string;
        iid: number;
        format: string;
    }[];
    /**
     * Unsubscribe from events for a set of characteristics.
     *
     * @param {Object[]} characteristics - Characteristics to unsubscribe from, as
     *                   a list of objects: {characteristicUuid, serviceUuid},
     *                   if ommited all currently subscribed characteristics will be unsubscribed
     * @returns {Promise} Promise which resolves when the procedure is done.
     */
    unsubscribeCharacteristics(characteristics?: {
        characteristicUuid: string;
        serviceUuid: string;
    }[]): Promise<void>;
    /**
     * Close all potential still open connections
     *
     * @returns {Promise<void>} Promise when done
     */
    close(): Promise<void>;
}
export {};
//# sourceMappingURL=gatt-client.d.ts.map