Updates for V4 (#197)

* update yotta defaults for 16kb devices

* refactor deprecated blocks

* updates for button events

* update button events

* update refference

* update docs

* update docs

* update button event blocks

* update docs

* update block id

docs/reference/basic.md

@@ -27,4 +27,4 @@ basic.showIcon(IconNames.ArrowNorth);
 [showIcon](/reference/basic/show-icon),
 [showLeds](/reference/basic/show-leds), [showString](/reference/basic/show-string), 
 [clearScreen](/reference/basic/clear-screen), [forever](/reference/basic/forever), [pause](/reference/basic/pause), 
-[showAnimation](/reference/basic/show-animation)
+[showAnimation](/reference/basic/show-animation)

docs/reference/basic/forever.md

@@ -1,4 +1,4 @@
-# Forever
+# forever
 
 Keep running part of a program 
 [in the background](/reference/control/in-background).
@@ -8,7 +8,20 @@ basic.forever(() => {
 })
 ```
 
-## Example: compass
+You can have part of a program continuously by placing it in an **forever** loop. The **forever** loop will _yield_ to the other code in your program though, allowing that code to have time to run when needs to.
+
+### ~ reminder
+
+#### Event-based loops
+
+Both the **forever** loop and the **every** loop are _event-based_ loops where the code inside is run as part of a function. These are different from the [for](/blocks/loops/for) and [while](/blocks/loops/while) loops. Those are loops are part of the programming language and can have [break](/blocks/loops/break) and [continue](/blocks/loops/continue) statements in them.
+You can NOT use **break** or **continue** in either a **forever** loop or an **every** loop.
+
+### ~
+
+## Examples
+
+### Example: compass
 
 The following example constantly checks the 
 [compass heading](/reference/input/compass-heading) 
@@ -32,7 +45,7 @@ basic.forever(() => {
 })
 ```
 
-## Example: counter
+### Example: counter
 
 The following example keeps showing the [number](/types/number) stored in a global variable.
 When you press button `A`, the number gets bigger.
@@ -43,7 +56,7 @@ let num = 0
 basic.forever(() => {
     basic.showNumber(num)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     num = num + 1
 })
 ```
@@ -59,12 +72,12 @@ Try this on your @boardname@:
 basic.forever(() => {
     basic.showNumber(6789)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     basic.showNumber(2)
 })
 ```
 
 ## See also
 
-[while](/blocks/loops/while), [on button pressed](/reference/input/on-button-pressed), [in background](/reference/control/in-background)
+[while](/blocks/loops/while), [in background](/reference/control/in-background), [every](/reference/loops/every-interval)
 

docs/reference/basic/pause.md

@@ -24,6 +24,10 @@ for (let i = 0; i < 5; i++) {
 }
 ```
 
+## Advanced
+
+If `ms` is `NaN` (not a number), it will default to `20` ms.
+
 ## See also
 
 [while](/blocks/loops/while), [running time](/reference/input/running-time), [for](/blocks/loops/for)

docs/reference/basic/plot-leds.md

@@ -1,34 +0,0 @@
-# Plot LEDs
-
-Display an [Image](/reference/images/image) on the @boardname@'s [LED screen](/device/screen).
-
-```sig
-basic.showLeds(`
-. . . . .
-. # . # .
-. . # . .
-# . . . #
-. # # # .
-`)
-```
-
-## Parameters
-
-* leds - a series of LED on/off states that form an image (see steps below)
-
-## Example: smiley
-
-```blocks
-basic.showLeds(`
-. . . . .
-. # . # .
-. . # . .
-# . . . #
-. # # # .
-`)
-```
-
-## See also
-
-[show animation](/reference/basic/show-animation), [image](/reference/images/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
-

docs/reference/basic/rgb.md

@@ -0,0 +1 @@
+# RGB

docs/reference/basic/set-led-color.md

@@ -0,0 +1 @@
+# Set LED Color

docs/reference/basic/show-animation.md

@@ -1,64 +0,0 @@
-# show Animation
-
-Show a group of image frames (pictures) one after another on the [LED screen](/device/screen). It pauses the amount of time you tell it after each frame.
-
-```sig
-basic.showAnimation(`
-. . # . . . # # # . . # # # .
-. # # . . . . . # . . . . # .
-. . # . . . . # . . . # # # .
-. . # . . . # . . . . . . # .
-. . # . . . # # # . . # # # .
-`)
-```
-
-## Parameters
-
-* `leds` is a [string](/types/string) that shows which LEDs are on and off, in groups one after another.
-* `interval` is an optional [number](/types/number). It means the number of milliseconds to pause after each image frame.
-
-## Example: Animating a group of image frames
-
-In this animation, each row is 15 spaces wide because
-there are three frames in the animation, and each frame is
-five spaces wide, just like the screen on the @boardname@.
-
-```blocks
-basic.showAnimation(`
-. . # . . . # # # . . # # # .
-. # # . . . . . # . . . . # .
-. . # . . . . # . . . # # # .
-. . # . . . # . . . . . . # .
-. . # . . . # # # . . # # # .
-`)
-```
-
-## ~hint 
-
-If the animation is too fast, make `interval` bigger.
-
-## ~
-
-## Example: animating frames with a pause
-
-This example shows six frames on the screen, pausing 500 milliseconds after each frame.
-
-In this animation, each row is 30 spaces wide because
-there are six frames in the animation, and each frame is
-five spaces wide, just like the screen.
-
-```blocks
-basic.showAnimation(`
-. . . . . # . . . . . . . . . . . . . # . . . . . # . . . .
-. . # . . . . . . . . . # . . . . . . . . . # . . . . . . .
-. # . # . . . # . . . # . # . . . # . . . # . # . . . # . .
-. . # . . . . . . . . . # . . . . . . . . . # . . . . . . .
-. . . . . . . . . # . . . . . # . . . . . . . . . . . . . #
-`, 500)
-```
-
-## ~hint 
-
-Use [forever](/reference/basic/forever) to show an animation over and over.
-
-## ~

docs/reference/basic/show-compass.md

@@ -0,0 +1 @@
+# Show Compass

docs/reference/basic/show-number.md

@@ -8,7 +8,7 @@ basic.showNumber(2)
 
 ## Parameters
 
-* `value` is a [Number](/types/number).
+* `value` is a [Number](/types/number). If the number is not single-digit number, it will scroll on the display.
 * `interval` is an optional [Number](/types/number). It means the number of milliseconds before sliding the `value` left by one LED each time. Bigger intervals make the sliding slower.
 
 ## Examples:
@@ -37,6 +37,10 @@ for (let i = 0; i < 6; i++) {
 }
 ```
 
+## Advanced
+
+If `value` is `NaN` (not a number), `?` is displayed.
+
 ## Other show functions
 
 * Use [show string](/reference/basic/show-string) to show a [String](/types/string) with letters on the screen.

docs/reference/basic/turn-rgb-led-off.md

@@ -0,0 +1 @@
+# Turn RGB Led Off

docs/reference/bluetooth.md

@@ -3,6 +3,7 @@
 Support for additional Bluetooth services.
 
 ## ~hint
+
 ![](/static/bluetooth/Bluetooth_SIG.png)
 
 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.
@@ -34,14 +35,6 @@ bluetooth.uartWriteValue("", 0);
 bluetooth.onUartDataReceived(",", () => {})
 ```
 
-## Eddystone
-
-```cards
-bluetooth.advertiseUid(42, 1, 7, true);
-bluetooth.advertiseUrl("https://makecode.microbit.org/", 7, true);
-bluetooth.stopAdvertising();
-```
-
 ## Advanced
  
 For more advanced information on the @boardname@ Bluetooth UART service including information on using a smartphone, see the [Lancaster University @boardname@ runtime technical documentation](http://lancaster-university.github.io/microbit-docs/ble/uart-service/)
@@ -56,9 +49,7 @@ For more advanced information on the @boardname@ Bluetooth UART service includin
 [uartWriteNumber](/reference/bluetooth/uart-write-number), 
 [uartWriteValue](/reference/bluetooth/uart-write-value), 
 [onBluetoothConnected](/reference/bluetooth/on-bluetooth-connected), 
-[onBluetoothDisconnected](/reference/bluetooth/on-bluetooth-disconnected),
+[onBluetoothDisconnected](/reference/bluetooth/on-bluetooth-disconnected)
-[advertiseUrl](/reference/bluetooth/advertise-url),
-[stopAdvertising](/reference/bluetooth/stop-advertising)
 
 ```package
 bluetooth

docs/reference/bluetooth/advertise-uid-buffer.md

@@ -2,6 +2,18 @@
 
 Advertises a UID via the Eddystone protocol over Bluetooth.
 
+```sig
+bluetooth.advertiseUidBuffer(pins.createBuffer(16), 7, true);
+```
+
+### ~ reminder
+
+#### Deprecated
+
+This API is deprecated. The Eddystone beacon format is no longer supported, see [Google Beacon format (Deprecated)](https://developers.google.com/beacons/eddystone).
+
+### ~
+
 ## ~hint
 
 ## Eddystone
@@ -17,10 +29,6 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
 
 ## ~
 
-```sig
-bluetooth.advertiseUidBuffer(pins.createBuffer(16), 7, true);
-```
-
 ## Parameters
 
 * ``buffer`` - a 16 bytes buffer containing the namespace (first 10 bytes) and instance (last 6 bytes).

docs/reference/bluetooth/advertise-uid.md

@@ -2,6 +2,18 @@
 
 Advertises a UID via the Eddystone protocol over Bluetooth.
 
+```sig
+bluetooth.advertiseUid(42, 1, 7, true);
+```
+
+### ~ reminder
+
+#### Deprecated
+
+This API is deprecated. The Eddystone beacon format is no longer supported, see [Google Beacon format (Deprecated)](https://developers.google.com/beacons/eddystone).
+
+### ~
+
 ## ~hint
 
 ## Eddystone
@@ -17,10 +29,6 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
 
 ## ~
 
-```sig
-bluetooth.advertiseUid(42, 1, 7, true);
-```
-
 ## Parameters
 
 * ``namespace`` last 4 bytes of the namespace uid (6 to 9)

docs/reference/bluetooth/advertise-url.md

@@ -2,6 +2,18 @@
 
 Advertises a URL via the Eddystone protocol over Bluetooth.
 
+```sig
+bluetooth.advertiseUrl("https://makecode.microbit.org/", 7, true);
+```
+
+### ~ reminder
+
+#### Deprecated
+
+This API is deprecated. The Eddystone beacon format is no longer supported, see [Google Beacon format (Deprecated)](https://developers.google.com/beacons/eddystone).
+
+### ~
+
 ## ~hint
 
 ## Eddystone
@@ -17,10 +29,6 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
 
 ## ~
 
-```sig
-bluetooth.advertiseUrl("https://makecode.microbit.org/", 7, true);
-```
-
 ## Parameters
 
 * ``url`` - a [string](/types/string) containing the URL to broadcast, at most 17 characters long, excluding the protocol (eg: ``https://``) which gets encoded as 1 byte.

docs/reference/bluetooth/on-uart-data-received.md

@@ -1,21 +1,50 @@
 # Bluetooth On UART Data Received
 
-Registers an event to be fired when one of the delimiter is matched.
+Runs some code in an event when a delimiter is matched in the received data.
 
 ```sig
-bluetooth.onUartDataReceived(",", () => {})
+bluetooth.onUartDataReceived(serial.delimiters(Delimiters.NewLine), function() {})
 ```
 
 ## Parameters
 
-* `delimiters` is a [string](/types/string) containing any of the character to match
+* **delimiters**: a [string](/types/string) containing the delimiter characters to match in the received data.
+
+### ~ hint
+
+#### Delimiters
+
+Delimiters are characters in a received data string which divide the string into smaller strings to form separate data items.
+
+Although multiple delimiter characters can be set in the **delimiters** string, it is common to have received data separated using just one delimiter character, such as a comma:
+
+``"data1,data2,data3,data4"``
+
+So, you can specify a delimiter character using the ``||serial:serial delimiters||`` which create a single character delimiter string for you...
+
+```block
+bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), function () {
+})
+```
+Or, maybe...
+
+```block
+let delim = serial.delimiters(Delimiters.NewLine)
+basic.showString(bluetooth.uartReadUntil(delim))
+```
+
+### ~
 
 ## Example
 
-Read values separated by `,`:
+Read the data items separated by a comma (`,`):
 
 ```blocks
-bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), () => {
+bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), function () {
-    basic.showString(serial.readUntil(serial.delimiters(Delimiters.Comma)))
+    basic.showString(bluetooth.uartReadUntil(serial.delimiters(Delimiters.Space)))
 })
 ```
+
+```package
+bluetooth
+```

docs/reference/control.md

@@ -4,7 +4,7 @@ Runtime and event utilities.
 
 ```cards
 control.inBackground(() => {
-    
+
 });
 control.reset();
 control.waitMicros(4);

docs/reference/devices.md

@@ -1,33 +0,0 @@
-# Devices
-
-Control a phone with the @boardname@ via Bluetooth.
-
-## ~ hint
-
-**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
-
-## ~
-
-```cards
-devices.tellCameraTo(MesCameraEvent.TakePhoto);
-devices.tellRemoteControlTo(MesRemoteControlEvent.play);
-devices.raiseAlertTo(MesAlertEvent.DisplayToast);
-devices.onNotified(MesDeviceInfo.IncomingCall, () => {
-    
-});
-devices.onGamepadButton(MesDpadButtonInfo.ADown, () => {
-    
-});
-devices.signalStrength();
-devices.onSignalStrengthChanged(() => {
-    
-});
-```
-
-```package
-devices
-```
-
-## See Also
-
-[tellCameraTo](/reference/devices/tell-camera-to), [tellRemoteControlTo](/reference/devices/tell-remote-control-to), [raiseAlertTo](/reference/devices/raise-alert-to), [onNotified](/reference/devices/on-notified), [onGamepadButton](/reference/devices/on-gamepad-button), [signalStrength](/reference/devices/signal-strength), [onSignalStrengthChanged](/reference/devices/on-signal-strength-changed)

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

@@ -1,25 +0,0 @@
-# On Gamepad Button
-
-Register code to run when the @boardname@ receives a command from the paired gamepad.
-
-## ~hint
-
-**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
-
-* ``body``: Action code to run when the the @boardname@ receives a command from the paired gamepad.
-
-## 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)
-
-```package
-devices
-```

docs/reference/devices/on-notified.md

@@ -1,35 +0,0 @@
-# On Notified
-
-Register code to run when the signal strength of the paired device changes.
-
-## ~hint
-
-**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
-
-* ``body``: code to run when the signal strength changes.
-
-## Examples
-
-Display the signal strength on screen:
-
-```blocks
-devices.onNotified(MesDeviceInfo.IncomingCall, () => {
-    basic.showString("RING RING")
-})
-```
-
-## 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)
-
-```package
-devices
-```

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

@@ -1,37 +0,0 @@
-# On Signal Strength Changed
-
-Register code to run when the signal strength of the paired device changes.
-
-## ~hint
-
-**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
-
-## ~
-
-
-
-```sig
-devices.onSignalStrengthChanged(() => {})
-```
-
-## Parameters
-
-* ``body``: code to run when the signal strength changes.
-
-## Examples
-
-Display the signal strength on screen:
-
-```blocks
-devices.onSignalStrengthChanged(() => {
-    basic.showNumber(devices.signalStrength())
-})
-```
-
-## 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)
-
-```package
-devices
-```

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

@@ -1,65 +0,0 @@
-# raise alert to
-
-Raise an alert on a remote device.
-
-## ~hint
-
-**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
-
-## ~
-
-
-
-```sig
-devices.raiseAlertTo(MesAlertEvent.Vibrate)
-```
-
-## Parameters
-
-* event - an event identifier
-
-## Examples
-
-To tell the connected device to display toast
-
-```blocks
-devices.raiseAlertTo(MesAlertEvent.DisplayToast)
-```
-
-To tell the connected device to vibrate
-
-```blocks
-devices.raiseAlertTo(MesAlertEvent.Vibrate)
-```
-
-To tell the connected device to play a sound
-
-```blocks
-devices.raiseAlertTo(MesAlertEvent.PlaySound)
-```
-
-To tell the connected device to play a ringtone
-
-```blocks
-devices.raiseAlertTo(MesAlertEvent.PlayRingtone)
-```
-
-To tell the connected device to find my phone
-
-```blocks
-devices.raiseAlertTo(MesAlertEvent.FindMyPhone)
-```
-
-To tell the connected device to ring alarm
-
-```blocks
-devices.raiseAlertTo(MesAlertEvent.RingAlarm)
-```
-
-## See also
-
-[tell remote control to](/reference/devices/tell-remote-control-to), [tell camera to](/reference/devices/tell-camera-to)
-
-```package
-devices
-```

docs/reference/devices/signal-strength.md

@@ -1,36 +0,0 @@
-# Signal Strength
-
-Returns the signal strength reported by the paired device from ``0`` (no signal) to ``4`` (full strength).
-
-## ~hint
-
-**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
-
-## ~
-
-
-```sig
-devices.signalStrength();
-```
-
-## Returns
-
-* the signal strength from ``0`` (no signal) to ``4`` (full strength).
-
-## Examples
-
-Display the signal strength on screen:
-
-```blocks
-devices.onSignalStrengthChanged(() => {
-    basic.showNumber(devices.signalStrength())
-})
-```
-
-## 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)
-
-```package
-devices
-```

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

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

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

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

docs/reference/event-handler.md

@@ -9,7 +9,7 @@ An event handler is code that is associated with a particular event, such as "bu
 Functions named "on <event>" create an association between an event and the event handler code.  For example, the following code registers the event handler (the code between the `do` and `end` keywords) with the event of a press of button A:
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     basic.showString("hello", 150)
 })
 ```
@@ -21,7 +21,7 @@ After this code executes, then whenever button A is pressed in the future, the s
 Once you have registered an event handler for an event, like above, that event handler is active for the rest of the program execution. If you want to stop the string "hello" from printing each time button A is pressed then you need to arrange for the following code to execute:
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
 })
 ```
 
@@ -32,10 +32,10 @@ The above code associated an event handler that does nothing with the event of a
 The above example also illustrates that there is only one event handler for each event. What is the result of the following code?
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     basic.showString("hello", 150)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     basic.showString("goodbye", 150)
 })
 ```
@@ -43,7 +43,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
 The answer is that whenever button A is pressed, the string "goodbye" will be printed. If you want both the strings "hello" and "goodbye" to be printed, you need to write the code like this:
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     basic.showString("hello", 150)
     basic.showString("goodbye", 150)
 })

docs/reference/game/change.md

@@ -1,19 +1,23 @@
 # change (Sprite Property)
 
-Change the kind of [number](/types/number) you say for a [sprite](/reference/game/create-sprite).
+Change a value for a [sprite](/reference/game/create-sprite) property by some amount.
 
 ```sig
 game.createSprite(0,0).change(LedSpriteProperty.X, 0);
 ```
 
+The value of a sprite propery is changed by using either a positive or negative number. Giving `1` will increase a property value by `1` and giving a `-1` will decrease it by `1`.
+
 ## Parameters
 
 * **property**: the property of the **Sprite** you want to change, like:
->* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
+>* ``x`` - the change in horizontal location to set the sprite at on the LED screen (`0`-`4`)
->* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
+>* ``y`` - the change vertical location to set the sprite at on the LED screen (`0`-`4`)
->* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+>* ``direction`` - the change of direction in degrees for the sprite to go when the next [move](/reference/game/move) happens. Direction degree range is from `-180` to `180`.
->* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+>* ``brightness`` - the change in brightness for the LED sprite. Completely dark is `0` and very bright is `255`.
->* ``blink`` -  how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+>* ``blink`` - the change in how fast the sprite is will blink on and off. The blink rate is in milliseconds.
+
+* **value**: a [number](/types/number) value that is the amount of change for the property.
 
 ## Example
 

docs/reference/game/get.md

@@ -1,6 +1,6 @@
 # get (Sprite Property)
 
-Find something out about a [sprite](/reference/game/create-sprite).
+Get a value for a [sprite](/reference/game/create-sprite) property.
 
 ```sig
 game.createSprite(0,0).get(LedSpriteProperty.X);
@@ -9,11 +9,11 @@ game.createSprite(0,0).get(LedSpriteProperty.X);
 ## Parameters
 
 * **property**: the property of the **Sprite** you want to know about, like:
->* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
+>* ``x`` - the horizontal location to set the sprite at on the LED screen (`0`-`4`)
->* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
+>* ``y`` - the vertical location to set the sprite at on the LED screen (`0`-`4`)
->* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+>* ``direction`` - the direction in degrees for the sprite to go when the next [move](/reference/game/move) happens. The degree range is from `-180` to `180`.
->* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+>* ``brightness`` - how bright the LED sprite is. Completely dark is `0` and very bright is `255`.
->* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+>* ``blink`` - how fast the sprite is will blink on and off. The blink rate is in milliseconds.
 
 ## Returns
 

docs/reference/game/is-running.md

@@ -15,7 +15,7 @@ game.isRunning()
 If the game is currently running, end the game if button **B** is pressed.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.B, input.buttonEventClick(), function () {
 	if (game.isRunning()) {
         game.gameOver()
     }

docs/reference/game/set-score.md

@@ -16,11 +16,11 @@ Press button ``A`` as much as possible to increase the score.
 Press ``B`` to display the score and reset the score.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     basic.showNumber(game.score())
     game.setScore(0)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     game.addScore(1)
 })
 ```

docs/reference/game/set.md

@@ -1,6 +1,6 @@
 # set (Sprite Property)
 
-Make a [sprite](/reference/game/create-sprite) store the kind of [number](/types/number) you say.
+Set a value for a [sprite](/reference/game/create-sprite) property.
 
 ```sig
 game.createSprite(0,0).set(LedSpriteProperty.X, 0);
@@ -9,22 +9,39 @@ game.createSprite(0,0).set(LedSpriteProperty.X, 0);
 ## Parameters
 
 * **property**: the property of the **Sprite** you want to store a value for, like:
->* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
+>* ``x`` - the horizontal location to set the sprite at on the LED screen (`0`-`4`)
->* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
+>* ``y`` - the vertical location to set the sprite at on the LED screen (`0`-`4`)
->* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+>* ``direction`` - the direction in degrees for the sprite to go when the next [move](/reference/game/move) happens. The degree range is from `-180` to `180`.
->* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+>* ``brightness`` - how bright the LED sprite is. Completely dark is `0` and very bright is `255`.
->* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+>* ``blink`` - how fast the sprite is will blink on and off. The blink rate is in milliseconds.
+
+* **value**: the a [number](/types/number) value to set for the property.
 
 ## Example
 
-This program makes a sprite on the left side of the screen,
+Make an LED sprite move to random locations on the screen. Use button **A** to freeze and unfreeze the sprite while it's moving. When the sprite is frozen, it will blink and dim to half brightness.
-waits two seconds (2000 milliseconds),
-and then moves it to the right side of the screen.
 
 ```blocks
-let ball = game.createSprite(0, 2);
+input.onButtonEvent(Button.A, input.buttonEventClick(), function () {
-basic.pause(2000);
+    if (freeze) {
-ball.set(LedSpriteProperty.X, 4);
+        sprite.set(LedSpriteProperty.Brightness, 255)
+        sprite.set(LedSpriteProperty.Blink, 0)
+    } else {
+        sprite.set(LedSpriteProperty.Brightness, 128)
+        sprite.set(LedSpriteProperty.Blink, 200)
+    }
+    freeze = !(freeze)
+})
+let freeze = false
+let sprite: game.LedSprite = null
+sprite = game.createSprite(0, 0)
+basic.forever(function () {
+    if (!(freeze)) {
+        sprite.set(LedSpriteProperty.X, randint(0, 4))
+        sprite.set(LedSpriteProperty.Y, randint(0, 4))
+    }
+    basic.pause(500)
+})
 ```
 
 ## See also

docs/reference/game/start-countdown.md

@@ -17,7 +17,7 @@ Press button ``A`` as much as possible.
 At the end of 10 seconds, the program will show your score.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     game.addScore(1)
 })
 game.startCountdown(10000)

docs/reference/images/create-big-image.md

@@ -36,10 +36,10 @@ let arrows = images.createBigImage(`
     . . # . .   . # # # .
     . . # . .   . . # . .
     `);
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     arrows.showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     arrows.showImage(5);
 });
 ```

docs/reference/images/create-image.md

@@ -25,7 +25,7 @@ arrow and show it on the LED screen. If you press button `B`, the
 program will show a picture of the arrow upside-down.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     images.createImage(`
         . . # . .
         . # # # .
@@ -34,7 +34,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
         . . # . .
         `).showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     images.createImage(`
         . . # . .
         . . # . .

docs/reference/images/icon-image.md

@@ -20,14 +20,10 @@ Show a happy face when button A is pressed or a sad face when button B is presse
 let iamHappy = images.iconImage(IconNames.Happy)
 let iamSad = images.iconImage(IconNames.Sad)
 
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     iamHappy.showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     iamSad.showImage(0);
 });
 ```
-
-## See also
-
-[arrow image](/reference/images/arrow-image)

docs/reference/images/show-image.md

@@ -31,10 +31,10 @@ let arrows = images.createBigImage(`
     . . # . .   . # # # .
     . . # . .   . . # . .
     `);
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     arrows.showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     arrows.showImage(5);
 });
 ```

docs/reference/input.md

@@ -3,31 +3,31 @@
 Events and data from sensors
 
 ```cards
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), function () {})
-    
+input.onGesture(Gesture.Shake, function () {})
-});
+input.onPinEvent(TouchPin.P0, input.buttonEventDown(), function() {})
-input.onGesture(Gesture.Shake, () => {
+input.buttonIsPressed(Button.A)
-    
+input.pinIsPressed(TouchPin.P0)
-});
+input.isGesture(Gesture.Shake)
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
+input.compassHeading()
-    
+input.temperature()
-});
+input.acceleration(Dimension.X)
-input.buttonIsPressed(Button.A);
+input.lightLevel()
-input.isGesture(Gesture.Shake);
+input.rotation(Rotation.Pitch)
-input.compassHeading();
+input.magneticForce(Dimension.X)
-input.pinIsPressed(TouchPin.P0);
+input.runningTime()
-input.temperature();
+input.runningTimeMicros()
-input.acceleration(Dimension.X);
+input.setAccelerometerRange(AcceleratorRange.OneG)
-input.lightLevel();
-input.rotation(Rotation.Pitch);
-input.magneticForce(Dimension.X);
-input.runningTime();
-input.runningTimeMicros();
-input.setAccelerometerRange(AcceleratorRange.OneG);
 ```
 
 ## See also
 
-[onButtonPressed](/reference/input/on-button-pressed), [onGesture](/reference/input/on-gesture), [onPinPressed](/reference/input/on-pin-pressed), [buttonIsPressed](/reference/input/button-is-pressed), 
+[On Button Event](/reference/input/on-button-event), [onGesture](/reference/input/on-gesture),
+[On Pin Event](/reference/input/on-pin-event),
+[buttonIsPressed](/reference/input/button-is-pressed), [pinIsPressed](/reference/input/pin-is-pressed),
 [is gesture](/reference/input/is-gesture),
-[compassHeading](/reference/input/compass-heading), [pinIsPressed](/reference/input/pin-is-pressed), [temperature](/reference/input/temperature), [acceleration](/reference/input/acceleration), [lightLevel](/reference/input/light-level), [rotation](/reference/input/rotation), [magneticForce](/reference/input/magnetic-force), [runningTime](/reference/input/running-time), [setAccelerometerRange](/reference/input/set-accelerometer-range), [calibrate-compass](/reference/input/calibrate-compass)
+[compassHeading](/reference/input/compass-heading), [temperature](/reference/input/temperature),
+[acceleration](/reference/input/acceleration), [lightLevel](/reference/input/light-level),
+[rotation](/reference/input/rotation), [magneticForce](/reference/input/magnetic-force),
+[runningTime](/reference/input/running-time), [setAccelerometerRange](/reference/input/set-accelerometer-range),
+[calibrate-compass](/reference/input/calibrate-compass)

docs/reference/input/button-event.md

@@ -0,0 +1,62 @@
+# Button event
+
+Returns the ID of one of these button event types:
+* Pressed Down (1)
+* Released Up (2)
+* Clicked (3)
+* Long clicked (4)
+* Hold (5)
+
+This block can be used to define the event type in [on button event](input/on-button-event) and [on pin event](input/on-pin-event).
+
+Note, that by pressing a Button multiple events can raise at the same moment:
+
+| # | User input               | Event raised |
+|---|--------------------------|--------------|
+| 1 | Press A down             | A.Down       |
+| 2 | Hold A for > 1.5 seconds | A.Hold       |
+| 3 | release A                | A.Up         |
+|   |                          | A.LongClick  |
+
+| # | User input   | Event raised |
+|---|--------------|--------------|
+| 1 | Press A down | A.Down       |
+| 2 | Press B down | B.Down       |
+| 3 |              | A+B.Down     |
+|   | Release A up | A.Up         |
+|   |              | A+B.Up       |
+|   |              | A+B.Click    |
+|   | Release B up | B.Up         |
+
+* Every Up-Event will always be followed by either a Click- OR Long-Click-Event, depending on how long the Down-Event has been ago.
+
+## Pressed Down
+
+* For button `A` or `B`: This handler works when the button is pushed down.
+* For `A` and `B` together: This handler works when `A` and `B` are both pushed down, at the moment the second button is pressed.
+
+## Released Up
+
+* For button `A` or `B`: This handler works when the button is released up.
+* For `A` and `B` together: This handler works at the moment the first button is released up while `A` and `B` are both pushed down.
+
+## Clicked
+
+* For button `A` or `B`: This handler works when the button is pushed down and released within 1 second.
+* For `A` and `B` together: This handler works when `A` and `B` are both pushed down, then one of them is released within 1.5 seconds of pushing down the second button.
+
+## Long clicked
+
+* For button `A` or `B`: This handler works when the button is pushed down and released after more than 1 second.
+* For `A` and `B` together: This handler works when `A` and `B` are both pushed down, then one of them is released after more than 1.5 seconds after pushing down the second button.
+  
+## Hold
+
+* For button `A` or `B`: This handler works when the button is pushed down and hold for 1 second.
+* For `A` and `B` together: This handler works when `A` and `B` are both pushed down and hold for 1.5 seconds after pushing down the second button.
+
+**This is an advanced API.**  For more information, see the
+[@boardname@ runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).
+
+## See also
+[on button event](input/on-button-event), [on pin event](input/on-pin-event)

docs/reference/input/calibrate-compass.md

@@ -23,7 +23,7 @@ confuse the @boardname@.
 This example runs the calibration when the user presses **A+B** buttons.
 
 ```blocks
