pxt-microbit 4.1.5 → 4.1.9

package/docs/blocks/comments.md

@@ -0,0 +1,131 @@
+# Comments
+
+For simple programs, is easy to understand the steps and the flow the program might take when it runs. If you have just a few steps in your program that run one after the other in a sequence, it's fairly easy to understand what's happening at each place in your program.
+
+The following program does 4 simple things:
+
+1. Show a "Hello" message
+2. Display a smiley face as part of a greeting
+2. Pause for a second so you can see the smiley
+3. Clear the screen
+
+```blocks
+basic.showString("Hello!")
+basic.showIcon(IconNames.Happy)
+basic.pause(1000)
+basic.clearScreen()
+```
+
+It's quite obvious what this program is doing. Each block does one thing, the next block runs after the previous one in a sequence, then the program ends. Let's say you want the user to show that they saw the greeting. You could add button press event that shows a check mark icon.
+
+```blocks
+basic.showString("Hello!")
+basic.showIcon(IconNames.Happy)
+basic.pause(1000)
+basic.clearScreen()
+input.onButtonPressed(Button.A, function () {
+    basic.showIcon(IconNames.Yes)
+})
+```
+
+You know, of course, that the button press event means that the user has acknowleged your greeting. If you shared your program with someone else though, they might not understand why you wanted to add the button press to the program. 
+
+## Block comments
+
+To let others know what certain parts of your program are supposed to do, you can add **comments**. Comments are a text description that says what that part of your program is doing. To put a comment on a block, open the block menu and select **Add comment**.
+
+![Block menu](/static/blocks/block-menu.jpg)
+
+A place for your comment will appear and you can type in your description of what that block is for and what it's supposed to do.
+
+![Insert the comment](/static/blocks/insert-comment.jpg)
+
+Once a comment is added to a block, a comment icon will show in the upper-left corner of the block. Here's our program with the comment on the ``||input:on button A press||``.
+
+```blocks
+// Signal that the greeting was seen
+input.onButtonPressed(Button.A, function () {
+    basic.showIcon(IconNames.Yes)
+})
+basic.showString("Hello!")
+basic.showIcon(IconNames.Happy)
+basic.pause(1000)
+basic.clearScreen()
+```
+
+In the Blocks editor, the comment is displayed when you click on the comment icon. If you view the JavaScript or Python code, you'll see a comment line directly above the button press code.
+
+```typescript
+// Signal that the greeting was seen
+input.onButtonPressed(Button.A, function () {
+    basic.showIcon(IconNames.Yes)
+})
+basic.showString("Hello!")
+basic.showIcon(IconNames.Happy)
+basic.pause(1000)
+basic.clearScreen()
+```
+
+When a program contains conditionals, loops, or functions, adding comments becomes important to help understand what's happening at those places in your program. The program can take a different path based on a condition, result from a function, or some other action.
+
+### ~ hint
+
+#### Workspace comments
+
+You can add comments an notes about your project with **Workspace Comments**. Just right-click on the Workspace background and choose **Add Comment** to insert your comments for the project.
+
+```block
+/**
+ * This is a workspace comment.
+ * 
+ * Use this space to make comments
+ * 
+ * and notes about your project.
+ */
+// Display a message
+function showMessage () {
+    basic.showString("Workspaces have comments!")
+}
+```
+
+### ~
+
+The following example has a conditional inside a loop to choose one of three different mood values. For each mood, a function will display an icon for it. Each block has a comment that describes what it will do. Take a look at the JavaScript or Python code to see the comments on the code text also.
+
+```blocks
+/**
+ * The mood icon project.
+ * 
+ * TODO: add more moods
+ * 
+ * 1. Sad
+ * 
+ * 2. Confused
+ */
+// Display an emotion of love
+function heart () {
+    basic.showIcon(IconNames.Heart)
+}
+// Show a surprised expression
+function surprised () {
+    basic.showIcon(IconNames.Surprised)
+}
+// Display a smiley mood
+function smiley () {
+    basic.showIcon(IconNames.Happy)
+}
+// My program that shows three mood icons
+// Run the loop to show 3 icons
+for (let index = 0; index <= 2; index++) {
+    // Select an icon based on the index
+    if (index == 0) {
+        smiley()
+    } else if (index == 1) {
+        heart()
+    } else {
+        surprised()
+    }
+    // Pause for a second between moods
+    basic.pause(1000)
+}
+```

