nodemcu-firmware/docs/modules/ble.md

BT HCI Module

Since	Origin / Contributor	Maintainer	Source
2021-10-10	pjsg	pjsg	ble.c

The BLE module provides a simple interface to allow implementation of a simple GAP/GATT server. This allows you to build simple gadgets that can be interrogated and controlled over BLE.

ble.init(configuration)

This initializes the BlueTooth stack and starts advertising according to the data in the configuration table. See below for a detailed description of this table.

At the present time, you can only call the init function once. There is some problem in the underlying implementation of the BLE stack that prevents a init, shutdown, init sequence from working.

Syntax

ble.init(ble_config)

Parameters

• ble_config A table with the keys as defined below.

Returns

nil

Example

function read_battery_level()
  -- This ought to do something better!
  return 50
end
local battery = { uuid="180f", characteristics={ {uuid="2a19", type='B', read=read_battery_level} } }
local myservice = {uuid="0123456789abcdef0123456789abcdef", characteristics={{uuid="1234", value=0, type='c'}}}
local config = {name="MyGadget=", services={ myservice, battery }
ble.init(config)

ble.advertise()

Updates the advertising data field for future advertising frames.

Syntax

ble.advertise(advertisement)

Parameters

• advertisement This string will be placed in future advertising frames as the manufacturer data field. This overrides the aadvertisement value from the config block.

Returns

nil

Example

ble.advertise("foo")

ble.shutdown()

Shuts down the BlueTooth controller and returns it to the state where another init ought to work (but currently doesn't).

Syntax

ble.shutdown()

Returns

nil

Example

ble.shutdown()

Conventions

UUID

The service and characteristic identifiers are UUIDs. These are represented in twin-hex. They must be either 4 characters, 8 characters or 32 characters long.

Configuration Table

The configuration table contains the following keys:

• name The name to use to advertise the gadget

• services This is a list of tables that define the individual services. The primary service is the first service. Many examples will only have a single service.

• advertisement This is a string to be advertised in the mfg data field.

Service table

The service table contains the following keys:

• uuid The UUID of the service. This is a 16 byte string (128 bits) that identifies the particular service. It can also be a two byte string for a well-known service.
• characteristics This is a list of tables, where each entry describes a characateristic (attribute)

Characteristic table

The characteristic table contains the following keys:

• uuid The UUID of the characteristics. This can be either a 16 byte string or a 2 byte string that identifies the particular characteristic. Typically, 2 byte strings are used for well-known characteristics.
• type This is the optional type of the value. It has the same value as a unpack code in the struct module.
• value This is the actual value of the characteristic. This will be a string of bytes unless a type value is set.
• read This is a function that will be invoked to read the value (and so does not need the value entry). It should return a string of bytes (unless type is set).
• write This is a function that will be invoked to write the value (and so does not need the value entry). It is given a string of bytes (unless type is set)

If the value key is present, then the characteristic is read/write. However, if one or read or write is set to true, then it restricts access to that mode.

The characteristics are treated as read/write unless only one of the read or write keys is present and the value key is not specified.

The calling conventions for these functions are as follows:

• read This is invoked with the characteristic table as its only argument.
• write This is invoked with two arguments, the characteristic table and the data to be written (after conversion by type)

Example

function read_attribute(t)
  return something
end

function write_attribute(t, val)
  -- Just store the written value in the table.
  t.value = val
end

Type conversions

If the type value converts a single item, then that will be the value that is placed into the value element. If it converts multiple elements, then the elements will be placed into an array that that will be plaed into the value element.