-input.onButtonEvent(Button.AB, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.AB, input.buttonEventClick(), () => {
     input.calibrateCompass();
 })
 ```

docs/reference/input/compass-heading.md

@@ -70,7 +70,7 @@ confuse the @boardname@.
 Keep the calibration handy by running it when the user pressed **A+B**.
 
 ```block
-input.onButtonEvent(Button.AB, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.AB, input.buttonEventClick(), () => {
     input.calibrateCompass();
 })
 ```

docs/reference/input/light-level.md

@@ -29,7 +29,7 @@ program shows the light level
 on the [LED screen](/device/screen).
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     let level = input.lightLevel()
     basic.showNumber(level)
 })

docs/reference/input/logo-is-pressed.md

@@ -0,0 +1,42 @@
+# logo Is Pressed
+
+Check if the @boardname@ logo is currently being pressed.
+
+```sig
+input.logoIsPressed()
+```
+
+## ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+## ~
+
+The logo on the @boardname@ works just like a touch pin. You can check the whether or not the logo is currently being pressed. You use the [boolean](/types/boolean) value for the status of the logo press to make a logical decision in your program.
+
+## Returns
+
+* a [boolean](types/boolean) value that is `true` if the logo is pressed, `false` if the logo is not pressed.
+
+## Example
+
+Show an icon on the LEDs while the logo is pressed.
+
+```blocks
+basic.forever(function () {
+    if (input.logoIsPressed()) {
+        basic.showIcon(IconNames.Diamond)
+    } else {
+        basic.clearScreen()
+    }
+})
+```
+
+## See also
+
+[micro:bit V2](/device/v2),
+[on logo event](/reference/input/on-logo-event),
+[pin is pressed](/referene/inpu/pin-is-pressed),
+[touch set mode](/referene/inpu/touch-set-mode)

docs/reference/input/on-button-event.md

@@ -1,7 +1,9 @@
 # On Button Event
 
 Start an [event handler](/reference/event-handler) (part of the program that will run when something happens, like when a button is pressed).
-This handler works when button `A` or `B` is pressed, or `A` and `B` together.
+This handler works when button `A` or `B` is clicked, or `A` and `B` together. You can choose another event type by using 
+the [button event block](/reference/input/button-event). Possible event types are `pressed down` (1), `released up` (2), `clicked` (3), `long clicked` (4) or `hold` (5).
+
 When you are using this function in a web browser, click the buttons on the screen instead of the ones
 on the @boardname@.
 
@@ -9,7 +11,7 @@ on the @boardname@.
 * For `A` and `B` together: This handler works when `A` and `B` are both pushed down, then one of them is released within 1.5 seconds of pushing down the second button.
 
 ```sig
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {})
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {})
 ```
 
 Find out how buttons provide input to the @boardname@ in this video:
@@ -24,7 +26,7 @@ Each time you press the button, the [LED screen](/device/screen) shows the `coun
 ```blocks
 let count = 0
 basic.showNumber(count)
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     count++;
     basic.showNumber(count);
 })
@@ -35,7 +37,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
 This example shows a number from 1 to 6 when you press the `B` button.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     let dice = randint(0, 5) + 1
     basic.showNumber(dice)
 })
@@ -50,5 +52,5 @@ Otherwise, sometimes they would show a `0`.
 
 ## See also
 
-[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/blocks/math)
+[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/blocks/math), [button event block](/reference/input/button-event)
 

docs/reference/input/on-logo-event.md

@@ -0,0 +1,38 @@
+# on Logo Event
+
+Run some code in your program when the @boardname@ logo is pressed, touched, or released.
+
+```sig
+input.onLogoEvent(TouchButtonEvent.Pressed, function () {})
+```
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+The logo on the @boardname@ works just like a touch pin. The logo will detect your touch. You can have code inside an event that will run when the logo is pressed.
+
+## Parameters
+
+* **action**: the logo event to run your code for. The events are ``released``, ``pressed``, ``touched`` or ``long pressed``.
+
+## Example
+
+Show a message on the LEDs when the @boardname@ logo is pressed.
+
+```blocks
+input.onLogoEvent(TouchButtonEvent.Pressed, function () {
+    basic.showString("I was pressed!")
+})
+```
+
+## See also
+
+[micro:bit V2](/device/v2),
+[logo is pressed](/reference/input/logo-is-pressed),
+[on pin pressed](/reference/input/on-logo-released),
+[touch set mode](/referene/inpu/touch-set-mode)

docs/reference/input/on-pin-event.md

@@ -3,18 +3,19 @@
 Start an [event handler](/reference/event-handler) (part of the
 program that will run when something happens, like when a button is
 pressed).  This handler works when you touch pin `0`, `1`, or `2`
-together with `GND`, and release it within 1 second.
+together with `GND`, and release it within 1 second. You can choose another event type by using 
+the [button event block](/reference/input/button-event). Possible event types are `pressed down` (1), `released up` (2), `clicked` (3), `long clicked` (4) or `hold` (5).
 When you are using this function in a web
 browser, click the pins on the screen instead of the ones on the
 @boardname@.
 
-If you hold the `GND` pin with one hand and touch pin `0`, `1`, or `2`
+If you hold the `GND` pin with one hand and touch pin `0`, `1`, `2` or `3`
 with the other, a very small (safe) amount of electricity will flow
 through your body and back into the @boardname@. This is called
 **completing a circuit**. It's like you're a big wire!
 
 ```sig
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventClick(), () => {
 })
 ```
 
@@ -43,7 +44,7 @@ Every time you press the pin, the program shows the number of times on the scree
 ```blocks
 let count = 0
 basic.showNumber(count)
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventClick(), () => {
     count = count + 1
     basic.showNumber(count)
 })
