BSBtManager

11 min

use the bsbtmanager object to discover whether any ble adapters are present and to receive events (for example, when adapters are added or removed) it can also be used to retrieve and modify bluetooth advertising attributes the bsbtmanager object has the following attribute readonly attribute array adapters a list of all available bluetooth adapters if this list is empty, there are no adapters present events use the onbtevent() callback to receive events "add adapter" an adapter has been added the value reports the name of the adapter "startup complete" the initial advertising list has been built this event is sent after any initial "add adapter" events applications should wait for this event before detecting a missing adapter "remove adapter" an adapter has been removed the value reports the name of the adapter "update advertising" bluetooth advertising has changed the value identifies the source of the change (from "brightscript" or "javascript") if your script maintains a variable containing the advertising list, this event indicates that it may need to be refreshed since additional events may be added in the future, your script should have the capacity to handle unrecognized events example btm onbtevent = function (ev) { console log("event " + ev name + "; parameter " + ev parameter); } methods the bsbtmanager object has the following methods object getcurrentadvertising() returns a bsbtadvertisementlist object containing current advertisement parameters boolean startadvertising(in object advertisement list) begins sending ble advertisements using the specified bsbtadvertisementlist object calling this method will replace all previous advertisements, including persistent advertisements, regardless of whether they were set from javascript or brightscript to preserve advertisements, retrieve the current bsbtadvertisementlist and make changes as needed before passing it to startadvertising() stopadvertising(new bsbtadvertisementlist()) stops all advertisements void close() shuts down the instance, preventing it from further consuming resources if this method is not called, garbage collection determines when the instance will be destroyed bsbtadvertisementlist the bsbtadvertisementlist object is a container for bsbtadvertisement objects elements can be added to the end of the list using push() or removed using pop() existing elements can be accessed with indexing bsbtadvertisement the bsbtadvertisement object represents a single ble advertisement it supports advertising data in standard formats or arbitrary custom values standard format values can be initialized on construction using a dictionary, but advanced custom fields must be set on the object supported modes are described below beacon format this mode uses a simple beaconing format mode "beacon" beaconuuid a string representation of a uuid, which can be in 16 bit, 32 bit, or 128 bit format a 16 bit uuid must be exactly four hex digits with no punctuation; a 32 bit uuid must be exactly eight hex digits with no punctuation; and a 128 bit uuid must be punctuated exactly as follows "cd7b6f81 f738 4cad aebf d2a2ea36d996" beaconmajor an integer specifying the 2 byte major value (0 to 65535) beaconminor an integer specifying the 2 byte minor value (0 to 65535) beacon level (optional) an 8 bit signed integer ( 127 to 128) that corresponds to the measurement of the tx power level (in dbm) at 1 meter the default level is 60 beaconmanufacturer (optional) a 2 byte integer value (0 to 65535) specifying the beacon manufacturer the default value is 76 (\&h4c) connectable (optional) a boolean value indicating whether the advertisement should be connectable (for gatt or other services) advertisements are non connectable by default persistent (optional) a boolean value indicating whether the advertisement should persist after every reboot beacon advertisements are not persistent by default eddystone url format this mode uses the eddystone url https //github com/google/eddystone/tree/master/eddystone url format mode "eddystone url" url the url to encapsulate in the advertisement packet if the url is too long to fit in the packet, the startadvertising() call will return an aborterror exception that includes the description "compressed url is too long" tx power (optional) an integer value specifying the tx power level in dbm at 0 meters the default value is 19, which corresponds to a level of 60dbm at 1 meter the recommended calibration practice is to measure at 1 meter and add 41 for example, 65dbm rssi leads to a value of 24 connectable (optional) a boolean value indicating whether the advertisement should be connectable (for gatt or other services) advertisements are non connectable by default persistent (optional) a boolean value indicating whether the advertisement should persist after every reboot eddystone url advertisements are not persistent by default eddystone uid format this mode uses the eddystone uid https //github com/google/eddystone/tree/master/eddystone uid format mode "eddystone uid" namespace a 10 byte value expressed as 20 hexadecimal digits instance a 6 byte value expressed as 12 hexadecimal digits tx power (optional) an integer value specifying the tx power level in dbm at 0 meters the default value is 19, which corresponds to a level of 60dbm at 1 meter the recommended calibration practice is to measure at 1 meter and add 41 for example, 65dbm rssi leads to a value of 24 connectable (optional) a boolean value indicating whether the advertisement should be connectable (for gatt or other services) advertisements are non connectable by default persistent (optional) a boolean value indicating whether the advertisement should persist after every reboot eddystone url advertisements are not persistent by default custom format this mode supports arbitrary custom data binary fields are specified as hexadecimal encoded strings (e g the decimal values 12, 128 would be specified as "0c80") all lists support push() / pop() calls and indexing duplicate values should not be included mode "custom" manufacturerdata (optional) a bsbtmanufacturerdata object containing the following fields manufacturer an unsigned 16 bit integer value data binary data serviceuuid (optional) a list of uuid strings servicedata (optional) a bsbtuuiddata object containing the following fields uuid the uuid string data binary data soliciituuid (optional) a list of uuid strings connectable (optional) a boolean value indicating whether the advertisement should be connectable (for gatt or other services) advertisements are non connectable by default persistent (optional) a boolean value indicating whether the advertisement should persist after every reboot custom advertisements are not persistent by default examples this script configures a simple advertisement and an eddystone url advertisement and then begins advertising ads = new bsbtadvertisementlist(); ad1 = new bsbtadvertisement({ mode "beacon", beaconuuid "41fac221 c8cb 41e7 b011 12d1016dd39e", beaconmajor 400, beaconminor 123}); ads push(ad1); ad2 = new bsbtadvertisement({ mode "eddystone url", url "http //www brightsign biz"}) ads push(ad2); btm startadvertising(ads); this script finds beacons matching a uuid and forms a string with major/minor codes s = ""; for(i = 0; i < adlist length; i++) { 	if (adlist\[i] mode == "beacon" 	 && adlist\[i] beaconuuid == "434b2eb8 c28f 4089 8e7a 1e644bb13b9f") { 	 s = s + "beacon " + adlist\[i] beaconmajor + "," + adlist\[i] beaconminor + " " 	 } } this script looks for eddystone url beacons and sends updates based on the current url btm = new bsbtmanager() adlist = btm getcurrentadvertising() for(i = 0; i < adlist length; i++) { 	// brightsign biz is now https 	 if (adlist\[i] mode == "eddystone url" && adlist\[i] url == "http //www brightsign biz") { 	 adlist\[i] url = "https //www brightsign biz" 	 } } btm startadvertising(adlist) this script produces an exception because the compressed url is too long al = new bsbtadvertisementlist() ad4 = new bsbtadvertisement( { mode "eddystone url", url "http //www brightsign biz/thisistoolong"} ) al push(ad4) b startadvertising(al)