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()