roBtManager

11 min

this object facilitates ble one way communication (i e "beaconing") use the robtmanager object to discover whether any ble adapters are present and to send ble advertisements using the adapters the javascript equivalent is bsbtmanager docid\ cf7q7xsa9drtcq3btxv a ifmessageport setport(port as romessageport) posts messages of type robtevent to the attached message port use these messages to detect insertion or removal of bluetooth adapters ifuserdata setuserdata(user data as object) sets the user data that will be returned when events are raised getuserdata() as object retrieves an arbitrary object set via the setuserdata() method ifidentity getidentity() as integer returns a unique number that can be used to identify events that originate from the object instance the ifidentity interface has been deprecated we recommend using the ifuserdata interface instead ifbtperipheralmanager getfailurereason() as string returns additional diagnostic information if a method returns false getadapterlist() as roarray returns an array describing all available bluetooth adapters each entry in the array consists of an associative array containing adapter properties at present, each associative array contains a single name property that describes the adapter name use this method to determine if bluetooth adapters are connected to the player available as of bos 9 0 198 and 9 1 21, this endpoint includes a boolean field in the returned array of adapter elements which indicates if the device is on or off stopadvertising() as boolean stops all ble advertisements this method returns true on success and false on failure getadvertisinglist() as roarray returns an array describing all active bluetooth advertisements each entry in the array consists of an associative array describing a single advertisement the associative array values correspond to the properties set using the startadvertising() method, but can also include default parameter values that were not set explicitly note that all uuid values will be returned in lowercase startadvertising(data as roassociativearray) as boolean begins transmitting a ble "beacon" message this method returns true on success and false on failure each message can contain data in a standard format or arbitrary custom values the message format is specified using the mode parameter, and other required values in the associative array will depend on the value of this parameter mode "beacon" this mode uses a simple beaconing format beacon uuid 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" beacon major \int \ the 2 byte major value (0 to 65535) beacon minor \int \ the 2 byte minor value (0 to 65535) beacon level \int\ \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 beacon manufacturer \int\ \optional\ a 2 byte integer value (0 to 65535) specifying the beacon manufacturer the default value is 76 (\&h4c) connectable \bool\ \optional\ whether the advertisement should be connectable or not advertisements are non connectable by default persistent \bool\ \optional\ whether the advertisement should persist after every reboot beacon advertisements are persistent by default mode "eddystone url" this mode uses the eddystone url https //github com/google/eddystone/tree/master/eddystone url format 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 false and getfailurereason() will report "compressed url is too long" tx power \int\ \optional\ the measurement of 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 the rssi in a circle at 1 meter from the beacon, then add 41 to the average measured signal strength to get the tx power value for example, measuring a 65dbm rssi at 1 meter yields a txpower value of 2 note that the tx power value does not modify the power level of the bluetooth transmitter (this requires physical attenuation docid\ wnlbaqwos9ev7ditddcnh ) rather, the tx power value is transmitted to bluetooth clients in the ble advertisement clients can then compare this value to the current rssi of the signal to determine their approximate distance from the beacon connectable \bool\ \optional\ whether the advertisement should be connectable or not advertisements are non connectable by default persistent \bool\ \optional\ whether the advertisement should persist after every reboot eddystone url advertisements are persistent by default mode "eddystone uid" this mode uses the eddystone uid https //github com/google/eddystone/tree/master/eddystone uid format namespace a 10 byte value expressed as 20 hexadecimal digits instance a 6 byte value expressed as 12 hexadecimal digits tx power \int\ \optional\ specifies 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 \bool\ \optional\ whether the advertisement should be connectable (for gatt or other services) advertisements are non connectable by default persistent \bool\ \optional\ whether the advertisement should persist after every reboot eddystone url advertisements are not persistent by default mode "custom" this mode supports arbitrary custom data in a vendor specific field cutom manufacturer data \optional \ an associative array containing two keys manufacturer a 2 byte integer value (0 to 65535) data an robytearray instance containing data service uuid \optional\ a set of serviceuuid elements, which can be specified as either an array of uuid strings or an array of associative arrays containing a uuid key/value pair each associative array can also contain a data key, which specifies servicedata as an robytearray instance connectable \bool\ \optional\ whether the advertisement should be connectable or not advertisements are non connectable by default persistent \bool\ \optional\ whether the advertisement should persist after every reboot custom advertisements are not persistent by default to specify multiple advertisements, pass an array of associative arrays to the startadvertising() method advertisements will be sent in rotation the method will fail if one or more advertisement is incorrect—try each advertisement individually and call getfailurereason() to determine which advertisement is causing the error calling the startadvertising() method will replace any previous advertisements you can change a list of advertisements by modifying the array and calling startadvertising() again examples this script uses robtmanager getadapterlist() to determine if there are any bluetooth adapters available btm = createobject("robtmanager") if btm getadapterlist() count() > 0 then print "bluetooth available" this script constructs two associative arrays for advertising with the "beacon" format and then broadcasts them both adv1 = { mode "beacon", beacon uuid "41fac2b21 c8cb 41e7 b011 12d1016dd39e", beacon major 400, beacon minor 22 } adv2 = { mode "beacon", beacon manufacturer \&h4c, beacon uuid "41fac221 c8cb 41e7 b011 12d1016dd39e", beacon major \&h1234, beacon minor \&hff01, beacon level 50 } advlist = \[adv1, adv2] bm startadvertising(advlist) the associative array can also be constructed in parts adv1 = { mode "beacon"} adv1 append({ beacon uuid "41fac221 c8cb 41e7 b011 12d1016dd39e" }) adv1 append({ beacon major 32000, beacon minor 100 }) this script constructs an advertisement with the "eddystone url" format it uses the optional tx power parameter as well adv1 = { mode "eddystone url", url "http //www brightsign biz", tx power 24} this script constructs a custom formatted advertisement custom adv = createobject("robytearray") custom adv fromhexstring("0215434b2eb8c28f40898e7a1e644bb13b9fa000b001c5") adv2 = { mode "custom", custom manufacturer data { manufacturer \&h4c, data custom adv } }