upstream mb v7.0.42

docs/reference/music/built-in-melody.md

@@ -0,0 +1,51 @@
+# built In Melody
+
+Get a melody string for a built-in melody.
+
+```sig
+music.builtInMelody(Melodies.Dadadadum)
+```
+
+A collection of built-in melodies are available. You choose one by selecting the name of the melody.
+
+## Parameters
+
+* **melody**: A melody name. The available melodies are:
+
+>* `dadadum`
+>* `entertainer`
+>* `prelude`
+>* `ode`
+>* `nyan`
+>* `ringtone`
+>* `funk`
+>* `blues`
+>* `birthday`
+>* `wedding`
+>* `funeral`
+>* `punchline`
+>* `baddy`
+>* `chase`
+>* `ba ding`
+>* `wawawawaa`
+>* `jump up`
+>* `jump down`
+>* `power up`
+>* `power down`
+
+## Returns
+
+* a [string](/types/string) that contains the melody.
+
+## Example
+
+Play the built-in melody for **blues**.
+
+```blocks
+music.startMelody(music.builtInMelody(Melodies.Blues), MelodyOptions.Once)
+```
+
+## See also
+
+[start melody](/reference/music/start-melody),
+[built-in sound effect](/reference/music/builtin-sound-effect)

docs/reference/music/built-in-playable-melody.md

@@ -0,0 +1,50 @@
+# built In Playable Melody
+
+Get a playable sound object for a built-in melody.
+
+```sig
+music.builtInPlayableMelody(Melodies.Dadadadum)
+```
+
+A collection of built-in melodies are available as [playable](/types/playable) sound objects. You choose one by selecting the name of the melody.
+
+## Parameters
+
+* **melody**: A melody name. The available melodies are:
+
+>* `dadadum`
+>* `entertainer`
+>* `prelude`
+>* `ode`
+>* `nyan`
+>* `ringtone`
+>* `funk`
+>* `blues`
+>* `birthday`
+>* `wedding`
+>* `funeral`
+>* `punchline`
+>* `baddy`
+>* `chase`
+>* `ba ding`
+>* `wawawawaa`
+>* `jump up`
+>* `jump down`
+>* `power up`
+>* `power down`
+
+## Returns
+
+* a [playable](/types/playable) object that contains the melody.
+
+## Example
+
+Play the built-in melody for **blues**.
+
+```blocks
+music.play(music.builtInPlayableMelody(Melodies.Blues), music.PlaybackMode.InBackground)
+```
+
+## See also
+
+[built-in sound effect](/reference/music/builtin-sound-effect)

docs/reference/music/is-sound-playing.md

@@ -0,0 +1,40 @@
+# is Sound Playing
+
+Check if sound is playing at any sound output.
+
+```sig
+music.isSoundPlaying()
+```
+
+### ~ reminder
+
+![works with micro:bit V2 only image](/static/v2/v2-only.png)
+
+This function requires the [micro:bit V2](/device/v2) hardware. If you use this function with a micro:bit v1 board, you will see the **927** error code on the screen.
+
+### ~
+
+Sound is played at the built-in speaker or at the selected audio output pin. You can check if any sound is currently being played at any of these outputs.
+
+## Returns
+
+* a [boolean](/types/boolean) value that is `true` if sound is being played at the built-in speaker or at the audio pin. The value is `false` otherwise.
+
+## Example #example
+
+Stop all sounds if any are currently playing.
+
+```blocks
+if (music.isSoundPlaying()) {
+    music.stopAllSounds()
+}
+```
+
+## See also
+
+[set built-in speaker enabled](/reference/music/set-built-in-speaker-enabled),
+[set audio pin](/reference/pins/set-audio-pin)
+
+```package
+music
+```

docs/reference/pins/analog-pin.md

@@ -0,0 +1,32 @@
+# analog Pin
+
+Get an analog pin number for a pin identifier.
+
+```sig
+pins._analogPin(AnalogPin.P0)
+```
+
+## Parameters
+
+* **pin**: a pin identifier for an analog pin (`P0` through `P20`).
+
+## Returns
+
+* a pin [number](/types/number) for the pin identifier.
+
+## Example
+
+Set an analog pin variable for `P1`, read pin `P1`, and show the input value on the LED screen.
+
+```blocks
+let myPin = AnalogPin.P1
+basic.forever(function() {
+    let value = pins.analogReadPin(myPin)
+    basic.showNumber(value)
+})
+```
+
+## See also
+
+[analog read pin](/reference/pins/analog-read-pin),
+[analog write pin](/reference/pins/analog-write-pin)

docs/reference/pins/digital-pin.md

@@ -0,0 +1,43 @@
+# digital Pin
+
+Get an digital pin number for a pin identifier.
+
+```sig
+pins._digitalPin(DigitalPin.P3)
+```
+
+## Parameters
+
+* **pin**: a pin identifier for an digital pin (`P0` through `P20`).
+
+## Returns
+
+* a pin [number](/types/number) for the pin identifier.
+
+## Example: football score keeper
+
+This program reads pin `P0` to find when a goal is scored. When `P0`
+is `1`, the program makes the score bigger and plays a buzzer sound
+through `P2` with ``||pins:digital write pin||``. Use pin variables
+to set the read and write pin numbers.
+
+```blocks
+let score = 0
+let readPin = DigitalPin.P0
+let writePin = DigitalPin.P2
+basic.showNumber(score)
+basic.forever(() => {
+    if (pins.digitalReadPin(readPin) == 1) {
+        score++;
+        pins.digitalWritePin(writePin, 1)
+        basic.showNumber(score)
+        basic.pause(1000)
+        pins.digitalWritePin(writePin, 0)
+    }
+})
+```
+
+## See also
+
+[digital read pin](/reference/pins/digital-read-pin),
+[digital write pin](/reference/pins/digital-write-pin)

