Merge branch 'master' of https://github.com/microsoft/pxt-ev3

docs/SUMMARY.md

@@ -111,3 +111,25 @@
             * [pause for light](/reference/sensors/color-sensor/pause-for-light)
             * [color](/reference/sensors/color-sensor/color)
             * [light](/reference/sensors/color-sensor/ambient-light)
+    * [Music](/reference/music)
+        * [play sound effect](/reference/music/play-sound-effect)
+        * [play sound effect until done](/reference/music/play-sound-effect-until-done)
+        * [play tone](/reference/music/play-tone)
+        * [ring tone](/reference/music/ring-tone)
+        * [stop all sounds](/reference/music/stop-all-sounds)
+        * [rest](/reference/music/rest)
+        * [change tempo by](/reference/music/change-tempo-by)
+        * [set tempo](/reference/music/set-tempo)
+        * [note frequency](/reference/music/note-frequency)
+        * [beat](/reference/music/beat)
+        * [set volume](/reference/music/set-volume)
+    * [Control](/reference/control)
+        * [Timer](/reference/control/timer)
+            * [seconds](/reference/control/timer/seconds)
+            * [millis](/reference/control/timer/millis)
+            * [reset](/reference/control/timer/reset)
+            * [pause until](/reference/control/timer/pause-until)
+    * [Console](/reference/console)
+        * [log](/reference/console/log)
+        * [log value](/reference/console/log-value)
+        * [send to screen](/reference/console/send-to-screen)

docs/reference.md

@@ -1,9 +1,16 @@
 # Reference
 
 ```namespaces
-brick.showMood(moods.sleeping);
 sensors.color(null);
 motors.stopAll();
+brick.showMood(moods.sleeping);
+```
+
+## Advanced
+
+```namespaces
+console.log("");
+control.runInParallel(function(){});
 ```
 
 ## See Also
@@ -11,5 +18,5 @@ motors.stopAll();
 [brick](/reference/brick),
 [sensors](/reference/sensors),
 [motors](/reference/motors),
-[touch sensor](/reference/sensors/touch-sensor),
-[color sensor](/reference/sensors/color-sensor)
+[control](/reference/control),
+[console](/reference/console)

docs/reference/console.md

@@ -0,0 +1,15 @@
+# Console
+
+Output text and data values to the console.
+
+```cards
+console.log("");
+console.logValue("x", 0);
+console.sendToScreen();
+```
+
+## See also
+
+[log](/reference/console/log),
+[log value](/reference/console/log-value),
+[send to screen](/reference/console/send-to-screen)

docs/reference/console/send-to-screen.md

@@ -0,0 +1,26 @@
+# send To Screen
+
+Direct the console output to go to the @boardname@ screen.
+
+```sig
+console.sendToScreen();
+```
+
+A "console" is a place for a user to see special messages from a device. It could be  something connected to a serial port, a display that shows text, or even a text file. A console is typically used as a place to send information that is added to a message _log_ (a record of messages that are sent from a device). Your program can send log messages using the [console](/reference/console) functions. The MakeCode editor has a console view that lets you see the console output when your program runs in the simulator.
+
+On the @boardname@, the screen can serve as a console too and you can make your console output go there. Before using the console log functions, set the screen as the console output location.
+
+## Example
+
+Direct the console output to go to the screen. Show 20 values on the screen. Use the up and down buttons to scroll through the values.
+
+```blocks
+console.sendToScreen()
+for (let index = 0; index <= 20; index++) {
+    console.logValue("index", index)
+}
+```
+
+## See also
+
+[log](reference/console/log), [log value](/reference/console/log-value)

docs/reference/control.md

@@ -0,0 +1,33 @@
+# Control
+
+Program controls and events.
+
+```cards
+control.millis();
+control.runInParallel(() => {
+    
+});
+control.reset();
+control.waitMicros(4);
+control.deviceSerialNumber();
+```
+
+## Timer
+
+```cards
+control.timer1.reset()
+control.timer1.pauseUntil(5)
+control.timer1.millis()
+control.timer1.seconds()
+```
+
+## Advanced #advanced
+
+```cards
+control.raiseEvent(0, 0);
+control.onEvent(0, 0, () => {
+    
+});
+control.assert(false, 0);
+control.panic(0);
+```

