223 lines
6.4 KiB
Markdown
223 lines
6.4 KiB
Markdown
# BT HCI Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2016-09-29 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [bthci.c](../../components/modules/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
|
|
```lua
|
|
-- 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.md#fromhex)
|
|
[`encoder.toHex()`](encoder.md#tohex)
|
|
[`struct.pack()`](struct.md#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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
-- 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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
bthci.scan.on("adv_report", function(rep) print("ADV: "..encoder.toHex(rep))end)
|
|
```
|
|
|
|
#### See also
|
|
[`encoder.toHex()`](encoder.md#tohex)
|
|
[`struct.unpack()`](struct.md#unpack)
|
|
|