docs/teachertool/catalog.json

@@ -3,7 +3,7 @@
         {
             "id": "35610CA0-38F8-4CCE-BAB9-99593DB3358A",
             "use": "responds_to_events",
-            "template": "Responds to at least ${count} different events",
+            "template": "Responds to at least ${count} different event(s)",
             "description": "At least the specified number of event blocks are present.",
             "docPath": "/teachertool",
             "maxCount": 1,
@@ -38,7 +38,7 @@
         {
             "id": "2CA4A5DA-4690-4514-97F5-2FE145AB3A59",
             "use": "uses_led_coordinates",
-            "template": "Uses LED coordinates at least ${count} times",
+            "template": "Uses LED coordinates at least ${count} time(s)",
             "description": "Uses blocks with LED coordinate inputs at least the specified number of times.",
             "docPath": "/teachertool",
             "maxCount": 1,

editor/flash.ts

@@ -6,6 +6,8 @@ const dataAddr = 0x20002000;
 const stackAddr = 0x20001000;
 const FULL_FLASH_TIMEOUT = 100000; // 100s
 const PARTIAL_FLASH_TIMEOUT = 60000; // 60s
+const CONNECTION_CHECK_TIMEOUT = 2000; // 2s
+const RETRY_DAP_CMD_TIMEOUT = 50; // .05s
 
 const flashPageBIN = new Uint32Array([
     0xbe00be00, // bkpt - LR is set to this
@@ -270,7 +272,7 @@ class DAPWrapper implements pxt.packetio.PacketIOWrapper {
     private async getBaudRate() {
         const readSerialSettings = new Uint8Array([0x81])  // get serial settings
         const serialSettings = await this.dapCmd(readSerialSettings)
-        const baud = (serialSettings[4] << 24)+ (serialSettings[3] << 16) + (serialSettings[2] << 8) + serialSettings[1]
+        const baud = (serialSettings[4] << 24) + (serialSettings[3] << 16) + (serialSettings[2] << 8) + serialSettings[1]
         return baud
     }
 
@@ -334,7 +336,7 @@ class DAPWrapper implements pxt.packetio.PacketIOWrapper {
             await this.setBaudRate()
         // only init after setting baud rate, in case we got reset
         await this.cortexM.init()
-        if (resetOnConnection){
+        if (resetOnConnection) {
             log(`reset cortex`)
             await this.cortexM.reset(true)
         }
@@ -351,12 +353,20 @@ class DAPWrapper implements pxt.packetio.PacketIOWrapper {
     }
 
     private async clearCommandsAsync() {
-        // before calling into dapjs, push through a few commands to make sure the responses
-        // to commands from previous sessions (if any) are flushed. Count of 5 is arbitrary.
-        for (let i = 0; i < 5; i++) {
-            try {
-                await this.getDaplinkVersionAsync();
-            } catch (e) {}
+        try {
+            await pxt.Util.promiseTimeout(CONNECTION_CHECK_TIMEOUT, (async () => {
+                // before calling into dapjs, push through a few commands to make sure the responses
+                // to commands from previous sessions (if any) are flushed. Count of 5 is arbitrary.
+                for (let i = 0; i < 5; i++) {
+                    try {
+                        await this.getDaplinkVersionAsync();
+                    } catch (e) { }
+                }
+            })());
+        } catch (e) {
+            const errOut = new Error(e);
+            (errOut as any).type = "inittimeout";
+            throw errOut;
         }
     }
 
@@ -407,8 +417,8 @@ class DAPWrapper implements pxt.packetio.PacketIOWrapper {
             await this.io.reconnectAsync();
         }
 
-        await this.clearCommandsAsync()
         await this.stopReadersAsync();
+        await this.clearCommandsAsync()
         await this.cortexM.init();
         await this.cortexM.reset(true);
         await this.checkStateAsync();
@@ -438,11 +448,11 @@ class DAPWrapper implements pxt.packetio.PacketIOWrapper {
         // via the webusb events
     }
 
-    private recvPacketAsync() {
+    private recvPacketAsync(timeout?: number) {
         if (this.io.recvPacketAsync)
-            return this.io.recvPacketAsync()
+            return this.io.recvPacketAsync(timeout);
         else
-            return this.pbuf.shiftAsync()
+            return this.pbuf.shiftAsync(timeout);
     }
 
     private async dapCmd(buf: Uint8Array) {
@@ -456,12 +466,14 @@ class DAPWrapper implements pxt.packetio.PacketIOWrapper {
             // response is a left-over from previous communications
             log(msg + "; retrying");
             try {
-                const secondTryResp = await this.recvPacketAsync();
+                // Add in a timeout, as this can stall if device thinks communication is complete.
+                const secondTryResp = await this.recvPacketAsync(RETRY_DAP_CMD_TIMEOUT);
                 if (secondTryResp[0] === buf[0]) {
                     log(msg + "; retry success");
                     return secondTryResp;
                 }
             } catch (e) {
+                pxt.tickEvent('hid.flash.cmderror.retryfailed', { req: buf[0], resp: resp[0] });
                 log(e);
             }
             throw new Error(`retry failed ${msg}`);