docs/reference/control/timer.md

@@ -0,0 +1,8 @@
+# Timer
+
+```cards
+control.timer1.reset()
+control.timer1.pauseUntil(5)
+control.timer1.millis()
+control.timer1.seconds()
+```

docs/reference/control/timer/millis.md

@@ -0,0 +1,25 @@
+# millis
+
+Get the amount of time counted by the timer in milliseconds.
+
+The timer count begins from `0` when you program starts or is [reset](/reference/control/timer/reset). 
+
+## Returns
+
+* a [number](/types/number) that is the amount of time elapsed, in milliseconds, since the timer was started or reset.
+
+## Example
+
+Find out how many milliseconds go by between presses of the `down` button on the brick.
+
+```blocks
+brick.buttonDown.onEvent(ButtonEvent.Pressed, function () {
+    brick.showValue("DownButtonTime", control.timer1.millis(), 1)
+    control.timer1.reset()
+})
+```
+
+## See also
+
+[seconds](/reference/control/timer/seconds), [reset](/reference/control/timer/reset)
+

docs/reference/control/timer/pause-until.md

@@ -0,0 +1,32 @@
+# pauseUntil
+
+Pause until the timer counts up to a number of milliseconds.
+
+```sig
+control.timer1.pauseUntil(0)
+```
+
+When code in a block comes to a **pauseUntil**, it will wait until the timer count reaches the number of milliseconds you say. Code in blocks like **forever** and **runInParallel** will keep running while the current code is paused.
+
+The time number you give is the number of milliseconds past the running timer count. If the timer is currently at `25000` milliseconds and you want to pause for `10` seconds, then use a pause time of `35000`. If you want your pause time number to match the actual wait time, then [reset](/reference/control/timer/reset) the timer first.
+
+## Parameters
+
+* **ms**: the [number](/types/number) of milliseconds that you want the timer to count up to. For seconds, convert to milliseconds: 100 milliseconds = 1/10 second and 1000 milliseconds = 1 second.
+
+## Example
+
+Pause between messages on the screen by `5` seconds.
+
+```blocks
+brick.clearScreen()
+brick.showString("Testing my pause...", 1)
+let startTime = control.timer1.millis()
+brick.showValue("StartTime", startTime, 3)
+control.timer1.pauseUntil(startTime + 5000)
+brick.showValue("EndTime", control.timer1.millis() - startTime, 4)
+```
+
+## See also
+
+[millis](/reference/control/timer/millis), [reset](/reference/control/timer/reset)

docs/reference/control/timer/reset.md

@@ -0,0 +1,49 @@
+# reset
+
+Reset the elapsed time of the timer back to `0`.
+
+```sig
+control.timer1.reset()
+```
+
+A timer starts counting from `0` when your program starts. It's time value always gets larger as your program runs. Maybe you want to meausure how long some task takes to finish or you want to do some action  only for a little while. A timer can keep track of the time it takes to do it.
+
+Resetting the timer sets the time value to `0` so the next time you check the time it's exactly the amount of time that has _elapsed_. Otherwise, you need to remember a start time value and then subtract it from the current time. 
+
+## Examples
+
+### Press time
+
+Find out how much time goes by between presses of the `enter` button on the brick.
+
+```blocks
+brick.buttonEnter.onEvent(ButtonEvent.Pressed, function () {
+    brick.showValue("PressTime", control.timer1.seconds(), 1)
+    control.timer1.reset()
+})
+```
+
+### Difference timer
+
+Use a difference timer and compare it to a timer that resets. Use the ``left`` button to start timing and the ``right`` button to stop.
+
+```blocks
+let startTime = 0
+let timing = false
+brick.buttonLeft.onEvent(ButtonEvent.Pressed, function () {
+    brick.clearScreen()
+    brick.showString("Starting timers...", 1)
+    startTime = control.timer1.seconds()
+    control.timer2.reset()
+    timing = true
+})
+brick.buttonRight.onEvent(ButtonEvent.Pressed, function () {
+    if (timing) {
+        brick.clearScreen()
+        brick.showString("Timer results...", 1)
+        brick.showValue("timer 1", control.timer1.seconds() - startTime, 3)
+        brick.showValue("timer 2", control.timer2.seconds(), 4)
+        timing = false;
+    }
+})
+```