@@ -51,5 +52,5 @@ input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
 
 ## See also
 
-[@boardname@ pins](/device/pins), [pin is pressed](/reference/input/pin-is-pressed), [analog read pin](/reference/pins/analog-read-pin), [analog write pin](/reference/pins/analog-write-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin)
+[@boardname@ pins](/device/pins), [pin is pressed](/reference/input/pin-is-pressed), [analog read pin](/reference/pins/analog-read-pin), [analog write pin](/reference/pins/analog-write-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin), [button event block](/reference/input/button-event)
 

docs/reference/input/on-sound.md

@@ -0,0 +1,46 @@
+# on Sound
+
+Run some code when the microphone hears a sound.
+
+```sig
+input.onSound(DetectedSound.Loud, function () {})
+```
+
+The microphone will detect sounds that are quiet or loud. You can have the microphone detect
+a sound at a certain level and run some code in and event when it hears the sound. There are
+two sound ranges you can detect for: `loud` or `quiet`.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+* **sound**: the type of sound to detect: `loud` or `quiet`.
+* **handler**: the code to run when a sound is heard.
+
+## Example
+
+Show an icon animation when the microphone detects a sound.
+
+```blocks
+input.onSound(DetectedSound.Loud, function () {
+    basic.showIcon(IconNames.Square)
+    basic.showIcon(IconNames.SmallSquare)
+    basic.showIcon(IconNames.SmallDiamond)
+    basic.clearScreen()
+})
+```
+
+# See also #seealso
+
+[sound level](/reference/input/sound-level),
+[set sound threshold](/reference/input/sound-level)
+
+```package
+microphone
+```

