diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 853f1303..16f1d46d 100644 --- a/docs/SUMMARY.md +++ b/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) diff --git a/docs/reference.md b/docs/reference.md index 92cbabc2..f0f57d82 100644 --- a/docs/reference.md +++ b/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) \ No newline at end of file +[control](/reference/control), +[console](/reference/console) diff --git a/docs/reference/console.md b/docs/reference/console.md new file mode 100644 index 00000000..2f6a086d --- /dev/null +++ b/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) diff --git a/docs/reference/console/send-to-screen.md b/docs/reference/console/send-to-screen.md new file mode 100644 index 00000000..2e63bf6a --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/reference/control.md b/docs/reference/control.md new file mode 100644 index 00000000..9c780657 --- /dev/null +++ b/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); +``` \ No newline at end of file diff --git a/docs/reference/control/timer.md b/docs/reference/control/timer.md new file mode 100644 index 00000000..c97c4c39 --- /dev/null +++ b/docs/reference/control/timer.md @@ -0,0 +1,8 @@ +# Timer + +```cards +control.timer1.reset() +control.timer1.pauseUntil(5) +control.timer1.millis() +control.timer1.seconds() +``` diff --git a/docs/reference/control/timer/millis.md b/docs/reference/control/timer/millis.md new file mode 100644 index 00000000..90d4d2b2 --- /dev/null +++ b/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) + diff --git a/docs/reference/control/timer/pause-until.md b/docs/reference/control/timer/pause-until.md new file mode 100644 index 00000000..47c1c897 --- /dev/null +++ b/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) diff --git a/docs/reference/control/timer/reset.md b/docs/reference/control/timer/reset.md new file mode 100644 index 00000000..1031f9ce --- /dev/null +++ b/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; + } +}) +``` \ No newline at end of file diff --git a/docs/reference/control/timer/seconds.md b/docs/reference/control/timer/seconds.md new file mode 100644 index 00000000..21c0d85c --- /dev/null +++ b/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) + diff --git a/libs/core/console.ts b/libs/core/console.ts index 5f0a6afe..3e065fbe 100644 --- a/libs/core/console.ts +++ b/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(); } diff --git a/libs/core/control.cpp b/libs/core/control.cpp index 5005089d..2b53bada 100644 --- a/libs/core/control.cpp +++ b/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); } diff --git a/libs/core/timer.ts b/libs/core/timer.ts index 3fe0e16d..2db3bfdc 100644 --- a/libs/core/timer.ts +++ b/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)); } } diff --git a/libs/music/docs/reference/music.md b/libs/music/docs/reference/music.md new file mode 100644 index 00000000..b722fe1c --- /dev/null +++ b/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) +``` \ No newline at end of file diff --git a/libs/music/docs/reference/music/play-sound-effect-until-done.md b/libs/music/docs/reference/music/play-sound-effect-until-done.md new file mode 100644 index 00000000..55981e8a --- /dev/null +++ b/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) \ No newline at end of file diff --git a/libs/music/docs/reference/music/play-sound-effect.md b/libs/music/docs/reference/music/play-sound-effect.md new file mode 100644 index 00000000..af9e7937 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/libs/music/sounds.ts b/libs/music/sounds.ts index b073970f..6d2f35a1 100644 --- a/libs/music/sounds.ts +++ b/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++;