Remove extensions without MIT License (#215)

Replaces `dl1ekm/pxt-calliope-PCF85063-RTC` by `CalliTGS3/pxt-calliope-grovePCF85063TP` and removes `dl1ekm/pxt-calliope-ADS1x15`

.github/workflows/pxt-buildmain.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [8.x]
+        node-version: [18.x]
 
     steps:
       - uses: actions/checkout@v1

.github/workflows/pxt-buildpr.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [8.x]
+        node-version: [18.x]
 
     steps:
       - uses: actions/checkout@v1

.github/workflows/pxt-buildpush.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [8.x]
+        node-version: [18.x]
 
     steps:
       - uses: actions/checkout@v1

SECURITY.md

@@ -0,0 +1,41 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.7 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
+
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report).
+
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

docs/about.md

@@ -26,12 +26,12 @@ The Calliope mini is packaged with sensors, radio and other goodies. Learn about
 You can program the Calliope mini using [Blocks](/blocks) or [JavaScript](/javascript) in your web browser via the [Calliope mini APIs](/reference):
 
 ```block
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showString("Hi!");
 })
 ```
 ```typescript
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showString("Hi!");
 })
 ```
@@ -54,7 +54,7 @@ The simulator has support for the LED screen, buttons, as well as compass, accel
 basic.forever(() => {
   basic.showString("Hi!");
 })
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     led.stopAnimation();
     basic.showLeds(`
 . . . . .
@@ -63,7 +63,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
 # . . . #
 . # # # .`);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), () => {
     led.stopAnimation();
     basic.showLeds(`
 . # . # .

docs/blocks/logic/boolean.md

@@ -17,7 +17,7 @@ if (led.point(1,1) && led.point(2,2)) {
 When you compare two Numbers, you get a Boolean value, such as the comparison `x < 5` in the code below:
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     let x = randint(0, 5)
     if(x < 5) {
     basic.showString("low");

docs/blocks/logic/if.md

@@ -7,7 +7,7 @@
 If the [light level](/reference/input/light-level) is `< 100`, this code sets the brightness to `255` when the button A is pressed:
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     if(input.lightLevel()<100){
         led.setBrightness(255);
     }

docs/blocks/loops/for.md

@@ -7,7 +7,7 @@
 This program will show the numbers 0, 1, 2, 3, and 4 one after another on the LED screen.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     for(let i = 0; i < 5; ++i) {
         basic.showNumber(i)
     }

docs/blocks/loops/while.md

@@ -7,7 +7,7 @@
 The following example uses a while loop to make a diagonal line on the LED screen (points `0, 0`, `1, 1`, `2, 2`, `3, 3`, `4, 4`).
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     let index = 4;
     while(index >= 0) {
         led.plot(index, index);

docs/blocks/on-start.md

@@ -5,7 +5,7 @@
 In this example, ``on start`` sets a dimmer brightness on the screen and the button handler shows a string.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showString("Hello!")
 })
 led.setBrightness(50)

docs/blocks/variables/var.md

@@ -59,7 +59,7 @@ A counter is a great example:
 
 ```blocks
 let counter = 0;
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => { 
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => { 
   counter = counter + 1;
   basic.showNumber(counter);
 });

docs/calliope/templates.md

@@ -0,0 +1,27 @@
+# Projects
+
+Here are some cool tutorials to get you started with your @boardname@!
+
+## Basic
+
+```codecard
+[
+{
+  "name": "Calliope mini 2.x",
+  "url":"_f7ACuxgaocvr",
+  "description": "The Calliope mini 2.0 and newer has a larger memory than the previous versions. If you use this template for your project, you can make the most of all the features on your Calliope mini!",
+  "imageUrl": "/calliope/templates/32KB.png",
+  "largeImageUrl": "/calliope/templates/32KB_L.png",
+  "cardType": "sharedExample",
+  "buttonLabel": "New project"
+},{
+  "name": "Calliope mini 1.x",
+  "url":"_7YbU6iMhoTdR",
+  "description": "This template is designed for all Calliope mini, but especially for those up to version 1.3. If you have such a Calliope mini or an earlier version, you can start directly with this template.",
+  "imageUrl": "/calliope/templates/16KB.png",
+  "largeImageUrl": "/calliope/templates/16KB_L.png",
+  "cardType": "sharedExample",
+  "buttonLabel": "New project"
+}
+]
+```

docs/device/crocodile-clips.md

@@ -38,7 +38,7 @@ Each time the crocodile clip is firmly connected and disconnected from pin `P0`,
 the @boardname@ will return a random Number between 0 and the parameter limit.
 
 ```blocks
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Down, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showNumber(randint(0, 10))
 })
 ```

docs/device/data-analysis/led-plotting.md

@@ -63,7 +63,7 @@ for (let i = 0; i < values.length; i++) {
 The ``||led:plot bar graph||`` also sends the number value it's plotting to the console. You can see the output in the Data Viewer. It charts the values and they appear as individual numbers in console.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Click), () => {
     for (let i = 0; i < 25; i++) {
         if (i % 2 > 0) {
             led.plotBarGraph(0, 0)

docs/device/reactive.md

@@ -51,7 +51,7 @@ The first job of the scheduler is to allow multiple *subprograms* to be queued u
 ```typescript
 let count = 0
 
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     count++;
 })
 
@@ -74,7 +74,7 @@ The second statement informs the scheduler that on each and every event of the *
 // statement 1
 let count = 0
 // statement 2
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     count++;
 })
 ```
@@ -85,7 +85,7 @@ The third statement queues a `forever` loop for later execution by the scheduler
 // statement 1
 let count = 0
 // statement 2
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     count++;
 })
 // statement 3
@@ -157,7 +157,7 @@ As a result, you can easily add a new capability to the micro:bit by just adding
 ```typescript
 let count = 0
 
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     count = count + 1
 })
 
@@ -165,7 +165,7 @@ basic.forever(() => {
     basic.showNumber(count)
 })
 
-input.onButtonEvent(Button.B, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), () => {
     count = 0
 })
 ```

docs/device/serial.md

@@ -6,7 +6,7 @@ The code below shows a simple script that sends a line when the BBC micro:bit st
 
 ```blocks
 serial.writeLine("started...")
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     serial.writeLine("A pressed")
 })
 ```

docs/device/simulator.md

@@ -4,19 +4,19 @@ The JavaScript simulator allows you to test and execute most BBC micro:bit progr
 It allows you to emulate sensor data or user interactions.
 
 ```sim
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => {
    basic.showString("A");
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Click), () => {
    basic.showString("B");
 });
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventValue(ButtonEvent.Click), () => {
    basic.showString("0");
 });
-input.onPinTouchEvent(TouchPin.P1, ButtonEvent.Click, () => {
+input.onPinTouchEvent(TouchPin.P1, input.buttonEventValue(ButtonEvent.Click), () => {
    basic.showString("1");
 });
-input.onPinTouchEvent(TouchPin.P2, ButtonEvent.Click, () => {
+input.onPinTouchEvent(TouchPin.P2, input.buttonEventValue(ButtonEvent.Click), () => {
    basic.showString("2");
 });
 input.temperature()

docs/examples/gameofLife.md

@@ -22,13 +22,13 @@ Here's a program that simulates cell life in the LED matrix. Use button ``A`` fo
 let lifeChart: Image = null
 
 //Use button A for the next iteration of game of life
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => {
     gameOfLife();
     show();
 })
 
 //Use button B for reseting to random initial seed state
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Click), () => {
     reset();
     show();
 })

docs/hero-banner.md

@@ -9,7 +9,7 @@ Here are some cool activities to get you started with your @boardname@!
 * description: CALLIOPEO – Taking the Calliope mini to the ISS.
 * imageUrl: /calliope/02_Hero_CalliopEO.png
 * url: https://calliope.cc/calliopeo
-* buttonLabel: Participate!
+* buttonLabel: Explore!
 * cardType: link
 ---
 * name: The 5x5 LED matrix

docs/index-ref.json

@@ -1,3 +1,3 @@
 {
-    "appref": "v3.0.33"
+    "appref": "v4.0.29"
 }

docs/projects.md

@@ -2,6 +2,12 @@
 
 ```codecard
 [
+    {
+        "name": "New Project (iPad)",
+        "url": "/calliope/templates",
+        "imageUrl": "/calliope/templates/32KB.png",
+        "largeImageUrl": "/calliope/templates/32KB_L.png"
+    },
     {
         "name": "First Steps",
         "url": "/calliope/firststeps",
@@ -23,6 +29,7 @@
 
 ## See Also
 
+[New Project (iPad)](/calliope/templates),
 [First Steps](/calliope/firststeps),
 [Tutorials](/calliope/tutorials),
 [Calliope Links](/calliope/links)

docs/projects/SUMMARY.md

@@ -1,5 +1,8 @@
 # Projects
 
+* [New Project (iPad)](/calliope/templates)
+  * [Calliope mini 2.x](_f7ACuxgaocvr)
+  * [Calliope mini 1.x](_7YbU6iMhoTdR)
 * [First Steps](/calliope/firststeps)
   * [Get Ready](/calliope/firststeps/firstSteps)
   * [The 5x5 LED matrix](/calliope/firststeps/5x5LED)

docs/projects/coin-flipper.md

@@ -11,7 +11,7 @@ Let's create a coin flipping program to simulate a real coin toss. We'll use ico
 Get an ``||input:on button A pressed||`` block from the ``||input:Input||`` drawer in the toolbox. We'll put our coin flipping code in here.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => {
 })
 ```
 
@@ -22,7 +22,7 @@ Grab an ``||logic:if else||`` block and set it inside ``||input:on button A pres
 The ``||Math:pick random true or false||`` returns a random ``true`` or ``false`` value which we use to determine a ``heads`` or ``tails`` result for a coin toss.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => {
     if (Math.randomBoolean()) {
     } else {
     }
@@ -34,7 +34,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
 Now, put a ``||basic:show icon||`` block inside both the ``||logic:if||`` and the ``||logic:else||``. Pick images to mean ``heads`` and ``tails``.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => {
     if (Math.randomBoolean()) {
         basic.showIcon(IconNames.Skull)
     } else {
@@ -52,7 +52,7 @@ Press button **A** in the simulator to try the coin toss code.
 You can animate the coin toss to add the feeling of suspense. Place different ``||basic:show icon||`` blocks before the ``||logic:if||`` to show that the coin is flipping.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => {
     basic.showIcon(IconNames.Diamond)
     basic.showIcon(IconNames.SmallDiamond)
     basic.showIcon(IconNames.Diamond)

docs/projects/love-meter.md

@@ -11,7 +11,7 @@ Make a love meter, how sweet! The @boardname@ is feeling the love, then sometime
 Let's build a **LOVE METER** machine. Place an ``||input:on pin pressed||`` block to run code when pin **0** is pressed. Use ``P0`` from the list of pin inputs.
 
 ```blocks
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Down, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventValue(ButtonEvent.Down), () => {
 });
 ```
 
@@ -20,7 +20,7 @@ input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Down, () => {
 Using ``||basic:show number||`` and ``||Math:pick random||`` blocks, show a random number from `0` to `100` when pin **0** is pressed.
 
 ```blocks
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Down, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showNumber(randint(0, 100));
 });
 ```
@@ -34,7 +34,7 @@ Show ``"LOVE METER"`` on the screen when the @boardname@ starts.
 
 ```blocks
 basic.showString("LOVE METER");
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Down, () => {
+input.onPinTouchEvent(TouchPin.P0, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showNumber(randint(0, 100));
 });
 ```

docs/projects/mini-chat.md

@@ -12,7 +12,7 @@ Use ``||input:on button pressed||`` to send a text message over radio with ``||r
 Every @boardname@ nearby will receive this message.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     radio.sendString("Yo");
 });
 ```
