nativescript-bluetooth/bluetooth.common.d.ts

Connect to and interact with Bluetooth LE peripherals

import Observable from 'nativescript-observable';
import { BaseError } from 'make-error';
export declare class BluetoothUtil {
    static debug: boolean;
}
export declare enum CLogTypes {
    info = 0,
    warning = 1,
    error = 2
}
export declare class BluetoothError extends BaseError {
    arguments?: any;
    method?: string;
    status?: number;
    constructor(message: string, properties?: {
        [k: string]: any;
    });
    toString(): string;
}
export declare const CLog: (type?: CLogTypes, ...args: any[]) => void;
export declare function bluetoothEnabled(target: Object, propertyKey: string, descriptor: TypedPropertyDescriptor<any>): TypedPropertyDescriptor<any>;
export declare function prepareArgs(target: Object, propertyKey: string, descriptor: TypedPropertyDescriptor<any>): TypedPropertyDescriptor<any>;
export declare abstract class BluetoothCommon extends Observable {
    set debug(value: boolean);
    static msg_not_enabled: string;
    static msg_not_supported: string;
    static msg_cant_open_settings: string;
    static msg_missing_parameter: string;
    static msg_no_peripheral: string;
    static msg_no_service: string;
    static msg_no_characteristic: string;
    static msg_peripheral_not_connected: string;
    static msg_peripheral_disconnected: string;
    static msg_invalid_value: string;
    static msg_error_function_call: string;
    static msg_characteristic_cant_notify: string;
    static UUIDKey: string;
    static serviceUUIDKey: string;
    static peripheralUUIDKey: string;
    static characteristicUUIDKey: string;
    static bluetooth_status_event: string;
    static device_connected_event: string;
    static device_disconnected_event: string;
    static device_discovered_event: string;
    events: any;
    abstract isBluetoothEnabled(): Promise<boolean>;
    isGPSEnabled(): Promise<boolean>;
    enableGPS(): Promise<void>;
    requestLocationPermission(): Promise<boolean>;
    hasLocationPermission(): Promise<boolean>;
    /**
     * Notify events by name and optionally pass data
     */
    sendEvent(eventName: string, data?: any, msg?: string): void;
    abstract discoverServices(args: DiscoverServicesOptions): any;
    abstract discoverCharacteristics(args: DiscoverCharacteristicsOptions): any;
    discoverAll(args: DiscoverOptions): Promise<{
        services: Service[];
    }>;
    stop(): void;
}
export declare enum ScanMode {
    LOW_LATENCY = 0,
    BALANCED = 1,
    LOW_POWER = 2,
    OPPORTUNISTIC = 3
}
export declare enum MatchMode {
    AGGRESSIVE = 0,
    STICKY = 1
}
export declare enum MatchNum {
    MAX_ADVERTISEMENT = 0,
    FEW_ADVERTISEMENT = 1,
    ONE_ADVERTISEMENT = 2
}
export declare enum CallbackType {
    ALL_MATCHES = 0,
    FIRST_MATCH = 1,
    MATCH_LOST = 2
}
export declare enum Phy {
    LE_1M = 0,
    LE_CODED = 1,
    LE_ALL_SUPPORTED = 2
}
export declare type ConnectionState = 'connected' | 'connecting' | 'disconnected';
/**
 * The options object passed into the startScanning function.
 */