docs/reference/input/running-time.md

@@ -18,7 +18,7 @@ program finds the number of milliseconds since the program started
 and shows it on the [LED screen](/device/screen).
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     let now = input.runningTime()
     basic.showNumber(now)
 })

docs/reference/input/set-sound-threshold.md

@@ -0,0 +1,48 @@
+# set Sound Threshold
+
+Tell how loud it should be for your board to detect a loud sound.
+
+```sig
+input.setSoundThreshold(SoundThreshold.Loud, 0)
+```
+
+When the microphone hears a sound, it sets a number for how loud the sound was at that moment.
+This number is the sound level and has a value from `0` (low sound) to `255` (loud sound). You can use
+a sound level number as a _threshold_ (just the right amount of sound) to make the
+[on sound](/reference/input/on-sound) event happen. To set a threshold, you choose the type of sound
+to detect, `loud` or `quiet`, and then the sound level for that type.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+* **sound**: the type of sound to dectect: `loud` or `quiet`.
+* **threshold**: the sound level [number](/types/number) which makes a sound event happen.
+
+## Example #example
+
+Show an icon animation when the microphone detects a sound louder than a sound level of `200`.
+
+```blocks
+input.setSoundThreshold(SoundThreshold.Loud, 200)
+input.onSound(DetectedSound.Loud, function () {
+    basic.showIcon(IconNames.Square)
+    basic.showIcon(IconNames.SmallSquare)
+    basic.showIcon(IconNames.SmallDiamond)
+    basic.clearScreen()
+})
+```
+
+# See also #seealso
+
+[on sound](/reference/input/on-sound), [sound level](/reference/input/sound-level)
+
+```package
+microphone
+```

docs/reference/input/sound-level.md

