pxt-microbit 4.1.26 → 4.1.29

package/built/targetlight.json

@@ -355,11 +355,11 @@
     },
     "uploadDocs": true,
     "versions": {
-        "branch": "v4.1.26",
-        "tag": "v4.1.26",
-        "commits": "https://github.com/microsoft/pxt-microbit/commits/8e52fbaa54225431f38e20eb9de4e35bd29a8dc3",
-        "target": "4.1.26",
-        "pxt": "7.5.21"
+        "branch": "v4.1.29",
+        "tag": "v4.1.29",
+        "commits": "https://github.com/microsoft/pxt-microbit/commits/a50d2ca7104beaea76556dd147d117591ca51c17",
+        "target": "4.1.29",
+        "pxt": "7.5.25"
     },
     "blocksprj": {
         "id": "blocksprj",

package/built/theme.json

@@ -254,6 +254,7 @@
     },
     "winAppDeprImage": "/static/winapp.PNG",
     "showWinAppDeprBanner": false,
+    "legacyTutorial": true,
     "TOC": [
         {
             "name": "About",

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

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

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

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

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

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

package/docs/reference/music.md

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

package/docs/types/sound.md

@@ -0,0 +1,136 @@
+# Sound
+
+A **Sound** is a data object that is created from a sound expression. A sound expression is group of parameters that define a sound, such as wave shape, sound volume, frequency, and duration.
+
+A sound is generated from an expression based on a fundamental wave shape, or waveform. To make a sound wave, the sound data must change from a high peak to a low trough over a period of time and repeat. The peaks and troughs are the positive amplitudes and negative amplitudes of the wave across the zero line. The volume controls the amplitude of the wave.
+
+When the sound is played on a speaker or headphones, the vibrations create the pressures our ears detect as sound.
+
+### ~ hint
+
+#### Sounds and Sound Expressions
+
+In code, a **Sound** type is a complex data object that includes data for all the elements that represent a sound. This includes information about the frequencies and volumes at various points in time for the duration of the sound. A **SoundExpression** is another data type that helps create a **Sound**. It has the elements of how to make the sound. Many of them you specify when you edit a sound.
+
+Code for creating and playing a sound from a sound expression could look like this:
+
+```typescript-ignore
+let mySound = music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
+music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
+```
+
+### ~
+
+## Sound Editing
+
+When you click on the waveform in the ``||music:play sound||`` block, the sound editor will display. The sound editor defines the sound expression parameter with choices for the **waveform**, sound **duration** time, **frequency** range, **volume** range, **effect**, and **interpolation**.
+
+![Sound Editor](/static/types/sound/sound-editor.png)
+
+Both the frequency and volume can start and end with different values across the duration of the sound.
+
+## Wave shape
+
+The wave shape is chosen to create a natural sound or a synthetic sound. Some wave shapes can also serve to generate signals when played to a pin instead of a speaker or headphones.
+
+### Sine wave
+
+The waveform that matches natural sound is the sine wave. This is the wave type in music and voice.
+
+![Sine wave](/static/types/sound/sine-wave.png)
+
+### Sawtooth wave
+
+A sawtooth wave has a vertical rising edge and a linear falling edge. It's shape looks like the teeth on a saw.
+
+![Sawtooth wave](/static/types/sound/sawtooth-wave.png)
+
+### Triangle wave
+
+The triangle wave is has symmetrical a rising and a falling edge. It makes the shape of triangles in the waveform.
+
+![Triangle wave](/static/types/sound/triangle-wave.png)
+
+### Square wave
+
+A square wave has both verical rising and falling edges with a flat section on the top and bottom. The flat sections match the volume set for the sound. Square waves are sometimes used to represent digital data and will make an "electronic" sound.
+
+![Square wave](/static/types/sound/square-wave.png)
+
+### Noise wave
+
+The noise wave is created using random frequenices and volume. Setting the frequency parameters for the sound expression creates a "tuning" range for the noise sound effect.
+
+![Noise wave](/static/types/sound/noise-wave.png)
+
+## Duration
+
+The sound has a length of time that it plays for. This is set as a number of milliseconds (**ms**).
+
+## Volume
+
+The volume controls the loudness (amplitude) of the sound. The sound can start with one volume setting and end with another. It can begin loud and end quiet, or the other way around. The volume control has start and end points that can be adjusted higher and lower. Grab them and move them up or down.
+
+### High to low
+
+![Volume from high to low](/static/types/sound/volume-hilo.png)
+
+### Low to High
+
+![Volume from low to high](/static/types/sound/volume-lohi.png)
+
+### Constant volume
+
+![Constant volume](/static/types/sound/volume-constant.png)
+
+## Frequency
+
+Frequency is how fast a wave repeats itself from the zero line to its peak down to its trough and back to the zero line. If it does this 1000 times in one second then the frequency has 1000 cycles per second and is measured in units of Hertz (1000 Hz). The frequency of the sound at any point in time is its current _pitch_. Musical notes and parts of speech are different frequecies that last for short periods of time in a sound.
+
+A sound expression has both a starting frequency and an ending frequecy. The frequency can start low and end high, start high and end low, or remain the same for the duration of the sound.
+
+### High to low
+
+![Frequency from high to low](/static/types/sound/freq-hilo.png)
+
+### Low to High
+
+![Frequency from low to high](/static/types/sound/freq-lohi.png)
+
+### Effect
+
+Effects add small changes to the waveform but can make a big change in how it sounds to a listener. There are a few effects available to apply to a sound.
+
+* **Tremolo**: add slight changes in volume of the sound expression.
+
+>![Tremolo effect setting](/static/types/sound/effect-tremolo.png)
+
+* **Vibrato**: add slight changes in frequency to the sound expression.
+
+>![Vibrato effect setting](/static/types/sound/effect-vibrato.png)
+
+* **Warble**: similar to Vibrato but with faster variations in the frequency changes.
+
+>![Warble effect setting](/static/types/sound/effect-warble.png)
+
+### Interpolation
+
+Interpolation is how the sound expression will make the changes in frequency or volume of the sound. These changes can occur at a constant rate along duration of the sound or more suddenly at the beginning.
+
+* **Linear**: The change in frequency is constant for the duration of the sound.
+
+>![Frequency from low to high](/static/types/sound/interp-linear.png)
+
+* **Curve**: The change in frequency is faster at the beginning of the sound and slows toward the end.
+
+>![Frequency from low to high](/static/types/sound/interp-curve.png)
+
+* **Logarithmic**: The change in frequency is rapid during the very first part of the sound.
+
+
+>![Frequency from low to high](/static/types/sound/interp-log.png)
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect),
+[create sound effect](/reference/music/create-sound-effect)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pxt-microbit",
-    "version": "4.1.26",
+    "version": "4.1.29",
     "description": "micro:bit target for Microsoft MakeCode (PXT)",
     "keywords": [
         "JavaScript",
@@ -45,6 +45,6 @@
     },
     "dependencies": {
         "pxt-common-packages": "9.5.6",
-        "pxt-core": "7.5.21"
+        "pxt-core": "7.5.25"
     }
 }

package/pxtarget.json

@@ -15,7 +15,8 @@
         "libs/microphone",
         "libs/settings",
         "libs/flashlog",
-        "libs/datalogger"
+        "libs/datalogger",
+        "libs/color"
     ],
     "cloud": {
         "workspace": false,
@@ -601,7 +602,8 @@
             "incompatibleHardwareImage": "/static/download/incompatible.png"
         },
         "winAppDeprImage": "/static/winapp.PNG",
-        "showWinAppDeprBanner": false
+        "showWinAppDeprBanner": false,
+        "legacyTutorial": true
     },
     "queryVariants": {
         "hidemenu": {