export interface StartScanningOptions {
    /**
     * Zero or more services which the peripheral needs to broadcast.
     * Default: [], which matches any peripheral.
     */
    filters?: {
        serviceUUID?: string;
        deviceName?: string;
        deviceAddress?: string;
        manufacturerData?: ArrayBuffer;
    }[];
    /**
     * The number of seconds to scan for services.
     * Default: unlimited, which is not really recommended. You should stop scanning manually by calling 'stopScanning'.
     */
    seconds?: number;
    /**
     * This callback is invoked when a peripheral is found.
     */
    onDiscovered?: (data: Peripheral) => void;
    /**
     * *** ANDROID ONLY ***
     * Set this to true if you don't want the plugin to check (and request) the required Bluetooth permissions.
     * Particularly useful if you're running this function on a non-UI thread (ie. a Worker).
     */
    skipPermissionCheck?: boolean;
    /**
     * Android scanning specific options. The defaults should cover majority of use cases. Be sure to check documentation for the various values for Android Bluetooth.
     */
    android?: {
        /**
         * *** Only available on Android 21+ ***
         * The scan mode can be one of android.bluetooth.le.ScanSettings.SCAN_MODE_LOW_POWER (0),
         * android.bluetooth.le.ScanSettings.SCAN_MODE_BALANCED (1) ,
         * or android.bluetooth.le.ScanSettings.SCAN_MODE_LOW_LATENCY (2).
         * DEFAULT: SCAN_MODE_LOW_LATENCY (2)
         */
        scanMode?: ScanMode;
        /**
         * *** Only available on Android 23+ ***
         * The match mode can be one of android.bluetooth.le.ScanSettings.MATCH_MODE_AGGRESSIVE (1)
         * or android.bluetooth.le.ScanSettings.MATCH_MODE_STICKY (2)
         * DEFAULT: MATCH_MODE_AGGRESSIVE (2).
         */
        matchMode?: MatchMode;
        /**
         * *** Only available on Android 23+ ***
         * The num of matches can be one of android.bluetooth.le.ScanSettings.MATCH_NUM_ONE_ADVERTISEMENT (1),
         *  android.bluetooth.le.ScanSettings.MATCH_NUM_FEW_ADVERTISEMENT (2),
         * or android.bluetooth.le.ScanSettings.MATCH_NUM_MAX_ADVERTISEMENT (3)
         * DEFAULT: MATCH_NUM_MAX_ADVERTISEMENT(3)
         */
        matchNum?: MatchNum;
        /**
         * *** Only available on Android 23+ ***
         * The callback type flags for the scan.
         * TODO: Add documentation on the valid values for callbackTypes.
         */
        callbackType?: CallbackType;
        /**
         * Set whether only legacy advertisements should be returned in scan results.
         * Legacy advertisements include advertisements as specified by the
         * Bluetooth core specification 4.2 and below. This is true by default
         * for compatibility with older apps.
         *
         * @param legacy true if only legacy advertisements will be returned
         */
        legacy?: boolean;
        /**
         * Several phones may have some issues when it comes to offloaded filtering.
         * Even if it should be supported, it may not work as expected.
         * It has been observed for example, that setting 2 filters with different devices
         * addresses on Nexus 6 with Lollipop gives no callbacks if one or both devices advertise.
         * See https://code.google.com/p/android/issues/detail?id=181561.
         *
         * @param use true to enable (default) hardware offload filtering.
         *                 If false a compat software filtering will be used
         *                 (uses much more resources).
         */
        useHardwareBatchingIfSupported?: boolean;
        /**
         * Set report delay timestamp for Bluetooth LE scan.
         *
         * @param reportDelayMillis Delay of report in milliseconds. Set to 0 to be notified of
         *            results immediately. Values &gt; 0 causes the scan results to be queued up and
         *            delivered after the requested delay or when the internal buffers fill up.
         * @throws IllegalArgumentException If {@code reportDelayMillis} &lt; 0.
         */
        reportDelay?: number;
        /**
         * *** Only available on Android 23+ ***
         * Set the Physical Layer to use during this scan.
         * This is used only if {@link ScanSettings.Builder#setLegacy}
         * is set to false and only on Android 0reo or newer.
         * {@link android.bluetooth.BluetoothAdapter#isLeCodedPhySupported}
         * may be used to check whether LE Coded phy is supported by calling
         * {@link android.bluetooth.BluetoothAdapter#isLeCodedPhySupported}.
         * Selecting an unsupported phy will result in failure to start scan.
         *
         * @param phy Can be one of
         *   {@link BluetoothDevice#PHY_LE_1M},
         *   {@link BluetoothDevice#PHY_LE_CODED} or
         *   {@link ScanSettings#PHY_LE_ALL_SUPPORTED}
         */
        phy?: Phy;
    };
}
/**
 * The options object passed into the disconnect function.
 */
export interface DisconnectOptions {
    /**
     * The UUID of the peripheral to disconnect from.
     */
    UUID: string;
}
/**
 * The options object passed into the connect function.
 */
