@particle/device-control-ble
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.4 • Public • Published

    @particle/device-control-ble

    A library for controlling Particle devices over BLE.

    Installation

    npm install @particle/device-control-ble @particle/device-constants --save

    NOTE: @particle/device-control-ble declares @particle/device-constants as a peerDependency - this ensures your app only ever has one copy of that dependency

    API

    BleControlRequestChannel

    A class implementing the Device OS control request protocol for BLE.

    Kind: global class


    new BleControlRequestChannel(options)

    Constructor.

    Param Type Default Description
    options Object Options.
    options.stream Object Transport stream. The stream object is expected to behave similarly to a Node's stream.Duplex in flowing mode. The only method of the stream.Duplex interface that has to be implemented by the stream is write(). The method's callback argument and return value are not used. All writes must be buffered by the stream. The channel will add listeners for the following stream events: data, end, finish, close, error. Half-closed streams are not supported, meaning that an end or a finish event emitted by the stream will result in the channel being closed immediately.
    options.secret String | Uint8Array Device secret.
    [options.concurrentRequests] Number 1 Maximum number of requests that can be sent to the device concurrently. Requests attempted to be sent above this limit will be queued.
    [options.requestTimeout] Number 60000 Default request timeout in milliseconds.
    [options.handshakeTimeout] Number 10000 Handshake timeout in milliseconds.
    [options.env] Env defaultEnv() Environment-specific functions.

    bleControlRequestChannel.state : String

    Channel state.

    Possible values are new, opening, open and closed.

    Kind: instance property of BleControlRequestChannel


    bleControlRequestChannel.open() ⇒ Promise

    Open the channel and initiate a handshake with the device.

    An open event will be emitted when the channel is open. Requests can still be enqueued for sending via sendRequest() while the channel is being opened.

    The transport stream and the underlying BLE characteristics must be in a readable and writable state by the time this method is called.

    A closed channel cannot be reopened.

    Kind: instance method of BleControlRequestChannel


    bleControlRequestChannel.close()

    Close the channel.

    A closed event will be emitted when the channel is closed. All pending requests will be rejected with an error.

    Kind: instance method of BleControlRequestChannel


    BleCharacteristic

    A base class for a BLE characteristic.

    Kind: global class
    Emits: data, error


    bleCharacteristic.uuid : String

    Characteristic UUID.

    Kind: instance property of BleCharacteristic


    bleCharacteristic.read() ⇒ Promise.<Uint8Array>

    Read the current value of the characteristic.

    Kind: instance method of BleCharacteristic


    bleCharacteristic.write(data, [options]) ⇒ Promise

    Write to the characteristic.

    Kind: instance method of BleCharacteristic

    Param Type Default Description
    data Uint8Array Data to write.
    [options] Object Options.
    [options.withoutResponse] Boolean false Whether to write with or without a response.

    bleCharacteristic.enableNotifications() ⇒ Promise

    Enable notifications for this characteristic.

    Kind: instance method of BleCharacteristic


    bleCharacteristic.disableNotifications() ⇒ Promise

    Disable notifications for this characteristic.

    Kind: instance method of BleCharacteristic


    "data"

    An event emitted when the peripheral indicates that the characteristic has changed.

    In order to start receiving these events, notifications for the characteristic need to be enabled via enableNotifications.

    Kind: event emitted by BleCharacteristic


    "error"

    An event emitted when an error occurs.

    Kind: event emitted by BleCharacteristic


    BleService

    A base class for a BLE service.

    Kind: global class


    bleService.uuid : String

    Service UUID.

    Kind: instance property of BleService


    bleService.getCharacteristics() ⇒ Promise.<Array.<BleCharacteristic>>

    Get the characteristics of this service.

    Kind: instance method of BleService


    BlePeripheral

    A base class for a BLE peripheral device.

    Kind: global class
    Emits: connect, disconnect, error


    blePeripheral.name : String

    Peripheral name.

    Kind: instance property of BlePeripheral


    blePeripheral.manufacturerData : Uint8Array

    Advertised manufacturer data.

    If present, the manufacturer data is expected to start with a 2-byte company ID.

    Kind: instance property of BlePeripheral


    blePeripheral.mtu : Number

    ATT MTU of the current established connection.

    If defined, the value must be greater than or equal to 23, which is the minimum supported ATT MTU.

    Kind: instance property of BlePeripheral


    blePeripheral.connect() ⇒ Promise

    Connect to the peripheral.

    Kind: instance method of BlePeripheral


    blePeripheral.disconnect() ⇒ Promise

    Disconnect from the peripheral.

    Kind: instance method of BlePeripheral


    blePeripheral.getServices() ⇒ Promise.<Array.<BleService>>

    Get the services of this peripheral.

    Kind: instance method of BlePeripheral


    "connect"

    An event emitted when the host has connected to the peripheral.

    Kind: event emitted by BlePeripheral


    "disconnect"

    An event emitted when the host has disconnected from the peripheral.

    Kind: event emitted by BlePeripheral


    "error"

    An event emitted when an error occurs.

    Kind: event emitted by BlePeripheral


    BleManager

    A base class for a BLE manager.

    Kind: global class


    new BleManager()

    Constructor.


    bleManager.getDevices([options]) ⇒ Promise.<Array.<BlePeripheral>>

    Scan for available peripherals.

    If filtering options, such as names or services, are provided, a discovered peripheral will only be reported by this method if it satisfies all of the filtering options.

    Only one scan can be active at a time.

    Kind: instance method of BleManager
    Returns: Promise.<Array.<BlePeripheral>> - Discovered peripherals.

    Param Type Default Description
    [options] Object Options.
    [options.names] Array.<(String|RegExp)> Peripheral names.
    [options.services] Array.<String> Service UUIDs.
    [options.count] Number Maximum number of peripherals to scan for.
    [options.timeout] Number 5000 Maximum duration of the scan in milliseconds.

    bleManager.destroy() ⇒ Promise

    Shut down the BLE manager.

    Calling this method will interrupt the ongoing scan process and close all connections with peripherals with an error.

    Kind: instance method of BleManager


    Aes128Cipher

    A base class for an AES-128 cipher operating in ECB mode.

    Kind: global class


    aes128Cipher.encryptBlock(block) ⇒ Promise.<Uint8Array>

    Encrypt a single block of data.

    Kind: instance method of Aes128Cipher
    Returns: Promise.<Uint8Array> - Ciphertext block.

    Param Type Description
    block Uint8Array Plaintext block. The block must be 16 bytes long.

    Env

    A base class defining environment-specific functions used by the library.

    Kind: global class


    env.createAes128Cipher(key) ⇒ Aes128Cipher

    Create an AES-128 cipher operating in ECB mode.

    Kind: instance method of Env
    Returns: Aes128Cipher - Cipher object.

    Param Type Description
    key Uint8Array Encryption key. The key must be 16 bytes long.

    env.getRandomBytes(size) ⇒ Promise.<Uint8Array>

    Generate cryptographically strong random data.

    Kind: instance method of Env
    Returns: Promise.<Uint8Array> - Random data.

    Param Type Description
    size Number Number of bytes to generate.

    DEFAULT_BLE_SCAN_TIMEOUT

    Default timeout of a BLE scan.

    Kind: global constant


    defaultEnv() ⇒ Env

    Get the default environment-specific functions.

    Kind: global function


    Response ⇒ Promise.<Response>

    Send a request to the device.

    Kind: global typedef

    Param Type Description
    type Number Request type. See system_control.h in Device OS for the list of defined request types.
    [data] Uint8Array Request payload data.
    [options] Object Options.
    [options.timeout] Number Request timeout in milliseconds. If not specified, the default timeout configured at construction time will be used.

    Properties

    Name Type Description
    result Number Result code. See system_error.h in Device OS for the list of defined result codes.
    data Uint8Array Response payload data.

    NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in tests

    Keywords

    none

    Install

    npm i @particle/device-control-ble

    DownloadsWeekly Downloads

    19

    Version

    0.2.4

    License

    UNLICENSED

    Unpacked Size

    42.1 kB

    Total Files

    10

    Last publish

    Collaborators

    • jmw
    • amaury.particle
    • cole-abbeduto-particle
    • pedrosordo
    • rowan.hamilton
    • guohui
    • sbrust
    • busticated
    • particlebot
    • no1089
    • carlos.hdez
    • keeramis5
    • monkbroc
    • suda
    • mstan
    • sergeuz
    • debbie23
    • avtolstoy
    • mlauer
    • wraithan
    • azenk
    • shewy
    • bwalach
    • parteberseth
    • rickkas7
    • mrlambchop_particle
    • hugo.montero
    • toddparticle
    • mphsi