@@ -0,0 +1,32 @@
+# sound Level
+
+Find out what the the level of sound heard by the microphone is.
+
+```sig
+input.soundLevel()
+```
+
+## Returns
+
+* a ``number`` between `0` (low sound) and `255` (loud sound) which tells how loud the sounds are that the microphone hears.
+
+## Example
+
+Show a checkerboard icon while the sound level is greater than `100`.
+
+```blocks
+basic.forever(function () {
+    if (input.soundLevel() > 100) {
+        basic.showIcon(IconNames.Chessboard)
+    } else {
+        basic.clearScreen()
+    }
+})
+```
+
+## See also
+
+
+```package
+microphone
+```

docs/reference/led.md

@@ -19,4 +19,4 @@ led.enable(false)
 ## See Also
 
 [plot](/reference/led/plot), [unplot](/reference/led/unplot), [point](/reference/led/point), [brightness](/reference/led/brightness), [setBrightness](/reference/led/set-brightness), [stopAnimation](/reference/led/stop-animation), [plotBarGraph](/reference/led/plot-bar-graph), [toggle](/reference/led/toggle), [setDisplayMode](/reference/led/set-display-mode), [enabled](/reference/led/enable),
-[plotBrightness](/reference/led/plot-brightness),
+[plotBrightness](/reference/led/plot-brightness)

docs/reference/led/enable.md

@@ -15,7 +15,7 @@ led.enable(false);
 This program turns off the screen when pressing button ``B``
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     led.enable(false)
 });
 ```

docs/reference/led/stop-animation.md

@@ -13,7 +13,7 @@ This program sets up the ``stop animation`` part of the program,
 and then shows a string that you can stop with button ``B``.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     led.stopAnimation();
 });
 basic.showString("STOP ME! STOP ME! PLEASE, WON'T SOMEBODY STOP ME?");
@@ -29,4 +29,4 @@ to go.
 
 ## See Also
 
-[show animation](/reference/basic/show-animation)
+[show leds](/reference/basic/show-leds), [show icon](/reference/basic/show-icon), [plot](/reference/led/plot)

docs/reference/loops/every-interval.md

@@ -0,0 +1,42 @@
+# every Interval
+
+Run part of the program in a loop continuously at a time interval.
+
+```sig
+loops.everyInterval(500, function () {})
+```
+
+If you want to run some code continuously, but on a time interval, then use an **every** loop. You set the amount of time that the loop waits before the code inside runs again. This is similar to a [forever](/reference/basic/forever) loop, in that it runs continuously, except that there's a time interval set to wait on before the loop runs the next time. This loop is useful when you want some of a program's code run on a _schedule_.
+
+## Parameters
+
+* **interval**: a [number](/types/number) that is the amount of time in milliseconds to wait before running the loop again.
+
+### ~ reminder
+
+#### Event-based loops
+
+Both the **every** loop and the **forever** loop are _event-based_ loops where the code inside is run as part of a function. These are different from the [for](/blocks/loops/for) and [while](/blocks/loops/while) loops. Those are loops are part of the programming language and can have [break](/blocks/loops/break) and [continue](/blocks/loops/continue) statements in them.
+You can NOT use **break** or **continue** in either an **every** loop or a **forever** loop.
+
+### ~
+
+## Example
+
+At every `200` milliseconds of time, check if either the **A** or **B** button is pressed. If so, show on the screen which one is pressed.
+
+```blocks
+loops.everyInterval(200, function () {
+    if (input.buttonIsPressed(Button.A)) {
+        basic.showString("A")
+    } else if (input.buttonIsPressed(Button.B)) {
+        basic.showString("B")
+    } else {
+        basic.clearScreen()
+    }
+})
+```
+
+## See also
+
+[forever](/reference/basic/forever)

docs/reference/math/int.md

@@ -0,0 +1,2 @@
+# Int
+

docs/reference/math/random-boolean.md

@@ -0,0 +1,39 @@
+# random Boolean
+
+Returns a pseudo-random boolean value that is either `true` or `false`.
+
+```sig
+Math.randomBoolean()
+```
+
+## Returns
+
+* a pseudo-random [boolean](types/boolean) that is either `true` or `false`.
+
+### ~ hint
+
+#### What is pseudo-random?
+
+Random numbers generated on a computer are often called pseudo-random. This because the method to create the number is based on some starting value obtained from the computer itself. The formula for the random number could use some amount of mathematical operations on a value derived from a timer or some other input. The resulting "random" number isn’t considered entirely random because it started with some initial value and a repeatable set of operations on it. Therefore, it’s called a pseudo-random number.
+
+A random boolean is created by choosing a [random int](/reference/math/randint) ranging from `0` to `1`.
+
+### ~
+
+## Example
+
+Make your @boardname@ do a coin toss when it's dropped softly. Have the LEDs show 'heads' or 'tails' as the result of the toss.
+
+```blocks
+input.onGesture(Gesture.FreeFall, () => {
+    if (Math.randomBoolean()) {
+        basic.showIcon(IconNames.Happy)
+    } else {
+        basic.showIcon(IconNames.Sword)
+    }
+})
+```
+
+## See Also
+
+[random int](/reference/math/randint)

docs/reference/music.md

@@ -24,4 +24,8 @@ music.volume()
 [stopMelody](/reference/music/stop-melody), [onEvent](/reference/music/on-event),
 [beat](/reference/music/beat), [tempo](/reference/music/tempo),
 [changeTempoBy](/reference/music/change-tempo-by), [setTempo](/reference/music/set-tempo),
-[setVolume](/reference/music/set-volume), [volume](/reference/music/volume)
+[setVolume](/reference/music/set-volume), [volume](/reference/music/volume),
+[play sound effect](/reference/music/play-sound-effect),
+[create sound effect](/reference/music/create-sound-effect),
+[built-in sound effect](/reference/music/builtin-sound-effect)
+

docs/reference/music/begin-melody.md

@@ -22,7 +22,7 @@ Melodies are a sequence of notes, each played for some small amount time, one af
 music.beginMelody(['g4:1', 'c5', 'e', 'g:2', 'e:1', 'g:3'], MelodyOptions.Once)
 ```
 
-Melodies are played either in the _foreground_ or _background_. This allows more than one melody to be active at once. If a melody is set to play in the background, it can be interrupted, or paused, temporarily while a melody set for the foreground is played. If the foreground melody is not set to play ``forever``, then the background melody resumes when the foreground melody is finished.
+Melodies are played either in the _foreground_ or _background_. This allows more than one melody to be active at once. If a melody is set to play in the background, it can be interrupeted, or paused, temporarily while a melody set for the foreground is played. If the foreground melody is not set to play ``forever``, then the background melody resumes when the foreground melody is finished.
 
 You can set options for how you want the melody to play. You can ask that the melody plays just one time, ``once``, or have it keep repeating, ``forever``. With these options the melody will play in the foreground either once or continue to repeat. Of course, if you set ``forever``, any melody that was started in background will never play unless you [stop](/reference/music/stop-melody) the foreground melody. To make a background melody, set the option to ``once in background`` or ``forever in background``.
 

docs/reference/music/builtin-sound-effect.md

@@ -0,0 +1,40 @@
+# builtin Sound Effect
+
+Get a sound expression string for a built-in sound effect.
+
+```sig
+music.builtinSoundEffect(soundExpression.giggle)
+```
+
+A collection of built-in sound effects are available as sound expressions. You choose one by selecting the name of the effect
+
+## Parameters
+
+* **soundExpression**: A sound expression name. The available effects are:
+>* `giggle`
+>* `happy`
+>* `hello`
+>* `mysterious`
+>* `sad`
+>* `slide`
+>* `soaring`
+>* `spring`
+>* `twinkle`
+>* `yawn`
+
+## Returns
+
+* a [sound](/types/sound) expression [string](/types/string) with the the named sound effect.
+
+## Example
+
+Play the built-in sound effect for `giggle`.
+
+```blocks
+music.playSoundEffect(music.builtinSoundEffect(soundExpression.giggle), SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect),
+[create sound effect](/reference/music/create-sound-effect)

docs/reference/music/create-sound-effect.md

@@ -0,0 +1,48 @@
+# create Sound Effect
+
+Create a sound expression string for a sound effect.
+
+```sig
+music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+```
+
+A sound expression is set of parameters that describe a **[Sound](/types/sound)** that will last for some amount of time. These parameters specify a base waveform, frequency range, sound volume, and effects. Sound data is created as a [Sound](/types/sound) object and can then be [played](/reference/music/play-sound-effect) to the speaker, headphones, or at an output pin.
+
+## Parameters
+
+* **waveShape**: the primary shape of the waveform:
+>* `sine`: sine wave shape
+>* `sawtooth`: sawtooth wave shape
+>* `triangle`: triangle wave shape
+>* `square`: square wave shape
+>* `noise`: random noise generated wave shape
+* **startFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression starts.
+* **endFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression stops.
+* **startVolume**: a [number](/types/number) the initial volume of the sound expression.
+* **endVolume**: a [number](/types/number) the ending volume of the sound expression.
+* **duration**: a [number](/types/number) the duration in milliseconds of the sound expression.
+* **effect**: an effect to add to the waveform. These are:
+>* `tremolo`: add slight changes in volume of the sound expression.
+>* `vibrato`: add slight changes in frequency to the sound expression.
+>* `warble`: similar to `vibrato` but with faster variations in the frequency changes.
+* **interpolation**: controls the rate of frequency change in the sound expression.
+>* `linear`: the change in frequency is constant for the duration of the sound.
+>* `curve`: the change in frequency is faster at the beginning of the sound and slows toward the end.
+>* `logarithmic`: the change in frequency is rapid during the very first part of the sound.
+
+## Returns
+
+* a [sound](/types/sound) expression [string](/types/string) with the the desired sound effect parameters.
+
+## Example
+
+Create a sound expression string and assign it to a variable. Play the sound for the sound expression.
+
+```blocks
+let mySound = music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect), [built-in sound effect](/reference/music/builtin-sound-effect)

docs/reference/music/note-frequency.md

