Toit
Libraries
bignum
binary
bitmap
ble
bytes
core
crypto
device
encoding
esp32
expect
fixed-point
flash
font
gpio
i2c
i2s
icons
io
line-wrap
log
math
monitor
net
pulse-counter
reader
reader-writer
rmt
serial
spi
statistics
system
tls
uart
uuid
writer
zlib

Class DataBlock

extends Object
A Bluetooth data block.
Data blocks are used in advertising data (AD) and scan response data (SRD) to provide information about the device. They are also used in an extended inquiry response (EIR), additional controller advertising data (ACAD), and OOB data blocks.
The possible types are listed in section 2.3 of the Bluetooth "Assigned Numbers" document: https://www.bluetooth.com/specifications/assigned-numbers/
The core specification supplement discusses the encoding of the data: https://www.bluetooth.com/specifications/specs/core-specification-supplement/

Class summary

constructor type/int data/ByteArray
Constructs a new advertisement data field.

Constructors

constructor type/int data/ByteArray
Constructs a new advertisement data field.
No check is made to ensure that the data is valid for the given type.

Statics

decode raw/ByteArray -> List
Decodes a raw advertisement data packet into a list of data blocks.
If the data is invalid, a raw data block is created with the remaining data.
flags flags/int -> DataBlock
Constructs a field of flags for discovery.
Each bit of the flags value encodes a boolean.
Bit 0: LE Limited Discoverable Mode, BLE-ADVERTISE-FLAGS-LIMITED-DISCOVERY.
Bit 1: LE General Discoverable Mode, BLE-ADVERTISE-FLAGS-GENERAL-DISCOVERY.
Bit 2: BR/EDR Not Supported (i.e., bit 37 of LMP Feature Mask Page 0). "BR/EDR" is the Bluetooth Classic radio, and not supported by Toit. BLE-ADVERTISE-FLAGS-BREDR-UNSUPPORTED.
Bit 3: Simultaneous LE and BR/EDR to Same Device Capable (controller).
Bit 4: Previously Used.
The flags field may be 0 or multiple octets long. Currently, only the first octet is used.
The flags field must not be present in the scan response data; only in the advertising data.
The flags field is optional and may only be present once.
flags --limited-discovery/True --bredr-supported/bool=false -> DataBlock
Variant of DataBlock.flags.
Allows to specify some flags using named arguments.
flags --general-discovery/True --bredr-supported/bool=false -> DataBlock
Variant of DataBlock.flags.
Allows to specify some flags using named arguments.
manufacturer-specific manufacturer-data/Data --company-id/ByteArray=#[0xFF, 0xFF] -> DataBlock
Constructs a field with manufacturer specific data.
This field is optional and may appear multiple times.
The company-id is a 16-bit value that is assigned by the Bluetooth SIG. The value 0xFFFF is reserved for internal use.
name name/string --shortened/bool=false -> DataBlock
Constructs a field with the name of the device.
If shortened is true, then the name is not complete. The complete name may be retrieved by reading the device name characteristic after the connection has been established using GATT.
It might also be allowed to have an incomplete name in the advertising data, and the complete name in the scan response. The specification isn't clear on this.
If an incomplete name is provided, it must be a prefix of the complete name.
The name field is optional and may only be present once.
raw data/ByteArray -> DataBlock
Constructs a raw data block.
This block is written without the usual length and type fields, but verbatim as it is.
This constructor is used as an escape hatch when a data block cannot be decoded. It should not be used for normal data blocks.
service-data uuid/BleUuid service-data/Data -> DataBlock
Constructs a field with data for a service UUID.
This field consists of a service UUID with the data associated with that service.
This field is optional and may appear multiple times.
services-128 uuids/List --incomplete/bool=false -> DataBlock
Constructs a field with a list of 128-bit service UUIDs.
See DataBlock.services-16 for more information.
services-16 uuids/List --incomplete/bool=false -> DataBlock
Constructs a field with a list of 16-bit service UUIDs.
If incomplete is true, then the list is incomplete.
Omitting the service UUIDs is equivalent to providing an empty *incomplete* list. Provide an empty list to indicate that no service UUIDs are present.
UUID service fields are optional. Only one field per size (16, 32, 128 bits) may be present.
The specification is not clear on whether the advertising data may contain an incomplete list of service UUIDs and the scan response contain the complete list.
services-32 uuids/List --incomplete/bool=false -> DataBlock
Constructs a field with a list of 32-bit service UUIDs.
See DataBlock.services-16 for more information.
tx-power-level tx-power-level/int -> DataBlock
Constructs a field with the transmit power level.
The transmit power level is the power level at which the packet was transmitted.
The power level may be used to calculate path loss on a received packet using the following equation: path-loss = tx-power - rssi (where 'rssi' is the received signal strength indicator).
For example, if the TX power level is +4 (dBm) and the RSSI on the received packet is -60 (dBm) the the total path loss is +4 - (-60) = +64 dB.
The TX power level field is optional.
TYPE-FLAGS -> any
TYPE-RAW -> any
A raw data block.
This block is written without the usual length and type fields, but verbatim as it is.

