2.1.28, initiation update to PXT v5.28.24 (#54)

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

@@ -2,23 +2,21 @@
 
 Register code to run when the @boardname@ receives a command from the paired gamepad.
 
-### ~hint
+## ~hint
 
-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.
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
 
-### ~
+## ~
 
 ```sig
 devices.onGamepadButton(MesDpadButtonInfo.ADown, () => {})
 ```
 
-### Parameters
+## Parameters
 
 * ``body``: Action code to run when the the @boardname@ receives a command from the paired gamepad.
 
-### See Also
+## See Also
 
 [tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [signal strength](/reference/devices/signal-strength), [on signal strength changed](/reference/devices/on-signal-strength-changed)
 

docs/reference/devices/on-notified.md

@@ -1,25 +1,22 @@
-# On Signal Strength Changed
+# On Notified
 
 Register code to run when the signal strength of the paired device changes.
 
-### ~hint
+## ~hint
 
-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.
-
-### ~
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
 
+## ~
 
 ```sig
 devices.onNotified(MesDeviceInfo.IncomingCall, () => {})
 ```
 
-### Parameters
+## Parameters
 
 * ``body``: code to run when the signal strength changes.
 
-### Examples
+## Examples
 
 Display the signal strength on screen:
 
@@ -29,7 +26,7 @@ devices.onNotified(MesDeviceInfo.IncomingCall, () => {
 })
 ```
 
-### See Also
+## See Also
 
 [tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [signal strength](/reference/devices/signal-strength)
 

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

@@ -2,34 +2,33 @@
 
 Register code to run when the signal strength of the paired device changes.
 
-### ~hint
+## ~hint
 
-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.
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
+
+## ~
 
-### ~
 
 
 ```sig
 devices.onSignalStrengthChanged(() => {})
 ```
 
-### Parameters
+## Parameters
 
 * ``body``: code to run when the signal strength changes.
 
-### Examples
+## Examples
 
 Display the signal strength on screen:
 
 ```blocks
 devices.onSignalStrengthChanged(() => {
-    basic.showNumber(devices.signalStrength(), 150)
+    basic.showNumber(devices.signalStrength())
 })
 ```
 
-### See Also
+## See Also
 
 [tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [signal strength](/reference/devices/signal-strength)
 

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

@@ -2,62 +2,61 @@
 
 Raise an alert on a remote device.
 
-### ~hint
+## ~hint
 
-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.
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
+
+## ~
 
-### ~
 
 
 ```sig
-export function raiseAlertTo(event: string)
+devices.raiseAlertTo(MesAlertEvent.Vibrate)
 ```
 
-### Parameters
+## Parameters
 
 * event - an event identifier
 
-### Examples
+## Examples
 
 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
+## See also
 
 [tell remote control to](/reference/devices/tell-remote-control-to), [tell camera to](/reference/devices/tell-camera-to)
 

docs/reference/devices/signal-strength.md

@@ -2,33 +2,32 @@
 
 Returns the signal strength reported by the paired device from ``0`` (no signal) to ``4`` (full strength).
 
-### ~hint
+## ~hint
 
-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.
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
+
+## ~
 
-### ~
 
 ```sig
 devices.signalStrength();
 ```
 
-### Returns
+## Returns
 
 * the signal strength from ``0`` (no signal) to ``4`` (full strength).
 
-### Examples
+## Examples
 
 Display the signal strength on screen:
 
 ```blocks
 devices.onSignalStrengthChanged(() => {
-    basic.showNumber(devices.signalStrength(), 150)
+    basic.showNumber(devices.signalStrength())
 })
 ```
 
-### See Also
+## See Also
 
 [tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [on signal strength changed](/reference/devices/on-signal-strength-changed)
 

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

@@ -2,73 +2,72 @@
 
 Access the photo/video-taking functionality of a remote device using the ``tell camera to`` function.
 
-### ~hint
+## ~hint
 
-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.
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
+
+## ~
 
-### ~
 
 ```sig
-devices.tellCameraTo()
+devices.tellCameraTo(MesCameraEvent.TakePhoto)
 ```
 
-### Parameters
+## Parameters
 
 * event - an event identifier
 
-### Examples
+## Examples
 
 To tell the connected device to take a picture:
 
 ```blocks
-devices.tellCameraTo("take photo")
+devices.tellCameraTo(MesCameraEvent.TakePhoto)
 ```
 
-To tell the connected device to start recording a video
+To tell the connected device to start recording a video:
 
 ```blocks
-devices.tellCameraTo("start video capture")
+devices.tellCameraTo(MesCameraEvent.StartVideoCapture)
 ```
 
-To tell the connected device to stop recording a video
+To tell the connected device to stop recording a video:
 
 ```blocks
-devices.tellCameraTo("stop video capture")
+devices.tellCameraTo(MesCameraEvent.StopVideoCapture)
 ```
 
-To tell the connected device to toggle front-rear
+To tell the connected device to toggle front-rear:
 
 ```blocks
-devices.tellCameraTo("toggle front-rear")
+devices.tellCameraTo(MesCameraEvent.ToggleFrontRear)
 ```
 
-To tell the connected device to launch photo mode
+To tell the connected device to launch photo mode:
 
 ```blocks
-devices.tellCameraTo("launch photo mode")
+devices.tellCameraTo(MesCameraEvent.LaunchPhotoMode)
 ```
 
-To tell the connected device to launch video mode
+To tell the connected device to launch video mode:
 
 ```blocks
-devices.tellCameraTo("launch video mode")
+devices.tellCameraTo(MesCameraEvent.LaunchVideoMode)
 ```
 
-To tell the connected device to stop photo mode
+To tell the connected device to stop photo mode:
 
 ```blocks
-devices.tellCameraTo("stop photo mode")
+devices.tellCameraTo(MesCameraEvent.StopPhotoMode)
 ```
 
-To tell the connected device to stop video mode
+To tell the connected device to stop video mode:
 
 ```blocks
-devices.tellCameraTo("stop video mode")
+devices.tellCameraTo(MesCameraEvent.StopVideoMode)
 ```
 
-### See Also
+## See Also
 
 [tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to)
 

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

@@ -2,23 +2,22 @@
 
 Control the presentation of media content available on a remote device using the `tell remote control` to function.
 
-### ~hint
+## ~hint
 
-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.
+**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
+
+## ~
 
-### ~
 
 ```sig
-devices.tellRemoteControlTo(event: string)
+devices.tellRemoteControlTo(MesRemoteControlEvent.play)
 ```
 
-### Parameters
+## Parameters
 
 * event - an event identifier
 
-### Event values
+## Event values
 
 * play
 * stop
@@ -30,57 +29,57 @@ devices.tellRemoteControlTo(event: string)
 * previous track
 * next track
 
-### Examples
+## Examples
 
 To tell the connected device to start playing:
 
 ```blocks
-devices.tellRemoteControlTo("play")
+devices.tellRemoteControlTo(MesRemoteControlEvent.play)
 ```
 
 To tell the connected device to stop playing
 
 ```blocks
-devices.tellRemoteControlTo("stop")
+devices.tellRemoteControlTo(MesRemoteControlEvent.stop)
 ```
 
 To tell the connected device to go to next track
 
 ```blocks
-devices.tellRemoteControlTo("next track")
+devices.tellRemoteControlTo(MesRemoteControlEvent.nextTrack)
 ```
 
 To tell the connected device to go to previous track
 
 ```blocks
-devices.tellRemoteControlTo("previous track")
+devices.tellRemoteControlTo(MesRemoteControlEvent.previousTrack)
 ```
 
 To tell the connected device to go forward
 
 ```blocks
-devices.tellRemoteControlTo("forward")
+devices.tellRemoteControlTo(MesRemoteControlEvent.forward)
 ```
 
 To tell the connected device to rewind
 
 ```blocks
-devices.tellRemoteControlTo("rewind")
+devices.tellRemoteControlTo(MesRemoteControlEvent.rewind)
 ```
 
 To tell the connected device volume up
 
 ```blocks
-devices.tellRemoteControlTo("volume up")
+devices.tellRemoteControlTo(MesRemoteControlEvent.volumeUp)
 ```
 
 To tell the connected device volume down
 
 ```blocks
-devices.tellRemoteControlTo("volume down")
+devices.tellRemoteControlTo(MesRemoteControlEvent.volumeDown)
 ```
 
-### See also
+## See also
 
 [tell camera to](/reference/devices/tell-camera-to), [raise alert to](/reference/devices/raise-alert-to)