pxt-microbit 4.0.12 → 4.0.13

package/docs/projects/v2-blow-away.md

@@ -0,0 +1,317 @@
+# Blow Away
+
+## 1. Introduction pt. 1 @unplugged
+
+👻 Oh, no! Your @boardname@ is being haunted by a ghost named Haven 👻
+
+For this tutorial, we'll learn how to blow Haven away 🌬️
+
+![Blow away banner message](/static/mb/projects/blow-away.png)
+
+## 2. Haunted ghost setup
+
+🏚️ **BooOooOoo** 🏚️
+
+A wild Haven has appeared!
+
+---
+
+► From the ``||basic:Basic||`` category, find ``||basic:show icon [ ]||`` and add it to your ``||basic:on start||`` container.
+
+► Click the heart icon and set it to show a ghost.  
+💡 In the ``show icon`` dropdown menu options, you can hover to see what each design is called.
+
+```blocks
+// @highlight
+basic.showIcon(IconNames.Ghost)
+```
+
+---
+
+## 3. Loop setup
+
+➰ **Looping around** ➰
+
+---
+
+► From the ``||loops:Loops||`` category, find the ``||loops:repeat [4] times||`` loop and snap it into your empty ``||basic:forever||`` container.   
+💡 Why do we need a [__*repeat loop*__](#repeatLoop "repeat code for a given number of times") when we already have a ``forever`` container? Because ``forever`` has an embedded delay that we want to avoid!
+
+```blocks
+basic.forever(function () {
+    // @highlight
+    for (let index = 0; index < 4; index++) {
+            
+    }
+})
+```
+
+## 4. Conditional setup
+
+🤔 **Conditioning and comparing** 🤔
+
+Haven hates noise and will blow away if things get too loud. Let's use an [__*if statement*__](#ifstatement "if this condition is met, do something") to check for sounds.
+
+---
+
+► From ``||logic:Logic||``, grab an ``||logic:if <true> then||`` statement and snap it into your empty ``||loops:repeat [4] times do||`` loop.
+
+► Go back to ``||logic:Logic||`` to get a ``||logic:<[0] [=] [0]>||`` comparison.
+
+► Snap ``||logic:<[0] [=] [0]>||`` in to **replace** the ``||logic:<true>||`` condition for your ``||logic:if then||`` statement.
+
+```blocks
+basic.forever(function () {
+    // @highlight
+    for (let index = 0; index < 4; index++) {
+        // @highlight
+        if (0 == 0) {
+            
+        }   
+    }
+})
+```
+
+## 5. Blow sound
+
+👂 **Haven's ears** 👂
+
+We'll be using a [__*sound threshold*__](#soundThreshold "a number for how loud a sound needs to be to trigger an event. 0 = silence to 255 = maximum noise") to act as Haven's ears.
+
+---
+
+► From the ``||input:Input||`` category, drag ``||input:sound level||`` in to **replace** the **_left_ ``0``** of your ``||logic:<[0] [=] [0]>||`` comparison.
+
+► Using the dropdown in the **middle** of ``||logic:[sound level] [=] [0]||``, change the comparison to be **``>``** (greater than).
+
+► Finally, have the **right side** of the comparison say ``128`` so your full comparison reads: **``sound level > 128``**.  
+💡 This means Haven will hear any sound above ``128``.
+
+```blocks
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        // @highlight
+        if (input.soundLevel() > 128) {
+            
+        }   
+    }
+})
+```
+
+## 6. Making variables
+
+☀️ **Variable weather** 🌨️
+
+Let's create some [__*variables*__](#variable "a holder for information that may change") to keep track of Haven's movement.
+
+---
+
+►  In the ``||variables:Variables||`` category, click on ``Make a Variable...`` and make a variable named ``col``.  
+💡 ``col`` is short for "column".
+
+►  Make **another** variable and name it ``row``.
+
+## 7. Displacing LEDs part 1
+
+🔀 **Random chance** 🔀
+
+To show Haven is blowing away, we want to move a random set of lights sideways.
+
+---
+
+► Your ``||variables:Variables||`` category should now have the option to ``||variables:set [row] to [0]||``. Drag that block into your empty ``||logic:if then||`` statement.
+
+► From the ``||math:Math||`` category, find ``||math:pick random [0] to [10]||`` and snap that in to **replace** the ``[0]`` in your ``||variables:set [row] to [0]||`` block.
+
+► Change the maximum number from ``10`` to **``4``**.  
+💡 We are setting the maximum random value to 4 because the lights on the @boardname@ are numbered 0, 1, 2, 3, and 4 for columns and rows.
+
+```blocks
+let row = 0
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            // @highlight
+            row = randint(0, 4)    
+        }   
+    }
+})
+```
+
+## 8. Displacing LEDs part 2
+
+► Go back into ``||variables:Variables||`` and drag out another ``||variables:set [row] to [0]||``. Place this one below the last one (at **the end**) of your `if then` statement.
+
+► Using the **dropdown menu**, set the new block to read ``||variables:set [col] to [0]||``.
+
+► From the ``||math:Math||`` category, grab another ``||math:pick random [0] to [10]||`` and snap that in to **replace** the ``[0]`` in your ``||variables:set [col] to [0]||`` block.
+
+► Change the maximum number from ``10`` to **``4``**.  
+
+```blocks
+let col = 0
+let row = 0
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            row = randint(0, 4)   
+            // @highlight
+            col = randint(0, 4)         
+        }   
+    }
+})
+```
+
+## 9. Conditioning on one point
+
+✨ **Ooh, sparkly** ✨
+
+Time to move some lights around!
+
+---
+
+► From ``||logic:Logic||``, grab another ``||logic:if <true> then||`` and snap it at the **inside and at the bottom of** your ``||loops:repeat [4] times do||`` loop, right below your ``||logic:if [sound level] [>] [128]||`` statement.
+
+► From the ``||led:Led||`` category, find ``||led:point x [0] y [0]||`` and drag it in to **replace** the ``||logic:<true>||`` condition in the **new** ``||logic:if then||`` statement.  
+💡 This block will test if the light is on at the the given ``x`` and ``y`` coordinate points.
+
+```blocks
+let col = 0
+let row = 0
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            row = randint(0, 4)
+            col = randint(0, 4)         
+        }
+        // @highlight
+        if (led.point(0, 0)) { }
+    }
+})
+```
+
+## 10. Unplotting and replotting LEDs
+
+To create the animation effect of Haven blowing away, we will turn off (or ``unplot``) a light that is on and then turn it on again (``plot`` it) in a different spot.
+
+---
+
+► From ``||led:Led||``, grab ``||led:unplot x [0] y [0]||`` and snap it inside the **empty** ``||logic:if <point x [0] y [0]> then||`` statement.
+
+► Go back to ``||led:Led||`` and get ``||led:plot x [0] y [0]||``. Snap that in **beneath** the ``||led:unplot x [0] y [0]||`` block that you just added.
+
+```blocks
+let col = 0
+let row = 0
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            row = randint(0, 4)
+            col = randint(0, 4)         
+        }
+        // @highlight
+        if (led.point(0, 0)) {
+            led.unplot(0, 0)
+            led.plot(0, 0)
+        }
+    }
+})
+```
+
+## 11. Setting variables
+
+📃 **Columns and rows** 📃
+
+Notice how you have **three** blocks from the ``||led:Led||`` category. All three have ``||led:x||`` ``[0]`` and ``||led:y||`` ``[0]`` coordinates. In these **two** steps, we will set it so that every ``||led:x||`` is followed by the ``||variables:col||`` variable and every ``||led:y||`` is followed by the ``||variables:row||`` variable.
+
+---
+
+► From ``||variables:Variables||``, get three copies of ``||variables:col||``, and use them to **replace the ``x`` values** in the following three blocks:  
+**1.** ``||led:point x [0] y [0]||``  
+**2.** ``||led:unplot x [0] y [0]||``  
+**3.** ``||led:plot x [0] y [0]||``
+
+► Go into ``||variables:Variables||``, get three copies of ``||variables:row||``, and use them to **replace the ``y`` values** in the same three blocks.
+
+```blocks
+let col = 0
+let row = 0
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            row = randint(0, 4)
+            col = randint(0, 4)         
+        }
+        // @highlight
+        if (led.point(col, row)) {
+            led.unplot(col, row)
+            led.plot(col, row)
+        }
+    }
+})
+```
+
+## 12. Moving LEDs
+
+➕ **Math makes the lights go swoosh** ➗
+
+Right now, we are unplotting and replotting in the same spot. What we want to do  is move the lights we're turning back on just a smidge to the right every time until there's nothing left on the grid.
+
+---
+
+► From ``||math:Math||``, find the ``||math:[0] [+] [0]||`` operation and use it to **replace** ``||variables:col||`` in your ``||led:plot x [col] y [row]||`` block.  
+💡 If you move your entire ``||basic:forever||`` container, you should find a greyed out ``col`` variable in your workspace.
+
+► Take the greyed out ``||variables:col||`` variable (or get a new one) and use it to **replace** the **_first_ ``[0]``** so the operation reads ``||math:[col] [+] [0]||``.
+
+► Replace the **_second_ ``[0]``** with **``[1]``** so the operation reads ``||math:[col] [+] [1]||``.
+
+```blocks
+let col = 0
+let row = 0
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            row = randint(0, 4)
+            col = randint(0, 4)         
+        }
+        // @highlight
+        if (led.point(col, row)) {
+            led.unplot(col, row)
+            led.plot(col + 1, row)
+        }
+    }
+})
+```
+
+## 13. Testing in the simulator
+
+🌬️ **Test what you've created** 👻
+
+Check out the simulator!
+
+---
+
+► Click on the pink bar underneath the microphone icon. Drag it above the sound number you chose (we used ``128``!) to blow Haven away.
+
+► If you have a new @boardname@ (the one with the **shiny gold** logo at the top), download this code and try it out!  
+💡 Blow close to the @boardname@ and watch Haven swoosh away 💨  
+💡 Use your @boardname@'s reset button (it's on the back!) to bring Haven back 👻
+
+```blocks
+let col = 0
+let row = 0
+basic.showIcon(IconNames.Ghost)
+basic.forever(function () {
+    for (let index = 0; index < 4; index++) {
+        if (input.soundLevel() > 128) {
+            row = randint(0, 4)
+            col = randint(0, 4)         
+        }
+        if (led.point(col, row)) {
+            led.unplot(col, row)
+            led.plot(col + 1, row)
+        }
+    }
+})
+```

