0.2.139

Add few more radio documentation pages

.gitignore

@@ -1,9 +1,11 @@
 node_modules
+yotta_modules
+yotta_targets
 built
 typings
 tmp
 temp
-projects
+projects/**
 win10/app/bin
 win10/app/bld
 win10/*.opendb

README.md

@@ -1,26 +1,53 @@
 # micro:bit target for PXT
 
 This target allow to program a [BBC micro:bit](https://www.microbit.co.uk/) using 
-[Microsoft Programming Experience Toolkit](https://github.com/Microsoft/pxt).
+PXT ([Microsoft Programming Experience Toolkit](https://github.com/Microsoft/pxt)).
 
 * [Try it live](https://m.pxt.io)
 
 [![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
+```
+If the local server opens in the wrong browser, make sure to copy the URL containing the local token. 
+Otherwise, the editor will not be able to load the projects.
+
+If you need modify the `.cpp` files, turn on yotta compilation with the ``-yt`` flag:
+```
+pxt serve -yt
+```
+
+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`)
+that wraps ``m.pxt.io`` and provides additional features.
 
 ### Building
 

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)
                     }))

cmds/tsconfig.json

@@ -8,6 +8,6 @@
         "module": "commonjs",
         "rootDir": ".",
         "newLine": "LF",
-        "sourceMap": true
+        "sourceMap": false
     }
 }

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/docs.md

@@ -1,8 +1,35 @@
 # Documentation
 
-Welcome to the documentation.
+```sim
+basic.forever(() => {
+  basic.showString("DOCS ");
+})
+input.onButtonPressed(Button.A, () => {
+    led.stopAnimation();
+    basic.showLeds(`
+. . . . .
+. # . # .
+. . . . .
+# . . . #
+. # # # .`);
+});
+input.onButtonPressed(Button.B, () => {
+    led.stopAnimation();
+    basic.showLeds(`
+. # . # .
+# . # . #
+# . . . #
+. # . # .
+. . # . .`);
+});
+``` 
 
+* **[getting started](/getting-started)**   
 * Browse the [API reference](/reference)
 * Learn more about the [device](/device)
 * Get started with [lessons](/lessons)
-* Learn about [libraries](/libraries) (possibly using C++)
+* Follow up with the [release notes](/release-notes)
+
+### Developers
+
+* Learn about [packages](/packages) (possibly using C++ or ARM thumb)

docs/getting-started.md

@@ -1,27 +1,7 @@
-# Camp
+# Getting started
 
 Are you ready to build cool BBC micro:bit programs? For each challenge, reorder the blocks to recreate the program.
 
-## Basic
-
-### Show your name
-
-Reorder the blocks below to make the micro:bit show your name.
-```shuffle
-basic.showString('Hello!')
-```
-
-### Repeat Forever
-
-Instead of showing your name once, we will repeat it forever!
-
-Reorder the blocks to make the micro:bit show the name continuously.
-```shuffle
-basic.forever(() => {
-    basic.showString('Hello!')
-});
-```
-
 ### Show leds
 
 Use the blocks below to draw a figure on the screen. You can redo the smiley face or try something else!
@@ -36,9 +16,42 @@ basic.showLeds(`
     `)
 ```
 
-### Show an animation
+To transfer your code to the BBC micro:bit, 
+* connect your micro:bit to the computer using the USB cable
+* click on **Compile**
+* drag&drop the **.hex** file into the **MICROBIT** drive
+* wait till the yellow light is done blinking!
 
-To create animation, you can draw multiple drawing using ``show led`` and repeat it. This is just like cartoons in movies.
+### Show animation Forever
+
+Show one image after the other to create an animation by snapping them together.
+
+```blocks
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        # . . . #
+        . # # # .
+        `)
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        . # # # .
+        # . . . #
+        `)
+```
+
+To transfer your code to the BBC micro:bit, 
+* connect your micro:bit to the computer using the USB cable
+* click on **Compile**
+* drag&drop the **.hex** file into the **MICROBIT** drive
+* wait till the yellow light is done blinking!
+
+### Repeat forever
+
+Use the ``forever`` block to repeat your code and have a continuous animation.
 
 Unsuffle the blocks to create a happy, unhappy animation.... or changes the image to make it your own!
 ```shuffle
@@ -62,9 +75,8 @@ basic.forever(() => {
 
 ### Your turn now!
 
-Use the blocks and create your own custom awesome animation!
-
-## Inputs
+Use the blocks ``show leds`` and ``forever``
+to create your own custom awesome animation!
 
 ### Button A and B
 
@@ -155,4 +167,4 @@ input.onPinPressed(TouchPin.P0, () => {
 
 ### Your turn now!
 
-Use the scree, buttons, gestures, pins to create a fun game using the micro:bit.
+Use the screen, buttons, gestures, pins to create a fun game using the micro:bit.

docs/lessons.md

@@ -34,7 +34,7 @@
 * [Rock Paper Scissors](/lessons/rock-paper-scissors), create the classic game of rock paper scissors with if statement
 * [Truth or Dare](/lessons/truth-or-dare), a game that forces each player to reveal a secret or do something funny with if statement
 * [Spinner](/lessons/spinner), spin the arrow with multiple if statements
-* [Die Roll](/lessons/die-roll), spin with more if statements
+* [Dice Roll](/lessons/dice-roll), spin with more if statements
 * [Looper](/lessons/looper), display a series of numbers with a for loop index
 * [Strobe Light](/lessons/strobe-light), develop shapes with a nested for loops
 * [Temperature](/lessons/temperature), get the ambient temperature (degree Celsius °C)

docs/lessons/answering-machine.md

@@ -1,8 +1,6 @@
 # answering machine blocks lesson
 
-create an answering machine on the BBC micro:bit #docs
-
-### @video td/videos/answering-machine-0
+Create an answering machine on the BBC micro:bit
 
 ## Topic
 
@@ -25,12 +23,8 @@ Learn how to creating a message with a **string**, `show string` to write your m
 ```cards
 basic.showString('Hi!')
 input.onButtonPressed(Button.A, () => {})
-
 ```
 
-
-* **on button pressed** : [read more...](/reference/input/on-button-pressed)
-
 ## Objectives
 
 * learn how to show a string on the LED screen one character at a time

docs/lessons/answering-machine/activity.md

@@ -4,7 +4,6 @@ Learn to create an answering machine on the micro:bit
 
 ### ~avatar avatar
 
-### @video td/videos/answering-machine-0
 
 Let's learn how to create an answering machine!
 

docs/lessons/answering-machine/challenges.md

@@ -12,8 +12,6 @@ basic.showString("ASK ME A QUESTION")
 
 ### Challenge 1
 
-### @video td/videos/answering-machine-1
-
 Now we need to reply after someone asks micro:bit a  yes or no question. We want to respond `YES` when button `A` is pressed. Add a condition for button `A` and inside it show the string `YES`.
 
 ```blocks
@@ -27,8 +25,6 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 2
 
-### @video td/videos/answering-machine-2
-
 What if micro:bit's answer to the question is no? Let's have `NO` be displayed when button `B` is pressed. Add a condition for button `B` and inside it show the string `NO`.
 
 ```blocks

docs/lessons/beautiful-image.md

@@ -1,8 +1,6 @@
 # beautiful image lesson
 
-display beautiful images on the BBC micro:bit.
-
-### @video td/videos/beautiful-image-0
+Display beautiful images on the BBC micro:bit.
 
 ## Topic
 

docs/lessons/beautiful-image/activity.md

@@ -4,8 +4,6 @@ Generate and show a beautiful image.
 
 ### ~avatar avatar
 
-### @video td/videos/beautiful-image-0
-
 Let's learn how to show an image on the LED screen.
 
 ### ~

docs/lessons/beautiful-image/challenges.md

@@ -18,8 +18,6 @@ basic.showLeds(`
 
 ### Challenge 1
 
-### @video td/videos/beautiful-image-1-2
-
 Now show an new image that will display on the micro:bit.
 
 ```blocks

docs/lessons/blink.md

@@ -2,8 +2,6 @@
 
 Learn how to create a blinking LED.
 
-### @video td/videos/blink-0
-
 ## Topic
 
 Plot
@@ -30,7 +28,6 @@ basic.pause(100)
 basic.forever(() => {})
 ```
 
-
 ## Objectives
 
 * learn how to turn on LED lights on the LED screen

docs/lessons/blink/activity.md

@@ -4,7 +4,15 @@ Turn an LED on and off with forever
 
 ### ~avatar avatar
 
-### @video td/videos/blink-0
+```sim
+basic.forever(() => {
+    led.plot(2, 2)
+    basic.pause(500)
+    led.unplot(2, 2)
+    basic.pause(500)
+})
+```
+Let's build a blinking light!
 
 ### ~
 
@@ -43,7 +51,6 @@ basic.forever(() => {
     led.unplot(2, 2)
     basic.pause(500)
 })
-
 ```
 
 ### ~avatar boothing

docs/lessons/blink/challenges.md

@@ -17,8 +17,6 @@ basic.forever(() => {
 
 ### Challenge 1
 
-### @video td/videos/blink-1
-
 Let's display a "smiley face" on the screen! We'll start by plotting the eyes.
 
 Add `plot(1,1)` and `plot(3,1)` under `plot(2,2)` ; then add `unplot(1,1)`, `unplot(3,1)` and `unplot(2,2)` after `pause`. When you're ready, don't forget to run your code to try it out!
@@ -38,8 +36,6 @@ basic.forever(() => {
 
 ### Challenge 2
 
-### @video td/videos/blink-2
-
 Let's add the code to plot the mouth by using `plot` and `unplot` to the following coordinates: (1,4), (2,4) and (3,4). When you're ready, don't forget to run your code to try it out!
 
 ```blocks
@@ -63,8 +59,6 @@ basic.forever(() => {
 
 ### Challenge 3
 
-### @video td/videos/blink-3
-
 Let's keep using `plot` to convert the mouth into a smiley face.
 
 ```` bitmatrix

docs/lessons/catch-the-egg-game.md

@@ -2,8 +2,6 @@
 
 A game to catch eggs in a basket.
 
-### @video td/videos/catch-the-egg-game-0
-
 ## Topic
 
 Variables

docs/lessons/catch-the-egg-game/activity.md

@@ -108,8 +108,6 @@ basic.forever(() => {
 
 ### Challenge 3
 
-### @video td/videos/catch-the-egg-game-4
-
 Let's make the egg fall faster by decreasing the amount of time it pauses in each position by decreasing **falling pause** by `25` every 5 catches. Now, instead of pausing for 300 milliseconds we can pause for the value of **falling pause**.
 
 ```blocks

docs/lessons/compass.md

@@ -2,8 +2,6 @@
 
 create a die on the BBC micro:bit.
 
-### @video td/videos/compass-0
-
 ## Topic
 
 If (Conditionals)

docs/lessons/counter.md

@@ -2,8 +2,6 @@
 
 Learn how to create a counter with with on button pressed.
 
-### @video td/videos/counter-0
-
 ## Topic
 
 Variables

docs/lessons/counter/activity.md

@@ -4,8 +4,6 @@ Display a number with a variable.
 
 ### ~avatar avatar
 
-### @video td/videos/counter-0
-
 Welcome! This tutorial will teach you how to make a counter that increments when button A is pressed. Let's get started!
 
 ### ~

docs/lessons/counter/challenges.md

@@ -16,8 +16,6 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 1
 
-### @video td/videos/counter-1-2
-
 Let's add the code to `count` when `B` is pressed. Add an event handler with `on button pressed(B)` then add the code to `count`.
 
 
@@ -33,7 +31,6 @@ input.onButtonPressed(Button.B, () => {
 })
 ```
 
-
 ### Challenge 3
 
 Now let's try to reset the counter when the micro:bit is shaken. You will need to register an event handler with `on shake`.

docs/lessons/dice-roll.md

@@ -1,8 +1,6 @@
-# die roll lesson
+# dice roll lesson
 
-create a die on the BBC micro:bit.
-
-### @video td/videos/die-roll-0
+Create a  dice on the BBC micro:bit.
 
 ## Topic
 
@@ -10,10 +8,10 @@ If (Conditionals)
 
 ## Quick Links
 
-* [activity](/lessons/die-roll/activity)
-* [challenges](/lessons/die-roll/challenges)
-* [quiz](/lessons/die-roll/quiz)
-* [quiz answers](/lessons/die-roll/quiz-answers)
+* [activity](/lessons/dice-roll/activity)
+* [challenges](/lessons/dice-roll/challenges)
+* [quiz](/lessons/dice-roll/quiz)
+* [quiz answers](/lessons/dice-roll/quiz-answers)
 
 ## Prior learning/place of lesson in scheme of work
 

docs/lessons/dice-roll/activity.md

@@ -1,12 +1,10 @@
-# die roll activity
+# dice roll activity
 
-Create a die on the micro:bit
+Create a dice on the micro:bit
 
 ### ~avatar avatar
 
-### @video td/videos/die-roll-0
-
-Welcome! This tutorial will help you create a die. Let's get started!
+Welcome! This tutorial will help you create a dice. Let's get started!
 
 ### ~
 
@@ -19,7 +17,7 @@ input.onGesture(Gesture.Shake, () => {
 })
 ```
 
-We need to show a random value from 1 to 6 on our die. So let's make a local variable called **roll**.
+We need to show a random value from 1 to 6 on our dice. So let's make a local variable called **roll**.
 
 ```blocks
 input.onGesture(Gesture.Shake, () => {
@@ -27,7 +25,7 @@ input.onGesture(Gesture.Shake, () => {
 })
 ```
 
-We need a condition for if **roll** is 5. We will show a `6` if **roll** is 5 because **roll** has a range from 0 to 5. We can use `show LEDs` to display the side of a die that shows 6.
+We need a condition for if **roll** is 5. We will show a `6` if **roll** is 5 because **roll** has a range from 0 to 5. We can use `show LEDs` to display the side of a dice that shows 6.
 
 
 ```blocks
@@ -45,7 +43,7 @@ input.onGesture(Gesture.Shake, () => {
 ```
 
 
-Let's use an `else if` condition for if **roll** is 4. If **roll** is 4 we can show 5 dots on the die.
+Let's use an `else if` condition for if **roll** is 4. If **roll** is 4 we can show 5 dots on the dice.
 
 
 ```blocks
@@ -72,7 +70,7 @@ input.onGesture(Gesture.Shake, ()=> {
 ```
 
 
-Now we need to repeat the same steps for if **roll** is 3. If **roll** is 3 we will show `4` on the die.
+Now we need to repeat the same steps for if **roll** is 3. If **roll** is 3 we will show `4` on the dice.
 
 
 ```blocks
@@ -106,7 +104,7 @@ input.onGesture(Gesture.Shake, () => {
 ```
 
 
-Let's also repeat these steps to show the 3, 2, and 1 on the die. We are almost done with our die!
+Let's also repeat these steps to show the 3, 2, and 1 on the dice. We are almost done with our dice!
 
 ```blocks 
 input.onGesture(Gesture.Shake, () => {
@@ -165,7 +163,7 @@ input.onGesture(Gesture.Shake, () => {
 
 ### ~avatar avatar
 
-Excellent, you're ready to continue with the [challenges](/lessons/die-roll/challenges)!
+Excellent, you're ready to continue with the [challenges](/lessons/dice-roll/challenges)!
 
 ### ~
 

docs/lessons/dice-roll/challenges.md

@@ -1,10 +1,10 @@
-# die roll challenges
+# dice roll challenges
 
-Create a die on the micro:bit. 
+Create a dice on the micro:bit. 
 
 ## Before we get started
 
-Complete the following [guided tutorial](/lessons/die-roll/activity), your code should look like this:
+Complete the following [guided tutorial](/lessons/dice-roll/activity), your code should look like this:
 
 ```blocks 
 input.onGesture(Gesture.Shake, () => {
@@ -62,7 +62,7 @@ input.onGesture(Gesture.Shake, () => {
 
 ### Challenge 1
 
-Modify the line of code with `pick random` so that only number 1-4 can appear on the die.
+Modify the line of code with `pick random` so that only number 1-4 can appear on the dice.
 
 
 ```blocks 
@@ -121,7 +121,7 @@ input.onGesture(Gesture.Shake, () => {
 
 ### Challenge 2
 
-Let's make a trick die! Modify the line of code with `pick random` so that only numbers 3-6 can appear on the die. Also note that we need to ensure `roll = 0` when only 1 dot is shown on the BBC micro:bit.
+Let's make a trick dice! Modify the line of code with `pick random` so that only numbers 3-6 can appear on the dice. Also note that we need to ensure `roll = 0` when only 1 dot is shown on the BBC micro:bit.
 
 ```blocks 
 input.onGesture(Gesture.Shake, () => {

docs/lessons/dice-roll/quiz-answers.md

@@ -1,8 +1,8 @@
-# die roll quiz answers
+# dice roll quiz answers
 
-Create a die when the BBC micro:bit is shaken 
+Create a dice when the BBC micro:bit is shaken 
 
-These are the answers to the [die roll quiz](/lessons/die-roll/quiz).
+These are the answers to the [dice roll quiz](/lessons/dice-roll/quiz).
 
 ## 1. Create a variable named 'roll' that will be randomly assigned to a number between 0 and 5.
 

docs/lessons/dice-roll/quiz.md

@@ -1,12 +1,12 @@
-# die roll quiz
+# dice roll quiz
 
-Create a die when the BBC micro:bit is shaken 
+Create a dice when the BBC micro:bit is shaken 
 
 ## Name
 
 ## Directions
 
-Use this activity document to guide your work in the [die roll tutorial](/lessons/die-roll/activity).
+Use this activity document to guide your work in the [dice roll tutorial](/lessons/dice-roll/activity).
 
 Answer the questions while completing the tutorial. Pay attention to the dialogues!
 

docs/lessons/digi-yoyo.md

@@ -1,8 +1,6 @@
 # digi yoyo lesson
 
-create a counter with a while loop.
-
-### @video td/videos/digi-yoyo-0
+Create a counter with a while loop.
 
 ## Topic
 

docs/lessons/digi-yoyo/activity.md

@@ -4,8 +4,6 @@ Create a counter with a while loop.
 
 ### ~avatar avatar
 
-### @video td/videos/digi-yoyo-0
-
 Welcome! This tutorial will teach how to create a counter with a while loop. Let's get started!
 
 ### ~

docs/lessons/digi-yoyo/challenges.md

@@ -40,8 +40,6 @@ while (count > 0) {
 
 ### Challenge 2
 
-### @video td/videos/digi-yoyo-1-2
-
 Inside of the while loop, let's add `pause->(1000)` so that we have a pause between each number as it's counting down. Also, let's show `count`!
 
 

docs/lessons/flashing-heart.md

@@ -2,8 +2,6 @@
 
 Learn how to create LED images with a global variable.
 
-### @video td/videos/flashing-heart-0
-
 ## Topic
 
 Pause

docs/lessons/flashing-heart/activity.md

@@ -4,8 +4,6 @@ Control images with a variable.
 
 ### ~avatar avatar
 
-### @video td/videos/flashing-heart-0
-
 In this activity, you will learn how to blink an image on the LED screen.
 
 ### ~

docs/lessons/flashing-heart/challenges.md

@@ -25,8 +25,6 @@ basic.forever(() => {
 
 ### Challenge 1
 
-### @video td/videos/flashing-heart-1
-
 Let's plot a different image. Let's display a broken heart!
 
 To do this, you need to add a block between the last line and the end loop. Add a `show LEDs` block and then add a `pause` of 500 milliseconds.
@@ -60,8 +58,6 @@ basic.forever(() => {
 
 ### Challenge 2
 
-### @video td/videos/flashing-heart-2
-
 Now let's alternate flashing the heart and the broken heart. To do this, we need to add a `clear screen` block and then add a `pause` block of 500 milliseconds under the new code we added in Challenge 1.
 
 

docs/lessons/game-counter.md

@@ -2,8 +2,6 @@
 
 Learn how to create a counter with with on button pressed.
 
-### @video td/videos/counter-0
-
 ## Topic
 
 Game Library

docs/lessons/game-counter/activity.md

@@ -1,13 +1,5 @@
 # game counter activity
 
-Turn an LED on and off with forever loop
-
-### ~avatar avatar
-
-### @video td/videos/counter-0
-
-### ~
-
 Have you ever tried to create a game counter? The concept is fairly simply: increase the game `score` with `on button pressed` .
 
 Let's start by adding `on button (A) pressed` will run each time the user presses A. Let's add a line of code that increments `score` by `1`.

docs/lessons/game-counter/challenges.md

@@ -15,8 +15,6 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 1
 
-### @video td/videos/counter-1-2
-
 Let's add the code to `score` when `B` is pressed. Add an event handler with `on button (B) pressed` then add the code to `score`.
 
 

docs/lessons/guess-the-number.md

@@ -2,8 +2,6 @@
 
 Learn to create a random number with input from button A.
 
-### @video td/videos/guess-the-number-0
-
 ## Topic
 
 Math - Pick Random

docs/lessons/guess-the-number/activity.md

@@ -4,8 +4,6 @@ Guess the number with math random.
 
 ### ~avatar avatar
 
-### @video td/videos/guess-the-number-0
-
 Welcome! This tutorial will help you create a guess the number game! Let's get started!
 
 ### ~

docs/lessons/guess-the-number/challenges.md

@@ -15,8 +15,6 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 1
 
-### @video td/videos/guess-the-number-2
-
 When button `B` is pressed, we want to clear the screen. This will make it so users can play your game over and over again! Add an event handler to handle this case.
 
 ```blocks

docs/lessons/guess-the-number/tutorial.md

@@ -2,8 +2,6 @@
 
 ### ~avatar avatar
 
-### @video td/videos/guess-the-number-0
-
 This tutorial will help you create a guess the number game! Let's get started!
 
 ### ~

docs/lessons/looper.md

@@ -2,8 +2,6 @@
 
 Learn to control blinking LEDs.
 
-### @video td/videos/looper-0
-
 ## Topic
 
 For Loop

docs/lessons/looper/activity.md

@@ -1,13 +1,5 @@
 # looper blocks activity
 
-Display a series of numbers with a for loop. 
-
-### ~avatar avatar
-
-### @video td/videos/looper-0
-
-### ~
-
 Welcome! This activity will teach how to display a series of numbers for a for loop. Let's get started!
 
 Let's create a for loop where `0` is the loop's starting value, `i` is the index variable, and `5` is the ending value. The index variable `i` starts at 0 and increases by 1 each time through the loop. The loop ends when `i = 5`.

docs/lessons/looper/challenges.md

@@ -20,8 +20,6 @@ for (let i = 0; i < 6; i++) {
 
 ### Challenge 1
 
-### @video td/videos/looper-1
-
 What if we want to count up to lucky number 7 instead? Let's do that by changing the ending value to `7` instead of `5`.
 
 
@@ -37,8 +35,6 @@ for (let i = 0; i < 8; i++) {
 
 ### Challenge 2
 
-### @video td/videos/looper-2
-
 What about 9? Let's do that by changing the ending value to `9`.
 
 ```blocks
@@ -55,8 +51,6 @@ for (let i = 0; i < 10; i++) {
 
 ### Challenge 3
 
-### @video td/videos/looper-3
-
 Now let's start counting from `3` instead! Our for loop will always start at `0` so we simply add `3` to the `i` variable when passing it to `show number`.
 
 ```blocks
@@ -72,8 +66,6 @@ Run it on the simulator!
 
 ### Challenge 4
 
-### @video td/videos/looper-4
-
 Now, let's **count down from 9**. Change the line `show number(i + 2, 150)` to `show number(9 - i, 150)`.
 
 ```blocks

docs/lessons/love-meter.md

@@ -1,8 +1,6 @@
 # love meter blocks lesson
 
-create a love meter with the BBC micro:bit.
-
-### @video td/videos/love-meter-0
+Create a love meter with the BBC micro:bit.
 
 ## Topic
 

docs/lessons/love-meter/activity.md

@@ -4,8 +4,6 @@ Create a love meter with the micro:bit
 
 ### ~avatar avatar
 
-### @video td/videos/love-meter-0
-
 Welcome! This activity will help you create a love meter with the micro:bit. Let's get started!
 
 ### ~

docs/lessons/love-meter/challenges.md

@@ -45,8 +45,6 @@ input.onPinPressed(TouchPin.P0, () => {
 
 ### Challenge 3
 
-### @video td/videos/love-meter-3
-
 **If** the rating is between 4 and 7, display the text "MEDIOCRE!" **else** display the text "MATCHED!"
 
 ```blocks

docs/lessons/lucky-7.md

@@ -1,8 +1,6 @@
 # lucky 7 blocks lesson
 
-show a number on the LED screen.
-
-### @video td/videos/lucky-7-0
+Show a number on the LED screen.
 
 ## Topic
 

docs/lessons/lucky-7/activity.md

@@ -4,8 +4,6 @@ Show a number on the LED screen.
 
 ### ~avatar avatar
 
-### @video td/videos/lucky-7-0
-
 Let's learn how to show the lucky number 7 on the LED screen.
 
 ### ~

docs/lessons/lucky-7/challenges.md

@@ -21,8 +21,6 @@ basic.pause(500)
 
 ### Challenge 2
 
-### @video td/videos/lucky-7-1-2
-
 What about other multiples of 7? Let's display the next multiple of 7 on the screen!
 
 ```blocks

docs/lessons/magic-logo.md

@@ -2,7 +2,7 @@
 
 show an image that points up when the logo is up.
 
-### @video td/videos/magic-logo-0
+
 
 ## Topic
 

docs/lessons/magic-logo/activity.md

@@ -4,8 +4,6 @@ Show an image that points up when the logo is up.
 
 ### ~avatar avatar
 
-### @video td/videos/magic-logo-0
-
 Welcome! This tutorial will help you display an arrow pointing toward the logo! Let's get started.
 
 ### ~

docs/lessons/magic-logo/challenges.md

@@ -24,8 +24,6 @@ input.onLogoUp(() => {
 
 How about when the logo is down? We should display an arrow pointing downward!
 
-### @video td/videos/magic-logo-1-2
-
 ```blocks
 input.onLogoUp(() => {
     basic.showLeds(`

docs/lessons/night-light.md

@@ -2,8 +2,6 @@
 
 change the brightness of the BBC micro:bit.
 
-### @video td/videos/night-light-0
-
 ## Topic
 
 Set Brightness

docs/lessons/night-light/activity.md

@@ -4,8 +4,6 @@ Change the brightness of the micro:bit.
 
 ### ~avatar avatar
 
-### @video td/videos/night-light-0
-
 Welcome! This tutorial will teach you how to change the brightness of the micro:bit. Let's get started!
 
 ### ~

docs/lessons/night-light/challenges.md

@@ -23,7 +23,7 @@ input.onButtonPressed(Button.A, () => {
 ```
 ### Challenge 1
 
-### @video td/videos/night-light-2
+
 
 What if we want to turn off all the LEDs? Let's do this by setting the brightness to `0` when button `B` is pressed. Add an event handler with `on button pressed(B)` add `set brightness(0)` to turn off the LEDs.
 

docs/lessons/offset-image/activity.md

@@ -55,7 +55,7 @@ input.onButtonPressed(Button.B, () => {
 
 ### Challenge 2
 
-### @video td/videos/offset-image-2
+
 
 Now we want to make sure that the button does not go off the screen to the right. Add a new line that checks to see if offset = 5 after button `A` is pressed.
 

docs/lessons/rock-paper-scissors.md

@@ -2,7 +2,7 @@
 
 a game against the BBC micro:bit.
 
-### @video td/videos/rock-paper-scissors-0
+
 
 ## Topic
 

docs/lessons/rock-paper-scissors/activity.md

@@ -4,7 +4,7 @@ A classic game against the micro:bit.
 
 ### ~avatar avatar
 
-### @video td/videos/rock-paper-scissors-0
+
 
 Welcome! This tutorial will help you create a game of rock paper scissors with the micro:bit. Let's get started!
 

docs/lessons/rotation-animation/challenges.md

@@ -93,7 +93,7 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 2
 
-### @video td/videos/rotation-animation-1-and-2
+
 
 Now that we have the on button pressed condition, let's make the animation stop rotating by setting the rotating global variable to false when button `A` is pressed.
 

docs/lessons/screen-wipe.md

@@ -2,7 +2,7 @@
 
 clear the screen by pressing button "A".
 
-### @video td/videos/screen-wipe-0
+
 
 ## Topic
 

docs/lessons/screen-wipe/activity.md

@@ -4,7 +4,7 @@ Clear the screen by pressing buttons on the micro:bit
 
 ### ~avatar avatar
 
-### @video td/videos/screen-wipe-0
+
 
 This activity will teach how to clear the screen by pressing button A on the micro:bit.
 

docs/lessons/screen-wipe/challenges.md

@@ -85,7 +85,7 @@ input.onButtonPressed(Button.B, () => {
 
 ### Challenge 2
 
-### @video td/videos/screen-wipe-2
+
 
 Replay the animation when the "B" button is pressed placing the `show LEDs` block on the canvas.
 

docs/lessons/smiley.md

@@ -2,7 +2,7 @@
 
 design a blinking image lesson #docs
 
-### @video td/videos/smiley-0
+
 
 ## Topic 
 

docs/lessons/smiley/activity.md

@@ -4,7 +4,7 @@ Learn to design a blinking image.
 
 ### ~avatar avatar
 
-### @video td/videos/smiley-0
+
 
 Welcome! This tutorial will help you make a smiley face blink. Let's get started!
 

docs/lessons/smiley/challenges.md

@@ -54,7 +54,7 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 2
 
-### @video td/videos/smiley-2
+
 
 Now, we want to show a frowny face when this button is pressed. Let's show the LEDs.
 

docs/lessons/snowflake-fall.md

@@ -2,7 +2,7 @@
 
 design a blinking rectangle animation.
 
-### @video td/videos/snowflake-fall-0
+
 
 ## Topic
 

docs/lessons/snowflake-fall/activity.md

@@ -4,7 +4,7 @@ design a blinking rectangle animation.
 
 ### ~avatar avatar
 
-### @video td/videos/snowflake-fall-0
+
 
 Welcome! This tutorial will teach how design a **snowfall animation**. Let's get started!
 

docs/lessons/snowflake-fall/challenges.md

@@ -27,7 +27,7 @@ basic.forever(() => {
 
 ### Challenge 1
 
-### @video td/videos/snowflake-fall-1
+
 
 To finalize our snowflake fall, let's add a different snowflake pattern.
 

docs/lessons/speed-button.md

@@ -2,7 +2,7 @@
 
 code a speed game by declaring Booleans on the BBC micro:bit.
 
-### @video td/videos/speed-button-3
+
 
 ## Topic
 

docs/lessons/speed-button/activity.md

@@ -63,7 +63,7 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 3
 
-### @video td/videos/speed-button-3
+
 
 Now let's display if the user won or lost. To do so, we need to check the status of `fastPress` when the game is finished, and then show the correct message.
 
@@ -91,7 +91,7 @@ input.onButtonPressed(Button.A, () => {
 
 ### Challenge 4
 
-### @video td/videos/speed-button-4
+
 
 Modify the code to change the difficulty level. Increasing the time will make it easier, while decreasing the time will make it harder. For example, changing the 5000 milliseconds to 6000 milliseconds will make the difficulty easier.
 

docs/lessons/spinner.md

@@ -2,7 +2,7 @@
 
 a spin the BBC micro:bit game with the input on shake.
 
-### @video td/videos/spinner-0
+
 
 ## Topic
 

docs/lessons/spinner/activity.md

@@ -4,7 +4,7 @@ Create an arrow that randomly points to a player.
 
 ### ~avatar avatar
 
-### @video td/videos/spinner-0
+
 
 ### ~
 

docs/lessons/strobe-light.md

@@ -2,7 +2,7 @@
 
 Learn how to create a blinking LED script.
 
-### @video td/videos/strobe-light-0
+
 
 ## Topic
 

docs/lessons/strobe-light/activity.md

@@ -4,7 +4,7 @@ Develop shapes with a for loop.
 
 ### ~avatar avatar
 
-### @video td/videos/strobe-light-0
+
 
 Welcome! This guided tutorial will teach how to develop shapes with a for loop. Let's get started!
 

docs/lessons/strobe-light/challenges.md

@@ -19,7 +19,7 @@ for (let i = 0; i < 5; i++) {
 
 ### Challenge 1
 
-### @video td/videos/strobe-light-1
+
 
 Make the LEDs light up faster by changing the **pause** from 200 to 100 milliseconds:
 
@@ -36,7 +36,7 @@ for (let i = 0; i < 5; i++) {
 
 ### Challenge 2
 
-### @video td/videos/strobe-light-2
+
 
 Make the board light up by rows instead of by columns by swapping the `i` and `j` variables in `plot(i, j)`.
 
@@ -53,7 +53,7 @@ for (let i = 0; i < 5; i++) {
 
 ### Challenge 3
 
-### @video td/videos/strobe-light-ultimate
+
 
 Now that all the LEDs are lit up, let's make them turn off by reversing the strobe light pattern! You can use `unplot` to turn off a single LED.
 

docs/lessons/teach.md

@@ -22,7 +22,7 @@ The lesson plan maps to the Progressions Pathways, Computing Curriculum, and Qui
 
 Expand your knowledge of programming with lots of great step-by-step activities. All the lessons come with instructions that will drive the students to a complete, functional code. These activities are very directive to make sure that students keep progressing. When the activities are over, additional challenges are given to advance code through printed instructions. An activity contains supporting videos as shown with the [blink activity](/lessons/blink/activity).
 
-### @video td/videos/blink-0
+
 
 3) Quiz
 

docs/lessons/truth-or-dare.md

@@ -2,7 +2,7 @@
 
 create a love meter with the BBC micro:bit.
 
-### @video td/videos/truth-or-dare-0
+
 
 ## Topic
 

docs/lessons/truth-or-dare/activity.md

@@ -4,7 +4,7 @@ A multi-player game that forces each player to reveal a secret or something funn
 
 ### ~avatar avatar
 
-### @video td/videos/truth-or-dare-0
+
 
 Welcome! This tutorial will teach how to program a game of truth or dare on the micro:bit. Let's get started!
 

docs/lessons/truth-or-dare/tutorial.md

@@ -2,7 +2,7 @@
 
 ### ~avatar avatar
 
-### @video td/videos/truth-or-dare-0
+
 
 The *Truth or dare!* game works as follows: a player spins the BBC micro:bit on the table. 
 When the micro:bit stops spinning, the player pointed by the arrow (displayed on screen) must press the button "A" 

docs/lessons/zoomer.md

@@ -2,7 +2,7 @@
 
 measure the acceleration on the micro:bit in the "z" direction.
 
-### @video td/videos/zoomer-0
+
 
 ## Topic
 

docs/lessons/zoomer/activity.md

@@ -4,7 +4,7 @@ Measure the acceleration on the micro:bit in the "z" direction.
 
 ### ~avatar avatar
 
-### @video td/videos/zoomer-0
+
 
 ### ~
 

docs/lessons/zoomer/challenges.md

@@ -14,7 +14,7 @@ basic.forever(() => {
 ```
 ### Challenge 1
 
-### @video td/videos/zoomer-2
+
 
 We'll modify the code to display the `x` acceleration if the `A` button is pressed. For that, we need to store `acceleration (x)` in a new variable `ax` and use a `button (A) is pressed` to detect if the button is pressed.
 

docs/libraries.md

@@ -1,14 +0,0 @@
-# Extensions
-
-You can publish libraries (also known as packages or extensions)
-that users can then add to their scripts. These typically
-provide a driver for a particular hardware device you can connect
-to a microbit.
-
-* [Sample C++ extension](https://github.com/Microsoft/pxt-microbit-cppsample)
-* [Sample TypeScript extension](https://github.com/Microsoft/pxt-microbit/tree/master/libs/i2c-fram)
-
-## Finding libraries
-
-## Publishing libraries
-

docs/microbit-reference.md

@@ -1,23 +0,0 @@
-# microbit Reference
-
-```namespaces
-basic.showNumber(0);
-input.onButtonPressed(Button.A, () => {
-    
-});
-led.plot(0, 0);
-music.playTone(0, 0);
-game.addScore(1);
-images.createImage(`
-. . . . .
-. . . . .
-. . # . .
-. . . . .
-. . . . .
-`);
-pins.digitalReadPin(DigitalPin.P0);
-serial.writeValue(x, 0);
-control.inBackground(() => {
-    
-});
-```

docs/open-source.md

@@ -0,0 +1,9 @@
+# Open Source
+
+The editor is open source on GitHub under the MIT license. Contributions are welcome, please check our GitHub repos.
+
+### Repos
+
+* [microbit/pxt](https://github.com/Microsoft/pxt), programming experience toolkit (PXT)
+* [microsoft/pxt-microbit](https://github.com/Microsoft/pxt-microbit), PXT target for BBC micro:bit
+* [microsoft/pxt-microbit-core](https://github.com/Microsoft/pxt-microbit-core), Yotta module used to build the BBC micro:bit runtime

docs/packages.md

@@ -0,0 +1,48 @@
+# Extensions
+
+You can publish libraries (also known as packages or extensions)
+that users can then add to their scripts. These typically
+provide a driver for a particular hardware device you can connect
+to a microbit.
+
+* [Sample C++ extension](https://github.com/Microsoft/pxt-microbit-cppsample)
+* [Sample TypeScript extension](https://github.com/Microsoft/pxt-microbit/tree/master/libs/i2c-fram)
+
+## Finding libraries
+
+From the editor, the user clicks on **More** then **Add Package** and searches for the package. 
+
+To see the list of packages, click on **More** then **Show Files** to see the project file list.
+
+To remove a package, click on the garbage button in the file list next to the package.
+
+## Publishing libraries
+
+Packages can be published from the pxt command line. We are still sorting out the details.
+
+## Localizing libraries
+
+It is possible to package localization strings for the **jsDoc** description associated to the API in the package.
+
+When compiling a package, the PXT compiler generates a `strings.json` file under the `_locales/` folder. 
+This file contains a map from the symbol name to the en
+
+```
+{
+  ...
+  "basic": "Provides access to basic micro:bit functionality.",
+   ...
+}
+```
+
+```
+{
+  "basic.clearScreen": "Eteint toutes les diodes."
+}
+```
+
+```
+_locales/
+_locales/fr/strings.json
+_locales/pt-BR/strings.json
+```

docs/projects.md

@@ -0,0 +1,15 @@
+# Projects 
+
+
+### @short Projects
+
+### ~column 
+
+## Beginner
+
+* [Rock Paper Scissors](/projects/rock-paper-scissors)
+
+### ~
+
+### ~column 
+

docs/projects/a1-display.md

@@ -0,0 +1,34 @@
+## Getting started
+	• Go to https://m.pxt.io/
+	• To create a new project, click new Project
+Tap or click Blocks.
+
+## Step 1
+
+Use [show leds](/reference/basic/showLeds) and make your code look like this:
+
+```blocks
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+```
+
+Once you are done coding, don't forget to run your code with the Play button.
+
+## Step 2
+
+Add a [pause](/reference/basic/pause) to wait and [clear screen](/reference/basic/clearScreen) to turn off the LEDs.
+
+```blocks
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+basic.pause(500);
+basic.clearScreen();
+```

docs/projects/rock-paper-scissors.md

@@ -0,0 +1,234 @@
+# rock paper scissors
+
+### ~avatar avatar
+
+```sim
+input.onGesture(Gesture.Shake, () => {
+    let img = Math.random(3)
+    if (img == 0) {
+        basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+
+    } else if (img == 1) {
+        basic.showLeds(`
+            . . . . .
+            . # # # .
+            . # # # .
+            . # # # .
+            . . . . .
+            `)
+    } else {
+        basic.showLeds(`
+            # # . . #
+            # # . # .
+            . . # . .
+            # # . # .
+            # # . . #
+            `)
+    }
+})
+```
+In this project, you will build a Rock Paper Scissors game with the BBC micro:bit.
+You can play the game with a friend who has it on a micro:bit.
+You can also play it with friends who are just using their hands.
+
+### ~
+
+## Materials needed
+
+* Your BBC micro:bit -- that's it!
+
+## Step 1: Getting started
+
+We want the micro:bit to choose rock, paper, or scissors when you shake it.
+Try creating an ``on shake`` block so when you shake the micro:bit, it will run part of a program.
+
+```blocks
+input.onGesture(Gesture.Shake, () => {
+    
+})
+```
+
+Next, when you shake the micro:bit, it should pick a random number from `0` to `2`
+and store it in the variable `weapon`. (This variable is named `weapon` because 
+rock, paper, and scissors are the weapons you use to battle your friends!)
+
+Add a ``set`` block with a variable. Then add a ``pick random`` block,
+and store the random number in the variable,
+like this:
+
+```blocks
+input.onGesture(Gesture.Shake, () => {
+    let weapon = Math.random(3)
+})
+
+```
+
+### ~hint
+No one can predict random numbers. That's what makes them great for Rock Paper Scissors!
+### ~
+
+Each possible number these blocks can make (`0`, `1`, or `2`) means a different picture.
+We will show the right picture for that number on the LED screen.
+
+
+## Step 2: Picking paper
+
+Put an ``if`` block after the ``let`` block that checks whether
+`weapon` is `0`. Make sure the ``if`` block has an ``else if`` part
+and an ``else`` part.
+
+Next, add a ``show leds`` block that shows a
+picture of a piece of paper:
+
+```blocks
+input.onGesture(Gesture.Shake, () => {
+    let weapon = Math.random(3)
+    if (weapon == 0) {
+        basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+    } else if (false) {
+
+    } else {
+
+    }
+})
+```
+
+## Step 3: A random rock
+
+Now we are going to add a new picture for the micro:bit to show
+when another random number comes up.
+
+Make the ``else if`` part check if the variable `weapon` is `1`.
+Then add a ``show leds`` block with a picture of a rock.
+
+```blocks
+input.onGesture(Gesture.Shake, () => {
+    let weapon = Math.random(3)
+    if (weapon == 0) {
+        basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+
+    } else if (weapon == 1) {
+        basic.showLeds(`
+            . . . . .
+            . # # # .
+            . # # # .
+            . # # # .
+            . . . . .
+            `)
+    } else {
+
+    }
+})
+```
+
+## Step 4: Suddenly scissors
+
+Add a ``show leds`` block with a picture of scissors to the ``else`` part:
+
+```blocks
+input.onGesture(Gesture.Shake, () => {
+    let weapon = Math.random(3)
+    if (weapon == 0) {
+        basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+
+    } else if (weapon == 1) {
+        basic.showLeds(`
+            . . . . .
+            . # # # .
+            . # # # .
+            . # # # .
+            . . . . .
+            `)
+    } else {
+        basic.showLeds(`
+            # # . . #
+            # # . # .
+            . . # . .
+            # # . # .
+            # # . . #
+            `)
+    }
+})
+
+```
+
+### ~hint
+
+You don't need to check if `weapon` is `2` because `2` is the only number left out of `0`, `1`, and `2`.
+That's why you can use an ``else`` instead of an ``else if``.
+
+### ~
+
+Your game is ready! Have fun!
+
+## Step 5: Are you the greatest?
+
+Here is a way you can make your Rock Paper Scissors game better.
+When button ``A`` is pressed, 
+the micro:bit will add `1` to your score.
+
+Open the ``Game`` drawer, and then add the block ``change score by 1`` to your program,
+like this:
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    game.addScore(1)
+})
+
+```
+
+## Step 6: Prove you're the greatest!
+
+After your micro:bit can add `1` to the score, show how many wins you have.
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    game.addScore(1)
+    basic.showString("WINS:")
+    basic.showNumber(game.score())
+})
+```
+## Step 7: Staying honest
+
+Success! Your micro:bit can track wins!
+But what about losses? 
+Use the ``Game`` drawer to subtract `1` from your score when you press button `B`. 
+
+Here are all the blocks you will need:
+
+```shuffle
+input.onButtonPressed(Button.B, () => {
+    game.addScore(-1)
+    basic.showString("LOSSES:")
+    basic.showNumber(game.score())
+})
+```
+
+## Step 8: Hacking Rock Paper Scissors
+
+How else can you make your game better?
+Ever hear of [Rock Paper Scissors Spock Lizard](http://www.samkass.com/theories/RPSSL.html)?

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/String.md

@@ -0,0 +1,5 @@
+# String
+
+```cards
+String.fromCharCode(0);
+```

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)
     }
 })