undusted BT docs

docs/SUMMARY.md

@@ -88,6 +88,35 @@
         * [set transmit power](/reference/radio/set-transmit-power)
         * [set transmit serial number](/reference/radio/set-transmit-serial-number)
         * [write received packet to serial](/reference/radio/write-received-packet-to-serial)
+    * [Bluetooth](/reference/bluetooth)
+        * [About](/reference/bluetooth/about-bluetooth)    
+        * [Pairing](/reference/bluetooth/bluetooth-pairing)
+        * [on bluetooth connected](/reference/bluetooth/on-bluetooth-connected)
+        * [on bluetooth disconnected](/reference/bluetooth/on-bluetooth-disconnected)
+        * [start accelerometer service](/reference/bluetooth/start-accelerometer-service)
+        * [start button service](/reference/bluetooth/start-button-service)
+        * [start io pin service](/reference/bluetooth/start-io-pin-service)
+        * [start led service](/reference/bluetooth/start-led-service)
+        * [start magnetometer service](/reference/bluetooth/start-magnetometer-service)
+        * [start temperature service](/reference/bluetooth/start-temperature-service)
+        * [start uart service](/reference/bluetooth/start-uart-service)
+        * [uart read until](/reference/bluetooth/uart-read-until)
+        * [uart write string](/reference/bluetooth/uart-write-string)
+        * [uart write number](/reference/bluetooth/uart-write-number)
+        * [uart write value](/reference/bluetooth/uart-write-value)
+        * [advertise url](/reference/bluetooth/advertise-url)
+        * [stop advertising](/reference/bluetooth/stop-advertising)
+        * [advertise uid](/reference/bluetooth/advertise-uid)
+        * [advertise-uid-buffer](/reference/bluetooth/advertise-uid-buffer)
+    * [Devices](/reference/devices)
+        * [tell camera to](/reference/devices/tell-camera-to)
+        * [tell remote control to](/reference/devices/tell-remote-control-to)
+        * [raise alert to](/reference/devices/raise-alert-to)
+        * [on notified](/reference/devices/on-notified)
+        * [on gamepad button](/reference/devices/on-gamepad-button)
+        * [signal strength](/reference/devices/signal-strength)
+        * [on signal strength changed](/reference/devices/on-signal-strength-changed)
+        
 
 ## #other
 

docs/reference/devices/on-gamepad-button.md

@@ -3,10 +3,9 @@
 Register code to run when the @boardname@ receives a command from the paired gamepad.
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 

docs/reference/devices/on-notified.md

@@ -3,14 +3,14 @@
 Register code to run when the signal strength of the paired device changes.
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 
 
+
 ```sig
 devices.onNotified(MesDeviceInfo.IncomingCall, () => {})
 ```

docs/reference/devices/on-signal-strength-changed.md

@@ -3,14 +3,14 @@
 Register code to run when the signal strength of the paired device changes.
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 
 
+
 ```sig
 devices.onSignalStrengthChanged(() => {})
 ```
@@ -25,7 +25,7 @@ Display the signal strength on screen:
 
 ```blocks
 devices.onSignalStrengthChanged(() => {
-    basic.showNumber(devices.signalStrength(), 150)
+    basic.showNumber(devices.signalStrength())
 })
 ```
 

docs/reference/devices/raise-alert-to.md

@@ -3,16 +3,16 @@
 Raise an alert on a remote device.
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 
 
+
 ```sig
-export function raiseAlertTo(event: string)
+devices.raiseAlertTo(MesAlertEvent.Vibrate)
 ```
 
 ### Parameters
@@ -24,37 +24,37 @@ export function raiseAlertTo(event: string)
 To tell the connected device to display toast
 
 ```blocks
-devices.raiseAlertTo("display toast")
+devices.raiseAlertTo(MesAlertEvent.DisplayToast)
 ```
 
 To tell the connected device to vibrate
 
 ```blocks
-devices.raiseAlertTo("vibrate")
+devices.raiseAlertTo(MesAlertEvent.Vibrate)
 ```
 
 To tell the connected device to play a sound
 
 ```blocks
-devices.raiseAlertTo("play sound")
+devices.raiseAlertTo(MesAlertEvent.PlaySound)
 ```
 
 To tell the connected device to play a ringtone
 
 ```blocks
-devices.raiseAlertTo("play ringtone")
+devices.raiseAlertTo(MesAlertEvent.PlayRingtone)
 ```
 
 To tell the connected device to find my phone
 
 ```blocks
-devices.raiseAlertTo("find my phone")
+devices.raiseAlertTo(MesAlertEvent.FindMyPhone)
 ```
 
 To tell the connected device to ring alarm
 
 ```blocks
-devices.raiseAlertTo("ring alarm")
+devices.raiseAlertTo(MesAlertEvent.RingAlarm)
 ```
 
 ### See also

docs/reference/devices/signal-strength.md

@@ -3,13 +3,13 @@
 Returns the signal strength reported by the paired device from ``0`` (no signal) to ``4`` (full strength).
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 
+
 ```sig
 devices.signalStrength();
 ```
@@ -24,7 +24,7 @@ Display the signal strength on screen:
 
 ```blocks
 devices.onSignalStrengthChanged(() => {
-    basic.showNumber(devices.signalStrength(), 150)
+    basic.showNumber(devices.signalStrength())
 })
 ```
 

docs/reference/devices/tell-camera-to.md

@@ -3,13 +3,13 @@
 Access the photo/video-taking functionality of a remote device using the ``tell camera to`` function.
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 
+
 ```sig
 devices.tellCameraTo(MesCameraEvent.TakePhoto)
 ```

docs/reference/devices/tell-remote-control-to.md

@@ -3,13 +3,13 @@
 Control the presentation of media content available on a remote device using the `tell remote control` to function.
 
 ### ~hint
+![](/static/bluetooth/Bluetooth_SIG.png)
 
-The functions in the ``devices`` namespace allow the @boardname@ to communicate with a separate (remote) device, 
-such as a smartphone, over Bluetooth (Smart).
-The set of supported events will depend on the remote device and the @boardname@ apps available for the remote device.
+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.
 
 ### ~
 
+
 ```sig
 devices.tellRemoteControlTo(MesRemoteControlEvent.play)
 ```

libs/devices/shims.d.ts

@@ -4,7 +4,7 @@
     /**
      * Control a phone with the BBC micro:bit via Bluetooth.
      */
-    //% color=156 weight=80
+    //% color=#008272 weight=80 icon="\uf10b"
 declare namespace devices {
 
     /**