@@ -0,0 +1,31 @@
+# note Frequency
+
+Get the frequency of a musical note.
+
+```sig
+music.noteFrequency(Note.C)
+```
+
+## Parameters
+
+* ``name`` is the name of the **Note** you want a frequency value for.
+
+## Returns
+
+* a [number](/types/number) that is the frequency (in [Hertz](https://wikipedia.org/wiki/Hertz))
+of a note you chose.
+
+## Example #example
+
+Play a 'C' note for one second, rest for one second, and then play an 'A' note for one second.
+
+```blocks
+music.playTone(music.noteFrequency(Note.C), 1000)
+music.rest(1000)
+music.playTone(music.noteFrequency(Note.A), 1000)
+```
+## See also #seealso
+
+[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone),
+[rest](/reference/music/rest), [tempo](/reference/music/tempo),
+[change tempo by](/reference/music/change-tempo-by)

docs/reference/music/on-event.md

@@ -43,7 +43,7 @@ music.onEvent(MusicEvent.BackgroundMelodyResumed, () => {
 music.onEvent(MusicEvent.BackgroundMelodyRepeated, () => {
     serial.writeLine("background repeated")
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
 })
 music.setTempo(100)

docs/reference/music/play-melody.md

@@ -0,0 +1,38 @@
+# play Melody
+
+Play a short melody of notes composed in a string.
+
+```sig
+music.playMelody("", 120);
+```
+
+The melody is short series of notes composed in a string. The melody is played at a rate set by the **tempo** value you give. The melody string contains a sequence of notes formatted like this:
+
+``"E B C5 A B G A F "``
+
+The melody is shown in the ``||music:play melody||`` block as note symbols which also appear in the Melody Editor.
+
+```block
+music.playMelody("E B C5 A B G A F ", 120);
+```
+
+The melodies are most often created in the Melody Editor from the block so that valid notes are chosen and the correct melody length is set.
+
+## Parameters
+
+* **melody**: a [string](/types/string) which contains the notes of the melody.
+* **tempo**: a [number](/types/number) which is the rate to play the melody at in beats per minute.
+
+## Example #example
+
+Play the ``Mystery`` melody continuously.
+
+```blocks
+basic.forever(function () {
+    music.playMelody("E F G F E G B C5 ", 120)
+})
+```
+
+## See also #seealso
+
+[set tempo](/reference/music/set-tempo), [play](/reference/music/play), [play until done](/reference/music/play-until-done)

docs/reference/music/play-sound-effect.md

@@ -0,0 +1,40 @@
+# play Sound Effect
+
+Play a sound that is generated from a sound expression.
+
+```sig
+music.playSoundEffect("", SoundExpressionPlayMode.UntilDone)
+```
+
+This will play a **[Sound](/types/sound)** object created from a sound expression. The sound will play for the duration that was set in the sound expression. The sound can play on the speaker or at a pin that is set for sound output.
+
+Your program can wait for the sound to finish before it runs its next step. To do this, set the play mode to `until done`. Otherwise, use `background` for the program to continue immediately after the sound starts.
+
+### ~ reminder
+
+#### Works with micro:bit V2
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+* **sound**: a [string](/types/string) that is the sound expression for the sound you want to play.
+* **mode**: the play mode for the sound, either `until done` or `background`.
+
+## Example
+
+Play a sound from a sound expression for `1` second.
+
+```blocks
+music.playSoundEffect(music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 1000, SoundExpressionEffect.None, InterpolationCurve.Linear), SoundExpressionPlayMode.UntilDone)
+```
+
+## See also
+
+[create sound effect](/reference/music/create-sound-effect),
+[built-in sound effect](/reference/music/builtin-sound-effect),
+[analog set pitch pin](/reference/pins/analog-set-pitch-pin)

docs/reference/music/play-until-done.md

@@ -0,0 +1,44 @@
+# play Until Done
+
+Play a sound expression until it finishes.
+
+```sig
+soundExpression.giggle.playUntilDone()
+```
+
+A sound expression is a preformatted set of tones that create a certain sound. There are several sounds to choose from. The sound is started and your program waits until the sound stops playing.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+In blocks, the sound is selected from the list in the ``||music:play sound until done||`` block.
+
+```block
+soundExpression.giggle.playUntilDone()
+```
+
+When coding in JavaScript or Python, the sound is a ``soundExpression`` object which from which you run the ``playUntilDone()`` function from. For example, to play the ``soaring`` sound, select ``soaring`` from the ``soundExpression`` namespace and run ``playUntilDone()``:
+
+```typescript
+soundExpression.soaring.playUntilDone()
+```
+
+## Example
+
+Play the ``twinkle`` sound on the speaker and wait until it finishes.
+
+```blocks
+soundExpression.twinkle.playUntilDone()
+basic.showString("twinkle has stopped")
+```
+
+## See also
+
+[play](/reference/music/play)

docs/reference/music/play.md

@@ -0,0 +1,43 @@
+# play
+
+Play a sound expression.
+
+```sig
+soundExpression.giggle.play()
+```
+
+A sound expression is a preformatted set of tones that create a certain sound. There are several sounds to choose from. The sound is started and your program then continues.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+In blocks, the sound is selected from the list in the ``||music:play sound||`` block.
+
+```block
+soundExpression.giggle.play()
+```
+
+When coding in JavaScript or Python, the sound is a ``soundExpression`` object which from which you run the ``play()`` function from. For example, to play the ``soaring`` sound, select ``soaring`` from the ``soundExpression`` namespace and run ``play()``:
+
+```typescript
+soundExpression.soaring.play()
+```
+
+## Example
+
+Play the ``twinkle`` sound on the speaker.
+
+```blocks
+soundExpression.twinkle.play()
+```
+
+## See also
+
+[play until done](/reference/music/play-until-done)

docs/reference/music/set-built-in-speaker-enabled.md

@@ -0,0 +1,37 @@
+# set Built In Speaker Enabled
+
+Enable the speaker on the @boardname@ to play music and sounds.
+
+```sig
+music.setBuiltInSpeakerEnabled(false)
+```
+
+The microbit v2 has a speaker on the board itself. You can enable the built-in speaker to play sounds instead having them an external speaker connected to the pitch pin.
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+## Parameters
+
+* **enabled**: a [boolean](/types/boolean) value that is ``true`` to enable the built-in speaker, or ``false`` to send sounds to the pitch pin.
+
+## Example #example
+
+Enable the built-in speaker play sounds.
+
+```blocks
+music.setBuiltInSpeakerEnabled(true)
+```
+
+## See also
+
+[analog-set-pitch-pin](/reference/pins/analog-set-pitch-pin)
+
+```package
+music
+```

docs/reference/music/set-play-tone.md

@@ -17,7 +17,7 @@ This example send the frequency and duration over radio
 and plays it on the remote @boardname@.
 
 ```typescript
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     music.playTone(440, 120)
     led.toggle(0, 0)
 })
@@ -26,7 +26,7 @@ radio.onReceivedNumber(function (receivedNumber) {
     const duration = receivedNumber & 0xffff;
     music.playTone(freq, duration);
 })
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     music.setPlayTone((frequency: number, duration: number) => {
         radio.sendNumber((frequency << 16) | (duration & 0xffff));
     })    

docs/reference/music/set-silence-level.md

@@ -0,0 +1,40 @@
+# set Silence Level
+
+Set the level for audio pin output during periods of silence.
+
+```sig
+music.setSilenceLevel(1000)
+```
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This function requires the [micro:bit V2](/device/v2) hardware. If you use this function with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+Normally the output signal level at the audio pin is `0` when no sounds are playing. This is the silence level and it stays constant since actual tones have varying levels over a period of time. Some devices (headphones, external speakers, etc.) which are sensitive to slight signal changes might play sounds from signal noise encountered along the connection between the audio pin and the audio device. 
+
+To reduce the effect of this signal noise it can be helpful to set an constant signal level for silence that is greater than `0`.
+
+## Parameters
+
+* **level**: a [number](/types/number) between `0` and `1024` to use as the silence level for the audio pin output when no sounds are playing. The default level is `0`.
+
+## Example #example
+
+Set silence level to `512` for the current audio pin.
+
+```typescript
+pins.setAudioPin(AnalogPin.P1)
+music.setSilenceLevel(512)
+```
+
+## See also
+
+[volume](/reference/music/volume), [set audio pin](/reference/pins/set-audio-pin)
+
+```package
+music
+```

docs/reference/music/stop-all-sounds.md

@@ -0,0 +1,34 @@
+# stop All Sounds
+
+Stop all the sounds that are playing right now and any others waiting to play.
+
+```sig
+music.stopAllSounds()
+```
+
+If you play sounds or sound effects more than once, the sounds you asked to play later have to wait until the sounds played earlier finish. You can stop the sound that is playing now and all the sounds waiting to play with ``||music:stop all sounds||``.
+
+## #simnote
+
+### ~hint
+
+#### Simulator
+
+``||music:stop all sounds||`` works on the @boardname@. It might not work in the simulator on every browser.
+
+### ~
+
+## Example #example
+
+Play a tone but stop it right away.
+
+```blocks
+let freq = music.noteFrequency(Note.C);
+music.playTone(freq, 1000)
+music.stopAllSounds()
+```
+
+## See also #seealso
+
+[play melody](/reference/music/play-melody), [play](/reference/music/play),
+[play tone](/reference/music/play-tone)

docs/reference/pins/digital-read-pin.md

@@ -48,7 +48,7 @@ keeper @boardname@, you can press button `B` on the remote to buzz and
 make the score bigger on the other @boardname@.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     pins.digitalWritePin(DigitalPin.P1, 1);
     basic.pause(500);
     pins.digitalWritePin(DigitalPin.P1, 0);

docs/reference/pins/digital-write-pin.md

@@ -46,7 +46,7 @@ will use ``digital write pin`` to make the other @boardname@ buzz and
 make the score bigger.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     pins.digitalWritePin(DigitalPin.P1, 1);
     basic.pause(500);
     pins.digitalWritePin(DigitalPin.P1, 0);

docs/reference/pins/neopixel-matrix-width.md

@@ -0,0 +1,35 @@
+# Neopixel matrix width
+
+For Neopixel matrix (strip) on the specified [pin](/device/pins),
+set the width of that matrix. This informs the simulator to display
+the Neopixel strip as a matrix.
+
+```sig
+pins.setMatrixWidth(Digital.P1, 16)
+```
+
+## Parameters
+
+* ``name``: The @boardname@ hardware pin to configure (``P0``-``P20``)
+* ``width``: a [number](/types/number) (for example, from `2` through `16`)
+
+## Example
+
+To use the example below, you should add the Neopixel extension to your
+project and then copy the JavaScript code below over to your project. 
+The example creates a strip of 25 neopixels corresponding to a 5x5 matrix and then draws 
+an `X` on the matrix. Try changing the value of the variable `width`
+to get matrices of different sizes.
+
+```blocks
+let width = 5
+let strip = neopixel.create(DigitalPin.P1, width * width, NeoPixelMode.RGB)
+strip.setMatrixWidth(width)
+pins.setMatrixWidth(DigitalPin.P1, width)
+for (let i = 0; i <= width - 1; i++) {
+    strip.setMatrixColor(i, i, neopixel.colors(NeoPixelColors.Red))
+    strip.setMatrixColor(width - (i + 1), i, neopixel.colors(NeoPixelColors.Blue))
+}
+strip.show()
+```
+

docs/reference/pins/set-audio-pin.md

@@ -0,0 +1,34 @@
+# set Audio Pin
+
+Set the [pin](/device/pins) (P0, P1, P2) that is used to play music and generate tones.
+
+```sig
+pins.setAudioPin(AnalogPin.P0)
+```
+
+### ~ hint
+
+#### micro:bit V2 speaker
+
+With the [micro:bit V2](/device/v2) hardware, the built-in speaker will play (mirror) the same tones and music sent to the audio pin.
+
+### ~
+
+## Parameters
+
+* **name**: the pin to set for audio output: `P0`, `P1`, or `P2`.
+
+## Example
+
+Play a tone for the "A4" note at pin **P0** for 1 second.
+
+```blocks
+pins.setAudioPin(AnalogPin.P0)
+let frequency = 440
+let duration = 1000
+pins.analogPitch(frequency, duration)
+```
+
+## See also
+
+[@boardname@ pins](/device/pins), [analog set pitch pin](/reference/pins/analog-set-pitch-pin)

docs/reference/radio.md

@@ -16,7 +16,6 @@ radio.setGroup(0);
 ## Advanced
 
 ```cards
-radio.writeReceivedPacketToSerial();
 radio.setTransmitPower(7);
 radio.setTransmitSerialNumber(false);
 radio.raiseEvent(0, 0);
@@ -38,5 +37,4 @@ radio
 [set group](/reference/radio/set-group),
 [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),
 [raise event](/reference/radio/raise-event)

docs/reference/radio/on-received-buffer.md

@@ -19,6 +19,7 @@ Two @boardname@s work like remote levels. They lie flat and detect any change in
 ```typescript
 let ax = 0;
 let ay = 0;
+radio.setGroup(3)
 basic.forever(() => {
     ax = input.acceleration(Dimension.X);
     ay = input.acceleration(Dimension.Y);

docs/reference/radio/on-received-number.md

@@ -29,6 +29,7 @@ thing from nearby @boardname@s. It shows these numbers as a
 [bar graph](/reference/led/plot-bar-graph).
 
 ```blocks
+radio.setGroup(1)
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.X));
 })