docs/reference/control/timer/seconds.md

@@ -0,0 +1,25 @@
+# seconds
+
+Get the amount of time counted by the timer in seconds.
+
+The timer count begins from `0` when you program starts or is [reset](/reference/control/timer/reset). The number of seconds returned also includes milliseconds if there is a fractional part of a second too.
+
+## Returns
+
+* a [number](/types/number) that is the amount of time elapsed, in seconds, since the timer was started or reset.
+
+## Example
+
+Find out how many seconds go by between presses of the `down` button on the brick.
+
+```blocks
+brick.buttonDown.onEvent(ButtonEvent.Pressed, function () {
+    brick.showValue("DownButtonTime", control.timer1.seconds(), 1)
+    control.timer1.reset()
+})
+```
+
+## See also
+
+[millis](/reference/control/timer/millis), [reset](/reference/control/timer/reset)
+

libs/core/console.ts

@@ -51,6 +51,7 @@ namespace console {
      */
     //% blockId=logsendtostreen block="send console to screen"
     //% weight=1
+    //% help=console/send-to-screen
     export function sendToScreen(): void {
         console.screen.attach();
     }

libs/core/control.cpp

@@ -10,6 +10,7 @@ namespace control {
  */
 //% weight=21 blockGap=12 blockId="control_raise_event"
 //% block="raise event|from %src|with value %value" blockExternalInputs=1
+//% help=control/raise-event
 void raiseEvent(int src, int value) {
     pxt::raiseEvent(src, value);
 }

libs/core/timer.ts

@@ -11,36 +11,40 @@ namespace control {
         }
 
         /**
-         * Gets the elapsed time in millis since the last reset
+         * Get the elapsed time in millis since the last reset
          */
         //% blockId=timerMillis block="%timer|millis"
+        //% help=control/timer/millis
         millis(): number {
             return control.millis() - this.start;
         }
         
         /**
-         * Gets the elapsed time in seconds since the last reset
+         * Get the elapsed time in seconds since the last reset
          */
         //% blockId=timerSeconds block="%timer|seconds"
+        //% help=control/timer/seconds
         seconds(): number {
             return this.millis() / 1000;
         }
 
         /**
-         * Resets the timer
+         * Reset the timer
          */
         //% blockId=timerRest block="%timer|reset"
+        //% help=control/timer/reset
         reset() {
             this.start = control.millis();
         }
 
         /**
-         * Pauses until the timer reaches the given amount of milliseconds
+         * Pause until the timer reaches the given amount of milliseconds
          * @param ms how long to pause for, eg: 5, 100, 200, 500, 1000, 2000
          */
         //% blockId=timerPauseUntil block="%timer|pause until (ms) %ms"
+        //% help=control/timer/pause-until
         pauseUntil(ms: number) {
-            const remaining = this.millis() - ms;
+            const remaining = ms - this.millis();
             pause(Math.max(0, remaining));
         }
     }

libs/music/docs/reference/music.md

@@ -0,0 +1,15 @@
+# Music
+
+```cards
+music.playSoundEffect(null)
+music.playSoundEffectUntilDone(null)
+music.stopAllSounds()
+music.playTone(0, 0)
+music.ringTone(Note.C)
+music.rest(100)
+music.changeTempoBy(20)
+music.setTempo(120)
+music.noteFrequency(Note.C)
+music.beat()
+music.setVolume(50)
+```

libs/music/docs/reference/music/play-sound-effect-until-done.md

@@ -0,0 +1,54 @@
+# play Sound Effect Until Done
+
+Play a sound from one of the built-in sound effect until it completes.
+
+```sig
+music.playSoundEffectUntilDone(null)
+```
+
+There are several sound effects you can play. Use the sounds list in the block to pick the sound you want to play. The sound plays and this part of your program waits until the sound finishes. Other parts of your program, like code in **forever** loops and **runInParallel** blocks will continue to run though.
+
+Many of the built-in sound effects make sounds match to the actions that your @boardname@ is doing. For example, you can add the ``mechanical motor start`` sound your program to indicate that your motors are running.
+
+## Parameters
+
+* **sound**: a built-in sound effect from the list of available sounds.
+
+## Example
+
+Make a game where the buttons on the brick are used to guess a number from `1` to `4` that your program randomly chooses. On the correct guess, flash a ``green`` status light and play a cheering sound. The ``enter`` button resets the game to play again.
+
+```blocks
+let pick = 0
+brick.buttonEnter.onEvent(ButtonEvent.Pressed, function () {
+    pick = 0
+    music.stopAllSounds()
+    brick.setStatusLight(StatusLight.Off)
+})
+brick.buttonDown.onEvent(ButtonEvent.Pressed, function () {
+    pick = 1
+})
+brick.buttonLeft.onEvent(ButtonEvent.Pressed, function () {
+    pick = 2
+})
+brick.buttonRight.onEvent(ButtonEvent.Pressed, function () {
+    pick = 3
+})
+brick.buttonUp.onEvent(ButtonEvent.Pressed, function () {
+    pick = 4
+})
+forever(function () {
+    if (pick > 0) {
+        if (Math.randomRange(0, 3) + 1 == pick) {
+            brick.setStatusLight(StatusLight.GreenFlash)
+            music.playSoundEffectUntilDone(sounds.expressionsCheering)
+        }
+        pick = 0
+    }
+    pause(300)
+})
+```
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect), [stop all sounds](/reference/music/stop-all-sounds)

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

