@moddable/typings 5.3.0 → 5.4.1

package/ble/bleclient.d.ts

@@ -0,0 +1,175 @@
+/*
+* Copyright (c) 2022-2025 Richard Lea, Satoshi Tanaka
+*
+*   This file is part of the Moddable SDK Tools.
+*
+*   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+*   it under the terms of the GNU General Public License as published by
+*   the Free Software Foundation, either version 3 of the License, or
+*   (at your option) any later version.
+*
+*   The Moddable SDK Tools is distributed in the hope that it will be useful,
+*   but WITHOUT ANY WARRANTY; without even the implied warranty of
+*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*   GNU General Public License for more details.
+*
+*   You should have received a copy of the GNU General Public License
+*   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+declare module "bleclient" {
+
+  import { GAP } from "gap";
+  import { Client, Service, Characteristic, Descriptor } from "gatt";
+  import { IOCapability } from "sm";
+
+  type gapScanFilterPolicies =
+    typeof GAP.ScanFilterPolicy.NONE |
+    typeof GAP.ScanFilterPolicy.NOT_RESOLVED_DIRECTED |
+    typeof GAP.ScanFilterPolicy.WHITELIST |
+    typeof GAP.ScanFilterPolicy.WHITELIST_NOT_RESOLVED_DIRECTED;
+
+  type securityParameters = {
+    encryption?: boolean,
+    bonding?: boolean,
+    mitm?: boolean,
+    ioCapability?: IOCapability,
+  }
+
+  /**
+   * The `BLEClient` class provides access to the BLE client features.
+   */
+  export class BLEClient {
+
+    securityParameters: securityParameters
+
+    /**
+     * Applications must wait for the `onReady` callback before calling
+     * other `BLEClient` functions
+     */
+    onReady(): void
+
+    onSecurityParameters(params: securityParameters): void
+
+  
+    /**
+     * The `startScanning` function enables scanning for nearby peripherals.
+     * 
+     * @param params If params is not provided, the default scan properties are used.
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#startscanningparams
+     */
+    startScanning(params?: {
+      active: boolean,
+      duplicates: boolean,
+      filterPolicy: gapScanFilterPolicies,
+      interval: number,
+      window: number,
+    }): void;
+
+    /**
+     * Called when one or more times for each peripheral device discovered.
+     * @param device 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#ondiscovereddevice
+     */
+    onDiscovered(device: Client): void;
+
+    /**
+     * Disables scanning for nearby peripherals.
+     */
+    stopScanning(): void;
+
+    /**
+     * Initiates a connection request between the `BLEClient` and a target peripheral `device`.
+     * @param device 
+     */
+    connect(device: Client): void;
+
+    /**
+     * Called when the client connects to a target peripheral `device`.
+     * @param device 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#onconnecteddevice
+     */
+    onConnected(device: Client): void;
+
+    /**
+     * Called when the peripheral signal strength is read.
+     * @param device 
+     * @param rssi 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#onrssidevice-rssi
+     */
+    onRSSI(device: Client, rssi: number): void;
+
+    /**
+     * Called when the MTU exchange procedure has been completed.
+     * @param device 
+     * @param mtu
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#onmtuexchangeddevice-mtu
+     */
+    onMTUExchanged(device: Client, mtu: number): void;
+
+    /**
+     * Called when the client connection is closed.
+     * @param device 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#ondisconnecteddevice
+     */
+    onDisconnected(device: Client): void;
+
+    /**
+     * Called when service discovery completes.
+     * @param services 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#onservicesservices
+     */
+    onServices(services: Service[]): void;
+
+    /**
+     * Called when characteristic discovery completes. 
+     * @param characteristics 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicscharacteristics
+     */
+    onCharacteristics(characteristics: Characteristic[]): void;
+
+    /**
+     * Called when a characteristic is read by the `readValue` function.
+     * @param characteristic 
+     * @param value 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicvaluecharacteristic-value
+     */
+    onCharacteristicValue(characteristic: Characteristic, value: any): void;
+
+    /**
+     * Called when notifications are enabled and the peripheral notifies the characteristic value.
+     * @param characteristic 
+     * @param buffer 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicnotificationcharacteristic-value
+     */
+    onCharacteristicNotification(characteristic: Characteristic, buffer: number[]): void;
+
+    /**
+     * Called when notifications have been enabled for the `characteristic`.
+     * @param characteristic 
+     * @param buffer 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicnotificationenabledcharacteristic
+     */
+    onCharacteristicNotificationEnabled(characteristic: Characteristic): void;
+
+    /**
+     * Called when notifications have been disabled for the `characteristic`.
+     * @param characteristic 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicnotificationdisabledcharacteristic
+     */
+    onCharacteristicNotificationDisabled(characteristic: Characteristic): void;
+
+    /**
+     * Called when a descriptor is read by the `readValue` function.
+     * @param descriptor 
+     * @param value 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#ondescriptorvaluedescriptor-value
+     */
+    onDescriptorValue(descriptor: Descriptor, value: any): void;
+
+    close(): void
+  }
+
+  export { BLEClient as default };
+}

