nodemcu-firmware/docs/modules/ble.md

BT HCI Module

Since	Origin / Contributor	Maintainer	Source
2021-10-10	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.

Syntax

ble.init(ble_config)

Parameters

• ble_config A table with the keys as defined below.

Returns

nil

Example

local config = {name="MyGadget=", services={{uuid="0123456789abcdef0123456789abcdef", characteristics={{uuid="1234", value=0, type='c'}}}}}
ble.init(config)

bthci.shutdown(callback)

Shuts down the BlueTooth controller and returns it to the state where another init can be performed.

Syntax

ble.shutdown([callback])

Parameters

• callback optional function to be invoked when the shutdown completes. Its only argument is an error code, or nil on success.

Returns

nil

Example

ble.shutdown(function(err) print(err or "Ok!") end)

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.

• mfg 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)

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

The calling conventions for these functions are as follows:

• read This is invoked with the charactersitic 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)