package/docs/projects/v2-clap-lights.md

@@ -0,0 +1,195 @@
+# Clap Lights
+
+## 1. Introduction @unplugged
+
+The new @boardname@s have a microphone to help them detect sound 🎤
+
+Let's learn how to use a clap 👏 to switch your @boardname@'s lights on and off!
+
+![Clap lights banner message](/static/mb/projects/clap-lights.png)
+
+## 2. Setting up the sound input
+
+🔊 **Reacting to sound** 🔊
+
+---
+
+► From the ``||input:Input||`` category, find the ``||input:on [loud] sound||`` container and add it to your workspace.
+
+```blocks
+input.onSound(DetectedSound.Loud, function () {
+
+})
+```
+
+## 3. Creating a lightsOn variable
+
+🤿 **Diving right in** 🤿
+
+Let's begin by creating a [__*variable*__](#variable "a holder for information that may change") to keep track of whether the @boardname@'s lights are on or off.
+
+---
+
+► In the ``||variables:Variables||`` category, click on ``Make a Variable...`` and make a variable named ``lightsOn``.
+
+## 4. Displaying LEDs part 1
+
+🔆 **On or not?** 🌑
+
+In this step, we'll be using an [__*if then / else*__](#ifthenelse "runs some code if a Boolean condition is true and different code if the condition is false") statement.
+
+---
+
+► From the ``||logic:Logic||`` category, grab an ``||logic:if <true> then / else||`` block and snap it into your ``||input:on [loud] sound||`` container.
+
+► Look in the ``||variables:Variables||`` category. Find the new ``||variables:lightsOn||`` variable and snap it in to **replace** the ``||logic:<true>||`` value in your ``||logic:if <true> then / else||`` statement.
+
+```blocks
+let lightsOn = 0
+input.onSound(DetectedSound.Loud, function () {
+    // @highlight
+    if (lightsOn) {
+    	
+    } else {
+    	
+    }
+})
+```
+
+## 5. Displaying LEDs part 2
+
+🌞 **Lighting the display** 🌞
+
+---
+
+► From ``||basic:Basic||``, grab ``||basic:show leds||`` and snap it into the **top container** of your ``||logic:if then / else||`` statement.
+
+► Set the lights to a pattern you like!  
+💡 In the hint, we chose to turn on all of the outside lights. Feel free to make your own design 🎨
+
+```blocks
+let lightsOn = 0
+input.onSound(DetectedSound.Loud, function () {
+    if (lightsOn) {
+        // @highlight
+    	basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+    } else {
+    }
+})
+```
+
+## 6. Clearing the screen
+
+► From ``||basic:Basic||``, find ``||basic:clear screen||`` and snap it into the **bottom container** of your ``||logic:if then / else||`` section.  
+💡 This will turn the display off if ``lightsOn`` is **not** ``true``.
+
+```blocks
+let lightsOn = 0
+input.onSound(DetectedSound.Loud, function () {
+    if (lightsOn) {
+    	basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+    } else {
+        // @highlight
+    	basic.clearScreen()
+    }
+})
+```
+
+## 7. Setting the lightsOn variable
+
+🎬 **Lights, camera, _action_** ✨
+
+Just like we'd toggle a light switch, each time we clap, we want to **flip** the variable ``lightsOn`` to the **opposite** of what it was before.
+
+---
+
+► From ``||variables:Variables||``, locate ``||variables:set [lightsOn] to [0]||`` and snap it in at the **very top** of your ``||input:on [loud] sound||`` container.
+
+► From the ``||logic:Logic||`` category, find the ``||logic:not <>||`` operator and use it to **replace the ``[0]``** in ``||variables:set [lightsOn] to [0]||``.
+
+► From ``||variables:Variables||``, grab ``||variables:lightsOn||`` and snap it into the **empty part** of the ``||logic:not <>||`` operator.
+
+```blocks
+let lightsOn = false
+input.onSound(DetectedSound.Loud, function () {
+    // @highlight
+    lightsOn = !(lightsOn)
+    if (lightsOn) {
+    	basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+    } else {
+    	basic.clearScreen()
+    }
+})
+```
+
+## 8. Testing in the simulator
+
+💡 **Test what you've created** 💡
+
+---
+
+► Check out the simulator!
+
+► Click on the pink slider bar beneath the microphone icon and drag it up and down.  
+💡 Right now, your @boardname@ thinks that anything above 128 is loud. Every time the sound goes > 128, your lights should switch on/off.
+
+## 8. Set loud sound threshold
+
+Your @boardname@ might detect sounds when you don't want it to. Setting a [__*sound threshold*__](#soundThreshold "a number for how loud a sound needs to be to trigger an event. 0 = silence to 255 = maximum noise") could help 🔉🔊
+
+---
+
+► Click on the ``||input:Input||`` category. A new category should show up beneath it called ``||input:...more||``.
+
+► From ``||input:...more||``, grab ``||input:set [loud] sound threshold to [128]||`` and snap it into your **empty** ``||basic: on start||`` container.  
+💡 Try to change the value of your sound threshold so that every time you clap, your lights will turn on if they are off and vice versa.
+
+```blocks
+// @highlight
+input.setSoundThreshold(SoundThreshold.Loud, 150)
+```
+
+## 9. Testing, round 2
+
+👏 **YOU DID IT!** 👏
+
+Don't forget to test your code in the simulator!
+
+If you have a new @boardname@ (the one with the **shiny gold** logo at the top), download this code and try it out!
+
+```blocks
+let lightsOn = false
+input.onSound(DetectedSound.Loud, function () {
+    lightsOn = !(lightsOn)
+    if (lightsOn) {
+    	basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+    } else {
+    	basic.clearScreen()
+    }
+})
+input.setSoundThreshold(SoundThreshold.Loud, 150)
+```

