From 2da0cf1178ea121cdef2277d59d9cf88378d5e6b Mon Sep 17 00:00:00 2001 From: Peli de Halleux Date: Fri, 23 Dec 2016 08:58:38 -0800 Subject: [PATCH] support for buffer signature (#325) --- docs/reference/bluetooth.md | 3 +- .../bluetooth/advertise-uid-buffer.md | 37 +++++++++++++++ docs/reference/bluetooth/advertise-uid.md | 46 +++++++++++++++++++ docs/reference/bluetooth/advertise-url.md | 7 +-- .../_locales/bluetooth-jsdoc-strings.json | 9 ++++ .../bluetooth/_locales/bluetooth-strings.json | 1 + libs/bluetooth/bluetooth.cpp | 18 ++++++++ libs/bluetooth/bluetooth.ts | 17 +++++++ libs/bluetooth/pxt.json | 2 +- libs/bluetooth/shims.d.ts | 9 ++++ sim/state/misc.ts | 1 + 11 files changed, 145 insertions(+), 5 deletions(-) create mode 100644 docs/reference/bluetooth/advertise-uid-buffer.md create mode 100644 docs/reference/bluetooth/advertise-uid.md diff --git a/docs/reference/bluetooth.md b/docs/reference/bluetooth.md index 99ce0a45..29750895 100644 --- a/docs/reference/bluetooth.md +++ b/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(); ``` diff --git a/docs/reference/bluetooth/advertise-uid-buffer.md b/docs/reference/bluetooth/advertise-uid-buffer.md new file mode 100644 index 00000000..da388403 --- /dev/null +++ b/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 +``` diff --git a/docs/reference/bluetooth/advertise-uid.md b/docs/reference/bluetooth/advertise-uid.md new file mode 100644 index 00000000..942e5b20 --- /dev/null +++ b/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 +``` diff --git a/docs/reference/bluetooth/advertise-url.md b/docs/reference/bluetooth/advertise-url.md index 852f4090..4f261e86 100644 --- a/docs/reference/bluetooth/advertise-url.md +++ b/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 diff --git a/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json b/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json index ea5514a8..e14253fd 100644 --- a/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json +++ b/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", diff --git a/libs/bluetooth/_locales/bluetooth-strings.json b/libs/bluetooth/_locales/bluetooth-strings.json index 70761646..cde5e714 100644 --- a/libs/bluetooth/_locales/bluetooth-strings.json +++ b/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", diff --git a/libs/bluetooth/bluetooth.cpp b/libs/bluetooth/bluetooth.cpp index 75622de9..07f5aec3 100644 --- a/libs/bluetooth/bluetooth.cpp +++ b/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. diff --git a/libs/bluetooth/bluetooth.ts b/libs/bluetooth/bluetooth.ts index 3f480408..0652ea7a 100644 --- a/libs/bluetooth/bluetooth.ts +++ b/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); + } } diff --git a/libs/bluetooth/pxt.json b/libs/bluetooth/pxt.json index ac852cd5..92804b96 100644 --- a/libs/bluetooth/pxt.json +++ b/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, diff --git a/libs/bluetooth/shims.d.ts b/libs/bluetooth/shims.d.ts index e62b991f..12ae7ea4 100644 --- a/libs/bluetooth/shims.d.ts +++ b/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. diff --git a/sim/state/misc.ts b/sim/state/misc.ts index da5fe165..6f5a2237 100644 --- a/sim/state/misc.ts +++ b/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) {} }