0.2.128

README.md

@@ -7,21 +7,39 @@ This target allow to program a [BBC micro:bit](https://www.microbit.co.uk/) usin
 
 [![Build Status](https://travis-ci.org/Microsoft/pxt-microbit.svg?branch=master)](https://travis-ci.org/Microsoft/pxt-microbit)
 
-# Getting started
+## Local server
 
-Please follow instructions at https://github.com/Microsoft/pxt#running-a-target-from-localhost 
+### Setup
+
+The following commands are a 1-time setup after synching the repo on your machine.
+
+* install the PXT command line
+```
+npm install -g pxt
+```
+* install the dependencies
+```
+npm install
+```
+
+### Running
+
+Run this command to open a local web server:
+```
+pxt serve
+```
+To make sure you're running the latest tools, run
+```
+npm update
+```
+
+More instructions at https://github.com/Microsoft/pxt#running-a-target-from-localhost 
 
 ## Universal Windows App
 
 The Windows 10 app is a [Universal Windows Hosted Web App](https://microsoftedge.github.io/WebAppsDocs/en-US/win10/CreateHWA.htm)
 that wraps m.pxt.io and provides additional features.
 
-### Sideloading
-
-* Open Windows **settings** and search for **Developer options**
-* Enable the developer mode.
-* Find the latest build under ``win10/app/AppPackages/latest`` and run the ``Add-AppDevPackage.ps1`` PowerShell script (mouse right-click, then `run with PowerShell`)
-
 ### Building
 
 * Install Visual Studio 2015 Update 2 or higher. Make sure the Windows 10 templates are installed.

cmds/cmds.ts

@@ -1,8 +1,8 @@
 /// <reference path="../node_modules/pxt-core/built/pxt.d.ts"/>
 
-import * as fs from 'fs';
-import * as path from 'path';
-import * as child_process from 'child_process';
+import * as fs from "fs";
+import * as path from "path";
+import * as child_process from "child_process";
 
 let writeFileAsync: any = Promise.promisify(fs.writeFile)
 let execAsync: (cmd: string, options?: { cwd?: string }) => Promise<Buffer> = Promise.promisify(child_process.exec)
@@ -13,10 +13,10 @@ export function deployCoreAsync(res: ts.pxt.CompileResult) {
             if (drives.length == 0) {
                 console.log("cannot find any drives to deploy to")
             } else {
-                console.log("copy microbit.hex to " + drives.join(", "))
+                console.log(`copy ${ts.pxt.BINARY_HEX} to ` + drives.join(", "))
             }
             return Promise.map(drives, d =>
-                writeFileAsync(d + "microbit.hex", res.outfiles["microbit.hex"])
+                writeFileAsync(d + ts.pxt.BINARY_HEX, res.outfiles[ts.pxt.BINARY_HEX])
                     .then(() => {
                         console.log("wrote hex file to " + d)
                     }))

docs/about.md

@@ -26,7 +26,7 @@ input.onButtonPressed(Button.B, () => {
 The [BBC micro:bit](https://www.microbit.co.uk) is a [pocket-size computer](/device) with a 5x5 display of 25 LEDs, Bluetooth and sensors that can be programmed by anyone.
 The BBC micro:bit was made possible by many [partners](https://www.microbit.co.uk/partners).
 
-The micro:bit provides a fun introduction to programming and making – switch on, program it to do something fun – wear it, customize it.
+The micro:bit provides an easy and fun introduction to programming and making – switch on, program it to do something fun – wear it, customize it.
 Just like Arduino, the micro:bit can be connected to and interact with sensors, displays, and other devices. 
 
 ## Blocks or JavaScript

docs/reference.md

@@ -9,8 +9,9 @@ basic.showNumber(0);
 input.onButtonPressed(Button.A, () => {
     
 });
-led.plot(0, 0);
 music.playTone(0, 0);
+led.plot(0, 0);
+radio.sendNumber(0);
 game.addScore(1);
 images.createImage(`
 . . . . .

docs/reference/basic/clear-screen.md

@@ -8,7 +8,7 @@ basic.clearScreen()
 
 ### Example: vanishing heart
 
-The following code displays a heart on the screen and then turns off all the LED lights using `clear screen`:
+The following code shows a heart on the screen and then turns off all the LED lights using `clear screen`:
 
 ```blocks
 basic.showLeds(`

docs/reference/basic/forever.md

@@ -1,6 +1,7 @@
 # Forever
 
-Repeat code [in the background](/reference/control/in-background) forever.
+Keep running part of a program 
+[in the background](/reference/control/in-background).
 
 ```sig
 basic.forever(() => {
@@ -9,7 +10,9 @@ basic.forever(() => {
 
 ### Example: compass
 
-The following example constantly checks the [compass heading](/reference/input/compass-heading) and updates the screen with the direction.
+The following example constantly checks the 
+[compass heading](/reference/input/compass-heading) 
+and updates the screen with the direction.
 
 ```blocks
 basic.forever(() => {
@@ -30,7 +33,9 @@ basic.forever(() => {
 
 ### Example: counter
 
-The following example continually shows the current value of a global variable:
+The following example keeps showing the [number](/reference/types/number) stored in a global variable.
+When you press button `A`, the number gets bigger.
+You can use a program like this to count things with your BBC micro:bit.
 
 ```blocks
 let num = 0
@@ -42,9 +47,12 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-### Contention for the LED display
+### Competing for the LED screen
 
-If you have multiple processes that each show something on the LED screen, you may get unexpected results. Try, for example:
+If different parts of a program are each trying 
+to show something on the LED screen at the same time, 
+you may get unexpected results.
+Try this on your micro:bit:
 
 ```blocks
 basic.forever(() => {

docs/reference/basic/pause.md

@@ -1,6 +1,7 @@
 # Pause
 
-Pause program execution for the specified number of milliseconds. This function is helpful when you need to slow down your program's execution.
+Pause the program for the number of milliseconds you say. 
+You can use this function to slow your program down.
 
 ```sig
 basic.pause(400)
@@ -8,11 +9,13 @@ basic.pause(400)
 
 ### Parameters
 
-* ``ms`` - the number of milliseconds that you want to pause (100 = 1/10 second, 1000 milliseconds = 1 second)
+* ``ms`` is the number of milliseconds that you want to pause (100 milliseconds = 1/10 second, and 1000 milliseconds = 1 second).
 
 ### Example: diagonal line
 
-The following example code turns on LED `0, 0` thru `4, 4`, pausing 500 milliseconds after each LED. Without `pause`, the code would run so fast that you wouldn't see each individual LED turning on.
+This example draws a diagonal line by turning on LED `0, 0` (top left) through LED `4, 4` (bottom right). 
+The program pauses 500 milliseconds after turning on each LED. 
+Without `pause`, the program would run so fast that you would not have time to see each LED turning on.
 
 ```blocks
 for (let i = 0; i < 5; i++) {

docs/reference/basic/show-animation.md

@@ -1,6 +1,6 @@
 # Show Animation
 
-Show a series of image frames on the [LED screen](/device/screen), pausing the specified time after each frame.
+Show a group of image frames (pictures) one after another on the [LED screen](/device/screen). It pauses the amount of time you tell it after each frame.
 
 ```sig
 basic.showAnimation(`
@@ -14,10 +14,14 @@ basic.showAnimation(`
 
 ### Parameters
 
-* `leds` - [String](/reference/types/string); a series of LED on/off states
-* `interval` - [Number](/reference/types/number); the number of milliseconds to pause after each image frame
+* `leds` is a [String](/reference/types/string) that shows which LEDs are on and off, in groups one after another.
+* `interval` is an optional [Number](/reference/types/number). It means the number of milliseconds to pause after each image frame.
 
-### Show a series of image frames
+### Example: Animating a group of image frames
+
+In this animation, each row is 15 spaces wide because
+there are three frames in the animation, and each frame is
+five spaces wide, just like the screen on the BBC micro:bit.
 
 ```
 basic.showAnimation(`
@@ -31,13 +35,17 @@ basic.showAnimation(`
 
 ### ~hint 
 
-If the series of images appear too fast, increase the value of the *interval* parameter.
+If the animation is too fast, make `interval` bigger.
 
 ### ~
 
-### Example: animating frames
+### Example: animating frames with a pause
 
-The following example creates an image with six frames and then shows each frame o the screen, pausing 500 milliseconds after each frame:
+This example shows six frames on the screen, pausing 500 milliseconds after each frame.
+
+In this animation, each row is 30 spaces wide because
+there are six frames in the animation, and each frame is
+five spaces wide, just like the screen.
 
 ```
 basic.showAnimation(`
@@ -51,7 +59,7 @@ basic.showAnimation(`
 
 ### ~hint 
 
-Use [forever](/reference/basic/forever) to continually repeat an animation
+Use [forever](/reference/basic/forever) to show an animation over and over.
 
 ### ~
 

docs/reference/basic/show-leds.md

@@ -15,12 +15,13 @@ basic.showLeds(`
 
 ### Parameters
 
-* ``leds`` - a series of LED on/off states that form an image (see steps below)
-* (optional) ``ms`` - [Number](/reference/types/number) - time to wait after displaying image. In blocks, ``ms`` is 400 by default.
+* `leds` is a [String](/reference/types/string) that shows which LEDs are on and off.
+* `ms` is an optional [Number](/reference/types/number) that shows how many milliseconds to wait after showing a picture.
+If you are programming with blocks, `ms` starts out as 400 milliseconds.
 
-### Example - Block Editor
+### Example
 
-1. Open the `basic` category and select the `show leds` blocks.
+Open the `basic` card in the Block Editor and select the `show leds` blocks.
 
 ```blocks
 basic.showLeds(`
@@ -33,7 +34,7 @@ basic.showLeds(`
 )
 ```
 
-In JavaScript, the led off is represented by a `.` and the led on by a `#` character.
+If you are programming in JavaScript, `#` means an LED that is turned on and `.` means an LED that is turned off.
 
 ### Lessons
 

docs/reference/basic/show-number.md

@@ -1,6 +1,6 @@
 # Show Number
 
-Show a number on the [LED screen](/device/screen), one digit at a time (scrolling from left to right)
+Show a number on the [LED screen](/device/screen). It will slide left if it has more than one digit.
 
 ~~~~sig
 basic.showNumber(2, 150)
@@ -8,18 +8,18 @@ basic.showNumber(2, 150)
 
 ### Parameters
 
-* value - a [Number](/reference/types/number)
-* (optional) interval (ms) - [Number](/reference/types/number); the time (in milliseconds) before scrolling by one LED; the larger the number, the slower the scroll
+* `value` is a [Number](/reference/types/number).
+* `interval` is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the `value` left by one LED each time. Bigger intervals make the sliding slower.
 
-### ~
+### Examples:
 
-To display the number 10:
+To show the number 10:
 
 ~~~~blocks
 basic.showNumber(10)
 ~~~~
 
-To display the number stored in the `x` variable:
+To show the number stored in a variable:
 
 ~~~~blocks
 let x = 1
@@ -28,19 +28,19 @@ basic.showNumber(x)
 
 ### Example: count to 5
 
-This example uses a [for](/reference/loops/for) loop to show numbers ``1`` through ``5`` on the screen:
+This example uses a [for](/reference/loops/for) loop to show numbers ``0`` through ``5`` on the screen:
 
 ~~~~blocks
-for (let i = 0; i < 5; i++) {
-    basic.showNumber(i + 1)
+for (let i = 0; i < 6; i++) {
+    basic.showNumber(i)
     basic.pause(200)
 }
 ~~~~
 
 ### Other show functions
 
-* use [show string](/reference/basic/show-string) to show a string on the screen
-* use [show animation](/reference/basic/show-animation) to show a series of images on the screen
+* Use [show string](/reference/basic/show-string) to show a [String](/reference/types/string) with letters on the screen.
+* Use [show animation](/reference/basic/show-animation) to show a group of pictures on the screen, one after another.
 
 ### Lessons
 

docs/reference/basic/show-string.md

@@ -1,6 +1,6 @@
 # Show String
 
-Show a string on the [LED screen](/device/screen) one character at a time (scrolling from left to right).
+Show a number on the [LED screen](/device/screen). It will slide left if it is bigger than the screen.
 
 ```sig
 basic.showString("Hello!")
@@ -8,18 +8,18 @@ basic.showString("Hello!")
 
 ### Parameters
 
-* `text` - a [String](/reference/types/string)
-* (optional) `ms` - [Number](/reference/types/number); the time (in milliseconds) before scrolling left by one LED; the larger the number, the slower the scroll
+* `text` is a [String](/reference/types/string). It can contain letters, numbers, and punctuation.
+* `ms` is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the [String](/reference/types/string) left by one LED each time. Bigger intervals make the sliding slower.
 
 ### Examples:
 
-To display Hello:
+To show the word **Hello**:
 
 ```blocks
 basic.showString("Hello")
 ```
 
-To display the content of a string variable:
+To show what is stored in a [String](/reference/types/string) variable:
 
 ```blocks
 let s = "Hi"
@@ -28,8 +28,8 @@ basic.showString(s)
 
 ### Other show functions
 
-* use [show number](/reference/basic/show-number) to show a number on the screen
-* use [show animation](/reference/basic/show-animation) to show a series of images on the screen
+* Use [show number](/reference/basic/show-number) to show a number on the [LED screen](/device/screen).
+* Use [show animation](/reference/basic/show-animation) to show a group of pictures on the screen, one after another.
 
 ### Lessons
 

docs/reference/input/button-is-pressed.md

@@ -1,6 +1,6 @@
 # Button Is Pressed
 
-Get the state of an input button. The micro:bit has two input buttons: A and B.
+Check whether a button is pressed right now. The micro:bit has two buttons: button `A` and button `B`.
 
 ```sig
 input.buttonIsPressed(Button.A);
@@ -8,24 +8,26 @@ input.buttonIsPressed(Button.A);
 
 ### Parameters
 
-* name - [String](/reference/types/string); input button "A", "B", or "A+B" (both input buttons)
+* ``name`` is a [String](/reference/types/string). You should store `A` in it to check the left button, `B` to check the right button, or `A+B` to check both at the same time.
 
 ### Returns
 
-* [Boolean](/reference/types/boolean) - `true` if pressed, `false` if not pressed
+* [Boolean](/reference/types/boolean) that is `true` if the button you are checking is pressed, `false` if it is not pressed.
 
 ### Example
 
-The following code uses an [if](/reference/logic/if) statement to run code, depending on whether or not the A button is pressed:
+This program uses an [if](/reference/logic/if) to run 
+one part of the program if the `A` button is pressed, and 
+another part if it is not pressed.
 
 ```blocks
 basic.forever(() => {
     let pressed = input.buttonIsPressed(Button.A)
     if (pressed) {
-        // this code runs if the A button is pressed
+        // this part runs if the A button is pressed
         basic.showNumber(1, 150)
     } else {
-        // this code runs if the A button is *not* pressed
+        // this part runs if the A button is *not* pressed
         basic.showNumber(0, 150)
     }
 })

docs/reference/input/light-level.md

@@ -1,8 +1,14 @@
 # Light Level
 
-Gets the light level from ``0`` (dark) to ``255`` (bright). The light is measured by using various LEDs from the screen.
+Find the light level (how bright or dark it is) where you are.
+The light level ``0`` means darkness and ``255`` means bright light. 
+The BBC micro:bit measures the light around it by using some of the
+LEDs on the [LED screen](/device/screen).
 
-This function will return ``0`` on the first call to this method, a light reading will be available after the display has activated the light sensor for the first time.
+The first time you use it, this function will say ``0``.
+After that, it will say the real light level.
+This is because the light sensor (the part that can find the light level)
+has to be turned on first.
 
 ```sig
 input.lightLevel();
@@ -10,11 +16,26 @@ input.lightLevel();
 
 ### Returns
 
-* [Number](/reference/types/number) -  light level from ``0`` (dark) to ``255`` (bright).
+* a [Number](/reference/types/number) that means a light level from ``0`` (dark) to ``255`` (bright).
+
+### Example: show light level
+
+When you press button `B` on the microbit, this
+program shows the light level
+on the [LED screen](/device/screen).
+
+```blocks
+input.onButtonPressed(Button.B, () => {
+    let level = input.lightLevel()
+    basic.showNumber(level)
+})
+```
 
 ### Example: chart light level
 
-Use `plot bar chart` to visual the influence of various light source on the light level.
+This program shows the light level with a [bar chart](/reference/led/plot-bar-graph) on the micro:bit screen.
+If you carry the micro:bit around to different places with different light levels,
+the bar chart will change.
 
 ```blocks
 basic.forever(() => {

docs/reference/input/on-button-pressed.md

@@ -1,6 +1,9 @@
 # On Button Pressed
 
-Register an [event handler](/reference/event-handler) that will execute whenever an input button (A, B, or A and B together) is pressed during program execution. When [running code](/device/simulator) with this function in a web browser, click an on-screen input button - labelled A or B.
+Start an [event handler](/reference/event-handler) (part of the program that will run when something happens, like when a button is pressed). 
+This handler works when button `A` or `B` is pressed, or `A` and `B` together.
+When you are using this function in a web browser, click the buttons on the screen instead of the ones
+on the BBC micro:bit.
 
 ```sig
 input.onButtonPressed(Button.A, () => {})
@@ -8,7 +11,8 @@ input.onButtonPressed(Button.A, () => {})
 
 ### Example: count button clicks
 
-This example counts how many times the left or right input button is pressed. Each time a button is pressed, the global count variable is increased by 1 and displayed on the screen.
+This example counts how many times you press the `A` button. 
+Each time you press the button, the [LED screen](/device/screen) shows the `count` variable getting bigger.
 
 ```blocks
 let count = 0
@@ -19,22 +23,29 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-### Example: roll a dice
+### Example: roll dice
 
-This example generates a random number when you press the B input button, and then displays a random die image:
+This example shows a number from 1 to 6 when you press the `B` button.
 
 ```blocks
 input.onButtonPressed(Button.B, () => {
-    let dice = Math.random(6)
+    let dice = Math.random(6) + 1
     basic.showNumber(dice)
 })
 ```
 
+### ~hint
+
+This program adds a `1` to `random(6)` so the numbers on the dice will come out right.
+Otherwise, sometimes they would show a `0`.
+
+### ~
+
 ### Lessons
 
 [smiley](/lessons/smiley), [answering machine](/lessons/answering-machine), [screen wipe](/lessons/screen-wipe), [rotation animation](/lessons/rotation-animation)
 
 ### See also
 
-[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever)
+[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/reference/math/math)
 

docs/reference/input/running-time.md

@@ -1,6 +1,6 @@
 # Running Time
 
-Get the number of milliseconds elapsed since the script began. 1,000 milliseconds = 1 second.
+Find how long it has been since the program started.
 
 ```sig
 input.runningTime();
@@ -8,15 +8,20 @@ input.runningTime();
 
 ### Returns
 
-* [Number](/reference/types/number)
+* the [Number](/reference/types/number) of milliseconds since the program started.
+(One second is 1000 milliseconds.)
 
 ### Example: elapsed time
 
-This code gets the elapsed time since the start of the program execution and displays it on the screen.
+When you press button `B` on the microbit, this
+program finds the number of milliseconds since the program started
+and shows it on the [LED screen](/device/screen).
 
 ```blocks
-let now = input.runningTime()
-basic.showNumber(now)
+input.onButtonPressed(Button.B, () => {
+    let now = input.runningTime()
+    basic.showNumber(now)
+})
 ```
 
 ### Lessons

docs/reference/led/brightness.md

@@ -1,6 +1,6 @@
 # Brightness
 
-Set the brightness of the [LED screen](/device/screen).
+Find how bright the [LED screen](/device/screen) is.
 
 ```sig
 led.brightness();
@@ -8,11 +8,11 @@ led.brightness();
 
 ### Returns
 
-* [Number](/reference/types/number) - returns the LCD screen brightness as a number from 0 to 255. A return value of 255 means the screen brightness is at 100% and 127 is about 50% brightness.
+* a [Number](/reference/types/number) that means how bright the screen is, from `0` (darkest) to `255` (brightest). For example, the number `127` means the screen is halfway bright.
 
-### Example: maximum brightness
+### Example: highest brightness
 
-If the screen brightness is < 100%, the following code sets the brightness to 100% (255):
+This program makes the screen completely bright if it is not that way already:
 
 ```blocks
 if (led.brightness() < 255) {

docs/reference/led/plot-bar-graph.md

@@ -1,6 +1,7 @@
 # Plot Bar Graph
 
-Displays a vertical bar graph based on the value and high value.
+Displays a bar graph of the numbers you say.
+A bar graph is a kind of chart that shows numbers as lines with different lengths.
 
 ```sig
 led.plotBarGraph(2, 20);
@@ -8,10 +9,18 @@ led.plotBarGraph(2, 20);
 
 ### Parameters
 
-* value: [Number](/reference/types/number) , high : [Number](/reference/types/number) displays a vertical bar graph based on the value and high value
+* `value` is a [Number](/reference/types/number) that means what you are measuring or trying to show. For example, if you are measuring the temperature of ice with the BBC micro:bit, `value` might be 0 because the temperature might be 0 degrees centigrade.
+* `high` is a [Number](/reference/types/number) that means the highest possible number that the `value` parameter can be. This number is also the tallest that the lines in the bar chart can be.
 
 ### Example: chart acceleration
 
+This program shows a bar graph of the [acceleration](/reference/input/acceleration) 
+in the `x` direction of the micro:bit.
+The micro:bit's `x` direction is from left to right (or right to left).
+The more you speed up moving the micro:bit in this direction,
+the taller the lines in the bar graph will be, 
+until they are as tall as the parameter `high` says they can be.
+
 ```blocks
 basic.forever(() => {
     let a = input.acceleration(Dimension.X);

docs/reference/logic.md

@@ -1,39 +1,9 @@
 # Logic
 
-[if](/reference/logic/if)
-
-```blocks
-if(true) {
-}
-```
-
-[Boolean](/reference/types/boolean) values: *true*; *false*
-
-```blocks
-true
-false
-```
-
-Boolean binary operators: *and* (conjunction); *or* (disjunction)
-
-```blocks
+```cards
+if(true) {}
+true;
 true && false;
-true || false;
-```
-
-Boolean negation operator
-
-```blocks
-!true
-```
-
-Comparison operators (=, !=, <, >, <=, >=)
-
-```blocks
-0 == 0;
-1 !- 0;
-0 < 1;
-1 > 0;
-0 <= 1;
-1 >= 0;
+!true;
+1 != 0;
 ```

docs/reference/logic/if.md

@@ -1,23 +1,26 @@
 # If
 
-Run code based on a condition.
-
 ### @parent blocks/language
  
 
 Conditionally run code depending on whether a [Boolean](/reference/types/boolean) condition is true or false.
 
-### Block Editor
-
-![](/static/mb/hourofcode-0.png)
+```blocks
+if(true) {
+}
+```
 
 In the Block Editor, click on the dark blue gear icon (see above) to add an *else* or *if* to the current block.
 
 ### Example: adjusting screen brightness
 
-![](/static/mb/blocks/game-library/pic0.png)
+```blocks
+if(input.lightLevel()<100){
+    led.setBrightness(255);
+}
+```
 
-If the screen [brightness](/reference/led/brightness) is `< 100`, this code sets the brightness to `255`:
+If the [light level](/input/light-level) is `< 100`, this code sets the brightness to `255`:
 
 ### Lessons
 

docs/reference/loops.md

@@ -1,26 +1,8 @@
 # Loops
 
-Repeat code.
-
-
-[for](/reference/loops/for)
-
-```blocks
+```cards
 for(let i = 0;i<5;i++) {}
-```
-
-[repeat](/reference/loops/repeat)
-
-![](/static/mb/blocks/contents-0.png)
-
-[while](/reference/loops/while)
-
-```blocks
+for(let i = 1;i<5;i++) {}
 while(true) {}
-```
-
-[forever](/reference/basic/forever)
-
-```blocks
 basic.forever(() => {})
 ```

docs/reference/loops/for.md

@@ -1,20 +1,16 @@
 # For
 
-Repeat code a preset number of times.
-
 ### @parent blocks/language
  
+Run part of the program the number of times you say.
 
-Repeat code a fixed number of times.
+### Example: Count to 4
 
-### Block Editor
+This program will show the numbers 0, 1, 2, 3, and 4 one after another on the LED screen.
 
-![](/static/mb/events-0.png)
-
-The Block Editor *for* loop is different than the Touch Develop *for* loop in an important way. The above for loop will iterate *five* times, with the loop variable *i* taking on values 0, 1, 2, 3, and 4. The Touch Develop for loop shown below will iterate four times:
-
-```
-for (let k = 0; k < 4; k++) {
+```blocks
+for(let i = 0; i < 5; ++i) {
+basic.showNumber(i)
 }
 ```
 
@@ -24,5 +20,5 @@ for (let k = 0; k < 4; k++) {
 
 ### See also
 
-[while](/reference/loops/while), [if](/reference/logic/if)
+[repeat](/reference/loops/repeat), [while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)
 

docs/reference/loops/repeat.md

@@ -1,21 +1,16 @@
 # Repeat
 
-Repeat code a preset number of times.
-
-Repeat code a fixed number of times.
+Run part of the program the number of times you say.
 
 ### Block Editor
 
 ![](/static/mb/blocks/contents-0.png)
 
-### Touch Develop
+### Lessons
 
-Touch Develop has no `repeat` loop. Instead you can used a for loop
+[looper](/lessons/looper)
 
-```
-for (let i = 0; i < 5; i++) {
-}
-```
+### See also
 
-The loop above will repeat five (5) times.
+[for](/reference/loops/for), [while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)
 

docs/reference/loops/while.md

@@ -1,23 +1,14 @@
 # While
 
-Repeat code in a loop while a condition is true.
-
 ### @parent blocks/language
  
 
 Repeat code while a [Boolean](/reference/types/boolean) `condition` is true.
 
-### ~hide
-
+```blocks
+while(true) {
+}
 ```
-let condition = false
-```
-
-### ~
-
-### Block Editor
-
-![](/static/mb/string-0.png)
 
 The while loop has a *condition* that evaluates to a [Boolean](/reference/types/boolean) value. After the `do` keyword, add the code that you want to run while the `condition` is `true`. The while loop concludes with `end while`.
 
@@ -27,11 +18,13 @@ The condition is tested before any code runs. Which means that if the condition
 
 The following example uses a while loop to make a diagonal line on the LED screen (points `0, 0`, `1, 1`, `2, 2`, `3, 3`, `4, 4`).
 
-// index is set to 4
-
-![](/static/mb/blocks/var-10.png)
-
-// subtract 1 from `index` each time through loop
+```blocks
+let index = 4;
+while(index >= 0) {
+    led.plot(index, index);
+    index--;
+}
+```
 
 ### Lessons
 

docs/reference/music/play-tone.md

@@ -1,10 +1,10 @@
 # Play Tone
 
-Plays a music tone through pin ``P0`` for the given duration.
+Play a musical tone through pin ``P0`` of the micro:bit for as long as you say.
 
 ## Simulator
 
-Simulation of this function is available in many, but not all browsers.
+This function only works on the micro:bit and in some browsers.
 
 ```sig
 music.playTone(440, 120)
@@ -12,11 +12,14 @@ music.playTone(440, 120)
 
 ### Parameters
 
-* `frequency` : [Number](/reference/types/number) - the frequency of the note (in Herz)
-* `ms`: [Number](/reference/types/number) - the duration of the note (milliseconds)
+* `Hz` is the [Number](/reference/types/number) of Hertz (the frequency, how high or low the tone is).
+* `ms` is the [Number](/reference/types/number) of milliseconds that the tone lasts.
 
 ## Example
 
+This example stores the musical note C in the variable `freq`.
+Next, it plays that note for 1000 milliseconds (one second).
+
 ```blocks
 let freq = music.noteFrequency(Note.C)
 music.playTone(freq, 1000)

docs/reference/music/tempo.md

@@ -1,16 +1,16 @@
 # Tempo
 
-Returns the tempo in beats per minute.
+Finds the tempo (speed of a piece of music).
 
 ```sig
 music.tempo()
 ```
 
-### Parameters
+### Returns
 
-* Returns : [Number](/reference/types/number) - returns the tempo in beats per minute
+* a [Number](/reference/types/number) that means the bpm (beats per minute, or number of beats in a minute of the music that the micro:bit is playing).
 
 ### See also
 
-[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone) , [rest](/reference/music/rest), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
+[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone), [rest](/reference/music/rest), [set tempo](/reference/music/set-tempo), [change tempo by](/reference/music/change-tempo-by)
 

docs/reference/radio.md

@@ -16,5 +16,5 @@ radio.receivedSignalStrength();
 radio.setGroup(0);
 radio.setTransmitPower(0);
 radio.writeValueToSerial();
-radio.setTransmitSerialNumber(◊);
+radio.setTransmitSerialNumber(true);
 ```

docs/reference/serial.md

@@ -3,6 +3,9 @@
 Reading and writing data over a serial connection.
 
 ```cards
-serial.writeValue(x, 0);
 serial.writeLine("");
+serial.writeNumber(0);
+serial.writeValue(x, 0);
+serial.writeString("");
+serial.readLine();
 ```

docs/reference/toc.md

@@ -0,0 +1,197 @@
+acceleration
+
+analog-pitch
+
+analog-read-pin
+
+analog-set-period
+
+analog-set-pitch-pin
+
+analog-write-pin
+
+assign
+
+boolean
+
+brightness
+
+button-is-pressed
+
+change
+
+change-score-by
+
+change-tempo
+
+change-var
+
+clear
+
+clear-screen
+
+compass-heading
+
+create-image
+
+digital-read-pin
+
+digital-write-pin
+
+fade-in
+
+fade-out
+
+for
+
+forever
+
+game-library
+
+game-over
+
+if
+
+image
+
+in-background
+
+light-level
+
+magnetic-force
+
+map
+
+math
+
+move
+
+number
+
+[on button pressed](/reference/input/on-button-pressed)
+
+on-data-received
+
+on-gamepad-button
+
+on-gesture
+
+on-pin-pressed
+
+on-signal-strength-changed
+
+pause
+
+pin-is-pressed
+
+pixel
+
+play-tone
+
+plot
+
+plot-all
+
+plot-bar-graph
+
+plot-frame
+
+plot-image
+
+plot-leds
+
+point
+
+position
+
+raise-alert-to
+
+receive-number
+
+receive-number
+
+repeat
+
+reports
+
+reset
+
+rest
+
+ring-tone
+
+rotation
+
+running-time
+
+score
+
+screenshot
+
+scroll-image
+
+send-number
+
+servo-set-pulse
+
+servo-write-pin
+
+set-brightness
+
+set-display-mode
+
+set-group
+
+set-pixel
+
+set-tempo
+
+show-animation
+
+show-frame
+
+show-image
+
+show-leds
+
+show-number
+
+show-string
+
+signal-strength
+
+start-countdown
+
+stop-animation
+
+string
+
+tell-camera-to
+
+tell-microphone-to
+
+tell-remote-control-to
+
+temperature
+
+tempo
+
+toggle
+
+toggle-all
+
+touching
+
+turn
+
+unplot
+
+var
+
+while
+
+width
+
+write-line
+
+write-value

libs/microbit-radio/_locales/microbit-radio-strings.json

@@ -93,6 +93,9 @@
   "radio.setTransmitSerialNumber": "Set the radio to transmit the serial number in each message.",
   "radio.writeValueToSerial": "Reads a value sent with `stream value` and writes it\nto the serial stream as JSON",
   "serial": "Reading and writing data over a serial connection.",
+  "serial.readLine": "Reads a line of text from the serial port.",
   "serial.writeLine": "Prints a line of text to the serial",
+  "serial.writeNumber": "Prints a numeric value to the serial",
+  "serial.writeString": "Sends a piece of text through Serial connection.",
   "serial.writeValue": "Writes a ``name: value`` pair line to the serial."
 }

libs/microbit-radio/radio.ts

@@ -1,6 +1,6 @@
 /**
  * Communicate data using radio packets
  */
-//% color=270 weight=34
+//% color=#E3008C weight=34
 namespace radio {
 }

libs/microbit/basic.cpp

@@ -4,7 +4,7 @@
 /**
  * Provides access to basic micro:bit functionality.
  */
-//% color=190 weight=100
+//% color=#0078D7 weight=100
 namespace basic {
 
     /**

libs/microbit/enums.d.ts

@@ -105,6 +105,16 @@ declare namespace basic {
      */
     //% block="free fall"
     FreeFall = 7,  // MICROBIT_ACCELEROMETER_EVT_FREEFALL
+    /**
+     * Raised when a 3G shock is detected
+     */
+    //% block="3g"
+    ThreeG = 8,  // MICROBIT_ACCELEROMETER_EVT_3G
+    /**
+     * Raised when a 6G shock is detected
+     */
+    //% block="6g"
+    SixG = 9,  // MICROBIT_ACCELEROMETER_EVT_6G
     }
 declare namespace input {
 }

libs/microbit/game.ts

@@ -21,19 +21,19 @@ enum LedSpriteProperty {
 /**
  * A single-LED sprite game engine
  */
-//% color=176 weight=32
+//% color=#008272 weight=32
 namespace game {
-    var _score: number = 0;
-    var _life: number = 3;
-    var _startTime: number = 0;
-    var _endTime: number = 0;
-    var _isGameOver: boolean = false;
-    var _countdownPause: number = 0;
-    var _level: number = 1;
-    var _gameId: number = 0;
-    var img: Image;
-    var sprites: LedSprite[];
-    
+    let _score: number = 0;
+    let _life: number = 3;
+    let _startTime: number = 0;
+    let _endTime: number = 0;
+    let _isGameOver: boolean = false;
+    let _countdownPause: number = 0;
+    let _level: number = 1;
+    let _gameId: number = 0;
+    let img: Image;
+    let sprites: LedSprite[];
+
     /**
      * Creates a new LED sprite pointing to the right.
      * @param x sprite horizontal coordinate, eg: 2
@@ -47,7 +47,7 @@ namespace game {
         sprites.push(p);
         plot();
         return p;
-    }    
+    }
 
     /**
      * Gets the current score
@@ -394,7 +394,7 @@ namespace game {
             }
             plot();
         }
-        
+
         /**
          * Turn the sprite
          * @param this TODO
@@ -403,7 +403,7 @@ namespace game {
          */
         //% weight=49
         //% blockId=game_turn_sprite block="%sprite|turn %direction|by (°) %degrees"
-        public turn(direction : Direction, degrees: number) {
+        public turn(direction: Direction, degrees: number) {
             if (direction == Direction.Right)
                 this.setDirection(this._dir + degrees);
             else
@@ -435,8 +435,8 @@ namespace game {
          */
         //% weight=29
         //% blockId=game_sprite_set_property block="%sprite|set %property|to %value" blockGap=8
-        public set(property : LedSpriteProperty, value:number) {
-            switch(property) {
+        public set(property: LedSpriteProperty, value: number) {
+            switch (property) {
                 case LedSpriteProperty.X: this.setX(value); break;
                 case LedSpriteProperty.Y: this.setY(value); break;
                 case LedSpriteProperty.Direction: this.setDirection(value); break;
@@ -452,8 +452,8 @@ namespace game {
          */
         //% weight=30
         //% blockId=game_sprite_change_xy block="%sprite|change %property|by %value" blockGap=8
-        public change(property : LedSpriteProperty, value:number) {
-            switch(property) {
+        public change(property: LedSpriteProperty, value: number) {
+            switch (property) {
                 case LedSpriteProperty.X: this.changeXBy(value); break;
                 case LedSpriteProperty.Y: this.changeYBy(value); break;
                 case LedSpriteProperty.Direction: this.changeDirectionBy(value); break;
@@ -461,15 +461,15 @@ namespace game {
                 case LedSpriteProperty.Blink: this.changeBlinkBy(value); break;
             }
         }
-                
+
         /**
          * Gets a property of the sprite
          * @param property the name of the property to change
          */
         //% weight=28
         //% blockId=game_sprite_property block="%sprite|%property"
-        public get(property : LedSpriteProperty) {
-            switch(property) {
+        public get(property: LedSpriteProperty) {
+            switch (property) {
                 case LedSpriteProperty.X: return this.x();
                 case LedSpriteProperty.Y: return this.y();
                 case LedSpriteProperty.Direction: return this.direction()
@@ -681,7 +681,7 @@ namespace game {
     function init(): void {
         if (img == null) {
             img = images.createImage(
-`0 0 0 0 0
+                `0 0 0 0 0
 0 0 0 0 0
 0 0 0 0 0
 0 0 0 0 0

libs/microbit/images.cpp

@@ -3,7 +3,7 @@
 /**
 * Creation, manipulation and display of LED images.
 */
-//% color=45 weight=31
+//% color=#5C2D91 weight=31
 namespace images {
     /**
      * Creates an image that fits on the LED screen.

libs/microbit/input.cpp

@@ -94,7 +94,17 @@ enum class Gesture {
      * Raised when the board is falling!
      */
     //% block="free fall"
-    FreeFall = MICROBIT_ACCELEROMETER_EVT_FREEFALL
+    FreeFall = MICROBIT_ACCELEROMETER_EVT_FREEFALL,
+    /**
+    * Raised when a 3G shock is detected
+    */
+    //% block="3g"
+    ThreeG = MICROBIT_ACCELEROMETER_EVT_3G,
+    /**
+    * Raised when a 6G shock is detected
+    */
+    //% block="6g"
+    SixG = MICROBIT_ACCELEROMETER_EVT_6G
 };
 
 //% color=300 weight=99
@@ -117,6 +127,10 @@ namespace input {
     //% help=input/on-gesture weight=84 blockGap=8
     //% blockId=device_gesture_event block="on |%NAME" icon="\uf135"
     void onGesture(Gesture gesture, Action body) {
+        if ((int)gesture == MICROBIT_ACCELEROMETER_EVT_3G && uBit.accelerometer.getRange() < 3)
+            uBit.accelerometer.setRange(4);
+        else if ((int)gesture == MICROBIT_ACCELEROMETER_EVT_6G && uBit.accelerometer.getRange() < 6)
+            uBit.accelerometer.setRange(8);            
         registerWithDal(MICROBIT_ID_GESTURE, (int)gesture, body);
     }
 

libs/microbit/input.ts

@@ -1,7 +1,7 @@
 /**
  * Events and data from sensors
  */
-//% color=300 weight=99
+//% color=#B4009E weight=99
 namespace input {
     /**
      * Attaches code to run when the screen is facing up.

libs/microbit/led.ts

@@ -1,8 +1,8 @@
 /**
  * Control of the LED screen.
  */
-//% color=3 weight=35
-namespace led {
+//% color=#5C2D91 weight=35
+    namespace led {
 
     // what's the current high value
     let barGraphHigh = 0;

libs/microbit/music.ts

@@ -77,17 +77,17 @@ enum BeatFraction {
 /**
  * Generation of music tones through pin ``P0``.
  */
-//% color=52 weight=98
+//% color=#D83B01 weight=98
 namespace music {
     let beatsPerMinute: number = 120;
 
     /**
      * Plays a tone through pin ``P0`` for the given duration.
-     * @param frequency TODO
-     * @param ms TODO
+     * @param frequency pitch of the tone to play in Hertz (Hz)
+     * @param ms tone duration in milliseconds (ms)
      */
     //% help=music/play-tone weight=90
-    //% blockId=device_play_note block="play|tone (Hz) %note=device_note|for (ms) %duration=device_beat" icon="\uf025" blockGap=8
+    //% blockId=device_play_note block="play|tone %note=device_note|for %duration=device_beat" icon="\uf025" blockGap=8
     export function playTone(frequency: number, ms: number): void {
         pins.analogSetPitchPin(AnalogPin.P0);
         pins.analogPitch(frequency, ms);
@@ -95,7 +95,7 @@ namespace music {
 
     /**
      * Plays a tone through pin ``P0``.
-     * @param frequency TODO
+     * @param frequency pitch of the tone to play in Hertz (Hz)
      */
     //% help=music/ring-tone weight=80
     //% blockId=device_ring block="ring tone (Hz)|%note=device_note" icon="\uf025" blockGap=8
@@ -106,7 +106,7 @@ namespace music {
 
     /**
      * Rests (plays nothing) for a specified time through pin ``P0``.
-     * @param ms TODO
+     * @param ms rest duration in milliseconds (ms)
      */
     //% help=music/rest weight=79
     //% blockId=device_rest block="rest(ms)|%duration=device_beat"
@@ -117,16 +117,16 @@ namespace music {
 
     /**
      * Gets the frequency of a note.
-     * @param name TODO
+     * @param name the note name
      */
     //% weight=50 help=music/note-frequency
     //% blockId=device_note block="%note"
     export function noteFrequency(name: Note): number {
         return name;
     }
-    
+
     function init() {
-        if (beatsPerMinute <= 0) beatsPerMinute = 120;        
+        if (beatsPerMinute <= 0) beatsPerMinute = 120;
     }
 
     /**

libs/microbit/pins.ts

@@ -1,7 +1,7 @@
 /**
  * Control currents in Pins for analog/digital signals, servos, i2c, ...
  */
-//% color=351 weight=30
+//% color=#A80000 weight=30
 namespace pins {
     /**
      * Re-maps a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.

libs/microbit/serial.cpp

@@ -28,8 +28,8 @@ namespace serial {
     * Registers an event to be fired when one of the delimiter is matched
     * @param delimiters the characters to match received characters against. eg:"\n"
     */
-    //% help=serial/on-data-received
-    //% weight=19
+    // help=serial/on-data-received
+    // weight=19
     void onDataReceived(StringData* delimiters, Action body) {
       uBit.serial.eventOn(ManagedString(delimiters));
       registerWithDal(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_DELIM_MATCH, body);

libs/microbit/serial.ts

@@ -1,7 +1,7 @@
 /**
  * Reading and writing data over a serial connection.
  */
-//% weight=2 color=30
+//% weight=2 color=#002050
 namespace serial {
     /**
      * Prints a line of text to the serial
@@ -11,8 +11,7 @@ namespace serial {
     //% help=serial/write-line blockGap=8
     //% blockId=serial_writeline block="serial|write line %text"
     export function writeLine(text: string): void {
-        writeString(text);
-        writeString("\r\n");
+        writeString(text + "\r\n");
     }
 
     /**
@@ -34,19 +33,16 @@ namespace serial {
     //% help=serial/write-value
     //% blockId=serial_writevalue block="serial|write value %name|= %value"
     export function writeValue(name: string, value: number): void {
-        writeString(name);
-        writeString(":");
-        writeNumber(value);
-        writeLine("");
+        writeString(name + ":" + value + "\r\n");
     }
 
     /**
     * Registers an event to be fired when a line has been received
     */
-    //% help=serial/on-line-received
-    //% blockId=serial_on_line_received block="serial on line received"
-    //% weight=21 blockGap=8
+    // help=serial/on-line-received
+    // blockId=serial_on_line_received block="serial on line received"
+    // weight=21 blockGap=8
     export function onLineReceived(body: Action): void {
-        serial.onDataReceived("\n", body);
+       // serial.onDataReceived("\n", body);
     }
 }

libs/microbit/shims.d.ts

@@ -4,7 +4,7 @@
     /**
      * Creation, manipulation and display of LED images.
      */
-    //% color=45 weight=31
+    //% color=#5C2D91 weight=31
 declare namespace images {
 
     /**
@@ -113,7 +113,7 @@ declare interface Image {
     /**
      * Provides access to basic micro:bit functionality.
      */
-    //% color=190 weight=100
+    //% color=#0078D7 weight=100
 declare namespace basic {
 
     /**
@@ -575,14 +575,6 @@ declare namespace serial {
     //% weight=87
     //% blockId=serial_writestring block="serial write string %text" shim=serial::writeString
     function writeString(text: string): void;
-
-    /**
-     * Registers an event to be fired when one of the delimiter is matched
-     * @param delimiters the characters to match received characters against. eg:"\n"
-     */
-    //% help=serial/on-data-received
-    //% weight=19 shim=serial::onDataReceived
-    function onDataReceived(delimiters: string, body: () => void): void;
 }
 
 

libs/test-snippets/README.md

@@ -0,0 +1 @@
+run ``pxt testdir ../../buit/docs/blocks`` from this folder

libs/test-snippets/pxt.json

@@ -0,0 +1,13 @@
+{
+    "name": "test-snippets",
+    "description": "A test project for doc snippets",
+    "installedVersion": "file:.",
+    "files": [
+        "main.ts"
+    ],
+    "public": true,
+    "dependencies": {
+        "microbit": "file:../microbit",
+        "microbit-radio": "file:../microbit-radio"
+    }
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pxt-microbit",
-  "version": "0.2.122",
+  "version": "0.2.128",
   "description": "BBC micro:bit target for PXT",
   "keywords": [
     "JavaScript",
@@ -29,6 +29,6 @@
     "typescript": "^1.8.7"
   },
   "dependencies": {
-    "pxt-core": "0.2.129"
+    "pxt-core": "0.2.138"
   }
 }

pxtarget.json

@@ -63,6 +63,9 @@
         "aspectRatio": 1.22
     },
     "compileService": {
+        "yottaTarget": "bbc-microbit-classic-gcc",
+        "yottaCorePackage": "pxt-microbit-core",
+        "githubCorePackage": "microsoft/pxt-microbit-core",
         "gittag": "v0.1.10",
         "serviceId": "ws"
     },
@@ -72,7 +75,7 @@
         "log": true
     },
     "appTheme": {
-        "accentColor": "#5C2D91",
+        "accentColor": "#5C005C",
         "logoUrl": "https://m.pxt.io/about",
         "logo": "./static/microbit.simplified.svg",
         "docsLogo": "./static/microbit.simplified.svg",
@@ -102,6 +105,7 @@
                 "name": "Device",
                 "path": "/device"
             }
-        ]
+        ],
+        "sideDoc": "getting-started"
     }
 }

sim/libmbit.ts

@@ -430,6 +430,10 @@ namespace pxsim.serial {
         return board().readSerial();
     }
 
+    export function readLine(): string {
+        return board().readSerial();
+    }
+
     export function onDataReceived(delimiters: string, handler: RefAction) {
         let b = board();
         b.bus.listen(DAL.MICROBIT_ID_SERIAL, DAL.MICROBIT_SERIAL_EVT_DELIM_MATCH, handler);

testconv.json

@@ -527,7 +527,6 @@
         "tnvnko",
         "toqcgf",
         "tpdiyw",
-        "tpxxzl",
         "tqeddl",
         "tqhpqp",
         "tqwach",
@@ -550,12 +549,10 @@
         "vbcdot",
         "vbtmwf",
         "vcijrw",
-        "vcmhms",
         "vcoevo",
         "vcrvjm",
         "vcudrv",
         "vczceh",
-        "vezrot",
         "vfcwwr",
         "vftxlg",
         "vfusfw",