characteristics

This module provides core BLE characteristic classes that are used within Services.

class Characteristic(*, uuid: UUID | None = None, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int | None = None, fixed_length: bool = False, initial_value: ReadableBuffer | None = None)

Top level Characteristic class that does basic binding.

Parameters:

  • uuid (UUID) – The uuid of the characteristic

  • properties (int) – The properties of the characteristic, specified as a bitmask of these values bitwise-or’d together: BROADCAST, INDICATE, NOTIFY, READ, WRITE, WRITE_NO_RESPONSE.

  • read_perm (int) – Specifies whether the characteristic can be read by a client, and if so, which security mode is required. Must be one of the integer values Attribute.NO_ACCESS, Attribute.OPEN, Attribute.ENCRYPT_NO_MITM, Attribute.ENCRYPT_WITH_MITM, Attribute.LESC_ENCRYPT_WITH_MITM, Attribute.SIGNED_NO_MITM, or Attribute.SIGNED_WITH_MITM.

  • write_perm (int) – Specifies whether the characteristic can be written by a client, and if so, which security mode is required. Values allowed are the same as read_perm.

  • max_length (int) – Maximum length in bytes of the characteristic value. The maximum allowed by the BLE specification is 512. On nRF, if fixed_length is True, the maximum is 510. The default value is 20, which is the maximum number of data bytes that fit in a single BLE 4.x ATT packet.

  • fixed_length (bool) – True if the characteristic value is of fixed length.

  • initial_value (buf) – The initial value for this characteristic. If not given, will be filled with zeros.

BROADCAST

property: allowed in advertising packets

INDICATE

property: server will indicate to the client when the value is set and wait for a response

NOTIFY

property: server will notify the client when the value is set

READ

property: clients may read this characteristic

WRITE

property: clients may write this characteristic; a response will be sent back

WRITE_NO_RESPONSE

property: clients may write this characteristic; no response will be sent back

class ComplexCharacteristic(*, uuid: UUID | None = None, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: ReadableBuffer | None = None)

Characteristic class that does complex binding where the subclass returns a full object for interacting with the characteristic data. The Characteristic itself will be shadowed once it has been bound to the corresponding instance attribute.

bind(service: Service) → _bleio.Characteristic

Binds the characteristic to the local Service or remote Characteristic object given.

class StructCharacteristic(struct_format, *, uuid: UUID | None = None, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, initial_value: ReadableBuffer | None = None)

Data descriptor for a structure with a fixed format.

Parameters:

int

This module provides integer characteristics that are usable directly as attributes.

class IntCharacteristic(format_string: str, min_value: int, max_value: int, *, uuid: UUID | None = None, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, initial_value: ReadableBuffer | None = None)

Superclass for different kinds of integer fields.

class Int8Characteristic(*, min_value: int = -128, max_value: int = 127, **kwargs)

Int8 number.

class Uint8Characteristic(*, min_value: int = 0, max_value: int = 255, **kwargs)

Uint8 number.

class Int16Characteristic(*, min_value: int = -32768, max_value: int = 32767, **kwargs)

Int16 number.

class Uint16Characteristic(*, min_value: int = 0, max_value: int = 65535, **kwargs)

Uint16 number.

class Int32Characteristic(*, min_value: int = -2147483648, max_value: int = 2147483647, **kwargs)

Int32 number.

class Uint32Characteristic(*, min_value: int = 0, max_value: int = 4294967295, **kwargs)

Uint32 number.

float

This module provides float characteristics that are usable directly as attributes.

class FloatCharacteristic(*, uuid: UUID | None = None, properties: int = 0, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, initial_value: ReadableBuffer | None = None)

32-bit float

stream

This module provides stream characteristics that bind readable or writable objects to the Service object they are on.

class BoundWriteStream(bound_characteristic: Characteristic)

Writes data out to the peer.

write(buf: ReadableBuffer) → None

Write data from buf out to the peer.

class StreamOut(*, uuid: UUID | None = None, timeout: float = 1.0, buffer_size: int = 64, properties: int = 4, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN)

Output stream from the Service server.

bind(service: Service) → _bleio.CharacteristicBuffer | BoundWriteStream

Binds the characteristic to the given Service.

class StreamIn(*, uuid: UUID | None = None, timeout: float = 1.0, buffer_size: int = 64, properties: int = 48, write_perm: int = Attribute.OPEN)

Input stream into the Service server.

bind(service: Service) → _bleio.CharacteristicBuffer | BoundWriteStream

Binds the characteristic to the given Service.

string

This module provides string characteristics.

class StringCharacteristic(*, uuid: UUID | None = None, properties: int = 8, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, initial_value: ReadableBuffer | None = None)

UTF-8 Encoded string characteristic.

class FixedStringCharacteristic(*, uuid: UUID | None = None, read_perm: int = Attribute.OPEN)

Fixed strings are set once when bound and unchanged after.