Methods

contains-service uuid/BleUuid -> bool
Returns whether this data block contains the given service UUID.
flags -> int
Returns the value of the flags field.
See DataBlock.flags for more information on the bits.
is-flags -> bool
Whether this data block encodes the flags field (TYPE-FLAGS).
is-manufacturer-specific -> bool
Whether this data block encodes manufacturer specific data.
is-name -> bool
Whether this data block encodes a name (TYPE-NAME-SHORTENED or TYPE-NAME-COMPLETE).
Check the type against TYPE-NAME-COMPLETE to know whether the name is complete.
is-service-data -> bool
Whether this data block encodes data for a service UUID.
is-service-data-for uuid/BleUuid -> bool
Whether this data block encodes data for the given uuid.
is-services -> bool
Whether this data block encodes service uuids.
This is a convenience function that checks all three types of service UUIDs.
See is-services-16, is-services-32, and is-services-128.
is-services-128 -> bool
Whether this data block encodes 128-bit service UUIDs.
See is-services-16.
is-services-16 -> bool
Whether this data block encodes service UUIDs.
Check the type against TYPE-SERVICE-UUIDS-16-COMPLETE to know whether the list is complete.
is-services-32 -> bool
Whether this data block encodes 32-bit service UUIDs.
See is-services-16.
is-tx-power-level -> bool
Whether this data block encodes the transmit power level (TYPE-TX-POWER-LEVEL).
manufacturer-specific [block] -> any
Calls the given block with the company ID and manufacturer specific data.
Returns the result of calling the block.
See DataBlock.manufacturer-specific for more information.
name -> string
Returns the (possibly shortened) name of the device.
If the name is incomplete, it is a prefix of the complete name.
Check the type against TYPE-NAME-COMPLETE to know whether the name is complete.
operator == other/any -> bool
service-data [block] -> any
Calls the given block with the UUID and data of the service data block.
Returns the result of calling the block.
See DataBlock.service-data for more information.
services -> List
Returns a list of service UUIDs.
This is a convenience function that checks all three types of service UUIDs.
See services-16, services-32, and services-128.
services-128 -> List
Returns a (potentially incomplete) list of 128-bit service UUIDs.
See services-16.
services-16 -> List
Returns a (potentially incomplete) list of 16-bit service UUIDs.
Check the type against TYPE-SERVICE-UUIDS-16-COMPLETE to know whether the list is complete.
See DataBlock.services-16 for more information.
services-32 -> List
Returns a (potentially incomplete) list of 32-bit service UUIDs.
See services-16.
size -> int
The size of the data block in bytes.
stringify --add-prefix/bool=true -> string
to-raw -> ByteArray
Converts this data block to a raw byte array.
tx-power-level -> int
Returns the transmit power level.
See DataBlock.tx-power-level for more information.
write bytes/ByteArray --at/int [--on-error] -> int
Deprecated. Use write bytes --at [--if-error] instead.
write bytes/ByteArray --at/int [--if-error] -> int
Writes this field into the given bytes at the given position at.

Fields

data / ByteArray
The data of the data block.
type / int
The type of the data block.
The types are defined in the Bluetooth "Assigned Numbers" document: https://www.bluetooth.com/specifications/assigned-numbers/, section 2.3.
Some types have constants defined in this class: TYPE-FLAGS, ...