support for buffer signature (#325)

docs/reference/bluetooth.md

@@ -35,7 +35,8 @@ bluetooth.uartWriteValue("", 0);
 ## Eddystone
 
 ```cards
-bluetooth.advertiseUrl("https://pxt.microbit.org/", 7);
+bluetooth.advertiseUid(42, 1, 7, true);
+bluetooth.advertiseUrl("https://pxt.microbit.org/", 7, true);
 bluetooth.stopAdvertising();
 ```
 

docs/reference/bluetooth/advertise-uid-buffer.md

@@ -0,0 +1,37 @@
+# Avertise UID Buffer
+
+Advertises a UID via the Eddystone protocol over Bluetooth.
+
+## ~hint
+
+### Eddystone
+
+Bluetooth beacons are used to indicate proximity to a place or object of interest. 
+Beacons use Bluetooth advertising to broadcast a small amount of data, 
+which can be received and acted upon by anyone in range with a suitable device and software, typically a smartphone and application.
+
+There are various beacon message formats, which define the way Bluetooth advertising packets are used as containers for beacon data. 
+iBeacon is Apple's beacon message format. Eddystone comes from Google.
+
+Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/ .
+
+## ~
+
+```sig
+bluetooth.advertiseUidBuffer(pins.createBuffer(16), 7, true);
+```
+
+### Parameters
+
+* ``buffer`` - a 16 bytes buffer containing the namespace (first 10 bytes) and instance (last 6 bytes).
+* ``power`` - a [number](/reference/types/number) representing the power level between 0 (short) and 7 (maximum range).
+* ``connectable`` - a [boolean](/reference/type/boolean) indicating whether or not the micro:bit should accept connections. 
+
+
+## See Also
+
+[stop-advertising](/reference/bluetooth/stop-advertising), [advertise-uid](/reference/bluetooth/advertise-uid)
+
+```package
+bluetooth
+```

docs/reference/bluetooth/advertise-uid.md

@@ -0,0 +1,46 @@
+# Avertise UID
+
+Advertises a UID via the Eddystone protocol over Bluetooth.
+
+## ~hint
+
+### Eddystone
+
+Bluetooth beacons are used to indicate proximity to a place or object of interest. 
+Beacons use Bluetooth advertising to broadcast a small amount of data, 
+which can be received and acted upon by anyone in range with a suitable device and software, typically a smartphone and application.
+
+There are various beacon message formats, which define the way Bluetooth advertising packets are used as containers for beacon data. 
+iBeacon is Apple's beacon message format. Eddystone comes from Google.
+
+Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/ .
+
+## ~
+
+```sig
+bluetooth.advertiseUid(42, 1, 7, true);
+```
+
+### Parameters
+
+* ``namespace`` last 4 bytes of the namespace uid (6 to 9)
+* ``instance`` last 4 bytes of the instance (2 to 5)
+* ``power`` - a [number](/reference/types/number) representing the power level between 0 (short) and 7 (maximum range).
+* ``connectable`` - a [boolean](/reference/type/boolean) indicating whether or not the micro:bit should accept connections. 
+
+## Encoding
+
+The bytes of ``namespace`` and ``instance`` are encoded to generate the 10 bytes UID namespace and 6 bytes UID instance.
+
+```
+UID namespace: [0, ..., namespace]
+UID instance: [0, ..., instance]
+```
+
+## See Also
+
+[stop-advertising](/reference/bluetooth/stop-advertising), [advertise-uid-buffer](/reference/bluetooth/advertise-uid-buffer)
+
+```package
+bluetooth
+```

docs/reference/bluetooth/advertise-url.md

@@ -18,23 +18,24 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
 ## ~
 
 ```sig
-bluetooth.advertiseUrl("https://pxt.microbit.org/", 7, true);
+bluetooth.advertiseUrl("https://pxt.microbit.org/", true);
 ```
 
 ### Parameters
 
 * ``url`` - a [string](/reference/types/string) containing the URL to broadcast, at most 17 characters long, excluding the protocol (eg: ``https://``) which gets encoded as 1 byte.
 * ``power`` - a [number](/reference/types/number) representing the power level between 0 (short) and 7 (maximum range).
+* ``connectable`` - a [boolean](/reference/type/boolean) indicating whether or not the micro:bit should accept connections. 
 
 ### Example: Broadcast a secret code
 
 ```blocks
-bluetooth.advertiseUrl("https://pxt.io?secret=42", 7, true);
+bluetooth.advertiseUrl("https://pxt.io?secret=42", true);
 ```
 
 ## See Also
 
-[stop-advertising](/reference/bluetooth/stop-advertising)
+[stop-advertising](/reference/bluetooth/stop-advertising), [advertise-uid](/reference/bluetooth/advertise-uid)
 
 ```package
 bluetooth

libs/bluetooth/_locales/bluetooth-jsdoc-strings.json

@@ -1,5 +1,14 @@
 {
   "bluetooth": "Support for additional Bluetooth services.\n\nSupport for additional Bluetooth services.",
+  "bluetooth.advertiseUid": "Advertise an Eddystone UID",
+  "bluetooth.advertiseUidBuffer": "Advertise an Eddystone UID",
+  "bluetooth.advertiseUidBuffer|param|connectable": "true to keep bluetooth connectable for other services, false otherwise.",
+  "bluetooth.advertiseUidBuffer|param|nsAndInstance": "16 bytes buffer of namespace (bytes 0-9) and instance (bytes 10-15)",
+  "bluetooth.advertiseUidBuffer|param|power": "power level between 0 and 7, eg: 7",
+  "bluetooth.advertiseUid|param|connectable": "true to keep bluetooth connectable for other services, false otherwise.",
+  "bluetooth.advertiseUid|param|instance": "4 last bytes of the instance uid",
+  "bluetooth.advertiseUid|param|ns": "4 last bytes of the namespace uid",
+  "bluetooth.advertiseUid|param|power": "power level between 0 and 7, eg: 7",
   "bluetooth.advertiseUrl": "Advertise an Eddystone URL",
   "bluetooth.advertiseUrl|param|connectable": "true to keep bluetooth connectable for other services, false otherwise.",
   "bluetooth.advertiseUrl|param|power": "power level between 0 and 7, eg: 7",

libs/bluetooth/_locales/bluetooth-strings.json

@@ -1,4 +1,5 @@
 {
+  "bluetooth.advertiseUid|block": "bluetooth advertise UID|namespace (bytes 6-9)%ns|instance (bytes 2-6)%instance|with power %power|connectable %connectable",
   "bluetooth.advertiseUrl|block": "bluetooth advertise url %url|with power %power|connectable %connectable",
   "bluetooth.onBluetoothConnected|block": "on bluetooth connected",
   "bluetooth.onBluetoothDisconnected|block": "on bluetooth disconnected",

libs/bluetooth/bluetooth.cpp

@@ -137,6 +137,24 @@ namespace bluetooth {
         uBit.bleManager.setTransmitPower(power);
     }
 
+    /**
+    * Advertise an Eddystone UID
+	* @param nsAndInstance 16 bytes buffer of namespace (bytes 0-9) and instance (bytes 10-15)
+	* @param power power level between 0 and 7, eg: 7
+    * @param connectable true to keep bluetooth connectable for other services, false otherwise.
+    */
+    //% parts=bluetooth weight=12 advanced=true
+    void advertiseUidBuffer(Buffer nsAndInstance, int power, bool connectable) {
+        ManagedBuffer buf(nsAndInstance);
+        if (buf.length() != 16) return;
+
+        power = min(MICROBIT_BLE_POWER_LEVELS-1, max(0, power));
+        int8_t level = CALIBRATED_POWERS[power];
+        uint8_t uidNs[10]; buf.readBytes(uidNs, 0, 10);
+        uint8_t uidInst[6]; buf.readBytes(uidInst, 10, 6);
+        uBit.bleManager.advertiseEddystoneUid((const char*)uidNs, (const char*)uidInst, level, connectable);
+    }
+
     /**
     * Sets the bluetooth transmit power between 0 (minimal) and 7 (maximum).
     * @param power power level between 0 (minimal) and 7 (maximum), eg: 7.

libs/bluetooth/bluetooth.ts

@@ -46,4 +46,21 @@ namespace bluetooth {
         // dummy implementation for simulator
         return "???"
     }
+
+    /**
+    * Advertise an Eddystone UID
+    * @param ns 4 last bytes of the namespace uid
+    * @param instance 4 last bytes of the instance uid
+    * @param power power level between 0 and 7, eg: 7
+    * @param connectable true to keep bluetooth connectable for other services, false otherwise.
+    */
+    //% blockId=eddystone_advertise_uid block="bluetooth advertise UID|namespace (bytes 6-9)%ns|instance (bytes 2-6)%instance|with power %power|connectable %connectable"
+    //% parts=bluetooth weight=12 blockGap=8
+    //% help=bluetooth/advertise-uid blockExternalInputs=1
+    export function advertiseUid(ns: number, instance: number, power: number, connectable: boolean) {
+        const buf = pins.createBuffer(16);
+        buf.fill(ns, 6, 4);
+        buf.fill(instance, 12, 4);
+        bluetooth.advertiseUidBuffer(buf, power, connectable);
+    }
 }

libs/bluetooth/pxt.json

@@ -30,7 +30,7 @@
                     "event_service": 1,
                     "device_info_service": 1,
                     "eddystone_url": 1,
-                    "eddystone_uid": 0,
+                    "eddystone_uid": 1,
                     "open": 0,
                     "pairing_mode": 1,
                     "whitelist": 1,

libs/bluetooth/shims.d.ts

@@ -92,6 +92,15 @@ declare namespace bluetooth {
     //% help=bluetooth/advertise-url blockExternalInputs=1 shim=bluetooth::advertiseUrl
     function advertiseUrl(url: string, power: number, connectable: boolean): void;
 
+    /**
+     * Advertise an Eddystone UID
+     * @param nsAndInstance 16 bytes buffer of namespace (bytes 0-9) and instance (bytes 10-15)
+     * @param power power level between 0 and 7, eg: 7
+     * @param connectable true to keep bluetooth connectable for other services, false otherwise.
+     */
+    //% parts=bluetooth weight=12 advanced=true shim=bluetooth::advertiseUidBuffer
+    function advertiseUidBuffer(nsAndInstance: Buffer, power: number, connectable: boolean): void;
+
     /**
      * Sets the bluetooth transmit power between 0 (minimal) and 7 (maximum).
      * @param power power level between 0 (minimal) and 7 (maximum), eg: 7.

sim/state/misc.ts

@@ -178,6 +178,7 @@ namespace pxsim.bluetooth {
         // TODO
     }
     export function advertiseUrl(url: string, power: number, connectable: boolean) { }
+    export function advertiseUidBuffer(nsAndInstance: Buffer, power: number, connectable: boolean) { }
     export function stopAdvertising() { }
     export function setTransmitPower(power: number) {}
 }