package/ble/bleserver.d.ts

@@ -0,0 +1,303 @@
+/*
+* Copyright (c) 2022 Richard Lea
+*
+*   This file is part of the Moddable SDK Tools.
+*
+*   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+*   it under the terms of the GNU General Public License as published by
+*   the Free Software Foundation, either version 3 of the License, or
+*   (at your option) any later version.
+*
+*   The Moddable SDK Tools is distributed in the hope that it will be useful,
+*   but WITHOUT ANY WARRANTY; without even the implied warranty of
+*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*   GNU General Public License for more details.
+*
+*   You should have received a copy of the GNU General Public License
+*   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+declare module "bleserver" {
+
+  import { GAP } from "gap";
+  import { Bytes } from "btutils";
+  import { Characteristic, Client } from "gatt";
+  import { IOCapability } from "sm";
+
+  type ManufacturerSpec = {
+    /**
+     * The `identifier` property is a number corresponding to the
+     * _Company Identifier Code_.
+     */
+    identifier: string | number,
+  
+    /**
+     * The `data` property is an array of numbers corresponding
+     * to additional manufacturer specific data.
+     */
+    data: number[],
+  };
+
+  type gapScanFilterPolicies =
+    typeof GAP.ScanFilterPolicy.NONE |
+    typeof GAP.ScanFilterPolicy.NOT_RESOLVED_DIRECTED |
+    typeof GAP.ScanFilterPolicy.WHITELIST |
+    typeof GAP.ScanFilterPolicy.WHITELIST_NOT_RESOLVED_DIRECTED;
+
+  type AdvertisementData = {
+
+    /**
+     * The advertised flags value.
+     */
+    flags?: number;
+    /**
+     * Array of UUID objects corresponding to _Incomplete List
+     * of 16 bit Service UUIDs_
+     */
+    incompleteUUID16List?: Bytes[],
+
+    /**
+     * Array of UUID objects corresponding to _Complete List of
+     * 16 bit Service UUIDs_
+     */
+    completeUUID16List?: Bytes[],
+
+    /**
+     * Array of UUID objects corresponding to _Incomplete List of
+     * 128 bit Service UUIDs_
+     */
+    incompleteUUID128List?: Bytes[],
+
+    /**
+     * Array of UUID objects corresponding to _Complete List of
+     * 128 bit Service UUIDs_
+     */
+    completeUUID128List?: Bytes[],
+
+    /**
+     * String corresponding to the _Shortened Local Name_.
+     */
+    shortName?: string,
+
+    /**
+     * String corresponding to the _Complete Local Name_.
+     */
+    completeName?: string,
+
+    /**
+     * Object corresponding to the _Manufacturer Specific Data_.
+     */
+    manufacturerSpecific?: ManufacturerSpec,
+
+    /**
+     * Number corresponding to the TX Power Level.
+     */
+    txPowerLevel?: number,
+
+    /**
+     * Object corresponding to the _Slave Connection Interval Range_.
+     */
+    connectionInterval?: {
+      /**
+       * A number corresponding to the minimum connection interval value.
+       */
+      intervalMin: number,
+
+      /**
+       * A number corresponding to the maximum connection interval value.
+       */
+      intervalMax: number,
+    },
+
+    /**
+     * Array of UUID objects corresponding to the _List of 16 bit Service
+     * Solicitation UUIDs_.
+     */
+    solicitationUUID16List?: Bytes[],
+
+    /**
+     * Array of UUID objects corresponding to the _List of 128 bit Service
+     * Solicitation UUIDs_.
+     */
+    solicitationUUID128List?: Bytes[],
+
+    /**
+     * Object corresponding to the _Service Data - 16 bit UUID_.
+     */
+    serviceDataUUID16?: {
+      /**
+       * An object corresponding to the 16-bit Service UUID.
+       */
+      uuid: Bytes,
+
+      /**
+       * An array of numbers corresponding to additional service data.
+       */
+      data: number[],
+    },
+
+    /**
+     * Object corresponding to the _Service Data - 128 bit UUID_.
+     */
+    serviceDataUUID128?: {
+      /**
+       * An object corresponding to the 128-bit Service UUID.
+       */
+      uuid: Bytes,
+
+      /**
+       * An array of numbers corresponding to additional service data.
+       */
+      data: number[],
+    },
+
+    /**
+     * Number corresponding to the _Appearance_.
+     */
+    appearance?: number,
+
+    /**
+     * Address object corresponding to the _Public Target Address_.
+     */
+    publicAddress?: Bytes,
+
+    /**
+     * Address object corresponding to the _Random Target Address_.
+     */
+    randomAddress?: Bytes,
+
+    /**
+     * Number corresponding to the _Advertising Interval_.
+     */
+    advertisingInterval?: number,
+
+    /**
+     * Number corresponding to the _LE Role_.
+     */
+    role?: number,
+
+    /**
+     * String corresponding to the _Uniform Resource Identifier_.
+     */
+    uri?: string,
+  };
+
+  /**
+   * Provides access to the BLE server features.
+   */
+  export class BLEServer {
+
+    /**
+     * Configures the device security requirements and I/O capabilities.
+     */
+    set securityParameters(params: {
+      encryption?: boolean,
+      bonding?: boolean,
+      mitm?: boolean,
+      ioCapability?: IOCapability,
+    });
+
+    /**
+     * set/get the Bluetooth peripheral device name.
+     */
+    deviceName: string;
+
+    /**
+     * The Bluetooth peripheral's local address as a
+     * `Bytes` object.
+     *
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#localaddress
+     */
+    readonly localAddress: Bytes;
+
+    /**
+     * Applications must wait for the `onReady` callback
+     * before calling other `BLEServer` functions.
+     */
+    onReady(): void;
+
+    /**
+     * Starts broadcasting advertisement and scan response packets.
+     * The function is also used to configure discoverable and connectable modes.
+     * 
+     * @param params 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#startadvertisingparams
+     */
+    startAdvertising(params: {
+      advertisingData: AdvertisementData,
+      connectable?: boolean,
+      discoverable?: boolean,
+      fast?: boolean,
+      filterPolicy?: gapScanFilterPolicies,
+      scanResponseData?: any,
+    }): void;
+
+    /**
+     * Stops broadcasting Bluetooth advertisements.
+     * 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#stopadvertising
+     */
+    stopAdvertising(): void;
+
+    /**
+     * Send a characteristic value change notification to the connected client.
+     * 
+     * @param characteristic 
+     * @param value
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#notifyvaluecharacteristic-value
+     */
+    notifyValue(characteristic: Characteristic, value: any): void;
+
+    /**
+     * Called when a client enables notifications on the `characteristic`.
+     * 
+     * @param characteristic 
+     */
+    onCharacteristicNotifyEnabled(characteristic: Characteristic): void;
+
+    /**
+     * Called when a client writes a service characteristic value on demand.
+     *
+     * @param characteristic 
+     * @param value 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicwrittencharacteristic-value
+     */
+    onCharacteristicWritten(characteristic: Characteristic, value: any): void;
+
+    /**
+     * Called when a client reads a service characteristic value on demand.
+     * 
+     * @param characteristic 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#oncharacteristicreadcharacteristic
+     */
+    onCharacteristicRead(characteristic: Characteristic): Uint8Array | number[] | number | void;
+
+    /**
+     * Terminate the BLE client connection.
+     */
+    disconnect(): void;
+
+    /**
+     * Called when a client connects to the `BLEServer`.
+     *
+     * @param device 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#ondisconnecteddevice-1
+     */
+    onConnected(device: Client): void;
+
+    /**
+     * Called when the client connection is closed.
+     *
+     * @param device 
+     */
+    onDisconnected(device: Client): void;
+
+    /**
+     * Terminate any BLE client connection and release all BLE resources.
+     */
+    close(): void;
+  }
+
+  export { BLEServer as default };
+}