export interface ConnectOptions {
    /**
     * The UUID of the peripheral to connect to.
     */
    UUID: string;
    /**
     * Once the peripheral is connected this callback function is invoked.
     */
    onConnected?: (data: {
        UUID: any;
        name: string;
        state: ConnectionState;
        services?: Service[];
        advertismentData: AdvertismentData;
    }) => void;
    /**
     * Once the peripheral is disconnected this callback function is invoked.
     */
    onDisconnected?: (data: {
        UUID: any;
        name: string;
    }) => void;
    autoDiscoverAll?: boolean;
}
export interface AdvertismentData {
    localName?: string;
    manufacturerData?: ArrayBuffer;
    manufacturerId?: number;
    serviceUUIDs?: string[];
    serviceData?: {
        [k: string]: ArrayBuffer;
    };
    txPowerLevel?: number;
    flags?: number;
}
/**
 * The returned object in several callback functions.
 */
export interface Peripheral {
    /**
     * The UUID of the peripheral.
     */
    UUID: string;
    /**
     * A friendly description of the peripheral as provided by the manufacturer.
     */
    name: string;
    /**
     * A friendly description of the peripheral as provided by the manufacturer.
     */
    localName?: string;
    /**
     * The relative signal strength which more or less can be used to determine how far away the peripheral is.
     */
    RSSI?: number;
    /**
     * Once connected to the peripheral  and if autoDiscoverAll is not false, a list of services will be set.
     */
    services?: Service[];
    manufacturerId?: number;
    advertismentData?: AdvertismentData;
}
/**
 * A service provided by a periperhal.
 */
export interface Service {
    /**
     * The UUID of the service.
     */
    UUID: string;
    /**
     * Depending on the peripheral and platform this may be a more friendly description of the service.
     */
    name?: string;
    /**
     * A list of service characteristics a client can interact with by reading, writing, subscribing, etc.
     */
    characteristics?: Characteristic[];
}
/**
 * A characteristic provided by a service.
 */
export interface Characteristic {
    /**
     * The UUID of the characteristic.
     */
    UUID: string;
    /**
     * Depending on the service and platform (iOS only) this may be a more friendly description of the characteristic.
     * On Android it's always the same as the UUID.
     */
    name: string;
    /**
     * An object containing characteristic properties like read, write and notify.
     */
    properties?: {
        read: boolean;
        write: boolean;
        writeWithoutResponse: boolean;
        notify: boolean;
        indicate: boolean;
        broadcast: boolean;
        authenticatedSignedWrites: boolean;
        extendedProperties: boolean;
    };
    /**
     * ignored for now
     */
    descriptors?: any;
    /**
     * ignored for now
     */
    permissions?: any;
}
/**
 * Base properties for all CRUD actions
 */
export interface CRUDOptions {
    peripheralUUID: string;
    serviceUUID: string;
    characteristicUUID: string;
}
export interface ReadOptions extends CRUDOptions {
}
export interface WriteOptions extends CRUDOptions {
    value: any;
    encoding?: string;
}
export interface MtuOptions {
    value: any;
    peripheralUUID: string;
}
export interface DiscoverOptions {
    peripheralUUID: string;
}
export interface DiscoverServicesOptions extends DiscoverOptions {
    serviceUUIDs?: string[];
}
export interface DiscoverCharacteristicsOptions extends DiscoverOptions {
    serviceUUID: string;
    characteristicUUIDs?: string[];
}
export interface StopNotifyingOptions extends CRUDOptions {
}
export interface StartNotifyingOptions extends CRUDOptions {
    onNotify: (data: ReadResult) => void;
}
/**
 * Response object for the read function
 */
export interface ReadResult {
    value: ArrayBuffer;
    ios?: any;
    android?: any;
    characteristicUUID: string;
    serviceUUID: string;
}
export interface StartAdvertisingOptions {
    settings: any;
    UUID: any;
    data: any;
}
/**
 * All of the events for Bluetooth that can be emitted and listened to.
 */
export interface IBluetoothEvents {
    error_event: string;
    bluetooth_enabled_event: string;
    bluetooth_status_event: string;
    peripheral_connected_event: string;
    bluetooth_advertise_success_event: string;
    bluetooth_advertise_failure_event: string;
    server_connection_state_changed_event: string;
    bond_status_change_event: string;
    device_discovered_event: string;
    device_name_change_event: string;
    device_uuid_change_event: string;
    device_acl_disconnected_event: string;
    characteristic_write_request_event: string;
    characteristic_read_request_event: string;
    descriptor_write_request_event: string;
    descriptor_read_request_event: string;
    execute_write_event: string;
}