blz command

Name

blz - interact with Bluetooth Low Energy (BLE) devices on Linux using libblz and libsystemd.

Synopsis

package require blz
blz subcommand ?options?

Description

This command is used to deal with Bluetooth Low Energy (BLE) devices. The legal subcommands (which may be abbreviated) are:

blz callback handle ?callback?

If the callback argument is provided that argument replaces the callback function on the BLE connection identified by handle and returns the old callback function. Otherwise the current callback function is returned. In contrast to e.g. the Tk event bind mechanism, the callback argument has not all the freedom of a Tcl bind script, i.e. it must be a single command and be parseable as a list since internally the Tcl core function Tcl_EvalObjv() is used for executing the callback instead of the Tcl_Eval*() function family supporting full scripts.

blz characteristics handle suuid

Returns a list of characteristics of the service described by its UUID suuid on the BLE connection handle.

blz close handle

Closes the BLE connection identified by handle which was obtained earlier by a blz open command.

blz connect address callback ?random?

Connects to the Bluetooth LE device with address address (expressed as six hexadecimal 8 bit numbers separated by colons, like a Ethernet MAC address), and arranges for the callback command to be invoked on events on the connection to this device. The optional flag random is a boolean with default false controlling the address type (unkown or public). The callback command is called with two additional arguments, the first is a string (connection, scan, or characteristic) indicating the kind of event, the second is a dictionary with event related information, see the section Event Data below. For restrictions of the callback argument see the description in blz callback above. During connection establishment an automatic discovery takes place which detects all advertised services and characteristics of the remote Bluetooth LE device. Caution: this operation can block for some seconds when the remote device isn’t available or responds slowly.

blz devices handle

Reports known devices in the same way as scan results (see blz scan) are reported. To receive the respective events, scanning must have been turned on before.

blz disable handle suuid cuuid

Turns off notifications of a characteristic of the BLE connection handle identified by suuid (128 bit service UUID) and cuuid (128 bit characteristic UUID).

blz disconnect handle

Initiates a disconnect of the BLE connection handle.

blz enable handle suuid cuuid

Turns on notifications of a characteristic of the BLE connection handle identified by suuid (128 bit service UUID) and cuuid (128 bit characteristic UUID).

blz indenable handle suuid cuuid

Turns on indications of a characteristic of the BLE connection handle identified by suuid (128 bit service UUID) and cuuid (128 bit characteristic UUID).

blz info ?handle?

Returns information of the BLE connection identified by handle as a dictionary made up the fields address (Bluetooth address or empty), scanning (scan state, 0 or 1), and connected (connection state, 0 or 1). If handle is omitted, a list of all known connection identifiers (handles) is returned.

blz read handle suuid cuuid

Reads the characteristic of the BLE connection handle identified by suuid (128 bit service UUID) and cuuid (128 bit characteristic UUID). The result is a byte array of the current value of the characteristic.

blz scan handle callback

Starts detection (scan) of BLE devices on BLE connection handle and arranges for the callback command to be invoked on events on the connection. See the description of blz connect and the section Event Data for more details on the callback argument.

blz services handle

Returns a list of service UUIDs of the BLE connection handle.

blz stop handle

Stops scanning for BLE devices.

blz userdata handle ?data?

Associate or retrieve user data with the BLE connection handle. When data is given it replaces the former associated user data. When omitted, the current user data or an empty list is returned.

blz write handle suuid cuuid value

Writes value into a characteristic of the BLE connection handle identified by suuid (128 bit service UUID) and cuuid (128 bit characteristic UUID). The value to be written should be a string or byte array.

Abbreviated UUIDs

The 128 bit UUID arguments to blz commands can be specified in abbreviated 16 or 32 bit form as long as the value is unique with respect to the UUIDs learned during the discovery phase. Examples:

 TI SensorTag Base UUID:        F0000000-0451-4000-B000-000000000000

 IR Temperature Sensor Service: F000AA00-0451-4000-B000-000000000000
          abbreviated (32 bit): F000AA00
          abbreviated (16 bit):     AA00

 IR Temperature Sensor Value:   F000AA01-0451-4000-B000-000000000000
          abbreviated (32 bit): F000AA01
          abbreviated (16 bit):     AA01

 Generic descriptor for notify: 00002902-0000-1000-8000-00805F9B34FB
          abbreviated (32 bit): 00002902
          abbreviated (16 bit):     2902

Event Data

The first argument to callback functions is the type of event, as described below.

connection

Indicates change in connection state.

scan

Indicates change in scan state or reports newly detected Bluetooth LE devices.

characteristic

Information about a characteristic, used for data exchange.

The second argument to callback functions is a dictionary with keys depending on the kind of the event. The following paragraphs list the various event formats.

handle h address a connected c

Connection state event for blz connect. The value of connected indicates the connection state.

handle h address a type t rssi r scandata d

Scan result event. address is the Bluetooth address of the remote device, type the device type as integer, rssi</t> the receive SSI in dBm as integer, and scandata the advertisement record of the remote device as a byte array.

handle h address a suuid su cuuid cu flags f value v

Characteristic event. cuuid is the UUID of the characteristic. The value item holds the data of the characteristic as a byte array. Its interpretation is device/characteristic depending. This event is reported during operation when the remote devices sends notifications or indications.