package/ble/btutils.d.ts

@@ -0,0 +1,117 @@
+/*
+* Copyright (c) 2022-2025 Richard Lea, Satoshi Tanaka
+*
+*   This file is part of the Moddable SDK Tools.
+*
+*   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+*   it under the terms of the GNU General Public License as published by
+*   the Free Software Foundation, either version 3 of the License, or
+*   (at your option) any later version.
+*
+*   The Moddable SDK Tools is distributed in the hope that it will be useful,
+*   but WITHOUT ANY WARRANTY; without even the implied warranty of
+*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*   GNU General Public License for more details.
+*
+*   You should have received a copy of the GNU General Public License
+*   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+type ManufacturerSpec = {
+  /**
+   * The `identifier` property is a number corresponding to the
+   * _Company Identifier Code_.
+   */
+  identifier: string | number,
+
+  /**
+   * The `data` property is an array of numbers corresponding
+   * to additional manufacturer specific data.
+   */
+  data: number[],
+};
+
+declare module "btutils" {
+
+  export class Bytes extends ArrayBuffer {
+    constructor(bytes: string | ArrayBufferLike, littleEndian?: boolean)
+    /**
+     * The `equals` function returns `true` if the instance
+     * ArrayBuffer data equals the data contained in `buffer`.
+     * 
+     * @param bytes 
+     * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#equalsbuffer
+     */
+    equals(bytes: Bytes): boolean;
+
+    /**
+     * The `toString` function returns a printable hex string of the Bytes contents. The string is formatted in big endian order with separators.
+     * https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#tostring
+     */
+    toString(): string;
+  }
+
+  /**
+   * Provides Accessor functions to read common advertisement and
+   * scan response data types as JavaScript properties.
+   * 
+   * @url https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/network/ble/ble.md#class-advertisement
+   */
+  export interface Advertisement {
+
+    /**
+     * Contains the raw advertisement data bytes.
+     */
+    buffer: ArrayBuffer;
+
+    /**
+     * Number corresponding to the Appearance.
+     */
+    appearance: number;
+
+    /**
+     * The advertised complete local name.
+     */
+    completeName: string;
+
+    /**
+     * The advertised shortened local name.
+     */
+    shortName: string;
+
+    /**
+     * An object containing the advertised manufacturer specific data.
+     */
+    manufacturerSpecific: ManufacturerSpec;
+
+    /**
+     * The advertised flags value.
+     */
+    flags: number;
+
+    /**
+     * The advertised complete 16-bit UUID list.
+     */
+    completeUUID16List: Array<string | number>;
+
+    /**
+     * The advertised incomplete 16-bit UUID list.
+     */
+    incompleteUUID16List: Array<string | number>;
+
+    findIndex(type: number, index?: number): number;
+  }
+
+  /**
+   * Convert a Bluetooth UUID expressed as a hex string to a `Bytes` instance.
+   * @param strings 
+   */
+  export function uuid(strings: TemplateStringsArray): Bytes;
+
+  /**
+   * Convert a Bluetooth address expressed as a hex string to a `Bytes` instance.
+   * @param strings 
+   */
+  export function address(strings: TemplateStringsArray): Bytes;
+}

package/ble/connection.d.ts

@@ -0,0 +1,25 @@
+/*
+* Copyright (c) 2022 Richard Lea
+*
+*   This file is part of the Moddable SDK Tools.
+*
+*   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+*   it under the terms of the GNU General Public License as published by
+*   the Free Software Foundation, either version 3 of the License, or
+*   (at your option) any later version.
+*
+*   The Moddable SDK Tools is distributed in the hope that it will be useful,
+*   but WITHOUT ANY WARRANTY; without even the implied warranty of
+*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*   GNU General Public License for more details.
+*
+*   You should have received a copy of the GNU General Public License
+*   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+declare module "connection" {
+  export class Connection {
+    disconnect(): void;
+  }
+}