Pairing documentation worj in progress. UART write block added

This commit is contained in:
Martin Woolley 2016-06-24 07:59:08 +01:00
parent f068b3d204
commit 0834402b18
4 changed files with 133 additions and 60 deletions

View File

@ -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
```

View File

@ -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.
*/
@ -64,6 +80,28 @@ namespace bluetooth {
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
@ -84,39 +122,5 @@ namespace bluetooth {
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));
}
}

View File

@ -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 {
}

View File

@ -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.