@@ -41,7 +41,7 @@ radio.onReceivedString(function (receivedString) {
 Press button **A** on the simulator, you will notice that a second @boardname@ appears (if your screen is too small, the simulator might decide not to show it). Try pressing **A** again and notice that the "Yo" message gets displayed on the other @boardname@.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     radio.sendString("Yo");
 });
 radio.onReceivedString(function (receivedString) {

docs/projects/name-badge.md

@@ -13,7 +13,7 @@ First, let's get your name to display on the screen.
 From the ``||input:Input||`` Toolbox drawer, drag an ``||input:on button A pressed||`` block onto the Workspace.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), function () {
 
 })
 ```
@@ -23,7 +23,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
 From the ``||basic:Basic||`` Toolbox drawer drag a ``||basic:show string||`` block into the ``||input:on button A pressed||`` block.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), function () {
     basic.showString("Hello!")
 })
 ```
@@ -33,7 +33,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
 In the ``||basic:show string||`` block, type your name.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), function () {
     basic.showString("My Name")
 })
 ```
@@ -43,7 +43,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
 Go to the simulator and test your name badge by pressing button **A**.
 
 ```sim
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), function () {
     basic.showString("My Name")
 })
 ```

docs/projects/robot-unicorn.md

@@ -123,7 +123,7 @@ basic.forever(function () {
 **MakeCode blocks for the Robot Unicorn controller**
 
 ```blocks