@@ -43,6 +44,7 @@ This program uses the signal strength from received packets to graph the
 approximate distance between two @boardname@s.
 
 ```blocks
+radio.setGroup(1)
 basic.forever(() => {
     radio.sendNumber(0)
 })

docs/reference/radio/on-received-string.md

@@ -23,6 +23,7 @@ https://www.youtube.com/watch?v=Re3H2ISfQE8
 This program continuously sends a cheerful message. It also receives a messages from nearby @boardname@s. It shows these messages on the screen.
 
 ```blocks
+radio.setGroup(1)
 basic.forever(() => {
     radio.sendString("I'm happy");
 })

docs/reference/radio/on-received-value.md

@@ -27,6 +27,7 @@ thing from nearby @boardname@s, show the numbers as a
 [bar graph](/reference/led/plot-bar-graph).
 
 ```blocks
+radio.setGroup(1)
 basic.forever(() => {
     radio.sendValue("accel-x", input.acceleration(Dimension.X))
 })

docs/reference/radio/receive-string.md

@@ -34,7 +34,7 @@ If you load this program onto two or more @boardname@s, you can send a code word
 The other @boardname@s will receive the code word and then show it.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     radio.sendString("Codeword: TRIMARAN")
     basic.showString("SENT");
 })
@@ -59,10 +59,10 @@ This program will also receive your friend's mood.
 
 ```blocks
 let data: string = "";
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     radio.sendString("H");
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
     radio.sendString("S");
 });
 radio.onDataReceived(() => {

docs/reference/radio/received-packet.md

@@ -18,7 +18,7 @@ In addition to a [number](types/number), [string](/types/string), or name-value
 ## Returns
 
 * a [number](/types/number) that is the property selected in the **type** parameter:
->* ``signal strength``: the value ranges from `-128` to `-42` (`-128` means a weak signal and `-42` means a strong one.)
+>* ``signal strength``: the value ranges from `-128` up to `-28` (`-128` means a weak signal and `-28` means a strong one.)
 >* ``serial number``: the value is the serial number of the board sending the packet.
 >* ``time``: the value is the system time, in microseconds, of the sender at the time when the packet was sent.
 
@@ -28,6 +28,7 @@ This program uses the signal strength from received packets to graph the
 approximate distance between two @boardname@s.
 
 ```blocks
+radio.setGroup(1)
 basic.forever(() => {
     radio.sendNumber(0)
 })

docs/reference/radio/received-signal-strength.md

@@ -6,29 +6,35 @@ Find how strong the radio signal is.
 radio.receivedSignalStrength();
 ```
 
-## ~ hint
+### ~ hint
 
-**Deprecated**
+#### Deprecated
 
 This API has been deprecated! Use [received packet](/reference/radio/received-packet) instead.
 
-## ~
+### ~
 
-Find how strong the ``radio`` signal is, from `-128` to `-42`.
+Find how strong the ``radio`` signal is, from `-128` to `-28`.
-(`-128` means a weak signal and `-42` means a strong one.)
+(`-128` means a weak signal and `-28` means a strong one.)
 
 The @boardname@ finds the signal strength by checking how strong it was
 the last time it ran the
 [on received number](/reference/radio/on-received-number) function. That means
 it needs to run **receive number** first.
 
-
-
 ## Returns
 
-* a [number](/types/number) between `-128` and `-42` that means
+* a [number](/types/number) between `-128` and `-28` that means
 how strong the signal is.
 
+### ~ hint
+
+#### Signal strength and board version
+
+Measurement of the received signal strength is dependent on what version of @boardname@ you have. The @boardname@ boards prior to v2 can typically measure a signal strength up to `-42` dBm. Now, v2 boards will measure a signal strength up to `-28` dBm (typical).
+
+### ~
+
 ## Simulator
 
 This function only works on the @boardname@, not in browsers.
@@ -49,7 +55,8 @@ basic.forever(() => {
 
 ## See also
 
-[on received number](/reference/radio/on-received-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
+[on received number](/reference/radio/on-received-number), [send number](/reference/radio/send-number),
+[on data received](/reference/radio/on-data-received), [received packet](/reference/received-packet)
 
 ```package
 radio

docs/reference/radio/send-buffer.md

@@ -19,6 +19,7 @@ If you load this program onto two @boardname@s, each board will send the level i
 ```typescript
 let ax = 0;
 let ay = 0;
+radio.setGroup(6)
 basic.forever(() => {
     ax = input.acceleration(Dimension.X);
     ay = input.acceleration(Dimension.Y);

docs/reference/radio/send-number.md

@@ -27,7 +27,7 @@ in the `x` direction (left and right) to other @boardname@s.  This kind
 of program might be useful in a model car or model rocket.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     radio.sendNumber(input.acceleration(Dimension.X))
 })
 ```

docs/reference/radio/send-string.md

@@ -26,7 +26,8 @@ code word from one of them to the others by pressing button `A`.  The
 other @boardname@s will receive the code word and then show it.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+radio.setGroup(1)
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     radio.sendString("Codeword: TRIMARAN")
     basic.showString("SENT");
 })

docs/reference/radio/send-value.md

@@ -29,7 +29,7 @@ or model rocket.
 
 ```blocks
 radio.setGroup(99)
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     radio.sendValue("acc", input.acceleration(Dimension.X))
 })
 ```

docs/reference/radio/set-group.md

@@ -20,6 +20,14 @@ to talk to each other because they will have the same group ID.
 
 * **id**: a [number](/types/number) from ``0`` to ``255``.
 
+### ~ reminder
+
+#### Default radio group
+
+If you haven't set a radio group for the @boardname@, it will use one selected randomly. If you are transmiting data to a @boardname@ that has a different hardware version from the sending @boardname@, it will select a random default group that is not the same as the other @boardname@. To be certain that your program will send or receive data using the same radio group, you will need to first choose and set a radio group for your program if you want it to work between different versions of the @boardname@.
+
+### ~
+
 ## Simulator
 
 This function only works on the @boardname@, not in browsers.

docs/reference/radio/write-received-packet-to-serial.md

@@ -9,6 +9,14 @@ radio.writeReceivedPacketToSerial();
 This should be called within a callback to
 [on data packet received](/reference/radio/on-data-packet-received).
 
+### ~ hint
+
+#### Deprecated
+
+This API has been deprecated! Use [serial write value](/reference/serial/write-value) instead.
+
+### ~
+
 ## Data received format
 
 The format for received data when these send functions are used:
@@ -19,6 +27,8 @@ The format for received data when these send functions are used:
 
 ### ~hint
 
+#### Default serial number
+
 The serial number value sent in the packet is set to `0` unless transmission of the serial number is enabled with ``||radio:radio set transmit serial number||``.
 
 ### ~
@@ -30,7 +40,8 @@ the second @boardname@), this program sends temperature data to the
 serial port.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+radio.setGroup(44)
+input.onButtonEvent(Button.A, input.buttonEventClick(), function () {
     radio.sendNumber(input.temperature())
     radio.sendValue("temp", input.temperature())
     radio.sendString("It's warm now")

docs/reference/radio/write-value-to-serial.md

@@ -29,7 +29,8 @@ the second @boardname@), this program sends temperature data to
 serial.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+radio.setGroup(1)
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     radio.sendNumber(input.temperature());
 });
 radio.onDataReceived(() => {

docs/reference/serial/read-buffer.md

@@ -9,17 +9,19 @@ serial.readBuffer(64);
 ## Parameters
 
 * **length**: the [number](/types/number) of characters of serial data to read.
+Use ``0`` to return the available buffered data.
 
 ## Returns
 
 * a [buffer](/types/buffer) containing input from the serial port. The length of the buffer may be smaller than the requested length.
+The length is 0 if any error occurs.
 
 ## ~hint
 **Pause for more data**
 
 If the desired number of characters are available, **readBuffer** returns a buffer with the expected size. If not, the calling fiber (the part of your program calling the **readBuffer** function) sleeps until the desired number of characters are finally read into the buffer.
 
-The need to pause for more data is set by the @boardname@ **[serial mode](https://lancaster-university.github.io/microbit-docs/ubit/serial/#serial-modes)**.
+To avoid waiting for data, set the length to ``0`` so that buffered data is returned immediately.
 ## ~
 
 ## Example
@@ -27,13 +29,27 @@ The need to pause for more data is set by the @boardname@ **[serial mode](https:
 Read character data from the serial port one row at a time. Write the rows to an LED display connected to the I2C pins.
 
 ```typescript
-let rowData: Buffer = null;
+serial.setRxBufferSize(10)
 for (let i = 0; i < 24; i++) {
-    rowData = serial.readBuffer(80);
+    let rowData = serial.readBuffer(10);
     pins.i2cWriteBuffer(65, rowData, false);
 }
 ```
 
+## Example Async
+
+Read available data and process it as it comes.
+
+```typescript
+basic.forever(function() {
+    let rowData = serial.readBuffer(0);
+    if (rowData.length > 0) {
+        // do something!!!
+    }
+})
+```
+
+
 ## See Also
 
 [write buffer](/reference/serial/write-buffer)

docs/reference/serial/redirect.md

@@ -32,7 +32,7 @@ serial port to use the pins. The new configuration uses pin ``P1`` to transmit a
 ``P2`` to receive. The baud rate is set to `9600`.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
     serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
 });
 ```

docs/reference/storage/get-number.md

@@ -0,0 +1 @@
+# Get Number

docs/reference/storage/put-number.md

@@ -0,0 +1 @@
+# Put Number

docs/reference/storage/remove-number.md

@@ -0,0 +1 @@
+# Remove Number

editor/patch.ts

@@ -19,7 +19,7 @@ export function patchBlocks(pkgTargetVersion: string, dom: Element) {
     <block type="device_button_selected_event" x="35" y="429">
         <field name="NAME">Button.B</field>
         <value name="eventType">
-            <shadow type="control_button_event_value_id">
+            <shadow type="control_button_event_value">
                 <field name="id">ButtonEvent.Click</field>
             </shadow>
         </value>
@@ -27,7 +27,7 @@ export function patchBlocks(pkgTargetVersion: string, dom: Element) {
     <block type="device_pin_custom_event" x="368" y="428">
         <field name="NAME">TouchPin.P2</field>
         <value name="eventType">
-            <shadow type="control_button_event_value_id">
+            <shadow type="control_button_event_value">
                 <field name="id">ButtonEvent.Up</field>
             </shadow>
         </value>
@@ -51,7 +51,7 @@ const inputNodes = pxt.U.toArray(dom.querySelectorAll("block[type=device_button_
             valueNode.setAttribute("name", "eventType")
 
             const shadowNode = node.ownerDocument.createElement("shadow");
-            shadowNode.setAttribute("type", "control_button_event_value_id")
+            shadowNode.setAttribute("type", "control_button_event_value")
 
             const fieldNode = node.ownerDocument.createElement("field");
             fieldNode.setAttribute("name", "id")

libs/bluetooth/pxt.json

@@ -24,10 +24,6 @@
                     "enabled": 1
                 }
             }
-        },
+        }
-        "optionalConfig": {
-        },
-        "userConfigs": [
-        ]
     }
 }

libs/core/_locales/core-jsdoc-strings.json

@@ -426,7 +426,9 @@
   "input.acceleration": "Get the acceleration value in milli-gravitys (when the board is laying flat with the screen up, x=0, y=0 and z=-1024)",
   "input.acceleration|param|dimension": "x, y, or z dimension, eg: Dimension.X",
   "input.assumeCalibrationCompass": "Obsolete, compass calibration is automatic.",
-  "input.buttonEventValueId": "Returns the value of a C++ runtime constant",
+  "input.buttonEventClick": "Returns the ID of an Click Event",
+  "input.buttonEventDown": "Returns the ID of an Down Event",
+  "input.buttonEventValue": "Returns the ID of an Button Event",
   "input.buttonIsPressed": "Get the button state (pressed or not) for ``A`` and ``B``.",
   "input.buttonIsPressed|param|button": "the button to query the request, eg: Button.A",
   "input.calibrateCompass": "Obsolete, compass calibration is automatic.",

libs/core/_locales/core-strings.json

@@ -52,6 +52,7 @@
   "Button.AB|block": "A+B",
   "ButtonEvent.Click|block": "clicked",
   "ButtonEvent.Down|block": "pressed down",
+  "ButtonEvent.Hold|block": "hold",
   "ButtonEvent.LongClick|block": "long clicked",
   "ButtonEvent.Up|block": "released up",
   "Colors.Blue|block": "blue",
@@ -335,7 +336,9 @@
   "images|block": "images",
   "input.acceleration|block": "acceleration (mg)|%NAME",
   "input.assumeCalibrationCompass|block": "assume calibration compass",
-  "input.buttonEventValueId|block": "%id",
+  "input.buttonEventClick|block": "clicked",
+  "input.buttonEventDown|block": "pressed down",
+  "input.buttonEventValue|block": "%id",
   "input.buttonIsPressed|block": "button|%NAME|is pressed",
   "input.calibrateCompass|block": "calibrate compass",
   "input.clearCalibrationCompass|block": "clear calibration compass",
@@ -344,12 +347,12 @@
   "input.isGesture|block": "is %gesture gesture",
   "input.lightLevel|block": "light level",
   "input.magneticForce|block": "magnetic force (µT)|%NAME",
-  "input.onButtonEvent|block": "on button %NAME| %eventType=control_button_event_value_id",
+  "input.onButtonEvent|block": "on button %NAME| %eventType",
   "input.onButtonPressed|block": "on button|%NAME|pressed",
   "input.onGesture|block": "on |%NAME",
   "input.onPinPressed|block": "on pin %name|pressed",
   "input.onPinReleased|block": "on pin %NAME|released",
-  "input.onPinTouchEvent|block": "on pin %name| %eventType=control_button_event_value_id",
+  "input.onPinTouchEvent|block": "on pin %name| %eventType",
   "input.pinIsPressed|block": "pin %NAME|is pressed",
   "input.rotation|block": "rotation (°)|%NAME",
   "input.runningTimeMicros|block": "running time (micros)",

libs/core/basic.cpp

@@ -116,6 +116,7 @@ namespace basic {
    /**
     * Sets the color on the build-in LED. Set to 0 to turn off.
     */
+   //% help=basic/set-led-color
     //% blockId=device_set_led_color
     //% block="set led to %color=colorNumberPicker"
     //% color.defl=0xff0000
@@ -140,6 +141,7 @@ namespace basic {
     * Sets the color on the build-in LED. Set to 0 to turn off.
     */
     //% blockId=device_turn_rgb_led_off block="turn build-in LED off"
+    //% help=basic/turn-rgb-led-off
     //% weight=10
     //% group="RGB LED"
     //% advanced=true

libs/core/basic.ts

@@ -76,6 +76,7 @@ namespace basic {
      * @param blue value of the blue channel between 0 and 255. eg: 255
      */
     //% weight=3
+    //% help=basic/rgb
     //% blockId="core_rgb" block="red %red|green %green|blue %blue"
     //% group="RGB LED"
     export function rgb(red: number, green: number, blue: number): number {

libs/core/blocks-test/input.blocks

@@ -6,7 +6,7 @@
     <block type="device_button_selected_event" x="0" y="0">
         <field name="NAME">Button.AB</field>
         <value name="eventType">
-            <shadow type="control_button_event_value_id"></shadow>
+            <shadow type="control_button_event_value"></shadow>
         </value>
         <statement name="HANDLER">
             <block type="variables_set">
@@ -129,13 +129,13 @@
     <block type="device_pin_custom_event" x="556" y="156">
         <field name="name">TouchPin.P0</field>
         <value name="eventType">
-            <shadow type="control_button_event_value_id"></shadow>
+            <shadow type="control_button_event_value"></shadow>
         </value>
     </block>
     <block type="device_pin_custom_event" x="560" y="274">
         <field name="name">TouchPin.P0</field>
         <value name="eventType">
-            <shadow type="control_button_event_value_id"></shadow>
+            <shadow type="control_button_event_value"></shadow>
         </value>
     </block>
 </xml>

libs/core/blocks-test/test.blocks

@@ -133,7 +133,7 @@
         </block>
         <block type="device_pin_custom_event" x="2009" y="121">
                 <value name="eventType">
-                        <shadow type="control_button_event_value_id"></shadow>
+                        <shadow type="control_button_event_value"></shadow>
                 </value>
                 <statement name="HANDLER">
                         <block type="device_led_toggle">
@@ -435,7 +435,7 @@
         <block type="device_button_selected_event" x="896" y="634">
                 <field name="NAME">Button.AB</field>
                 <value name="eventType">
-                        <shadow type="control_button_event_value_id"></shadow>
+                        <shadow type="control_button_event_value"></shadow>
                 </value>
                 <statement name="HANDLER">
                         <block type="device_plot">
@@ -512,7 +512,7 @@
         </block>
         <block type="device_pin_custom_event" x="478" y="950">
                 <value name="eventType">
-                        <shadow type="control_button_event_value_id"></shadow>
+                        <shadow type="control_button_event_value"></shadow>
                 </value>
                 <statement name="HANDLER"></statement>
         </block>