characteristics

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

class Characteristic(*, uuid=None, properties=0, read_perm=0, write_perm=0, max_length=None, fixed_length=False, initial_value=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=None, properties=0, read_perm=0, write_perm=0, max_length=20, fixed_length=False, initial_value=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)

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

class StructCharacteristic(struct_format, *, uuid=None, properties=0, read_perm=0, write_perm=0, initial_value=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, min_value, max_value, *, uuid=None, properties=0, read_perm=0, write_perm=0, initial_value=None)

Superclass for different kinds of integer fields.

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

Int8 number.

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

Uint8 number.

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

Int16 number.

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

Uint16 number.

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

Int32 number.

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

Uint32 number.

stream

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

class BoundWriteStream(bound_characteristic)

Writes data out to the peer.

write(buf)

Write data from buf out to the peer.

class StreamOut(*, uuid=None, timeout=1.0, buffer_size=64, properties=0, read_perm=0, write_perm=0)

Output stream from the Service server.

bind(service)

Binds the characteristic to the given Service.

class StreamIn(*, uuid=None, timeout=1.0, buffer_size=64, properties=0, write_perm=0)

Input stream into the Service server.

bind(service)

Binds the characteristic to the given Service.

string

This module provides string characteristics.

class StringCharacteristic(*, uuid=None, properties=0, read_perm=0, write_perm=0, initial_value=None)

UTF-8 Encoded string characteristic.

class FixedStringCharacteristic(*, uuid=None, read_perm=0)

Fixed strings are set once when bound and unchanged after.