-input.onButtonEvent(Button.AB, ButtonEvent.Down, function () {
+input.onButtonEvent(Button.AB, input.buttonEventValue(ButtonEvent.Down), function () {
     radio.sendNumber(4)
     basic.showLeds(`
         # . . . #

docs/projects/rotary-dial-radio.md

@@ -83,7 +83,7 @@ Now that we are detecting pulses, we can use a variable to count them too. In th
 
 ```blocks
 let pulseCount = 0
-input.onButtonEvent(Button.A, ButtonEvent.Down, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), function () {
     basic.showNumber(pulseCount)
     pulseCount = 0
 })

docs/projects/smiley-buttons.md

@@ -12,7 +12,7 @@ Code the buttons on the @boardname@ to show that it's happy or sad.
 Place a ``||input:on button pressed||`` block to run code when button **A** is pressed.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => { 
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => { 
 });
 ```
 
@@ -21,7 +21,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
 Place a ``||basic:show leds||`` block inside ``||input:on button pressed||`` to display a smiley on the screen. Press the **A** button in the simulator to see the smiley.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => { 
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), () => { 
     basic.showLeds(`
         # # . # #
         # # . # #
@@ -37,7 +37,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
 Add ``||input:on button pressed||`` and ``||basic:show leds||`` blocks to display a frowny when button **B** is pressed.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => { 
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Click), () => { 
     basic.showLeds(`
         # # . # #
         # # . # #
@@ -53,7 +53,7 @@ input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
 Add a secret mode that happens when **A** and **B** are pressed together. For this case, add multiple ``||basic:show leds||`` blocks to create an animation.
 
 ```blocks
-input.onButtonEvent(Button.AB, ButtonEvent.Click, () => {
+input.onButtonEvent(Button.AB, input.buttonEventValue(ButtonEvent.Click), () => {
     basic.showLeds(`
         . . . . .
         # . # . .

docs/projects/snap-the-dot.md

@@ -59,7 +59,7 @@ Use a ``||input:on button pressed||`` block to handle the **A** button. Put in a
 
 ```blocks
 let sprite = game.createSprite(2, 2)
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), function () {
     if (sprite.get(LedSpriteProperty.X) == 2) {
     } else {
     }
@@ -77,7 +77,7 @@ Finally, pull out an ``||game:add score||`` and a ``||game:game over||`` block t
 
 ```blocks
 let sprite = game.createSprite(2, 2)
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Click), function () {
     if (sprite.get(LedSpriteProperty.X) == 2) {
         game.addScore(1)
     } else {

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),
-[advertiseUrl](/reference/bluetooth/advertise-url),
-[stopAdvertising](/reference/bluetooth/stop-advertising)
+[onBluetoothDisconnected](/reference/bluetooth/on-bluetooth-disconnected)
 
 ```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), () => {
-    basic.showString(serial.readUntil(serial.delimiters(Delimiters.Comma)))
+bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), function () {
+    basic.showString(bluetooth.uartReadUntil(serial.delimiters(Delimiters.Space)))
 })
 ```
+
+```package
+bluetooth
+```

docs/reference/bluetooth/stop-advertising.md

@@ -24,7 +24,7 @@ bluetooth.stopAdvertising();
 ## Example: stop advertising on button pressed
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     bluetooth.stopAdvertising();
 })
 ```

docs/reference/bluetooth/uart-write-line.md

@@ -27,7 +27,7 @@ bluetooth.onBluetoothDisconnected(() => {
     basic.showString("D");
     connected = 0;
 });
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     if (connected == 1) {
         bluetooth.uartWriteLine("HELLO");
     }

docs/reference/bluetooth/uart-write-string.md

@@ -27,7 +27,7 @@ bluetooth.onBluetoothDisconnected(() => {
     basic.showString("D");
     connected = 0;
 });
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     if (connected == 1) {
         bluetooth.uartWriteString("HELLO");
     }

docs/reference/control.md

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

docs/reference/control/in-background.md

@@ -29,7 +29,7 @@ control.inBackground(() => {
         basic.pause(100)
     }
 })
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     num++;
 })
 ```
@@ -42,7 +42,7 @@ let num = 0
 basic.forever(() => {
     basic.showNumber(num)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     num++;
 })
 ```

docs/reference/control/reset.md

@@ -24,11 +24,11 @@ When you get tired of counting, press button `B` to reset the
 ```blocks
 let item = 0;
 basic.showNumber(item);
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     item = item + 1;
     basic.showNumber(item);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), () => {
     control.reset();
 });
 ```

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/add-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.Down, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showNumber(game.score())
     game.setScore(0)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     game.addScore(1)
 })
 ```

docs/reference/game/change-score-by.md

@@ -16,7 +16,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.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     game.addScore(1)
 })
 game.startCountdown(10000)

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`)
->* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
->* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
->* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
->* ``blink`` -  how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+>* ``x`` - the change in horizontal location to set the sprite at on the LED screen (`0`-`4`)
+>* ``y`` - the change vertical location to set the sprite at on the LED screen (`0`-`4`)
+>* ``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`` - the change in brightness for the LED sprite. Completely dark is `0` and very bright is `255`.
+>* ``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/clear.md

@@ -27,7 +27,7 @@ let img = images.createImage(`
 . . . . .
 `)
 img.showImage(0)
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     img.clear()
     img.showImage(0)
 })

docs/reference/game/game-over.md

@@ -14,10 +14,10 @@ If you press button `B`, it shows an animation and ends the game.
 
 ```blocks
 basic.showString("PICK A BUTTON");
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     basic.showString("YOU WIN!");
 });
-input.onButtonEvent(Button.B, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), () => {
     game.gameOver();
 });
 ```

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`)
->* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
->* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
->* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
->* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+>* ``x`` - the horizontal location to set the sprite at on the LED screen (`0`-`4`)
+>* ``y`` - the vertical location to set the sprite at on the LED screen (`0`-`4`)
+>* ``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. Completely dark is `0` and very bright is `255`.
+>* ``blink`` - how fast the sprite is will blink on and off. The blink rate is in milliseconds.
 
 ## Returns
 

docs/reference/game/if-on-edge-bounce.md

@@ -20,7 +20,7 @@ degrees -- exactly the opposite direction.
 ```blocks
 let ball = game.createSprite(4, 2);
 basic.showNumber(ball.get(LedSpriteProperty.Direction));
-input.onButtonEvent(Button.B, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), () => {
     ball.ifOnEdgeBounce();
     basic.showNumber(ball.get(LedSpriteProperty.Direction));
 });