package/docs/blocks/loops.md

@@ -1,3 +1,15 @@
 # @extends
 
 ## #specific
+
+```cards
+loops.everyInterval(500, function () {})
+```
+
+## #seealso
+
+[for](/blocks/loops/for), 
+[while](/blocks/loops/while), 
+[repeat](/blocks/loops/repeat), 
+[for of](/blocks/loops/for-of),
+[every](/reference/loops/every)

package/docs/device/usb/webusb.md

@@ -1,12 +1,11 @@
 # WebUSB
 
-[WebUSB](https://wicg.github.io/webusb/) is an emerging web standard that allows to access @boardname@ from web pages. 
-It allows for a **one-click download** without installing any additional app or software! It also allows to receive data from the @boardname@.
+[WebUSB](https://wicg.github.io/webusb/) is a recent and developing web standard that allows you to access @boardname@ directly from a web page. It allows for a **one-click download** without installing any additional app or software! It also lets you receive data into the web page from the @boardname@.
 
 ## Support
 
-* Chrome 79+ browser for Android, Chrome OS, Linux, macOS and Windows 10.
-* Microsoft Edge 79+ browser for Android, Chrome OS, Linux, macOS and Windows 10.
+* Chrome (version 79 and newer) browser for Android, Chrome OS, Linux, macOS and Windows 10.
+* Microsoft Edge (version 79  and newer) browser for Android, Chrome OS, Linux, macOS and Windows 10.
 
 ## Prepare your @boardname@
 
@@ -18,13 +17,36 @@ Make sure that your @boardname@ is running version **0249** or above of the firm
 
 Here are the steps on the supported browsers:
 
-* connect your @boardname@ to your computer with the microUSB cable
-* open a project
-* click the triple dot icon on the **Download** button and click **Pair device**
-* click on the **Pair device** button and select **BBC micro:bit CMSIS-DAP** or **DAPLink CMSIS-DAP** from the list.
+* Connect your @boardname@ to your computer with the Micro USB cable
+* Open a project
+* Click the triple dot icon on the **Download** button and then click **Connect device**.
+
+![Download button and menu](/static/mb/device/usb/download-button-menu.jpg)
+
+* In the connection message window, click **Next**.
+
+![Connect device dialog](/static/mb/device/usb/connect-usb.jpg)
+
+* Another message window will display telling you which device you should pair with. Click **Next** to go to the device list.
+
+![Device name dialog](/static/mb/device/usb/pair-dap.jpg)
+
+* Select **BBC micro:bit CMSIS-DAP** or **DAPLink CMSIS-DAP** from the list and click **Connect**.
+
+![Device list for WebUSB pairing](/static/mb/device/usb/pair-device.jpg)
 
 If you don't see any devices in the list and @boardname@ has the right firmware (**0249** or above), you can create a [support ticket](https://support.microbit.org/support/tickets/new) to notify the Micro:bit Foundation of the problem. Skip the rest of these steps.
 
+![Device list for WebUSB pairing](/static/mb/device/usb/no-pair.jpg)
+
+* When your @boardname@ is connected, you'll see the **Connected to micro:bit** message window. Click on **Done** and you're ready to go! 
+
+![Connected message window](/static/mb/device/usb/connected.jpg)
+
+* If the connection to your @boardname@ was unsuccessful, you'll see the **Connect failed** message. You can press **Try Again** to attempt the connection again or cancel the window and [troubleshoot](/device/usb/webusb/troubleshoot) your connection.
+
+![Connect failed message window](/static/mb/device/usb/connect-fail.jpg)
+
 ## Unpair your @boardname@ #unpair
 
 You will need to unpair your device from the editor to disable WebUSB.
@@ -33,7 +55,7 @@ You will need to unpair your device from the editor to disable WebUSB.
 * Uncheck each **BBC micro:bit CMSIS-DAP** or **DAPLink CMSIS-DAP** device
 * Reload the page
 
-![](/static/webusb/unpair.gif)
+![Unpairing from the browser](/static/webusb/unpair.gif)
 
 ## One-click Download
 

package/docs/device/usb/windows-chrome.md

@@ -1,32 +1,22 @@
-# Uploading from Chrome for Windows
-
-## ~ hint
-
-Starting with Chrome 65 on Windows 10, 
-you can use **WebUSB** to download with one-click.
-[Learn more about WebUSB...](/device/usb/webusb).
-
-## ~
+# Transferring from Chrome for Windows
 
 While you're writing and testing your programs, you'll mostly be [running them
 in the simulator](/device/simulator), but once you've finished your program you
 can **compile** it and run it on your micro:bit.
 
-The basic steps are:
+## Transfer using a WebUSB connection
 
-1. Connect your micro:bit to your computer via USB
-2. Click **Download** and download the `.hex` file
-3. Copy the `.hex` file from your computer onto the micro:bit drive
+With Chrome (version 79 and newer), you can transfer your program to the @boardname@ with a single click. If your browser supports WebUSB, you can use the **one-click download** feature to send your programs to the @boardname@. See the [WebUSB](/device/usb/webusb) page to learn how to pair your @boardname@ with a computer and transfer your programs with a single click.
 
-## Requirements
+## Downloading your program as file
 
-You need the following things to transfer and run a script on your micro:bit:
+The basic steps are:
 
-* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
-    the same cable that is commonly used to connect a smart phone to a computer.
-* A PC running Windows 7 or later.
+1. Connect your @boardname@ to your computer with a USB cable (use an A-Male to Micro USB cable)
+2. Click **Download** and download the `.hex` file
+3. Copy the `.hex` file from your computer onto the micro:bit drive
 
-## Step 1: Connect your micro:bit to your computer
+### Step 1: Connect your micro:bit to your computer
 
 First, connect the micro:bit:
 
@@ -40,7 +30,7 @@ it appears as a new drive under Devices.
 
 ![](/static/mb/device/usb-windows-device.jpg)
 
-## Step 2 (optional): Configure Chrome to ask where to save the file
+### Step 2 (optional): Configure Chrome to ask where to save the file
 
 You only need to do this once.
 
@@ -49,7 +39,7 @@ You only need to do this once.
 3. Find the **Downloads** settings.
 4. Enable the setting **Ask where to save each file before downloading**.
 
-## Step 3: Download your program
+### Step 3: Download your program
 
 1. Open your project on @homeurl@
 2. Click **Download**
@@ -57,11 +47,11 @@ You only need to do this once.
     so save it into the `MICROBIT` drive.
     Otherwise, continue with one of the options in Step 4 below.
 
-## Step 4: Transfer the file to your micro:bit
+### Step 4: Transfer the file to your micro:bit
 
 If the file was saved onto your computer, you will need to transfer it to the micro:bit.
 
-## Manual transfer
+#### Manual transfer
 
 Your `.hex` file (created in Step 3 above) appears as a download at the bottom of the browser.
 Click on the arrow next to the name of the file and then click **Show in folder**.
@@ -74,7 +64,7 @@ Alternatively, right-click on the hex file, choose **Send to**, and then **MICRO
 
 ![](/static/mb/device/usb-windows-sendto.jpg)
 
-## Step 5: After transferring the file
+### Step 5: After transferring the file
 
 * The LED on the back of your micro:bit flashes during the transfer (which 
     should only take a few seconds).

package/docs/device/usb/windows-edge.md

@@ -1,26 +1,24 @@
-# Uploading from Microsoft Edge on Windows
+# Transferring from Microsoft Edge on Windows
 
-How to compile, transfer, and run a program on your micro:bit on **Microsoft Edge**.
+How to compile, transfer, and run a program on your micro:bit with **Microsoft Edge**.
 
 While you're writing and testing your programs, you'll mostly be [running them
 in the simulator](/device/simulator), but once you've finished your program you
 can **compile** it and run it on your micro:bit.
 
-The basic steps are:
+## Transfer using a WebUSB connection
 
-1. Connect your @boardname@ to your computer via USB
-2. Click **Download** to download the `.hex` file
-3. Click the **Save As** button in the bottom bar and save the `.hex` file into the MICROBIT drive
+With Microsoft Edge (version 79 and newer), you can transfer your program to the @boardname@ with a single click. If your browser supports WebUSB, you can use the **one-click download** feature to send your programs to the @boardname@. See the [WebUSB](/device/usb/webusb) page to learn how to pair your @boardname@ with a computer and transfer your programs with a single click.
 
-## Requirements
+## Downloading your program as file
 
-You need the following things to transfer and run a script on your micro:bit:
+The basic steps are:
 
-* A-Male to Micro USB cable to connect your computer to your micro:bit. This is
-    the same cable that is commonly used to connect a smart phone to a computer.
-* A PC running Windows 7 or later.
+1. Connect your @boardname@ to your computer with a USB cable (use an A-Male to Micro USB cable)
+2. Click **Download** to download the `.hex` file
+3. Click the **Save As** button in the bottom bar and save the `.hex` file into the MICROBIT drive
 
-## Step 1: Connect your micro:bit to your computer
+### Step 1: Connect your micro:bit to your computer
 
 First, connect the micro:bit:
 
@@ -34,7 +32,7 @@ it appears as a new drive under Devices.
 
 ![](/static/mb/device/usb-windows-device.jpg)
 
-## Step 2: Download your program
+### Step 2: Download your program
 
 1. Open your project on @homeurl@
 2. Click **Download**

package/docs/device/usb.md

@@ -1,10 +1,16 @@
-# Uploading programs to your @boardname@
+# Transferring programs to your @boardname@
 
-Most of the time you'll be writing and testing your programs in the [simulator](/device/simulator). Once you've finished your program though, you can **compile** it and run it on your @boardname@. Transferring your program to the @boardname@ is as simple as saving a file to a drive on your computer.
+Most of the time you'll be writing and testing your programs in the [simulator](/device/simulator). Once you've finished your program though, you can **compile** it and run it on your @boardname@. Transferring your program to the @boardname@ is as simple as clicking the **Download** button, or by saving a file to a drive on your computer.
 
-When you plug your @boardname@ into USB, a new drive is created with the **@drivename@** label. This is where you'll save your program.
+![micro:bit connected using USB](/static/mb/device/usb-thin.jpg)
 
-![](/static/mb/device/usb-thin.jpg)
+## Transfer using a WebUSB connection
+
+With some newer browsers, you can transfer your program to the @boardname@ with a single click. If your browser supports WebUSB, you can use the **one-click download** feature to send your programs to the @boardname@. See the [WebUSB](/device/usb/webusb) page to learn how to pair your @boardname@ with a computer and transfer your programs with a single click.
+
+## Downloading your program as file
+
+If your browser doesn't support WebUSB or you want to use your computer's file system to transfer your program instead, you can download it to the @boardname@ as a file. When you plug your @boardname@ into USB, a new drive is created with the **@drivename@** label. This is where you'll save your program.
 
 The basic steps are:
 

package/docs/device.md

@@ -1,16 +1,24 @@
 # Device
 
+### ~ hint
 
-## ~ hint
+#### Looking to buy a micro:bit?
 
-**Looking to buy a micro:bit?** See the [list of resellers](https://microbit.org/resellers).
+See the [list of resellers](https://microbit.org/resellers).
 
-## ~
+### ~
 
 All the bits and pieces that make up the BBC micro:bit
 
-![micro:bit board layout](/static/mb/device-0.png)
+![micro:bit board layout](/static/mb/device-v2.jpg)
 
+### ~ hint
+
+#### The current version of micro:bit is v2
+
+The version of @boardname@ is now currently at **v2**. See the what's new in MakeCode for programming the [@boardname@ v2](/device/v2).
+
+### ~
 
 ## LED Screen and Status LED
 
@@ -27,17 +35,21 @@ https://www.youtube.com/watch?v=qqBmvHD5bCw
 
 ## Buttons
 
-Buttons A and B are a form of input.  When you press a button, it completes an electrical circuit. 
+Buttons **A** and **B** are a form of input.  When you press a button, it completes an electrical circuit. 
 The micro:bit can detect either of its two buttons being pressed/released and be programmed 
 to act on these events.
 
-Button R on the back of the micro:bit is a system button. It has different uses. 
-When you have downloaded and run your code onto your micro:bit, press Button R to restart and run your program from the beginning.
+Button **R** on the back of the micro:bit is a system button. It has different uses. 
+When you have downloaded and run your code onto your micro:bit, press Button **R** to restart and run your program from the beginning.
 
 Find out how buttons provide input to the @boardname@ in this video:
 
 https://www.youtube.com/watch?v=t_Qujjd_38o
 
+## Touch
+
+Pins **0**, **1**, **2**, and the board **logo** can work as touch buttons when they are programmed for input.
+
 ## USB connection
 
 When you plug in your micro:bit via [USB](/device/usb), it should appear as  a ``MICROBIT`` drive. 
@@ -47,9 +59,9 @@ the micro:bit will appear as a ``MAINTENANCE`` drive instead of ``MICROBIT``. Th
 
 To continue programming your micro:bit YOU MUST unplug your USB and reconnect it. Check that the drive now shows as ``MICROBIT``.
 
-## ~ hint
+### ~ hint
 
-### Open the version file
+#### Open the version file
 
 Use with caution!
 If you click on the drive while it shows the ``MAINTENANCE`` label, 
@@ -57,7 +69,7 @@ you can see which version of firmware you have running on your micro:bit.
 Firmware on your micro:bit should be up-to-date already. 
 You can find the version of firmware in the 'version.txt' file on the micro:bit. See the @boardname@ **[firmware](https://microbit.org/guide/firmware/)** page for more about checking your board's firmware version.
 
-## ~
+### ~
 
 ## Compass
 
@@ -79,7 +91,11 @@ https://www.youtube.com/watch?v=byngcwjO51U
 ## Pins
 
 The [pins](/device/pins) can be a form of electrical input or output. 
-There are labels for the input/output pins ``P0``, ``P1``, ``P2``, which you can attach external sensors to such as thermometers or moisture detectors.
+There are labels for the input/output pins **0**, **1**, **2**, which you can attach external sensors to such as thermometers or moisture detectors.
+
+## Microphone
+
+Using the microphone, your programs can detect sounds that are present. You can check for loud or quiet sounds and find out what their sound level is.
 
 ## Light level
 
@@ -119,7 +135,7 @@ and [click here to read more about the error messages you might get](/device/err
 When your micro:bit is connected to your computer with the micro USB, it doesn’t need another power source.  
 When your micro:bit isn’t connected to your computer, tablet or mobile, you will need 2 x AAA 1.5 V batteries to power it.
 
-The pins labelled 3V and GND are the power supply pins. 
+The pins labelled **3V** and **GND** are the power supply pins. 
 You can attach an external device such as a motor to these and power it using the battery or USB.
 
 ## Serial Communication

package/docs/docs.md

@@ -21,7 +21,7 @@
 
 ## More questions?
 
-* [Frequently Asked Question](/faq)
+* [Frequently Asked Questions](/faq)
 * [Help Translate](/translate)
 * [Embedding project](/share)