diff --git a/docs/reference/bluetooth/bluetooth-pairing.md b/docs/reference/bluetooth/bluetooth-pairing.md new file mode 100755 index 00000000..6c0d0368 --- /dev/null +++ b/docs/reference/bluetooth/bluetooth-pairing.md @@ -0,0 +1,61 @@ +# Bluetooth Pairing + +### ~hint +![](/static/bluetooth/Bluetooth_SIG.png) + +For another device like a smartphone to be able to connect to a micro:bit and uses its Bluetooth 'services' it must first be 'paired'. + +### ~ + +### What is 'pairing'? + +'Pairing' is what you have to do to have your micro:bit trust another device like a smartphone and similarly, have your smartphone trust your micro:bit. Why 'trust'? Well, pairing is all about security. You wouldn't usually want just anyone's smartphone connecting to your micro:bit and making it do things so by pairing *your* smartphone with *your* micro:bit you ensure that only your devices can talk to each other. + +Once you've paired your micro:bit with another device it also means that they are able to exchange information privately, without someone else being able to "see" the data they're exchanging over the air using Bluetooth. This is accomplished by data being [encrypted](https://en.wikipedia.org/wiki/Encryption) and pairing makes it possible for devices who trust each other to encrypt and decrypt data from each other. + +# How do you pair your micro:bit with another device? + +Making your micro:bit pair requires you to follow some simple steps which will be described shortly. What you do with the device you're pairing it to will vary slghtly depending on what that device is. We'll look at how it's done with common smartphones and tablets here too. + +To get your micro:bit ready for pairing do the following: + +1. Hold down buttons A and B on the front of your micro:bit together. The front is the side with two buttons and the LED display. Keep the two buttons held down. Don't let go of them yet! +2. While still holding down buttons A and B, press and then release the reset button on the back of the micro:bit. Keep holding down buttons A and B. +3. You should see "PAIRING MODE!" start to scroll across the micro:bit display. When you see this message start to appear you can release buttons A and B. +4. Eventually you'll see a strange pattern on your micro:bit display. This is like your micro:bit's signature. Other people's micro:bits will probably display a different pattern. + +Your micro:bit is now ready to be paired with the other device. Read the section below which relates to your 'other' device and watch the video too. + +### How do you pair your micro:bit with a Windows smartphone or tablet? + + +### How do you pair your micro:bit with an Android smartphone or tablet? + +Pairing an Android device with a micro:bit is done in the Settings screen. These are the steps to follow. If you have problems watch the video which may help. + +### How do you pair your micro:bit with an Apple iOS smartphone or tablet? + +### Video - How to pair a micro:bit with a Windows smartphone + +https://www.youtube.com/watch?v=AoW3mit7jIg + +### Video - How to pair a micro:bit with an Android smartphone or tablet + +https://www.youtube.com/watch?v=7hLBfdAGkZI + +### Video - How to pair a micro:bit with an Apple iOS smartphone or tablet + +https://www.youtube.com/watch?v=wslwyAMwMhs + + +### How often do I need to pair my micro:bit with my phone? + + + +### See also + +[Bluetooth SIG](https://www.bluetooth.com), [Bluetooth on micro:bit resources](http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html) + +```package +microbit-bluetooth +``` \ No newline at end of file diff --git a/libs/microbit-bluetooth/bluetooth.cpp b/libs/microbit-bluetooth/bluetooth.cpp index d9c89d00..23462190 100644 --- a/libs/microbit-bluetooth/bluetooth.cpp +++ b/libs/microbit-bluetooth/bluetooth.cpp @@ -5,6 +5,22 @@ MicroBitUARTService *uart; using namespace pxt; +enum Delimiters { + //% block="new line" + NewLine = 1, + //% block="," + Comma = 2, + //% block="$" + Dollar = 3, + //% block=":" + Colon = 4, + //% block="." + Fullstop = 5, + //% block="#" + Hash = 6, +}; + + /** * Support for additional Bluetooth services. */ @@ -63,8 +79,30 @@ namespace bluetooth { void startButtonService() { new MicroBitButtonService(*uBit.ble); } + + /** + * Starts the Bluetooth UART service + */ + //% help=bluetooth/start-uart-service + //% blockId=bluetooth_start_uart_service block="bluetooth uart service" blockGap=8 + + void startUartService() { + // 61 octet buffer size is 3 x (MTU - 3) + 1 + // MTU on nRF51822 is 23 octets. 3 are used by Attribute Protocol header data leaving 20 octets for payload + // So we allow a RX buffer that can contain 3 x max length messages plus one octet for a terminator character + uart = new MicroBitUARTService(*uBit.ble, 61, 60); + } - /** + /** + * Writes to the Bluetooth UART service buffer. From there the data is transmitted over Bluetooth to a connected device. + */ + //% help=bluetooth/uart-write + //% blockId=bluetooth_uart_write block="bluetooth|uart|write %data" blockGap=8 + void uartWrite(StringData *data) { + uart->send(ManagedString(data)); + } + + /** * Register code to run when the micro:bit is connected to over Bluetooth * @param body Code to run when a Bluetooth connection is established */ @@ -83,40 +121,6 @@ namespace bluetooth { void onBluetoothDisconnected(Action body) { registerWithDal(MICROBIT_ID_BLE, MICROBIT_BLE_EVT_DISCONNECTED, body); } - - /** - * Starts the Bluetooth UART service - */ - //% help=bluetooth/start-uart-service - //% blockId=bluetooth_start_uart_service block="bluetooth|uart|service" blockGap=8 - - void startUartService() { - // 61 octet buffer size is 3 x (MTU - 3) + 1 - // MTU on nRF51822 is 23 octets. 3 are used by Attribute Protocol header data leaving 20 octets for payload - // So we allow a buffer that can contain 3 x max length messages plus one octet for a terminator character - uart = new MicroBitUARTService(*uBit.ble, 61, 60); - } - - - /** - * Reads the Bluetooth UART service buffer, returning when a specified 'end of message' delimiter character is encountered - * @param eom End of Message delimiter character - */ - //% help=bluetooth/uart-read - //% blockId=bluetooth_uart_read block="bluetooth|uart|read %eom" blockGap=8 - StringData* uartRead(char* eom) { - // temp hard coding of : as eom delimiter - char delim[6] = {':', 0}; - return uart->readUntil(delim).leakData(); - } - - /** - * Writes to the Bluetooth UART service buffer. From there the data is transmitted over Bluetooth to a connected device. - */ - //% help=bluetooth/uart-write - //% blockId=bluetooth_uart_write block="bluetooth|uart|write %data" blockGap=8 - void uartWrite(StringData* data) { - uart->send(ManagedString(data)); - } - -} + + +} \ No newline at end of file diff --git a/libs/microbit-bluetooth/enums.d.ts b/libs/microbit-bluetooth/enums.d.ts index c1770c7b..b1a4cfa4 100644 --- a/libs/microbit-bluetooth/enums.d.ts +++ b/libs/microbit-bluetooth/enums.d.ts @@ -1,4 +1,20 @@ // Auto-generated. Do not edit. + + + declare enum Delimiters { + //% block="new line" + NewLine = 1, + //% block="," + Comma = 2, + //% block="$" + Dollar = 3, + //% block=":" + Colon = 4, + //% block="." + Fullstop = 5, + //% block="#" + Hash = 6, + } declare namespace bluetooth { } diff --git a/libs/microbit-bluetooth/shims.d.ts b/libs/microbit-bluetooth/shims.d.ts index ae918647..4dba2871 100644 --- a/libs/microbit-bluetooth/shims.d.ts +++ b/libs/microbit-bluetooth/shims.d.ts @@ -49,6 +49,20 @@ declare namespace bluetooth { //% blockId=bluetooth_start_button_service block="bluetooth button service" blockGap=8 shim=bluetooth::startButtonService function startButtonService(): void; + /** + * Starts the Bluetooth UART service + */ + //% help=bluetooth/start-uart-service + //% blockId=bluetooth_start_uart_service block="bluetooth uart service" blockGap=8 shim=bluetooth::startUartService + function startUartService(): void; + + /** + * Writes to the Bluetooth UART service buffer. From there the data is transmitted over Bluetooth to a connected device. + */ + //% help=bluetooth/uart-write + //% blockId=bluetooth_uart_write block="bluetooth|uart|write %data" blockGap=8 shim=bluetooth::uartWrite + function uartWrite(data: string): void; + /** * Register code to run when the micro:bit is connected to over Bluetooth * @param body Code to run when a Bluetooth connection is established @@ -64,28 +78,6 @@ declare namespace bluetooth { //% help=bluetooth/on-bluetooth-disconnected //% blockId=bluetooth_on_disconnected block="on bluetooth disconnected" shim=bluetooth::onBluetoothDisconnected function onBluetoothDisconnected(body: () => void): void; - - /** - * Starts the Bluetooth UART service - */ - //% help=bluetooth/start-uart-service - //% blockId=bluetooth_start_uart_service block="bluetooth|uart|service" blockGap=8 shim=bluetooth::startUartService - function startUartService(): void; - - /** - * Reads the Bluetooth UART service buffer, returning when a specified 'end of message' delimiter character is encountered - * @param eom End of Message delimiter character - */ - //% help=bluetooth/uart-read - //% blockId=bluetooth_uart_read block="bluetooth|uart|read %eom" blockGap=8 shim=bluetooth::uartRead - function uartRead(eom: char*): string; - - /** - * Writes to the Bluetooth UART service buffer. From there the data is transmitted over Bluetooth to a connected device. - */ - //% help=bluetooth/uart-write - //% blockId=bluetooth_uart_write block="bluetooth|uart|write %data" blockGap=8 shim=bluetooth::uartWrite - function uartWrite(data: string): void; } // Auto-generated. Do not edit. Really.