Bluetooth Low Energy (BLE)

BLE is one class: new BLE('name') carries the advertised device name, and the GATT database is declared with service()/char() chains. Handlers bind to the characteristic they immediately follow in the chain — declare them right where the characteristic is declared.

class

BLE

import { BLE, BlePerm, BleValueType } from '@typecad/hal'

A GATT peripheral server. Construct it with the advertised name, declare services and characteristics as chains, attach read/write handlers inline, then start(). char() without a preceding service() attaches to the default Environmental Sensing service — the common single-service case.

Example first

temp-sensor.ts

import { BLE, BleValueType, BlePerm, Time } from '@typecad/hal';

const ble = new BLE('TempSensor');

ble.char('2A6E', BleValueType.Int16, BlePerm.Read)
   .onRead(() => 2180);      // 21.80 °C — int16, 0.01 °C units per GATT 2A6E

ble.start();                 // register the database, enable the stack, advertise

while (true) {
  Time.sleep(1000);
}

Multiple services and characteristics

Chain declarations; each service() begins a grouping, and each char() appends to the most recent one. Read and write handlers:

gatt.ts

ble.service('180F')                          // Battery Service
   .char('2A19', BleValueType.Uint8, BlePerm.Read | BlePerm.Notify)
   .onRead(() => batteryPercent());

ble.notify(0, batteryPercent());             // push to subscribers — index is
                                             // declaration order, 0-based

ble.service('180A')
   .char('2A56', BleValueType.Int32, BlePerm.Write)
   .onWrite((value) => { setpoint = value; });

Permissions and value types

Tokens	Description
BlePerm.Read / Write / Notify	Permission flags — combine with \|
BleValueType.Int8 / Int16 / Int32	Signed GATT value types
BleValueType.Uint8 / Uint16 / Uint32	Unsigned GATT value types

Pick the GATT spec's type for the characteristic you implement.

onConnect / onDrop `onConnect(fn): void`

events.ts

ble.onConnect(() => UART0.writeLine('central connected'));
ble.onDrop(() => UART0.writeLine('central disconnected'));   // advertising stays armed

linked() is true while a central is connected; clients() reports the count. stop() stops advertising; the database and any link stay up.

All methods

Member	Description
new BLE(name)	Construct the peripheral; the name is the advertised identity
service(uuid)	Begin a service grouping for subsequent char() calls
char(uuid, type, perms)	Append a characteristic (to the default service when no service() precedes it)
.onRead(fn) / .onWrite(fn)	Handlers for the most recently declared characteristic; chainable
start()	Register the GATT database, enable the stack, begin advertising
stop()	Stop advertising — the database and any link stay up
linked() / clients()	Connection state and count (single-connection: 0 or 1)
onConnect(fn) / onDrop(fn)	Connection callbacks
notify(index, value)	Push a value to subscribers — index is declaration order (0-based)

Previous IoT Networking (MQTT) Next Storage & Persistent Data