From 6c11dbcdf4310617d3cab81b16a23b8e1683e2e2 Mon Sep 17 00:00:00 2001 From: Peli de Halleux Date: Wed, 7 Dec 2016 09:05:03 -0800 Subject: [PATCH] added setTransmitPower in BLE --- docs/reference/bluetooth.md | 1 + .../reference/bluetooth/set-transmit-power.md | 26 ++++++++++++++++++ .../_locales/bluetooth-jsdoc-strings.json | 5 +++- .../bluetooth/_locales/bluetooth-strings.json | 3 ++- libs/bluetooth/bluetooth.cpp | 27 +++++++++++++------ libs/bluetooth/shims.d.ts | 17 +++++++++--- sim/state/misc.ts | 3 ++- 7 files changed, 67 insertions(+), 15 deletions(-) create mode 100644 docs/reference/bluetooth/set-transmit-power.md diff --git a/docs/reference/bluetooth.md b/docs/reference/bluetooth.md index 21e850bb..99ce0a45 100644 --- a/docs/reference/bluetooth.md +++ b/docs/reference/bluetooth.md @@ -19,6 +19,7 @@ bluetooth.startMagnetometerService(); bluetooth.startTemperatureService(); bluetooth.onBluetoothConnected(() => {}); bluetooth.onBluetoothDisconnected(() => {}); +bluetooth.setTransmitPower(7); ``` ## UART diff --git a/docs/reference/bluetooth/set-transmit-power.md b/docs/reference/bluetooth/set-transmit-power.md new file mode 100644 index 00000000..6323f354 --- /dev/null +++ b/docs/reference/bluetooth/set-transmit-power.md @@ -0,0 +1,26 @@ +# Bluetooth Set Transmit Power + +### ~hint +![](/static/bluetooth/Bluetooth_SIG.png) + +For another device like a smartphone to use any of the Bluetooth "services" which the @boardname@ has, it must first be [paired with the @boardname@](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the @boardname@ and exchange data relating to many of the @boardname@'s features. + +### ~ + +Change the output power level of the transmitter to the given value. + +```sig +bluetooth.setTransmitPower(7); +``` + +### Parameters + +* `power`: a [number](/reference/types/number) in the range ``0..7``, where ``0`` is the lowest power and ``7`` is the highest. + +### See also + +[About Bluetooth](/reference/bluetooth/about-bluetooth), [@boardname@ Bluetooth profile overview ](http://lancaster-university.github.io/microbit-docs/ble/profile/), [@boardname@ Bluetooth profile reference](http://lancaster-university.github.io/microbit-docs/resources/bluetooth/microbit-profile-V1.9-Level-2.pdf), [Bluetooth on @boardname@ resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html), [Bluetooth SIG](https://www.bluetooth.com) + +```package +bluetooth +``` diff --git a/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json b/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json index b22f5b9c..df1ab95e 100644 --- a/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json +++ b/libs/bluetooth/_locales/bluetooth-jsdoc-strings.json @@ -1,12 +1,15 @@ { "bluetooth": "Support for additional Bluetooth services.", "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, e.g.: 7", - "bluetooth.advertiseUrl|param|url": "the url to transmit. Must be no longer than the supported eddystone url length", + "bluetooth.advertiseUrl|param|url": "the url to transmit. Must be no longer than the supported eddystone url length, eg: \"https://pxt.io/\"", "bluetooth.onBluetoothConnected": "Register code to run when the micro:bit is connected to over Bluetooth", "bluetooth.onBluetoothConnected|param|body": "Code to run when a Bluetooth connection is established", "bluetooth.onBluetoothDisconnected": "Register code to run when a bluetooth connection to the micro:bit is lost", "bluetooth.onBluetoothDisconnected|param|body": "Code to run when a Bluetooth connection is lost", + "bluetooth.setTransmitPower": "Sets the bluetooth transmit power between 0 (minimal) and 7 (maximum).", + "bluetooth.setTransmitPower|param|power": "power level between 0 (minimal) and 7 (maximum), eg: 7.", "bluetooth.startAccelerometerService": "Starts the Bluetooth accelerometer service", "bluetooth.startButtonService": "Starts the Bluetooth button service", "bluetooth.startIOPinService": "Starts the Bluetooth IO pin service.", diff --git a/libs/bluetooth/_locales/bluetooth-strings.json b/libs/bluetooth/_locales/bluetooth-strings.json index f4ac4022..70761646 100644 --- a/libs/bluetooth/_locales/bluetooth-strings.json +++ b/libs/bluetooth/_locales/bluetooth-strings.json @@ -1,7 +1,8 @@ { - "bluetooth.advertiseUrl|block": "bluetooth advertise url %url|with power %power", + "bluetooth.advertiseUrl|block": "bluetooth advertise url %url|with power %power|connectable %connectable", "bluetooth.onBluetoothConnected|block": "on bluetooth connected", "bluetooth.onBluetoothDisconnected|block": "on bluetooth disconnected", + "bluetooth.setTransmitPower|block": "bluetooth set transmit power %power", "bluetooth.startAccelerometerService|block": "bluetooth accelerometer service", "bluetooth.startButtonService|block": "bluetooth button service", "bluetooth.startIOPinService|block": "bluetooth io pin service", diff --git a/libs/bluetooth/bluetooth.cpp b/libs/bluetooth/bluetooth.cpp index 37d217ac..2ee3cde7 100644 --- a/libs/bluetooth/bluetooth.cpp +++ b/libs/bluetooth/bluetooth.cpp @@ -120,19 +120,30 @@ namespace bluetooth { registerWithDal(MICROBIT_ID_BLE, MICROBIT_BLE_EVT_DISCONNECTED, body); } - const int8_t CALIBRATED_POWERS[] = {-49, -37, -33, -28, -25, -20, -15, -10}; - /** * Advertise an Eddystone URL - * @param url the url to transmit. Must be no longer than the supported eddystone url length + * @param url the url to transmit. Must be no longer than the supported eddystone url length, eg: "https://pxt.io/" * @param power power level between 0 and 7, e.g.: 7 + * @param connectable true to keep bluetooth connectable for other services, false otherwise. */ - //% blockId=eddystone_advertise_url block="bluetooth advertise url %url|with power %power" + //% blockId=eddystone_advertise_url block="bluetooth advertise url %url|with power %power|connectable %connectable" //% parts=bluetooth weight=11 blockGap=8 - //% help=bluetooth/advertise-url - void advertiseUrl(StringData* url, int power) { - int8_t level = CALIBRATED_POWERS[min(7, max(0, power))]; - uBit.bleManager.advertiseEddystoneUrl(ManagedString(url), level); + //% help=bluetooth/advertise-url blockExternalInputs=1 + void advertiseUrl(StringData* url, int power, bool connectable) { + power = min(MICROBIT_BLE_POWER_LEVELS-1, max(0, power)); + int8_t level = MICROBIT_BLE_POWER_LEVEL[power]; + uBit.bleManager.advertiseEddystoneUrl(ManagedString(url), level, connectable); + uBit.bleManager.setTransmitPower(power); + } + + /** + * Sets the bluetooth transmit power between 0 (minimal) and 7 (maximum). + * @param power power level between 0 (minimal) and 7 (maximum), eg: 7. + */ + //% parts=bluetooth weight=5 help=bluetooth/set-transmit-power + //% blockId=bluetooth_settransmitpower block="bluetooth set transmit power %power" + void setTransmitPower(int power) { + uBit.bleManager.setTransmitPower(min(MICROBIT_BLE_POWER_LEVELS-1, max(0, power))); } /** diff --git a/libs/bluetooth/shims.d.ts b/libs/bluetooth/shims.d.ts index 57d9e45b..df6263d9 100644 --- a/libs/bluetooth/shims.d.ts +++ b/libs/bluetooth/shims.d.ts @@ -83,13 +83,22 @@ declare namespace bluetooth { /** * Advertise an Eddystone URL - * @param url the url to transmit. Must be no longer than the supported eddystone url length + * @param url the url to transmit. Must be no longer than the supported eddystone url length, eg: "https://pxt.io/" * @param power power level between 0 and 7, e.g.: 7 + * @param connectable true to keep bluetooth connectable for other services, false otherwise. */ - //% blockId=eddystone_advertise_url block="bluetooth advertise url %url|with power %power" + //% blockId=eddystone_advertise_url block="bluetooth advertise url %url|with power %power|connectable %connectable" //% parts=bluetooth weight=11 blockGap=8 - //% help=bluetooth/advertise-url shim=bluetooth::advertiseUrl - function advertiseUrl(url: string, power: number): void; + //% help=bluetooth/advertise-url blockExternalInputs=1 shim=bluetooth::advertiseUrl + function advertiseUrl(url: string, 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. + */ + //% parts=bluetooth weight=5 help=bluetooth/set-transmit-power + //% blockId=bluetooth_settransmitpower block="bluetooth set transmit power %power" shim=bluetooth::setTransmitPower + function setTransmitPower(power: number): void; /** * Stops advertising Eddystone end points diff --git a/sim/state/misc.ts b/sim/state/misc.ts index 521e9a05..da5fe165 100644 --- a/sim/state/misc.ts +++ b/sim/state/misc.ts @@ -177,7 +177,8 @@ namespace pxsim.bluetooth { export function onBluetoothDisconnected(a: RefAction) { // TODO } - export function advertiseUrl(url: string, power: number) { } + export function advertiseUrl(url: string, power: number, connectable: boolean) { } export function stopAdvertising() { } + export function setTransmitPower(power: number) {} }