Skip to main content

bluetooth.startadvertise(advert, minAdInterval, maxAdInterval, scanResponse)

Causes the imp to begin transmitting GAP advertisements

Availability

Device
Only available on the imp004m (impOS 38+) and imp006 (impOS 42+)

Parameters

Name Type Description
advert String or blob The advertising data, up to 31 bytes in length
minAdInterval Integer The minimum advertising interval in milliseconds (ms)
maxAdInterval Integer The maximum advertising interval in milliseconds (ms)
scanResponse String or blob Optional data the be returned in response to an external scan

Returns

Nothing

Description

This method causes a compatible imp to begin broadcasting Generic Access Profile (GAP) advertisements. It may be called as many times as you need to update the data broadcast and/or the data with which the imp responds to a scan. Advertising continues while the data is being updated.

The value passed into advert comprises up to 31 bytes of advertising data. It is the application’s responsibility to ensure the data meets the Bluetooth advertising and scan response data specification — this method will broadcast whatever data you pass in.

The parameters minAdInterval and maxAdInterval respectively set the minimum and maximum advertising interval. The values provided must lie in the range 20ms to 10,240ms, and minAdInterval must not be greater than maxAdInterval.

The data passed into scanResponse comprises up to 31 bytes of response data. It is the application’s responsibility to ensure the data meets the Bluetooth advertising and scan response data specification — this method will broadcast whatever data you pass in.

bluetooth.startadvertise() automatically sets up the advertisement type according to the following rules:

  • ADV_IND if bluetooth.onconnect() has a current connection function registered, or
  • ADV_SCAN_IND if a scanRespsonse is set, or
  • ADV_NONCONN_IND otherwise

Example Code

The following code sets the imp004m up as a Bluetooth transmitter operating to the Apple iBeacon specification, which uses a 31-byte advertisement of a pre-set format: after the iBeacon preamble data, bytes 9 through 25 contain the iBeacon’s ‘proximity’ UUID; bytes 26 and 27 a major value; bytes 28 and 29 a minor value; and byte 30 a calibrated RSSI value. All iBeacons in the same site typically use the same UUID, with the major and minor values used to identify specific beacons, eg. major for floor number, minor for beacon on a given floor.

local iBeacon = "\x02\x01\x06\x1A\xFF\x4C\x00\x02\x15\x92\x77\x83\x0A\xB2\xEB\x49\x0F\xA1\xDD\x7F\xE3\x8C\x49\x2E\xDE\x00\x01\x00\x02\xC5";

local uuid = "";
for (local i = 0 ; i < iBeacon.len() ; i++) {
    uuid += format("%02x", iBeacon[i]);
}

server.log("Advertising the following iBeacon:");
server.log("UUID: " + uuid.slice(18,26) + "-" + uuid.slice(26,30) + "-" + uuid.slice(30,34) + "-" + uuid.slice(34,38) + "-" + uuid.slice(38,50));
server.log("Major: " + uuid.slice(50,54));
server.log("Minor: " + uuid.slice(54,58));

bt.startadvertise(iBeacon, 100, 100);

The following code sets the imp004m up as an iBeacon advertiser as above, but this time we add a scan response which will be requested by the scanning device. See bluetooth.startscan() to see how the response can be read.

// Set iBeacon ad package
local iBeacon = "\x02\x01\x06\x1A\xFF\x4C\x00\x02\x15\x92\x77\x83\x0A\xB2\xEB\x49\x0F\xA1\xDD\x7F\xE3\x8C\x49\x2E\xDE\x00\x01\x00\x02\xC5";

// Create the scan response: first, the flags
local scanResponse = "\x02\x01\x06";

// Add a service UUID
// NOTE The second '\x03' is the data type: 'complete list of 16-bit UUIDs'
scanResponse += "\x03\x03\xFF\x00";

// Finally, add the device's ID as a local name
// NOTE '\x09' is the data type: 'complete local name'
local name = hardware.getdeviceid();
local nameDataLength = name.len() + 1;
scanResponse += (nameDataLength.tochar() + "\x09" + name);

bt.startadvertise(iBeacon, 100, 100, scanResponse);