docs/reference/game/is-paused.md

@@ -15,7 +15,7 @@ game.isPaused()
 Resume the game if it's paused and button **B** is pressed.
 
 ```blocks
-input.onButtonEvent(Button.B, ButtonEvent.Down, function () {
+input.onButtonEvent(Button.B, input.buttonEventValue(ButtonEvent.Down), function () {
 	if (game.isPaused()) {
         game.resume()
     }

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/score.md

@@ -13,7 +13,7 @@ This program adds one point to your score every time you press button
 second) and shows your score.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Down, () => {
+input.onButtonEvent(Button.A, input.buttonEventValue(ButtonEvent.Down), () => {
     game.addScore(1);
     basic.pause(500);
     basic.showNumber(game.score());

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`)
->* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
->* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
->* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
->* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+>* ``x`` - the horizontal location to set the sprite at on the LED screen (`0`-`4`)
+>* ``y`` - the vertical location to set the sprite at on the LED screen (`0`-`4`)
+>* ``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. Completely dark is `0` and very bright is `255`.
+>* ``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,
-waits two seconds (2000 milliseconds),
-and then moves it to the right 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.
 
 ```blocks
-let ball = game.createSprite(0, 2);
-basic.pause(2000);
-ball.set(LedSpriteProperty.X, 4);
+input.onButtonEvent(Button.A, input.buttonEventClick(), function () {
+    if (freeze) {
+        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.onGesture(Gesture.Shake, () => {
-    
-});
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
-    
-});
-input.buttonIsPressed(Button.A);
-input.isGesture(Gesture.Shake);
-input.compassHeading();
-input.pinIsPressed(TouchPin.P0);
-input.temperature();
-input.acceleration(Dimension.X);
-input.lightLevel();
-input.rotation(Rotation.Pitch);
-input.magneticForce(Dimension.X);
-input.runningTime();
-input.runningTimeMicros();
-input.setAccelerometerRange(AcceleratorRange.OneG);
+input.onButtonEvent(Button.A, input.buttonEventClick(), function () {})
+input.onGesture(Gesture.Shake, function () {})
+input.onPinEvent(TouchPin.P0, input.buttonEventDown(), function() {})
+input.buttonIsPressed(Button.A)
+input.pinIsPressed(TouchPin.P0)
+input.isGesture(Gesture.Shake)
+input.compassHeading()
+input.temperature()
+input.acceleration(Dimension.X)
+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 Pressed
+# 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

@@ -1,20 +1,21 @@
-# On Pin Pressed
+# On Pin 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 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-pin-released.md

@@ -1,48 +0,0 @@
-# On Pin Released
-
-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 release pin `0`, `1`, or `2`
-together with `GND`.  When you are using this function in a web
-browser, click and release 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`
-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.Up, () => {
-})
-```
-
-## ~hint
-
-This function works best when the @boardname@ is using batteries for power,
-instead of the USB cable.
-
-## ~
-
-## Parameters
-
-* ``name`` means the pin that is being released, either `P0`, `P1`, or `P2`
-
-## Example: pin pressed counter
-
-This program counts how many times you release the `P0` pin. 
-Every time you release the pin, the program shows the number of times on the screen.
-
-```blocks
-let count = 0
-basic.showNumber(count, 100)
-input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Up, () => {
-    count = count + 1
-    basic.showNumber(count, 100)
-})
-```
-
-## 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)
-

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
+