package/docs/projects/v2-countdown.md

@@ -0,0 +1,151 @@
+# Countdown
+
+## 1. Introduction @unplugged
+
+🎇3...🎇2...🎇1...  
+🎆GO!🎆
+
+Let's create a musical countdown using the new @boardname@ with sound!
+
+![Countdown banner message](/static/mb/projects/countdown.png)
+
+## 2. Setting up the loop
+
+➰ **All looped up** ➰
+
+We'll begin by using a [__*for loop*__](#forLoop "repeat code for a given number of times using an index") to recreate the same sound 3 times.
+
+---
+
+► From the ``||loops:Loops||`` category in your toolbox, find the ``||loops:for [index] from 0 to [4]||`` loop and add it to your ``||basic:on start||`` container.
+
+► Change your loop to count from ``0`` to **``2``**.  
+💡 This means the loop will count 0-1-2 instead of what we want, which is 3-2-1. We will worry about this later!
+
+```blocks
+// @highlight
+for (let index = 0; index <= 2; index++) {
+	
+}
+```
+
+## 3. Play music
+
+🎵 **Musical loops** 🎵
+
+---
+
+► From ``||music:Music||``, grab ``||music:play tone [Middle C] for [1 beat]||`` and snap it into your empty ``for`` loop.  
+💡 Your simulator might start playing music. You can mute it if distracting.
+
+► 1 beat is a little long. Use the **dropdown** to set the tone to play for ``||music:1/4 beat||``.
+
+```blocks
+for (let index = 0; index <= 2; index++) {
+    // @highlight
+    music.playTone(262, music.beat(BeatFraction.Quarter))
+}
+```
+
+## 4. Showing a number
+
+✨ **Razzle dazzle down** ✨
+
+With every tone, we also want to **display** our countdown.
+
+---
+
+► From ``||basic:Basic||``, find ``||basic:show number [0]||`` and snap it in at the **bottom** of your ``for`` loop.
+
+► From your ``||loops:for [index] from 0 to [2]||`` loop condition, click and drag out the **red** ``||variables:index||`` variable.
+
+► Use the ``||variables:index||`` that you dragged out to **replace** the ``0`` in ``||basic:show number [0]||``.
+
+```blocks
+for (let index = 0; index <= 2; index++) {
+    music.playTone(262, music.beat(BeatFraction.Quarter))
+    // @highlight
+    basic.showNumber(index)
+}
+```
+
+## 5. Inverting the number
+
+If you take a look at your simulator, you'll notice the @boardname@ flashing 0-1-2. We want it to say 3-2-1! Let's learn a trick to change that.
+
+---
+
+► From the ``||math:Math||`` category, snap ``||math:[0] - [0]||`` in to **replace** ``||variables:index||`` in your ``||basic:show number [index]||`` block.  
+💡 You should now have a greyed out ``index`` variable in your workspace. We'll use that in the next step.
+
+► Pick up the greyed out ``||variables:index||`` variable and snap it in to the **right side** of your ``||math:[0] - [0]||`` operator.  
+💡 Can't find ``||variables:index||``? Try moving your ``||basic:on start||`` container to see if ``||variables: index||`` is hiding behind it!
+
+► Set the **left side** of your ``||math:[0]-[index]||`` operator to **``3``**.  
+💡 Why does this work? Every time we loop, our ``index`` variable will grow by 1 and our @boardname@ will output: 3-0 = **3** ➡️ 3-1 = **2** ➡️ 3-2 = **1**!
+
+```blocks
+for (let index = 0; index <= 2; index++) {
+    music.playTone(262, music.beat(BeatFraction.Quarter))
+    // @highlight
+    basic.showNumber(3 - index)
+}
+```
+
+## 6. Printing "GO!"
+
+🏁 **You had me at "GO!"** 🏁
+
+---
+
+► From ``||basic:Basic||``, grab ``||basic:show string ["Hello!"]||`` and snap it into the **very bottom** of your ``||basic:on start||`` container.
+
+► Replace ``Hello!`` with the word ``GO!``
+
+```blocks
+for (let index = 0; index <= 2; index++) {
+    music.playTone(262, music.beat(BeatFraction.Quarter))
+    basic.showNumber(3 - index)
+}
+// @highlight
+basic.showString("GO!")
+```
+
+## 7. Adding a "GO!" noise
+
+🏇 **And we're off!** 🏇
+
+---
+
+► From the ``||music:Music||`` category, grab ``||music:play tone [Middle C] for [1 beat]||`` and place it **above** your ``||basic:show string ["GO!"]||`` block and **below** your ``||loops:for||`` loop.  
+💡 This will let your @boardname@ play the sound and show ``GO!`` at the same time.
+
+► Set the ``||music:tone||`` to be ``Middle G``.  
+💡 ``Middle G`` is also tone ``392``.
+
+```blocks
+for (let index = 0; index <= 2; index++) {
+    music.playTone(262, music.beat(BeatFraction.Quarter))
+    basic.showNumber(3 - index)
+}
+// @highlight
+music.playTone(392, music.beat(BeatFraction.Whole))
+basic.showString("GO!")
+```
+
+## 8. Testing in the simulator
+
+🚦 **Test what you've created** 🚦
+
+Make sure your speakers are on and check out the simulator!  
+
+If you have a @boardname@ with sound (the one with the **shiny gold** logo at the top), no need to plug in an external speaker - just download this code and try it out!
+
+```blocks
+for (let index = 0; index <= 2; index++) {
+    music.playTone(262, music.beat(BeatFraction.Quarter))
+    basic.showNumber(3 - index)
+}
+music.playTone(392, music.beat(BeatFraction.Whole))
+basic.showString("GO!")
+```