nodemcu-firmware/docs/modules/bthci.md

BT HCI Module

Since	Origin / Contributor	Maintainer	Source
2016-09-29	DiUS, Johny Mattsson	Johny Mattsson	bthci.c

The BT HCI module provides a minimal HCI-level interface to BlueTooth adverisements. Via this module you can set up BT LE advertisements and also receive advertisements from other devices.

Advertisements are an easy way of publishing sensor data to e.g. a smartphone app.

bthci.rawhci(hcibytes, callback)

Sends a raw HCI command to the BlueTooth controller.

Only intended for development use.

Syntax

bthci.rawhci(hcibytes [, callback])

Parameters

• hcibytes raw HCI command bytes to send to the BlueTooth controller.
• callback optional function to be invoked when the reset completes. Its first argument is the HCI error code, or nil on success. The second argument contains any subsequent raw result bytes, or an empty string if the result only contained the status code.

Returns

nil

Example

-- Send a HCI reset command (it would be easier to use bthci.reset() though)
bthci.rawhci(encoder.fromHex("01030c00"), function(err) print(err or "Ok!"))

See also

encoder.fromHex() encoder.toHex() struct.pack()

bthci.reset(callback)

Resets the BlueTooth controller.

Syntax

bthci.reset([callback])

Parameters

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

Returns

nil

Example

bthci.reset(function(err) print(err or "Ok!") end)

bthci.adv.enable(onoff, callback)

Enables or disables BlueTooth LE advertisements.

Before enabling advertisements, both parameters and data should be set.

Syntax

bthci.adv.enable(onoff [, callback])

Parameters

• onoff 1 or 0 to enable or disable advertisements, respectively.
• callback optional function to be invoked when the reset completes. Its only argument is the HCI error code, or nil on success.

Returns

nil

Example

bthci.adv.enable(1, function(err) print(err or "Ok!") end)

bthci.adv.setdata(advbytes, callback)

Configures the data to advertise.

Syntax

bthci.adv.setdata(advbytes [, callback])

Parameters

• advbytes the raw bytes to advertise (up to 31 bytes), in the correct format (consult the BlueTooth specification for details).
• callback optional function to be invoked when the reset completes. Its only argument is the HCI error code, or nil on success.

Returns

nil

Example

-- Configure advertisements of a short name "abcdefg"
bthci.adv.setdata(encoder.fromHex("080861626364656667"), function(err) print(err or "Ok!") end)

bthci.adv.setparams(paramtable, callback)

Configures advertisement parameters.

Syntax

bthci.adv.setparams(paramtable [, callback])

Parameters

• paramtable a table with zero or more of the following fields:
  • interval_min value in units of 0.625ms. Default 0x0400 (0.64s).
  • interval_max value in units of 0.625ms. Default 0x0800 (1.28s).
  • type advertising type, one of following constants:
    • bthci.adv.CONN_UNDIR, the default (ADV_IND in BT spec)
    • bthci.adv.CONN_DIR_HI (ADV_DIRECT_IND, high duty cycle in the BT spec)
    • bthci.adv.SCAN_UNDIR (ADV_SCAN_IND in the BT spec)
    • bthci.adv.NONCONN_UNDIR (ADV_NONCONN_IND in the BT spec)
    • bthci.adv.CONN_DIR_LO (ADV_DIRECT_IND, low duty cycle in the BT spec)
  • own_addr_type own address type. Default 0 (public address).
  • peer_addr_type peer address type. Default 0 (public address).
  • peer_addr TODO, not yet implemented
  • channel_map which channels to advertise on. The constants bthci.adv.CHAN_37, bthci.adv.CHAN_38, bthci.adv.CHAN_39 or bthci.adv.CHAN_ALL may be used. Default is all channels.
  • filter_policy filter policy, default 0 (no filtering).
• callback optional function to be invoked when the reset completes. Its only argument is the HCI error code, or nil on success.

Returns

nil

Example

bthci.adv.setparams({type=bthci.adv.NONCONN_UNDIR}, function(err) print(err or "Ok!") end)

bthci.scan.enable(onoff, callback)

Enables or disable scanning for advertisements from other BlueTooth devices.

Syntax

bthci.scan.enable(onoff [, callback])

Parameters

• onoff 1 or 0 to enable or disable advertisements, respectively.
• callback optional function to be invoked when the reset completes. Its only argument is the HCI error code, or nil on success.

Returns

nil

Example

bthci.scan.enable(1, function(err) print(err or "Ok!") end)

bthci.scan.setparams(paramstable, callback)

Configures scan parameters.

Note that if configuring the scan window to be the same as the scan interval this will fully occupy the radio and no other activity takes place.

Syntax

bthci.scan.setparams(paramstable [, callback])

Parameters

• paramstable a table with zero or more of the following fields:
  • mode scanning mode, 0 for passive, 1 for active. Default 0.
  • interval scanning interval in units of 0.625ms. Default 0x0010.
  • window length of scanning window in units of 0.625ms. Default 0x0010.
  • own_addr_type own address type. Default 0 (public).
  • filter_policy filtering policy. Default 0 (no filtering).
• callback optional function to be invoked when the reset completes. Its only argument is the HCI error code, or nil on success.

Returns

nil

Example

bthci.scan.setparams({mode=1,interval=40,window=20},function(err) print(err or "Ok!") end)

bthci.scan.on(event, callback)

Registers the callback to be passed any received advertisements.

Syntax

bthci.scan.on(event [, callback])

Parameters

• event the string describing the event. Currently only "adv_report" is supported, to register for advertising reports.
• callback the callback function to receive the advertising reports, or nil to deregister the callback. This callback receives the raw bytes of the advertisement payload.

Returns

nil

Example

bthci.scan.on("adv_report", function(rep) print("ADV: "..encoder.toHex(rep))end)

See also

encoder.toHex() struct.unpack()