From 82e34d852caf1118a911d32ae912f590ba35fa2f Mon Sep 17 00:00:00 2001
From: Martin Woolley <mwoolley@bluetooth.com>
Date: Thu, 23 Jun 2016 08:05:49 +0100
Subject: [PATCH 1/7] checking in

---
 libs/microbit-bluetooth/bluetooth.cpp | 16 ++++++++++++++--
 libs/microbit-bluetooth/shims.d.ts    |  7 +++++++
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/libs/microbit-bluetooth/bluetooth.cpp b/libs/microbit-bluetooth/bluetooth.cpp
index ab995204..0d86661e 100644
--- a/libs/microbit-bluetooth/bluetooth.cpp
+++ b/libs/microbit-bluetooth/bluetooth.cpp
@@ -1,5 +1,7 @@
 #include "pxt.h"
 #include "MESEvents.h"
+#include "MicroBitUARTService.h"
+MicroBitUARTService *uart;
 
 using namespace pxt;
 //% color=#0082FB weight=20
@@ -77,6 +79,16 @@ 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() {
+        // 32 octet buffer size is 
+        uart = new MicroBitUARTService(*uBit.ble, 32, 32);
+    }
+      
 }
diff --git a/libs/microbit-bluetooth/shims.d.ts b/libs/microbit-bluetooth/shims.d.ts
index 9d7d49b5..f618c4ba 100644
--- a/libs/microbit-bluetooth/shims.d.ts
+++ b/libs/microbit-bluetooth/shims.d.ts
@@ -62,6 +62,13 @@ 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;
 }
 
 // Auto-generated. Do not edit. Really.

From 76005841fa841fd2adb26a46f285977e8fdc0d3e Mon Sep 17 00:00:00 2001
From: Martin Woolley <mwoolley@bluetooth.com>
Date: Thu, 23 Jun 2016 11:38:23 +0100
Subject: [PATCH 2/7] Increased default power to 6, added UART write block

---
 .../bluetooth/start-accelerometer-service.md  |  2 +-
 .../reference/bluetooth/start-uart-service.md | 44 ++++++++++++++++
 docs/reference/bluetooth/uart-write.md        | 52 +++++++++++++++++++
 libs/microbit-bluetooth/bluetooth.cpp         | 28 +++++++++-
 libs/microbit-bluetooth/pxt.json              |  2 +-
 libs/microbit-bluetooth/shims.d.ts            | 15 ++++++
 6 files changed, 139 insertions(+), 4 deletions(-)
 create mode 100755 docs/reference/bluetooth/start-uart-service.md
 create mode 100755 docs/reference/bluetooth/uart-write.md

diff --git a/docs/reference/bluetooth/start-accelerometer-service.md b/docs/reference/bluetooth/start-accelerometer-service.md
index 140c3f77..a96e9bcd 100755
--- a/docs/reference/bluetooth/start-accelerometer-service.md
+++ b/docs/reference/bluetooth/start-accelerometer-service.md
@@ -27,7 +27,7 @@ bluetooth.startAccelerometerService();
 
 ### Video - Accelerometer service demo - Starts at 0:18
 
-http://www.youtube.com/watch?v=aep_GVowKfs
+http://www.youtube.com/watch?v=aep_GVowKfs#t=18s
 
 ### Advanced
  
