bump V3

docs/reference/basic/forever.md

@@ -43,7 +43,7 @@ let num = 0
 basic.forever(() => {
     basic.showNumber(num)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     num = num + 1
 })
 ```
@@ -59,7 +59,7 @@ Try this on your @boardname@:
 basic.forever(() => {
     basic.showNumber(6789)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     basic.showNumber(2)
 })
 ```

docs/reference/bluetooth/stop-advertising.md

@@ -24,7 +24,7 @@ bluetooth.stopAdvertising();
 ## Example: stop advertising on button pressed
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     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.Click, () => {
+input.onButtonPressed(Button.A, () => {
     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.Click, () => {
+input.onButtonPressed(Button.A, () => {
     if (connected == 1) {
         bluetooth.uartWriteString("HELLO");
     }

docs/reference/control/in-background.md

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

docs/reference/control/millis.md

@@ -0,0 +1,25 @@
+# millis
+
+Get the number of milliseconds of time passed since the board was turned on.
+
+```sig
+control.millis()
+```
+
+## Returns
+
+* the [number](/types/number) of milliseconds of time since the board was turned on.
+
+## Example #example
+
+Find how many days, hours, minutes, and seconds the @boardname@ has been running.
+
+```blocks
+let msecs = control.millis()
+let seconds = msecs / 1000
+let mins = seconds / 60
+let hours = mins / 60
+let days = hours / 24
+```
+
+## #seealso

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.Click, () => {
+input.onButtonPressed(Button.A, () => {
     item = item + 1;
     basic.showNumber(item);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     control.reset();
 });
 ```

docs/reference/control/wait-for-event.md

@@ -0,0 +1,67 @@
+# wait For Event
+
+Stop running the current code and wait for an event.
+
+```sig
+control.waitForEvent(0, 0)
+```
+You might want your code to stop for a while until some event you're expecting happens.
+If you want your code to pause until a known event happens, use a ``||control:wait for event||`` block.
+A known event is something you identify that happens on the board or in your program.
+An event has both a source and a cause. The source is where the event comes from, like a sensor or
+some condition in your program. The cause is what made the event happen at the source.
+
+You assign numbers for your event sources and causes. These numbers are used by [``||control:raise event||``](/reference/control/raise-event) to announce to your program that an event just happened.
+
+As an example, you could make a timer that always causes an event every 100 milliseconds. The source
+number for the timer is `6` and the cause value is `1`. The program could wait for one of the time
+events like this:
+
+```blocks
+const myTimer = 6;
+const timerTimeout = 1;
+
+control.runInParallel(function() {
+    while (true) {
+        control.waitMicros(100000)
+        control.raiseEvent(myTimer, timerTimeout)
+    }
+})
+
+control.waitForEvent(myTimer, timerTimeout)
+```
+
+## Parameters
+
+* **id**: the identification [number](/types/number) (the source) of this event, such as: `10`.
+* **value**: a [number](/types/number) tells what the cause of the event is, like: `4`.
+
+## Example #example
+
+Make a timeout timer to signal every 2 seconds. Wait two times and write to the
+console each time.
+
+```blocks
+const myTimer = 6;
+const timerTimeout = 1;
+
+control.runInParallel(function() {
+    while (true) {
+        pause(2000)
+        control.raiseEvent(myTimer, timerTimeout)
+    }
+})
+
+control.waitForEvent(myTimer, timerTimeout)
+console.log("Timer timeout")
+control.waitForEvent(myTimer, timerTimeout)
+console.log("Timer timeout")
+```
+
+**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 #seealso
+
+[raise event](/reference/control/raise-event), [on event](/reference/control/on-event)

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.onButtonPressed(Button.A, () => {
     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.onButtonPressed(Button.A, () => {
 })
 ```
 
@@ -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.onButtonPressed(Button.A, () => {
     basic.showString("hello", 150)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     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.onButtonPressed(Button.A, () => {
     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.Click, () => {
+input.onButtonPressed(Button.B, () => {
     basic.showNumber(game.score())
     game.setScore(0)
 })
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     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.Click, () => {
+input.onButtonPressed(Button.A, () => {
     game.addScore(1)
 })
 game.startCountdown(10000)

docs/reference/game/clear.md

@@ -27,7 +27,7 @@ let img = images.createImage(`
 . . . . .
 `)
 img.showImage(0)
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     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.Click, () => {
+input.onButtonPressed(Button.A, () => {
     basic.showString("YOU WIN!");
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     game.gameOver();
 });
 ```

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

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.onButtonPressed(Button.A, () => {
     game.addScore(1)
 })
 game.startCountdown(10000)

docs/reference/images/arrow-image.md

@@ -29,10 +29,10 @@ Display a left arrow when button A is pressed or a right arrow when button B is
 let arrowLeft = images.arrowImage(ArrowNames.West)
 let arrowRight = images.arrowImage(ArrowNames.East)
 
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     arrowLeft.showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     arrowRight.showImage(0);
 });
 ```

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

@@ -36,10 +36,10 @@ let arrows = images.createBigImage(`
     . . # . .   . # # # .
     . . # . .   . . # . .
     `);
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     arrows.showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     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.onButtonPressed(Button.A, () => {
     images.createImage(`
         . . # . .
         . # # # .
@@ -34,7 +34,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
         . . # . .
         `).showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     images.createImage(`
         . . # . .
         . . # . .

docs/reference/images/icon-image.md

@@ -20,10 +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.onButtonPressed(Button.A, () => {
     iamHappy.showImage(0);
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     iamSad.showImage(0);
 });
 ```

docs/reference/images/show-image.md

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

docs/reference/input.md

@@ -3,13 +3,13 @@
 Events and data from sensors
 
 ```cards
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     
 });
 input.onGesture(Gesture.Shake, () => {
     
 });
-input.onPinTouched(TouchPin.P0, Button.Click, () => {
+input.onPinPressed(TouchPin.P0, () => {
     
 });
 input.buttonIsPressed(Button.A);

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.onButtonPressed(Button.AB, () => {
     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.onButtonPressed(Button.AB, () => {
     input.calibrateCompass();
 })
 ```

docs/reference/input/is-gesture.md

@@ -17,7 +17,7 @@ This program shows a number from `2` to `9` when you shake the @boardname@.
 ```blocks
 forever(function() {
     if (input.isGesture(Gesture.Shake)) {
-        let x = Math.randomRange(2, 9)
+        let x = randint(2, 9)
         basic.showNumber(x)
     }
 })

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.onButtonPressed(Button.B, () => {
     let level = input.lightLevel()
     basic.showNumber(level)
 })

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

@@ -1,6 +1,6 @@
 # On Button Pressed
 
-Start an [event handler](/reference/event-handler) (part of the program that will run when something happens, like when a button is pressed). 
+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.
 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 +9,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.onButtonPressed(Button.A, () => {})
 ```
 
 Find out how buttons provide input to the @boardname@ in this video:
@@ -18,13 +18,13 @@ https://www.youtube.com/watch?v=t_Qujjd_38o
 
 ## Example: count button clicks
 
-This example counts how many times you press the `A` button. 
+This example counts how many times you press the `A` button.
 Each time you press the button, the [LED screen](/device/screen) shows the `count` variable getting bigger.
 
 ```blocks
 let count = 0
 basic.showNumber(count)
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     count++;
     basic.showNumber(count);
 })
@@ -35,8 +35,8 @@ 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, () => {
-    let dice = Math.randomRange(0, 5) + 1
+input.onButtonPressed(Button.B, () => {
+    let dice = randint(0, 5) + 1
     basic.showNumber(dice)
 })
 ```

docs/reference/input/on-gesture.md

@@ -19,7 +19,7 @@ This program shows a number from `2` to `9` when you shake the @boardname@.
 
 ```blocks
 input.onGesture(Gesture.Shake,() => {
-    let x = Math.randomRange(2, 9)
+    let x = randint(2, 9)
     basic.showNumber(x)
 })
 ```

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

@@ -14,7 +14,7 @@ through your body and back into the @boardname@. This is called
 **completing a circuit**. It's like you're a big wire!
 
 ```sig
-input.onPinTouched(TouchPin.P0, Button.Click, () => {
+input.onPinPressed(TouchPin.P0, () => {
 })
 ```
 
@@ -43,7 +43,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.onPinTouched(TouchPin.P0, Button.Click, () => {
+input.onPinPressed(TouchPin.P0, () => {
     count = count + 1
     basic.showNumber(count)
 })

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

@@ -13,7 +13,7 @@ through your body and back into the @boardname@. This is called
 **completing a circuit**. It's like you're a big wire!
 
 ```sig
-input.onPinTouched(TouchPin.P0, ButtonEvent.Click, () => {
+input.onPinReleased(TouchPin.P0, () => {
 })
 ```
 
@@ -36,7 +36,7 @@ Every time you release the pin, the program shows the number of times on the scr
 ```blocks
 let count = 0
 basic.showNumber(count, 100)
-input.onPinTouched(TouchPin.P0, ButtonEvent.Click, () => {
+input.onPinReleased(TouchPin.P0, () => {
     count = count + 1
     basic.showNumber(count, 100)
 })

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.onButtonPressed(Button.B, () => {
     let now = input.runningTime()
     basic.showNumber(now)
 })

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.onButtonPressed(Button.B, () => {
     led.enable(false)
 });
 ```

docs/reference/led/point-brightness.md

@@ -0,0 +1,46 @@
+# Point Brightness
+
+Read the brightness of a LED on the [LED screen](/device/screen).
+
+```sig
+led.pointBrightness(0,0);
+```
+
+## Parameters
+
+* ``x`` is a [number](/types/number) that means the
+  horizontal spot on the LED screen (from left to right: 0, 1, 2, 3,
+  or 4)
+* ``y`` is a [number](/types/number) that means the vertical
+  spot on the LED screen (from top to bottom: 0, 1, 2, 3, or 4)
+
+If a parameter is [out of bounds](/reference/out-of-bounds) (a value
+other than 0 to 4), this function will return `false`.
+
+## Returns
+
+* a [number](/blocks/logic/number). If it is `true`, that means the LED is on. If it is `false`, that means the LED is off.
+
+## ~hint
+
+The LED screen is a solid square of LEDs with five LEDs on each side.
+To learn more about how you number the LEDs with ``x`` and ``y``
+coordinates, see [LED screen](/device/screen).
+
+## ~
+
+## Example: Toggle off
+
+This program turns the center LED (2, 2) off it is not bright enough.  (If
+it is already off, this program leaves it off.)
+
+```blocks
+if (led.pointBrightness(2, 2) < 100) {
+    led.unplot(2, 2)
+}
+```
+
+## See also
+
+[unplot](/reference/led/unplot), [plot](/reference/led/plot), [LED screen](/device/screen)
+

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.onButtonPressed(Button.B, () => {
     led.stopAnimation();
 });
 basic.showString("STOP ME! STOP ME! PLEASE, WON'T SOMEBODY STOP ME?");

docs/reference/music.md

@@ -3,22 +3,25 @@
 Generation of music tones through pin ``P0``.
 
 ```cards
-music.playTone(0, 0);
-music.ringTone(0);
-music.rest(0);
-music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once);
-music.stopMelody(MelodyStopOptions.All);
-music.onEvent(MusicEvent.MelodyNotePlayed, () => {});
-music.beat(BeatFraction.Whole);
-music.tempo();
-music.changeTempoBy(20);
-music.setTempo(120);
+music.playTone(0, 0)
+music.ringTone(0)
+music.rest(0)
+music.startMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
+music.stopMelody(MelodyStopOptions.All)
+music.onEvent(MusicEvent.MelodyNotePlayed, () => {})
+music.beat(BeatFraction.Whole)
+music.tempo()
+music.changeTempoBy(20)
+music.setTempo(120)
+music.setVolume(0)
+music.volume()
 ```
 
 ## See Also
 
-[playTone](/reference/music/play-tone), [ringTone](/reference/music/ring-tone), [rest](/reference/music/rest),
-[beginMelody](/reference/music/begin-melody), 
-[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),
+[playTone](/reference/music/play-tone), [ringTone](/reference/music/ring-tone),
+[rest](/reference/music/rest), [startMelody](/reference/music/start-melody),
+[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)

docs/reference/music/making-melodies.md

@@ -6,9 +6,11 @@ Composing some sound, or maybe some music, is done by putting tones to together,
 
 A _note_ is a tone that is recognized as part of music. A note has a name like '**C**'. A note is played for an amount of time called its _duration_. 
 
-On your @boardname@, a note is played on the speaker by sending a signal to a it with a certain _frequency_ called [Hertz](http://wikipedia.org/Hertz). Frequency is how fast something vibrates during one second. If you ring a bell that was made to play an '**A**' note, the bell will vibrate at 440 Hertz (440 times per second). So, notes are just certain frequencies that have special names.
+On your @boardname@, a note is played on the speaker by sending a signal to it with a certain _frequency_ called [Hertz](http://wikipedia.org/Hertz). Frequency is how fast something vibrates during one second. If you ring a bell that was made to play an '**A**' note, the bell will vibrate at 440 Hertz (440 times per second). So, notes are just certain frequencies that have special names.
 
-## ~ hint
+### ~ hint
+
+#### Listen to music with headphones
 
 Watch this video to see how speakers and headphones make sound when connected to your @boardname@.
 
@@ -24,7 +26,7 @@ Basic notes have names that use one of the first nine letters of the alphabet. T
 
 ``|A|``, ``|B|``, ``|C|``, ``|D|``, ``|E|``, ``|F|``, ``|G|``
 
-Ther are other notes named like the basic notes but have extra parts to the name called _sharp_ and _flat_. These other notes are just a bit different from the basic notes and have frequencies a little higher or lower than the basic note. This makes music a little more complicated but much more interesting!
+There are other notes named like the basic notes but have extra parts to the name called _sharp_ and _flat_. These other notes are just a bit different from the basic notes and have frequencies a little higher or lower than the basic note. This makes music a little more complicated but much more interesting!
 
 Some of these other notes look like:
 
@@ -32,6 +34,14 @@ Some of these other notes look like:
 
 When a small amount music or even a song is written down it is called [sheet music](https://wikipedia.org/wiki/Sheet_music).
 
+### ~ hint
+
+#### Note names in different languages
+
+Many languages other than English use different names for some or all of the musical notes. MakeCode uses English for names in code.
+
+### ~
+
 ## Sounds and music in code
 
 Of course, we can't use written music in our code. We can make music another way. The way to do it is to put names of notes in [strings](/types/string). We make our notes using letters, symbols, and numbers. The notes of a melody are put together in an array like:
@@ -51,13 +61,13 @@ What you see here is not some alien language but a bunch of notes with their dur
 You might notice that the sound string has an ``'R:1'`` in it. The '**R**` means _rest_ and to rest for one beat. A rest is a pause, or a time of silence, in the sound.
 
 
-#### ~ hint
+### ~ hint
 
-**Duration**
+#### Duration
 
 The amount of time a note is played (duration) is measured as _beats_. The standard number _beats per minute_ (bpm) in music is 120 bpm which is one-half of a second of time. A _whole_ note lasts for 4 beats and a _quarter_ note takes just one beat.
 
-#### ~
+### ~
 
 ## Example
 

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.onButtonPressed(Button.A, () => {
     music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
 })
 music.setTempo(100)
@@ -56,7 +56,7 @@ The events related to background melody get triggered by a melody that is played
 
 ```
 control.inBackground(function () {
-    basic.pause(Math.randomRange(0, 5000))
+    basic.pause(randint(0, 5000))
     music.beginMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
 })
 music.onEvent(MusicEvent.BackgroundMelodyStarted, function () {

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.onButtonPressed(Button.A, () => {
     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.onButtonPressed(Button.B, () => {
     music.setPlayTone((frequency: number, duration: number) => {
         radio.sendNumber((frequency << 16) | (duration & 0xffff));
     })    

docs/reference/music/set-volume.md

@@ -0,0 +1,35 @@
+# set Volume
+
+Set the volume for the sound synthesizer.
+
+```sig
+music.setVolume(128)
+```
+
+### ~hint
+
+#### Simulator
+
+``||music:set volume||`` works on the @boardname@. It might not work in the simulator on every browser.
+
+### ~
+
+## Parameters
+
+* ``volume``: the volume of of the sounds played to the sound output. The volume [number](/types/number) can be between `0` for silent and `255` for the loudest sound.
+
+## Example #example
+
+Set the synthesizer volume to something quieter.
+
+```blocks
+music.setVolume(50)
+```
+
+## See also
+
+[volume](/reference/music/volume)
+
+```package
+music
+```

docs/reference/music/start-melody.md

@@ -0,0 +1,64 @@
+# start Melody
+
+Start playing a musical melody through pin ``P0`` of the @boardname@.
+
+```sig
+music.startMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
+```
+
+## ~ hint
+
+**Simulator**: This function only works on the @boardname@ and in some browsers.
+
+## ~
+
+There are built-in melodies that you can choose from the ``||start melody||`` block. These are already composed for you and are easy to use by just selecting the one you want. If you want to play your own melody, you can [compose](/reference/music/making-melodies) one and use it instead of one of the built-in ones.
+
+Melodies are a sequence of notes, each played for some small amount time, one after the other. The notes in a melody are held in an [array](/types/array) of [strings](/types/string). Each string in the array is a note of the melody. You make a melody by assembling the notes along with the _duration_ that the note plays for. The melody is [formed](/reference/music/making-melodies) like this:
+
+``NOTE[octave][:duration] eg: ['g5:1']``
+
+```block
+music.startMelody(['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 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``.
+
+## Parameters
+
+* **melody**: A built-in melody or an [array](/types/array) representation of a [melody](reference/music/making-melodies) you wish to play.
+* **options**: the play option for the melody:
+>* ``once``: play the melody in the foreground one time
+>* ``forever``: play the melody in the foreground and keep repeating it
+>* ``once in background``: play the melody in the background one time
+>* ``forever in background``: play the melody in the background and keep repeating it
+
+## Examples
+
+### Play the "Entertainer"
+
+This example plays the ``Entertainer`` built-in melody.
+
+```blocks
+music.startMelody(music.builtInMelody(Melodies.Entertainer), MelodyOptions.Once)
+```
+
+### Play a composed melody forever
+
+Play a made-up melody in the background forever.
+
+```blocks
+music.startMelody(['g4:1', 'c5', 'e', 'g:2', 'e:1', 'g:3'], MelodyOptions.ForeverInBackground)
+```
+
+## See also
+
+[stop melody](/reference/music/stop-melody), [play tone](/reference/music/play-tone),
+[rest](/reference/music/rest), [ring tone](/reference/music/ring-tone),
+[tempo](/reference/music/tempo), [set tempo](/reference/music/set-tempo),
+[change tempo by](/reference/music/change-tempo-by)
+
+[Making Melodies](/reference/music/making-melodies)
+

docs/reference/music/volume.md

@@ -0,0 +1,27 @@
+# volume
+
+Get the current volume level of the sound synthesizer.
+
+```sig
+music.volume()
+```
+
+### ~hint
+
+#### Simulator
+
+Using ``||music:volume||`` works on the @boardname@. It might not work in the simulator on every browser.
+
+### ~
+
+## Returns
+
+* a [number](/types/number) that is the current volume level of output from the sound synthesizer. The value can be between `0` for silent and `255` for the loudest sound.
+
+## See also
+
+[set volume](/reference/music/set-volume)
+
+```package
+music
+```

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.onButtonPressed(Button.B, () => {
     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.onButtonPressed(Button.B, () => {
     pins.digitalWritePin(DigitalPin.P1, 1);
     basic.pause(500);
     pins.digitalWritePin(DigitalPin.P1, 0);

docs/reference/pins/set-pull.md

@@ -11,7 +11,7 @@ is connected to ``GND`` (0 volts), then when you press the button,
 button press.
 
 ```sig
-pins.setPull(DigitalPin.P9, PinPullMode.PullDown);
+pins.setPull(DigitalPin.C9, PinPullMode.PullDown);
 ```
 
 The pull-up and -down resistors are about 13kOhm.

docs/reference/pins/spi-format.md

@@ -30,7 +30,7 @@ The default number of bits is `8` and the default mode value is `3`.
 Set the pins and format for the SPI connection.
 
 ```blocks
-pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+pins.spiPins(DigitalPin.C15, DigitalPin.C14, DigitalPin.C13);
 pins.spiFormat(8, 3);
 ```
 

docs/reference/pins/spi-frequency.md

@@ -26,7 +26,7 @@ Read the value of the _WHOAMI_ register from the device connected to the SPI bus
 
 ```blocks
 pins.digitalWritePin(DigitalPin.P0, 1);
-pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+pins.spiPins(DigitalPin.C15, DigitalPin.C14, DigitalPin.C13);
 pins.spiFormat(8, 3);
 pins.spiFrequency(1000000);
 pins.digitalWritePin(DigitalPin.P0, 0);

docs/reference/pins/spi-pins.md

@@ -31,7 +31,7 @@ If you don't set the pins for the SPI connection, the default pin assignments ar
 Set the pin assignments for a SPI connection to the default pins.
 
 ```blocks
-pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+pins.spiPins(DigitalPin.C15, DigitalPin.C14, DigitalPin.C13);
 ```
 
 ## See also

docs/reference/pins/spi-write.md

@@ -28,7 +28,7 @@ Send the command to read the value of the _WHOAMI_ register from the device conn
 
 ```blocks
 pins.digitalWritePin(DigitalPin.P0, 1);
-pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+pins.spiPins(DigitalPin.C15, DigitalPin.C14, DigitalPin.C13);
 pins.spiFormat(8, 3);
 pins.spiFrequency(1000000);
 pins.digitalWritePin(DigitalPin.P0, 0);

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.onButtonPressed(Button.A, () => {
     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.onButtonPressed(Button.A, () => {
     radio.sendString("H");
 });
-input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.B, () => {
     radio.sendString("S");
 });
 radio.onDataReceived(() => {

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.onButtonPressed(Button.A, () => {
     radio.sendNumber(input.acceleration(Dimension.X))
 })
 ```

docs/reference/radio/send-string.md

@@ -26,7 +26,7 @@ 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, () => {
+input.onButtonPressed(Button.A, () => {
     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.onButtonPressed(Button.A, () => {
     radio.sendValue("acc", input.acceleration(Dimension.X))
 })
 ```

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

@@ -30,7 +30,7 @@ the second @boardname@), this program sends temperature data to the
 serial port.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
+input.onButtonPressed(Button.A, 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,7 @@ the second @boardname@), this program sends temperature data to
 serial.
 
 ```blocks
-input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
+input.onButtonPressed(Button.A, () => {
     radio.sendNumber(input.temperature());
 });
 radio.onDataReceived(() => {

docs/reference/serial/read-line.md

@@ -8,9 +8,12 @@ serial.readLine();
 
 ### ~hint
 
-This function expects the line it reads to be terminated with the `\r`
+This function expects the line it reads to be terminated with the `\n`
 character.  If your terminal software does not terminate lines with
-`\r`, this function will probably never return a value.
+`\n`, this function will probably never return a value.
+
+
+You can override the ``serial.NEW_LINE_DELIMITER`` field to change the newline delimiter.
 
 ### ~
 

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.onButtonPressed(Button.A, () => {
     serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
 });
 ```