@@ -0,0 +1,29 @@
+# play Sound Effect
+
+Play a sound from one of the built-in sound effects.
+
+```sig
+music.playSoundEffect(null)
+```
+
+There are several sound effects you can play. Use the sounds list in the block to pick the sound you want to play. When the sounds starts, your program continues on and doesn't wait for the sound to finish. This lets your program do other things while your sound plays in the _background_.
+
+Many of the built-in sound effects make sounds match to the actions that your @boardname@ is doing. For example, you can add the ``mechanical motor start`` sound to your program to indicate that your motors are running.
+
+## Parameters
+
+* **sound**: a built-in sound effect from the list of available sounds.
+
+## Example
+
+Drive the brick backwards and play a backup alert sound.
+
+```blocks
+music.playSoundEffect(sounds.mechanicalBackingAlert);
+motors.largeBC.tank(-50, -50, 15, MoveUnit.Rotations);
+music.stopAllSounds();
+```
+
+## See also
+
+[play sound effect until done](/reference/music/play-sound-effect-until-done), [stop all sounds](/reference/music/stop-all-sounds)

libs/music/sounds.ts

@@ -260,11 +260,12 @@ namespace music {
     const soundsLimit = 1;
 
     /**
-     * Plays a sound
+     * Play a sound and wait until it finishes
      * @param sound the sound to play
      */
     //% blockId=music_play_sound_effect_until_done block="play sound effect %sound|until done"
     //% weight=98 blockGap=8
+    //% help=music/play-sound-effect-until-done
     export function playSoundEffectUntilDone(sound: Sound) {
         if (!sound || numSoundsPlaying >= soundsLimit) return;
         numSoundsPlaying++;
@@ -288,6 +289,7 @@ namespace music {
      */
     //% blockId=music_play_sound_effect block="play sound effect %sound"
     //% weight=99 blockGap=8
+    //% help=music/play-sound-effect
     export function playSoundEffect(sound: Sound) {
         if (!sound || numSoundsPlaying >= soundsLimit) return;
         numSoundsPlaying++;