diff --git a/docs/reference/bluetooth/start-uart-service.md b/docs/reference/bluetooth/start-uart-service.md
new file mode 100755
index 00000000..6b8d5784
--- /dev/null
+++ b/docs/reference/bluetooth/start-uart-service.md
@@ -0,0 +1,44 @@
+# Bluetooth UART Service 
+
+### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
+
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+
+### ~
+
+The Bluetooth UART service allows another device such as a smartphone to exchange any data it wants to with the micro:bit, in small chunks which are intended to be joined together. [UART[(https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter) stands for Universal Asynchronous Receiver Transmitter and is one way in which serial data communications can be performed, usually between two devices connected by a physical, wired connection. The Bluetooth UART service emulates the behaviour of a physical UART system and allows the exchange of a maximum of 20 bytes of data at a time in either direction. 
+
+When this service is used, the micro:bit sets up a 60 byte buffer and data it receives will be accumulated in the buffer until it is full. When using the UART service from your micro:bit code, you can indicate a special character which will be used to mean that the entire message in at most three chunks has now been sent by the other, connected device, at which point the micro:bit will release the entire contents of its buffer to any code trying to read it. In other words this special character, known as a 'delimiter' is used by the device connected to the micro:bit to mean "I've sent my whole message, you can now use it".
+
+You could use the UART service for many things. It doesn't care what you put in messages which makes it very flexible. You could create a guessing game, with questions and answers passing between micro:bit and a smartphone or you could connect a camera to the micro:bit and transmit image data obtained from the edge connector, in chunks over Bluetooth to a smartphone. There are a great many possibilities. 
+
+To use the Bluetooth UART service from another device you'll need additional micro:bit code which reads and uses data from the UART buffer and / or writes data to the buffer for transmission over Bluetooth to another device.
+
+```sig
+bluetooth.startUartService();
+```
+
+### Example: Starting the Bluetooth UART service
+
+The following code shows the Bluetooth UART service being started:
+
+```blocks
+bluetooth.startUartService();
+```
+
+### Video - UART service guessing game
+
+https://www.youtube.com/watch?v=PgGeWddMAZ0
+
+### Advanced
+ 
+For more advanced information on the micro:bit Bluetooth UART service including information on using a smartphone, see the [Lancaster University micro:bit runtime technical documentation](http://lancaster-university.github.io/microbit-docs/ble/uart-service/)
+
+### 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
+```
diff --git a/docs/reference/bluetooth/uart-write.md b/docs/reference/bluetooth/uart-write.md
new file mode 100755
index 00000000..0f308b8e
--- /dev/null
+++ b/docs/reference/bluetooth/uart-write.md
@@ -0,0 +1,52 @@
+# UART Write 
+
+### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
+
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+
+### ~
+
+The [Bluetooth UART service](start-uart-service.md) allows another device such as a smartphone to exchange any data it wants to with the micro:bit, in small chunks. 
+
+With the Bluetooth UART service running, this block allows a micro:bit to send data to a Bluetooth connected device.
+
+```sig
+bluetooth.uartWrite("");
+```
+
+### Example: Starting the Bluetooth UART service and then sending "HELLO" whenever button A is pressed and another device has connected over Bluetooth
+
+```blocks
+let connected = 0;
+bluetooth.onBluetoothConnected(() => {
+    basic.showString("C");
+    connected = 1;
+});
+bluetooth.onBluetoothDisconnected(() => {
+    basic.showString("D");
+    connected = 0;
+});
+bluetooth.startUartService();
+input.onButtonPressed(Button.A, () => {
+    if (connected == 1) {
+        bluetooth.uartWrite("HELLO");
+    }
+});
+```
+
+### Video - UART service guessing game
+
+https://www.youtube.com/watch?v=PgGeWddMAZ0
+
+### Advanced
+ 
+For more advanced information on the micro:bit Bluetooth UART service including information on using a smartphone, see the [Lancaster University micro:bit runtime technical documentation](http://lancaster-university.github.io/microbit-docs/ble/uart-service/)
+
+### 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
+```
diff --git a/libs/microbit-bluetooth/bluetooth.cpp b/libs/microbit-bluetooth/bluetooth.cpp
index 3bb46d0d..d9c89d00 100644
--- a/libs/microbit-bluetooth/bluetooth.cpp
+++ b/libs/microbit-bluetooth/bluetooth.cpp
@@ -91,8 +91,32 @@ namespace bluetooth {
     //% blockId=bluetooth_start_uart_service block="bluetooth|uart|service" blockGap=8
 
     void startUartService() {
-        // 32 octet buffer size is 
-        uart = new MicroBitUARTService(*uBit.ble, 32, 32);
+        // 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));
+    }    
       
 }
diff --git a/libs/microbit-bluetooth/pxt.json b/libs/microbit-bluetooth/pxt.json
index 584ea366..bfa289f0 100644
--- a/libs/microbit-bluetooth/pxt.json
+++ b/libs/microbit-bluetooth/pxt.json
@@ -21,7 +21,7 @@
                     "open": 0,
                     "whitelist": 1,
                     "advertising_timeout": 0,
-                    "tx_power": 0,
+                    "tx_power": 6,
                     "dfu_service": 1,
                     "event_service": 1,
                     "device_info_service": 1
diff --git a/libs/microbit-bluetooth/shims.d.ts b/libs/microbit-bluetooth/shims.d.ts
index 5de9f0e0..ae918647 100644
--- a/libs/microbit-bluetooth/shims.d.ts
+++ b/libs/microbit-bluetooth/shims.d.ts
@@ -71,6 +71,21 @@ declare namespace bluetooth {
     //% 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.

From 205a486e58eb5bd00a2b360bf32f7962d570b6ae Mon Sep 17 00:00:00 2001
From: Martin Woolley <Martin Woolley>
Date: Fri, 24 Jun 2016 07:28:23 +0100
Subject: [PATCH 3/7] Bump pxt-core to 0.2.179

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index b26b229b..5b954f27 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,6 @@
     "typescript": "^1.8.7"
   },
   "dependencies": {
-    "pxt-core": "0.2.187"
+    "pxt-core": "0.2.179"
   }
 }

From 0834402b185ec97dec4182b95e89fd4f414ab215 Mon Sep 17 00:00:00 2001
From: Martin Woolley <mwoolley@bluetooth.com>
Date: Fri, 24 Jun 2016 07:59:08 +0100
Subject: [PATCH 4/7] Pairing documentation worj in progress. UART write block
 added

---
 docs/reference/bluetooth/bluetooth-pairing.md | 61 ++++++++++++++
 libs/microbit-bluetooth/bluetooth.cpp         | 80 ++++++++++---------
 libs/microbit-bluetooth/enums.d.ts            | 16 ++++
 libs/microbit-bluetooth/shims.d.ts            | 36 ++++-----
 4 files changed, 133 insertions(+), 60 deletions(-)
 create mode 100755 docs/reference/bluetooth/bluetooth-pairing.md

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.

From ecc71a329538046f376b47fea33d7014cce39bc9 Mon Sep 17 00:00:00 2001
From: Martin Woolley <mwoolley@bluetooth.com>
Date: Fri, 24 Jun 2016 08:46:05 +0100
Subject: [PATCH 5/7] UART read block with string param unlimited length added

---
 libs/microbit-bluetooth/bluetooth.cpp | 11 ++++++++++-
 libs/microbit-bluetooth/bluetooth.ts  | 12 ++++++++++++
 libs/microbit-bluetooth/shims.d.ts    |  9 ++++++++-
 3 files changed, 30 insertions(+), 2 deletions(-)
 create mode 100755 libs/microbit-bluetooth/bluetooth.ts

diff --git a/libs/microbit-bluetooth/bluetooth.cpp b/libs/microbit-bluetooth/bluetooth.cpp
index 23462190..49d275bd 100644
--- a/libs/microbit-bluetooth/bluetooth.cpp
+++ b/libs/microbit-bluetooth/bluetooth.cpp
@@ -97,11 +97,20 @@ namespace bluetooth {
     *  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
+    //% blockId=bluetooth_uart_write block="bluetooth uart write %data" blockGap=8
     void uartWrite(StringData *data) {
             uart->send(ManagedString(data));
     }    
 
+    /**
+    *  Reads from the Bluetooth UART service buffer, returning its contents when the specified delimiter character is encountered.
+    */
+    //% help=bluetooth/uart-read
+    //% blockId=bluetooth_uart_read block="bluetooth uart read %del" blockGap=8
+    StringData* uartRead(StringData *del) {
+        return uart->readUntil(ManagedString(del)).leakData();
+    }    
+
     /**
      * Register code to run when the micro:bit is connected to over Bluetooth
      * @param body Code to run when a Bluetooth connection is established
diff --git a/libs/microbit-bluetooth/bluetooth.ts b/libs/microbit-bluetooth/bluetooth.ts
new file mode 100755
index 00000000..d7c46790
--- /dev/null
+++ b/libs/microbit-bluetooth/bluetooth.ts
@@ -0,0 +1,12 @@
+//% blockId="delimiter_conv" block="%del"
+export function delimiters(del : Delimiters) : string {
+    switch(del) {
+        case Delimiters.NewLine: return "\n";
+        case Delimiters.Comma: return ",";
+        case Delimiters.Dollar: return "$";
+        case Delimiters.Colon: return ":";
+        case Delimiters.Fullstop: return ".";
+        case Delimiters.Hash: return "#";
+        default: return "\n";
+    }
+}
\ No newline at end of file
diff --git a/libs/microbit-bluetooth/shims.d.ts b/libs/microbit-bluetooth/shims.d.ts
index 4dba2871..ff96c2b5 100644
--- a/libs/microbit-bluetooth/shims.d.ts
+++ b/libs/microbit-bluetooth/shims.d.ts
@@ -60,9 +60,16 @@ declare namespace bluetooth {
      *  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
+    //% blockId=bluetooth_uart_write block="bluetooth uart write %data" blockGap=8 shim=bluetooth::uartWrite
     function uartWrite(data: string): void;
 
+    /**
+     *  Reads from the Bluetooth UART service buffer, returning its contents when the specified delimiter character is encountered.
+     */
+    //% help=bluetooth/uart-read
+    //% blockId=bluetooth_uart_read block="bluetooth uart read %del" blockGap=8 shim=bluetooth::uartRead
+    function uartRead(del: string): string;
+
     /**
      * Register code to run when the micro:bit is connected to over Bluetooth
      * @param body Code to run when a Bluetooth connection is established

From af5bf6e04e4c0ab1dd837ea9e35989910f7900e0 Mon Sep 17 00:00:00 2001
From: Martin Woolley <mwoolley@bluetooth.com>
Date: Fri, 24 Jun 2016 09:35:31 +0100
Subject: [PATCH 6/7] Documentation for the uartRead block

---
 docs/reference/bluetooth/uart-read.md | 53 +++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100755 docs/reference/bluetooth/uart-read.md

diff --git a/docs/reference/bluetooth/uart-read.md b/docs/reference/bluetooth/uart-read.md
new file mode 100755
index 00000000..a1afcbfd
--- /dev/null
+++ b/docs/reference/bluetooth/uart-read.md
@@ -0,0 +1,53 @@
+# UART Read 
+
+### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
+
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+
+### ~
+
+The [Bluetooth UART service](start-uart-service.md) allows another device such as a smartphone to exchange any data it wants to with the micro:bit, in small chunks. 
+
+With the Bluetooth UART service running, this block allows a micro:bit to read data which has been received from a Bluetooth connected device, terminating reading and returning the value obtained as soon as a specified delimiter character is encountered. This means that connected devices can send data to the micro:bit and indicate that the complete message has been sent by appending the message with the delimiter character.
+
+```sig
+bluetooth.uartRead("");
+```
+
+### Example: Starting the Bluetooth UART service and then reading data received from another device which is terminated by ":" character and then displaying it
+
+```blocks
+let uart_data: string = "";
+let connected = 0;
+basic.showString("UART");
+bluetooth.startUartService();
+bluetooth.onBluetoothConnected(() => {
+    basic.showString("C");
+    connected = 1;
+    while (connected == 1) {
+        uart_data = bluetooth.uartRead(":");
+        basic.showString(uart_data);
+    }
+});
+bluetooth.onBluetoothDisconnected(() => {
+    basic.showString("D");
+});
+
+```
+
+### Video - UART service guessing game
+
+https://www.youtube.com/watch?v=PgGeWddMAZ0
+
+### Advanced
+ 
+For more advanced information on the micro:bit Bluetooth UART service including information on using a smartphone, see the [Lancaster University micro:bit runtime technical documentation](http://lancaster-university.github.io/microbit-docs/ble/uart-service/)
+
+### 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
+```

From b9a24a4542a4f68a427dc1d11ce4d4361c63e941 Mon Sep 17 00:00:00 2001
From: Martin Woolley <mwoolley@bluetooth.com>
Date: Fri, 24 Jun 2016 11:09:56 +0100
Subject: [PATCH 7/7] Documentation for pairing. Hint section updated to
 reference this.

---
 docs/reference/bluetooth/bluetooth-pairing.md | 60 +++++++++++++++----
 .../bluetooth/on-bluetooth-connected.md       |  2 +-
 .../bluetooth/on-bluetooth-disconnected.md    |  2 +-
 .../bluetooth/start-accelerometer-service.md  |  2 +-
 .../bluetooth/start-button-service.md         |  2 +-
 .../bluetooth/start-io-pin-service.md         |  2 +-
 docs/reference/bluetooth/start-led-service.md |  2 +-
 .../bluetooth/start-magnetometer-service.md   |  2 +-
 .../bluetooth/start-temperature-service.md    |  2 +-
 .../reference/bluetooth/start-uart-service.md |  2 +-
 docs/reference/bluetooth/uart-read.md         |  2 +-
 docs/reference/bluetooth/uart-write.md        |  2 +-
 12 files changed, 60 insertions(+), 22 deletions(-)

diff --git a/docs/reference/bluetooth/bluetooth-pairing.md b/docs/reference/bluetooth/bluetooth-pairing.md
index 6c0d0368..d9677e60 100755
--- a/docs/reference/bluetooth/bluetooth-pairing.md
+++ b/docs/reference/bluetooth/bluetooth-pairing.md
@@ -3,7 +3,7 @@
 ### ~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'.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
@@ -15,7 +15,7 @@ Once you've paired your micro:bit with another device it also means that they ar
 
 # 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.
+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 slightly 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:
 
@@ -28,29 +28,67 @@ Your micro:bit is now ready to be paired with the other device. Read the section
 
 ### How do you pair your micro:bit with a Windows smartphone or tablet?
 
+1. Go into Settings
+2. Select Bluetooth
+3. Switch your micro:bit into 'pairing mode' using the steps above
+4. Wait until 'PAIRING MODE!' has finished scrolling across the micro:bit display. You should see your micro:bit listed on your Windows smartphone with a name something like 'BBC micro:bit [zatig]'. Note that the 5 characters in brackets at the end will vary.
+5. On the Windows smartphone, tap the micro:bit named in the device list. This will initiate the pairing process.
+6. The micro:bit will display a left pointing arrow and the Windows smartphone will pop up a box into which you will be invited to enter a "pin" (Personal Identity Number).
+7. Press button A on the micro:bit and watch carefully as the micro:bit displays a sequence of 6 random numbers. You may find it easier to write them down than to remember them.
+8. Enter the 6 digits which the micro:bit displayed into your Windows smartphone in the pop-up box provided and then select "done".
+9. If you entered the right number the micro:bit will display a tick / check mark. If you made a mistake it will display a cross or X and you should repeat the process to try again. 
+
+#### Video
+https://www.youtube.com/watch?v=AoW3mit7jIg
+
 
 ### 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.
+1. Go into Settings
+2. Select Bluetooth
+3. Switch your micro:bit into 'pairing mode' using the steps above
+4. Wait until 'PAIRING MODE!' has finished scrolling across the micro:bit display. You should see your micro:bit listed on your Android smartphone under the heading "Available devices" with a name something like 'BBC micro:bit [zatig]'. Note that the 5 characters in brackets at the end will vary.
+5. On the Android smartphone, tap the micro:bit named in the Available devices list. This will initiate the pairing process.
+6. The micro:bit will display a left pointing arrow and the Android smartphone will pop up a box into which you will be invited to enter a "pin" (Personal Identity Number).
+7. Press button A on the micro:bit and watch carefully as the micro:bit displays a sequence of 6 random numbers. You may find it easier to write them down than to remember them.
+8. Enter the 6 digits which the micro:bit displayed into your Android smartphone in the pop-up box provided and then select "done".
+9. If you entered the right number the micro:bit will display a tick / check mark. If you made a mistake it will display a cross or X and you should repeat the process to try again. 
+
+#### Video
+https://www.youtube.com/watch?v=7hLBfdAGkZI
 
 ### 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
+The steps to pair with an Apple iOS device are different to those followed for an Android or Windows device. To trigger pairing you need an application which will try to interact with your micro:bit and it's that interaction that triggers the iOS pairing process. There are many you could use but for the purposes of this documentation we'll suggest you install the "nRF Master Control Panel" (nRF MCP) application from Nordic Semiconductor. You'll find it in the Apple app store. It's a really useful Bluetooth application which will help you learn about Bluetooth as well as it having the ability to trigger the pairing process. After installing nRF MCP you should follow these steps to pair with your micro:bit:
 
-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
+1. Switch your micro:bit into 'pairing mode' using the steps above
+2. Wait until 'PAIRING MODE!' has finished scrolling across the micro:bit display.
+3. Launch the nRF MCP application. Your micro:bit should be listed and have a "Connect" button next to it.
+4. Select "Connect" to connect your Apple device to the micro:bit. This will trigger the pairing process.
+5. The micro:bit will display a left pointing arrow and the Apple device will pop up a box into which you will be invited to enter a "pin" (Personal Identity Number).
+6. Press button A on the micro:bit and watch carefully as the micro:bit displays a sequence of 6 random numbers. You may find it easier to write them down than to remember them.
+7. Enter the 6 digits which the micro:bit displayed into your Apple device in the pop-up box provided and then select "Pair".
+8. If you entered the right number the micro:bit will display a tick / check mark. If you made a mistake it will display a cross or X and you should repeat the process to try again. 
 
+#### Video
 https://www.youtube.com/watch?v=wslwyAMwMhs
 
 
 ### How often do I need to pair my micro:bit with my phone?
 
+You do *not* need to pair your micro:bit and smartphone or tablet every time you use them together. Pairing establishes 'trust' which will be retained until it is somehow lost. When another device wants to talk to your micro:bit it must connect to it but connecting and pairing are not the same thing.
 
+There are circumstances which will result in pairing data being lost however and when this happens you will need to pair again.  
+
+Currently, flashing new code via a USB cable causes the micro:bit's Bluetooth pairing data to be lost. Consequently, if you do flash new code to your micro:bit using a USB cable you will need to pair again.
+
+In contrast if you upload new code to your micro:bit over Bluetooth, using for example the Samsung micro:bit application for Android devices, you will not need to pair again.
+
+If you do find yourself needing to pair again you will first need to remove the pairing from your other device (i.e. smartphone or tablet):
+
+* On Android go into Settings/Bluetooth, select the 'cog' next to your micro:bit and then select FORGET
+* On iOS go into Settings/Bluetooth, select your micro:bit and then select Forget This Device
+* On a Windows device go into Settings/Bluetooth. Press and hold the micro:bit entry on the Windows device. A pop-up will appear with the option "delete". Select "delete" to unpair your micro:bit.
 
 ### See also
 
diff --git a/docs/reference/bluetooth/on-bluetooth-connected.md b/docs/reference/bluetooth/on-bluetooth-connected.md
index 990ca12a..8594d947 100755
--- a/docs/reference/bluetooth/on-bluetooth-connected.md
+++ b/docs/reference/bluetooth/on-bluetooth-connected.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/on-bluetooth-disconnected.md b/docs/reference/bluetooth/on-bluetooth-disconnected.md
index 3bfd3859..942f7efa 100755
--- a/docs/reference/bluetooth/on-bluetooth-disconnected.md
+++ b/docs/reference/bluetooth/on-bluetooth-disconnected.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-accelerometer-service.md b/docs/reference/bluetooth/start-accelerometer-service.md
index a96e9bcd..abb9e4b5 100755
--- a/docs/reference/bluetooth/start-accelerometer-service.md
+++ b/docs/reference/bluetooth/start-accelerometer-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-button-service.md b/docs/reference/bluetooth/start-button-service.md
index 64c9b625..1e8e1313 100755
--- a/docs/reference/bluetooth/start-button-service.md
+++ b/docs/reference/bluetooth/start-button-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-io-pin-service.md b/docs/reference/bluetooth/start-io-pin-service.md
index 77d349e1..48ffa914 100755
--- a/docs/reference/bluetooth/start-io-pin-service.md
+++ b/docs/reference/bluetooth/start-io-pin-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-led-service.md b/docs/reference/bluetooth/start-led-service.md
index b05098fd..3dc1c5ea 100755
--- a/docs/reference/bluetooth/start-led-service.md
+++ b/docs/reference/bluetooth/start-led-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-magnetometer-service.md b/docs/reference/bluetooth/start-magnetometer-service.md
index 8869a713..4dcab9d7 100755
--- a/docs/reference/bluetooth/start-magnetometer-service.md
+++ b/docs/reference/bluetooth/start-magnetometer-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-temperature-service.md b/docs/reference/bluetooth/start-temperature-service.md
index 4f695da6..0679fbb0 100755
--- a/docs/reference/bluetooth/start-temperature-service.md
+++ b/docs/reference/bluetooth/start-temperature-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/start-uart-service.md b/docs/reference/bluetooth/start-uart-service.md
index 6b8d5784..a74875a9 100755
--- a/docs/reference/bluetooth/start-uart-service.md
+++ b/docs/reference/bluetooth/start-uart-service.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/uart-read.md b/docs/reference/bluetooth/uart-read.md
index a1afcbfd..18c7d68c 100755
--- a/docs/reference/bluetooth/uart-read.md
+++ b/docs/reference/bluetooth/uart-read.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~
 
diff --git a/docs/reference/bluetooth/uart-write.md b/docs/reference/bluetooth/uart-write.md
index 0f308b8e..34568c9f 100755
--- a/docs/reference/bluetooth/uart-write.md
+++ b/docs/reference/bluetooth/uart-write.md
@@ -3,7 +3,7 @@
 ### ~hint
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
-For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first connect to the micro:bit.
+For another device like a smartphone to use any of the Bluetooth "services" which the micro:bit has, it must first be [paired with the micro:bit](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the micro:bit and exchange data relating to many of the micro:bit's features.
 
 ### ~