0.2.161

will move select lessons back to "educators" section

.gitignore

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

.travis.yml

@@ -13,4 +13,5 @@ notifications:
 cache:
   directories:
     - node_modules
+    - built/cache
 

.vscode/settings.json

@@ -0,0 +1,5 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+    "tslint.enable": true,
+    "tslint.rulesDirectory": "node_modules/tslint-microsoft-contrib"
+}

README.md

@@ -1,26 +1,54 @@
 # 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 (add ``sudo`` for Mac/Linux shells)
+```
+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 (add ``sudo`` for Mac/Linux shells):
+```
+pxt serve -yt
+```
+
+To make sure you're running the latest tools, run (add ``sudo`` for Mac/Linux shells)
+```
+pxt 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 codemicrobit.com 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
 
 * Install Visual Studio 2015 Update 2 or higher. Make sure the Windows 10 templates are installed.
-* open the ``win10/app.sln`` solution and launch the ``codemicrobit`` project.
+* open the ``win10/app.sln`` solution and launch the ``m.pxt.io`` project.

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/_locales/pl/_theme.json

@@ -0,0 +1,22 @@
+{
+    "name": "koduj z micro:bit",
+    "title": "koduj z micro:bit",
+    "docMenu": [
+        {
+            "name": "O nas",
+            "path": "/about"
+        },
+        {
+            "name": "Lekcje",
+            "path": "/lessons"
+        },
+        {
+            "name": "Instrukcja obsługi",
+            "path": "/reference"
+        },
+        {
+            "name": "Urządzenie",
+            "path": "/device"
+        }
+    ]
+}

docs/_locales/pl/docs.md

@@ -0,0 +1,7 @@
+# Dokumentacja
+
+Witamy na stronach dokumentacji!
+
+* Przeglądnij [instrukcje obsługi](/reference)
+* Dowiedz się więcej o [urządzeniu](/device)
+* Wystartuj z [lekcjami](/lessons)

docs/about.md

@@ -26,20 +26,20 @@ 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
 
-The student can program the BBC micro:bit using [visual blocks](http://www.github.com/Google/blockly) or JavaScript.
+The student can program the BBC micro:bit using Blocks or JavaScript.
 
 ```blocks
-basic.showString("BBC micro:bit!");
+basic.showString("Hi!");
 ```
 
 ## Compile and Flash
 
-When a user has her code ready, she can connect her BBC micro:bit to a computer via a USB cable, so it appears as a mounted drive.
+When a user has her code ready, she can connect her BBC micro:bit to a computer via a USB cable, so it appears as a mounted drive (named MICROBIT). 
 
 Compilation to the ARM thumb machine code happens in the browser.
 
@@ -47,6 +47,7 @@ The student is prompted to save the ARM binary program to a file, which she then
 which flashes the micro:bit device with the new program.
 
 ## Simulator: Test Your Code
+
 Before a student compiles her code for the micro:bit, she can run it using the micro:bit simulator, all within the confines of a web browser. 
 The simulator has support for the LED screen, buttons, as well as compass, accelerometer, and digital I/O pins.
 
@@ -54,5 +55,10 @@ The simulator has support for the LED screen, buttons, as well as compass, accel
 
 The [C++ BBC micro:bit runtime](http://lancaster-university.github.io/microbit-docs/), created at [Lancaster University](http://www.lancaster.ac.uk/), provides access to the hardware functions of the micro:bit, 
 as well as a set of helper functions (such as displaying a number/image/string on the LED screen). 
+
 The JavaScript micro:bit library mirrors the functions of the C++ library. 
 When code is compiled to ARM machine code, the calls to JavaScript micro:bit functions are replaced with calls to the corresponding C++ functions.
+
+## Open Source
+
+The editor for the BBC micro:bit is [open source](/open-source) on GitHub. Contributors are welcome!

docs/blocks.md

@@ -0,0 +1,8 @@
+# Blocks language
+
+```namspaces
+for (let i = 0;i<5;++i) {}
+if (true){}
+let x = 0;
+Math.random(5);
+```

docs/device.md

@@ -15,12 +15,14 @@ It flashes yellow when the system wants to tell the user that something has happ
 ### Buttons
 
 Buttons A and B are a form of input.  When you press a button, it completes an electrical circuit. 
-The micro:bit can detect either of its two buttons being pressed and un-pressed and be programmed 
-to act on that or send the information to another device.
+The micro:bit can detect either of its two buttons being pressed/released and be programmed 
+to act on these events.
 
 Button R on the back of the micro:bit is a system button. It has different uses. 
 When you have downloaded and run your code onto your micro:bit, press Button R to restart and run your program from the beginning.
 
+### USB connection
+
 When you plug in your micro:bit, it should appear as MICROBIT. 
 If you accidentally hold down the reset button as you’re plugging in your micro:bit, 
 the micro:bit will appear as a MAINTENANCE drive instead of MICROBIT. This is known as maintenance mode.**
@@ -43,7 +45,7 @@ This data can be used by the micro:bit in a program or be sent to another device
 
 ### Accelerometer
 
-There is a an accelerometer on your micro:bit which detects changes in the micro:bit’s speed. 
+There is an accelerometer on your micro:bit which detects changes in the micro:bit’s speed. 
 It converts analogue information into digital form that can be used in micro:bit programs. 
 Output is in milli-g. The device will also detect a small number of standard actions e.g. shake, tilt and free-fall.
 
@@ -63,15 +65,19 @@ and about the error messages you might get [here](/device/error-codes).
 
 ### Powering your micro:bit
 
-When your micro:bit  is connected to your computer with the micro USB, it doesn’t need another power source.  
+When your micro:bit is connected to your computer with the micro USB, it doesn’t need another power source.  
 When your micro:bit isn’t connected to your computer, tablet or mobile, you will need 2 x AAA 1.5 V batteries to power it.
 
 The pins labelled 3V and GND are the power supply pins. 
 You can attach an external device such as a motor to these and power it using the battery or USB.
 
-### Bluetooth Low Energy Antenna
+### Serial Communication
 
-You will see the label BLE ANNTENA on the back of your micro:bit. It is for a messaging service, 
+The BBC micro:bit can send an receive data via [serial communication](/device/serial). The serial data can be transfered via USB or BlE.
+
+### Bluetooth Low Energy (BLE) Antenna
+
+You will see the label BLE ANTENNA on the back of your micro:bit. It is for a messaging service, 
 so that devices can talk to each other. The micro:bit is a peripheral 
 device which can talk to a central device like a smart phone or tablet that has Bluetooth Low Energy (BLE). 
 The micro:bit can send signals and receive signals from a central device so another BLE device can 

docs/device/contents.md

@@ -1,7 +1,5 @@
 # micro:bit - the device
 
-The micro:bit device #docs
-
 The micro:bit is a very capable device with many components:
 
 * [the USB connector](/device/usb)

docs/device/crocodile-clips.md

@@ -1,8 +1,7 @@
 # crocodile clips
 
-The on pin pressed accessories. 
-
-Register an [event handler](/reference/event-handler) that will execute whenever the user attaches one side of the crocodile clip to the `GND` pin, then connects and disconnects the unattached side of the crocodile clip to pin `0`, `1`, or `2`.
+The large holes at the bottom of the board are designed to attach alligator/crocodile clips.
+Register an event that will execute whenever the user attaches one side of the crocodile clip to the `GND` pin, then connects and disconnects the unattached side of the crocodile clip to pin `0`, `1`, or `2`.
 
 ### Example: on pin pressed with random numbers
 
@@ -12,14 +11,6 @@ This example displays a random number every time the crocodile clip holds  `GND`
 
 ### Connecting Crocodile Clips
 
-![](/static/mb/crocodile-clips-1.jpg)
-
-![](/static/mb/crocodile-clips-2.jpg)
-
-### Lessons
-
-[love meter](/lessons/love-meter)
-
 ### See also
 
 [micro:bit pins](/device/pins), [pin is pressed](/reference/input/pin-is-pressed), [analog read pin](/reference/pins/analog-read-pin), [analog write pin](/reference/pins/analog-write-pin), [digital read pin](/reference/pins/digital-read-pin), [digital write pin](/reference/pins/digital-write-pin)

docs/device/error-codes.md

@@ -1,6 +1,6 @@
 # Error codes
 
-The micro:bit error codes #docs
+The micro:bit error codes
 
 Your micro:bit may encounter a situation that prevents it from running your code. When this happens, a frowny face will appear on your micro:bit screen (see picture) followed by an error number.
 

docs/device/reactive.md

@@ -1,7 +1,5 @@
 # The micro:bit - a reactive system
 
-The micro:bit is a reactive system. #docs
-
 ### Computing systems
 
 What sort of a *computing system* is the micro:bit?

docs/device/screen.md

@@ -2,56 +2,89 @@
 
 The micro:bit LED screen 
 
-![](/static/mb/device/screen-0.png)
+```sim
+    basic.showLeds(`
+        # . # . #
+        . # . # .
+        # . # . #
+        . # . # .
+        # . # . #
+        `);
+```
 
 The micro:bit LED screen consists of 25 red LED lights arranged in a 5X5 grid (5 LEDs across by 5 LEDs down).
+In the screen above, we created a checkerboard pattern using the LEDs.
 
 ### Which LED?
 
-You use ``x , y`` coordinates to specify a particular LED in the grid; where ``x`` is the horizontal position and ``y`` is the vertical position (0, 1, 2, 3, 4). To figure out the ``x``, ``y`` coordinates, position your micro:bit horizontally, like a credit card (see picture above).
+You use `(x ,y)` coordinates to specify a particular LED in the grid; 
+where `x` is the horizontal position (0,1,2,3,4) and `y` is the vertical position 
+(0, 1, 2, 3, 4). 
+
+To figure out the ``x``, ``y`` coordinates, position your micro:bit horizontally, like a credit card (see picture above).
 
 Here are the x, y coordinates for the LEDs in the 5X5 grid:
 
-`0, 0` `1, 0` `2, 0` `3, 0` `4, 0`
+`(0,0)` `(1,0)` `(2,0)` `(3,0)` `(4,0)`
 
-`0, 1` `1, 1` `2, 1` `3, 1` `4, 1`
+`(0,1)` `(1,1)` `(2,1)` `(3,1)` `(4,1)`
 
-`0, 2` `1, 2` `2, 2` `3, 2` `4, 2`
+`(0,2)` `(1,2)` `(2,2)` `(3,2)` `(4,2)`
 
-`0, 3` `1, 3` `2, 3` `3, 3` `4, 3`
+`(0,3)` `(1,3)` `(2,3)` `(3,3)` `(4,3)`
 
-`0, 4` `1, 4` `2, 4` `3, 4` `4, 4`
+`(0,4)` `(1,4)` `(2,4)` `(3,4)` `(4,4)`
 
-The x, y coordinates for the LED in the centre of the grid are `2, 2`. Starting from `0, 0` count over 2 columns and then down 2 rows.
+The x, y coordinates for the LED in the centre of the grid are `(2,2)`. Starting from `(0,0)` count over 2 columns and then down 2 rows.
+
+### Check your understanding
+
+Which LEDs are turned on in the checkboard pattern above? 
 
 ### Row, column - 1
 
-Since the row and column numbers start at 0, an easy way to figure out the x, y coordinates is to subtract 1 from the row and column number (when counting from 1). In other words, to specify the LED in the 4th column 5th row, subtract 1 from each number to get coordinates `3, 4`.
+Since the row and column numbers start at 0, an easy way to figure out the (x,y) coordinates 
+is to subtract 1 from the row and column number (when counting from 1). 
+In other words, to specify the LED in the 4th column 5th row, subtract 1 from each number to get coordinates `(3,4)`.
 
 ### Turn a LED on/off
 
-Use [plot](/led/plot) and [unplot](/led/unplot) to turn a LED on or off
+Use [plot](/reference/led/plot) and [unplot](/reference/led/unplot) to turn a LED on or off
+
+```blocks
+led.plot(0,0);
+led.plot(1,1);
+basic.pause(1000);
+led.unplot(0,0);
+basic.pause(1000);
+led.unplot(1,1);
+```
 
 ### Is a LED on/off?
 
-Use the [point](/led/point) function to find out if a LED is on or off.
+Use the [point](/reference/led/point) function to find out if a LED is on or off.
+
+```blocks
+if(led.point(0,0)) {
+}
+```
 
 ### Display images, strings and numbers
 
-Instead of turning individual LEDs on or off, as above, you can display an [image](/reference/image/image) directly to the screen or show text/numbers on screen using the [show number](/reference/basic/show-number)/[show string](/reference/basic/show-string) function.
+Instead of turning individual LEDs on or off, as above, you can display an [image](/reference/images/image) directly to the screen or show text/numbers on screen using the [show number](/reference/basic/show-number)/[show string](/reference/basic/show-string) function.
 
 ### The display buffer
 
 The micro:bit runtime keeps an in-memory representation of the state of all 25 LEDS. This state is known as the "display buffer" and controls which LEDS are on and which are off. The plot/unplot/point functions access the display buffer directly. On the other hand, the functions that show an image, number or string overwrite the buffer completely. To illustrate, first try running this code sequence
 
-```
-basic.showString("d", 150)
+```blocks
+basic.showString("d")
 led.plot(0, 0)
 ```
 
 You will see the letter "d" displayed as well as the LED in position `0,0` lit up. Now try reversing the order of the two statements above:
 
-```
+```blocks
 led.plot(0, 0)
 basic.showString("d", 150)
 ```

docs/device/serial.md

@@ -0,0 +1,83 @@
+# Serial
+
+The [serial](/reference/serial) supports [serial communication](https://en.wikipedia.org/wiki/Serial_port) between the BBC micro:bit and another computer. Basically, this allows you to send data from the micro:bit to your own computer. This is very useful for debugging purposes: you can add `write line` statements in your code and see them display on your computer as the program executes.
+
+The code below shows a simple script that sends a line when the BBC micro:bit starts and another line each time the button ``A`` is pressed.
+
+```blocks
+serial.writeLine("started...")
+input.onButtonPressed(Button.A, () => {
+    serial.writeLine("A pressed")
+})
+```
+
+Data is also automatically streamed to serial by the ** bar graph** block
+and picked up by the editor. This data can be streamed to the cloud as well.
+
+```blocks
+basic.forever(() => {
+   led.plotBarGraph(input.acceleration(Dimension.X), 0);
+});
+```
+
+## How to read the micro:bit's serial output from your computer
+
+Unfortunately, using the serial library requires quite a bit of a setup.
+
+### BBC micro:bit Chrome Extension
+
+If you are using the Google Chrome browser, you can use our extension to get serial data streaming in the editor.
+
+* Install the [Extension for BBC micro:bit](https://chrome.google.com/webstore/detail/extension-for-bbc-microbi/cihhkhnngbjlhahcfmhekmbnnjcjdbge?hl=en-US) on the Chrome Web Store.
+* Restart Chrome and open the web editor.
+
+### Windows
+
+You must install a device driver (for the computer to recognize the serial interface of the micro:bit); then, you must also install a terminal emulator (which is going to connect to the micro:bit and read its output). Here's how to do it:
+
+* Follow instructions at https://developer.mbed.org/handbook/Windows-serial-configuration in order to install the device driver
+
+#### Windows > Tera Term
+
+* Install the terminal emulator [Tera Term](https://ttssh2.osdn.jp/index.html.en). At the time of this writing, the latest version is 4.88 and can be downloaded [from here](http://en.osdn.jp/frs/redir.php?m=jaist&f=%2Fttssh2%2F63767%2Fteraterm-4.88.exe). Follow the instructions from the installer.
+
+Once both the driver and the terminal emulator are installed, plug in the micro:bit and wait until the device is fully setup. Then, open TeraTerm.
+
+* Hit `File` > `New Connection`
+* Check "Serial"; in the dropdown menu, pick the COM port that says "mbed Serial Port". Hit `Ok`.
+* In the menus, hit `Setup` > `Serial Port` and set the baud rate to `115200`.
+
+You should be good. Feel free to hit `Setup` > `Save Setup` in the menus to erase the default configuration file with a new one so that you don't have to type in the settings again.
+
+Please note that Windows will assign you a different COM port if you plug in another micro:bit. If you're juggling between micro:bits, you'll have to change the COM port every time.
+
+#### Windows > Putty
+
+If you prefer another terminal emulator (such as [PuTTY](http://www.putty.org/)), here are some instructions.
+
+* Open Windows's [Device Manager](https://windows.microsoft.com/en-us/windows/open-device-manager); expand the section called "Ports (COM & LPT)"; write down the com number for "mbed Serial Port" (e.g. COM14)
+* Open PuTTY; on the main screen, use the following settings: Serial / COM14 / 115200. Replace COM14 with the COM port number you wrote down previously. Feel free to type in a name and hit "Save" to remember this configuration.
+
+![](/static/mb/serial-library-0.png)
+
+* (optional): in the "Terminal" section, check "implicit cr in every lf"
+
+![](/static/mb/serial-library-1.png)
+
+### Linux
+
+(Untested).
+
+* Plug in the micro:bit
+* Open a terminal
+* `dmesg | tail` will show you which `/dev/` node the micro:bit was assigned (e.g. `/dev/ttyUSB0`)
+* Then, do: `screen /dev/ttyUSB0 115200` (install the `screen` program if you don't have it). To exit, run `Ctrl-A` `Ctrl-D`.
+
+Alternative programs include minicom, etc.
+
+### Mac OS
+
+* Plug in the micro:bit
+* Open a terminal
+* `ls /dev/cu.*` will return to you a list of serial devices; one of them will look like `/dev/cu.usbmodem1422` (the exact number depends on your computer)
+* `screen /dev/cu.usbmodem1422 115200` will open up the micro:bit's serial output. To exit, hit `Ctrl-A` `Ctrl-D`.

docs/device/simulator.md

@@ -0,0 +1,25 @@
+# Simulator
+
+The JavaScript simulator allows to test and execute most BBC micro:bit programs in the browser.
+It allows to emulate sensor data or user interactions.
+
+```sim
+input.onButtonPressed(Button.A, () => {
+   basic.showString("A");
+});
+input.onButtonPressed(Button.B, () => {
+   basic.showString("B");
+});
+input.onPinPressed(TouchPin.P0, () => {
+   basic.showString("0");
+});
+input.onPinPressed(TouchPin.P1, () => {
+   basic.showString("1");
+});
+input.onPinPressed(TouchPin.P2, () => {
+   basic.showString("2");
+});
+input.temperature()
+input.compassHeading()
+input.lightLevel()
+```

docs/device/usb.md

@@ -2,7 +2,7 @@
 
 How to compile, transfer, and run a script on your micro:bit.
 
-While you're writing and testing your Block Editor or Touch Develop scripts, you'll mostly be running scripts in your browser by clicking the `Run` button (see [run code in your browser](/js/simulator) for info about this).
+While you're writing and testing your Block Editor or Touch Develop scripts, you'll mostly be running scripts in your browser by clicking the `Run` button (see [run code in your browser](/device/simulator) for info about this).
 
 Once your masterpiece is complete, you can compile your script and run it on your micro:bit.
 
@@ -31,12 +31,6 @@ Windows
 Mac (picture bvabdbco)
 WARN: unknown picture: bvabdbco:5x3
 
-### ~hide
-
-If your computer doesn't recognise your micro:bit, please see [troubleshooting USB problems](/diagnosing-usb).
-
-### ~
-
 ## Step 2: Compile your script
 
 Next, compile your script:
@@ -133,5 +127,5 @@ Or it may appear that there are two hex files on your micro:bit so the micro:bit
 
 ### See also
 
-[Run code in a browser](/js/simulator)
+[Run code in a browser](/device/simulator)
 

docs/docs.md

@@ -1,7 +1,36 @@
 # 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(`
+. # . # .
+# . # . #
+# . . . #
+. # . # .
+. . # . .`);
+});
+``` 
 
-* Browse the [reference](/reference)
+* **[getting started](/getting-started)**
+* Get started with [projects](/projects)
+* Browse the [API reference](/reference)
 * Learn more about the [device](/device)
-* Get started with [lessons](/lessons)
+* Frequently Asked Question [faq](/faq)
+* Follow up with the [release notes](/release-notes)
+
+### Developers
+
+* Learn about [packages](/packages) (possibly using C++ or ARM thumb)

docs/faq.md

@@ -0,0 +1,6 @@
+# Frequently Asked Questions
+
+## Where can I get a BBC micro:bit?
+
+More information at [http://uk.farnell.com/bbc-microbit](http://uk.farnell.com/bbc-microbit).
+

docs/getting-started.md

@@ -0,0 +1,502 @@
+# Getting started
+
+## ~avatar
+
+Are you ready to build cool BBC micro:bit programs?
+
+Here are some challenges for you. Unscramble the blocks in the editor
+to make real programs that work!
+
+## ~
+
+### Happy face
+
+There are three blocks in the editor (the area to the left).
+They should look like this:
+
+```blocks
+basic.forever(() => {
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        # . . . #
+        . # # # .
+        `)
+    basic.showLeds(`
+        . . . . .
+        . . . . .
+        . . . . .
+        . . . . .
+        . . . . .
+        `)
+});
+```
+
+When you run this program, you will see a smiley face, then a blank
+screen, then a smiley again -- it never stops! (That's because of the
+``forever`` block.)
+
+Click **Compile** to move your program to the BBC micro:bit!
+
+### Happy unhappy face
+
+Draw an unhappy face instead of the blank screen.  Click on the dots
+in the second ``show leds`` block until it matches the blocks below.
+Now you have an **animation** (cartoon) that shows a happy face,
+then an unhappy one, then a happy one again, forever (or until
+you turn off your micro:bit)!
+
+```blocks
+basic.forever(() => {
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        # . . . #
+        . # # # .
+        `)
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        . # # # .
+        # . . . #
+        `)
+});
+```
+Click **Compile** to move your program to the BBC micro:bit!
+
+### Your turn!
+
+Pile up more ``show leds`` blocks to create your animation! Create an
+animation with at least 5 pictures.  What does this animation show?
+
+```blocks
+basic.forever(() => {
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        # . . . #
+        . # # # .
+        `)
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        # # # # #
+        . . . . .
+        `)
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        . # # # .
+        # . . . #
+        `)
+    basic.showLeds(`
+        . . . . .
+        . # . # .
+        . . . . .
+        # # # # #
+        . . . # #
+        `)
+    basic.showLeds(`
+        . . . . .
+        # . # . .
+        . . . . .
+        # . . . #
+        . # # # .
+        `)
+    basic.showLeds(`
+        . . . . .
+        . . # . #
+        . . . . .
+        # . . . #
+        . # # # .
+        `)
+});
+```
+Click **Compile** to move your program to the BBC micro:bit!
+
+#### ~hint
+
+You can find the ``show leds`` block in the **Basic** part of the editor.
+
+#### ~
+
+### Button A and button B
+
+This program will show the word **ANTEATER** on the LED
+screen when you press button `A`.
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    basic.showString("ANTEATER");
+});
+```
+
+#### ~hint
+
+The ``showString`` block can show letters, numbers, and punctuation
+on the micro:bit screen.
+
+#### ~
+
+Now try to unscramble these blocks in the editor so that the micro:bit
+shows **BANANA** when you press button `B`.
+
+```shuffle
+input.onButtonPressed(Button.B, () => {
+    basic.showString("BANANA");
+});
+```
+#### ~hint
+
+You can find the letter `B` by clicking the letter `A` on the
+``onButtonPressed`` block.
+
+#### ~
+
+Click **Compile** to move your program to the BBC micro:bit!
+
+#### Your turn!
+
+Can you combine these blocks so your program shows your real name
+instead of **ANTEATER** when you press `A`, but _your secret agent
+name_ instead of **BANANA** when you press `B`?
+
+### Shake
+
+You can find when someone is shaking the BBC micro:bit by checking its
+**accelerometer** (it finds whether the micro:bit is speeding up or
+slowing down).
+
+Unscramble these blocks in the editor to show a frownie when someone
+shakes the micro:bit. (Ouch!)
+
+```shuffle
+input.onGesture(Gesture.Shake, () => {
+    basic.showLeds(`
+. . . . .
+. # . # .
+. . . . .
+. # # # .
+# . . . #`);
+});
+```
+Click **Compile** to move your program to the BBC micro:bit!
+
+### Pins
+
+You can also use the pins as buttons.  (The pins are the holes in the
+metal stripe at the bottom of the micro:bit board.)  For example, hold
+the ``GND`` button with one hand and touch the ``0`` pin (called
+``P0``) with your other hand to tell the micro:bit you're pressing it.
+
+Unscramble the blocks in the editor to show a heart when you touch
+pin ``P0``.
+
+```shuffle
+input.onPinPressed(TouchPin.P0, () => {
+    basic.showLeds(`
+. # . # .
+# . # . #
+# . . . #
+. # . # .
+. . # . .`);
+});
+```
+Click **Compile** to move your program to the BBC micro:bit!
+
+## ~hint
+
+Try this experiment: find a friend and hold hands. Touch the ``GND``
+pin while your friend presses the ``P0`` pin. You should see the
+heart! The electric current is going through your bodies and across
+your handshake to make it happen!
+
+## ~
+
+## The amazing coin flipper
+
+### ~avatar avatar
+
+Are you trying to choose whether to play soccer or go to the movies
+instead, or which toppings to have on your pizza?  Build a coin
+flipping machine with the BBC micro:bit to choose for you!
+
+### ~
+
+Here are the blocks to make your coin flipper.  When you press button
+`B`, the coin flipper will show either `H` for heads or `T` for tails
+on the LED screen.
+
+```blocks
+input.onButtonPressed(Button.B, () => {
+    if (Math.randomBoolean()) {
+        basic.showString("H");
+    } else {
+        basic.showString("T");
+    }
+});
+```
+### ~hint
+
+The ``pick random true or false`` block randomly tells the ``if``
+block `true` or `false`.  If the ``pick`` block picked `true`, the
+``if`` block shows the letter `H`. Otherwise, it shows the letter `T`.
+
+That's it!
+
+### ~
+
+### Keeping score
+
+#### ~avatar
+
+To keep track out of how many guesses you've won,
+add these blocks to your coin flipper:
+
+#### ~
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    game.addScore(1);
+});
+input.onButtonPressed(Button.AB, () => {
+    basic.showNumber(game.score());
+});
+```
+
+These blocks mean that if you press button `A`, you will add `1` to
+your score, and if you press `A` and `B` together, the micro:bit will
+show your score.
+
+When you're done, your coin flipping program should look like this:
+
+```blocks
+input.onButtonPressed(Button.B, () => {
+    if (Math.randomBoolean()) {
+        basic.showString("H");
+    } else {
+        basic.showString("T");
+    }
+});
+input.onButtonPressed(Button.A, () => {
+    game.addScore(1);
+});
+input.onButtonPressed(Button.AB, () => {
+    basic.showNumber(game.score());
+});
+```
+
+Flip until your thumbs get tired!
+
+## Let's play Rock Paper Scissors!
+
+### ~avatar avatar
+
+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.  (The game is built
+like a coin flipper, but with three choices instead of two.)
+
+### ~
+
+## 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.
+
+Clear up the blocks and add the blocks below.
+
+```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 `item`.
+
+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 item = 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
+`item` 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 item = Math.random(3)
+    if (item == 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 `item` is `1`.
+Then add a ``show leds`` block with a picture of a rock.
+
+```blocks
+input.onGesture(Gesture.Shake, () => {
+    let item = Math.random(3)
+    if (item == 0) {
+        basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+    } else if (item == 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 item = Math.random(3)
+    if (item == 0) {
+        basic.showLeds(`
+            # # # # #
+            # . . . #
+            # . . . #
+            # . . . #
+            # # # # #
+            `)
+
+    } else if (item == 1) {
+        basic.showLeds(`
+            . . . . .
+            . # # # .
+            . # # # .
+            . # # # .
+            . . . . .
+            `)
+    } else {
+        basic.showLeds(`
+            # # . . #
+            # # . # .
+            . . # . .
+            # # . # .
+            # # . . #
+            `)
+    }
+})
+
+```
+
+### ~hint
+
+You don't need to check if `item` 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!
+
+Click **Compile** to move your program to the BBC micro:bit!
+
+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())
+})
+```
+Click **Compile** to move your program to the BBC micro:bit!
+
+## Your turn!
+
+How else can you make your game better?
+Ever hear of [Rock Paper Scissors Spock Lizard](http://www.samkass.com/theories/RPSSL.html)?

docs/lessons/banana-keyboard.md

@@ -1,21 +0,0 @@
-# banana keyboard blocks lesson
-
-display beautiful images on the BBC micro:bit.
-
-## Topic
-
-Music
-
-## Quick Links
-
-* [activity](/lessons/banana-keyboard/activity)
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to convert your BBC micro:bit into a music player using pins P0 and GND, earphones (or speakers), as well as crocodile clips (or spring clips). The connect fruit using pins P1 and GND.
-
-## Objectives
-
-* learn how to setup the BBC micro:bit with earphones to play music
-* learn how to setup the BBC micro:bit with fruit be the musical instrument
-

docs/lessons/beatbox.md

@@ -1,22 +0,0 @@
-# beatbox blocks lesson
-
-display beautiful images on the BBC micro:bit.
-
-## Topic
-
-Music
-
-## Quick Links
-
-* [activity](/lessons/beatbox/activity)
-* [challenges](/lessons/beatbox/challenges)
-
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to make a beatbox music player using pins P1 and P2. We will be learning how to code musical notes using a local variable, for loop, on pin pressed as well as simple commands such as play and notes.
-
-## Objectives
-
-* learn how to code music on the BBC micro:bit
-

docs/lessons/buzzer.md

@@ -1,81 +0,0 @@
-# buzzer lesson 
-
-design a blinking image lesson #docs
-
-## Topic 
-
-Ring
-
-## Quick Links
-
-* [activity](/lessons/buzzer/activity)
-* [challenges](/lessons/buzzer/challenges)
-
-## Class
-
-Year 7
-
-## Prior learning / place of lesson in scheme of work
-
-Learn how to **ring** the buzzer to turn on the sound. We will be learning basic comments such as ring and clear screen.
-
-## Documentation
-
-* **ring** : [read more...](/reference/music/ring)
-* **clear screen** : [read more...](/reference/basic/clear-screen)
-* **on button pressed** : [read more...](/reference/input/on-button-pressed)
-
-## Objectives
-
-* learn how to ring the BBC micro:bit
-* learn how to clear the screen
-* learn how to run code when an input button is pressed
-
-## Progression Pathways / Computational Thinking Framework
-
-#### Algorithms
-
-* Designs solutions (algorithms) that use repetition and two-way  selection, ie if, then and else.(AL)
-* Uses diagrams to express solutions.(AB)
-*  Uses logical reasoning to predict  outputs, showing an awareness of inputs (AL)
-* Recognises that different algorithms exist for the same problem (AL) (GE)
-* Represents solutions using a structured notation (AL) (AB)
-
-#### Programming & Development
-
-* Creates programs that implement algorithms to achieve given goals (AL)
-* Selects the appropriate data types(AL) (AB
-
-#### Data & Data Representation
-
-* Understands the difference between data and information(AB)
-
-#### Hardware & Processing
-
-* Understands the difference between hardware and application software, and their roles within a computer system (AB)
-
-#### Communication Networks
-
-* Demonstrates responsible use of technologies and online services, and knows a range of ways to report concerns (AL)
-
-#### Information Technology
-
-* Collects, organizes, and presents data and information in digital content (AB)
-* Makes appropriate improvements to solutions based on feedback received, and can comment on the success of the solution (EV)
-
-Computational Thinking Concept: AB = Abstraction; DE = Decomposition; AL = Algorithmic Thinking; EV = Evaluation; GE = Generalisation
-
-## Activity
-
-* time: 20 min.
-* [activity](/lessons/buzzer/activity)
-
-## Extended Activity
-
-* time: 20 min.
-* [challenges](/lessons/buzzer/challenges)
-
-## Homework
-
-* Extended Activity: [challenges](/lessons/buzzer/challenges)
-

docs/lessons/charting/activity.md

@@ -1,53 +0,0 @@
-# charting activity
-
-Measure the acceleration on the micro:bit in the "z" direction. 
-
-### ~avatar avatar
-
-### ~
-
-Welcome! This activity will teach how to use the 1st micro:bit to chart the second micro:bit's acceleration in the "x" direction. Let's get started!
-
-Let's measure `acceleration (mg)` and then `send number`. `Acceleration` is measured in **milli-gravities**, so a value of -1000 is equivalent to -1g or -9.81m/s^2. We will be able to get the acceleration value (g-force), in the specified "x" dimension. `Send number` will broadcast a number data packet to other micro:bits connected via radio.
-
-```blocks
-radio.sendNumber(input.acceleration(Dimension.X));
-```
-
-We want to display the acceleration forever. In order to do so, we need a `forever` loop. A forever loop will repeat code in the background forever.
-
-```blocks
-basic.forever(() => {
-    radio.sendNumber(input.acceleration(Dimension.X));
-});
-
-
-```
-
-We want to register code to run when a packet is received over radio. We can implement this code by adding `on data received`.
-
-```blocks
-basic.forever(() => {
-    radio.sendNumber(input.acceleration(Dimension.X))
-})
-radio.onDataReceived(() => {
-    
-})
-```
-
-Finally, we want to chart the acceleration. So we must first implement `plot bar graph`. `Plot Bar Graph` will display a vertical bar graph based on the value and high value. In order to transfer the receive the number from the 1st micro:bit, we must implement `receive number` to constantly display a vertical bar graph based on the value. Remember, the value will equal to the micro:bit's acceleration in the "x" direction.
-
-```blocks
-basic.forever(() => {
-    radio.sendNumber(input.acceleration(Dimension.X))
-})
-radio.onDataReceived(() => {
-    led.plotBarGraph(radio.receiveNumber(), 1023)
-})
-
-```
-
-
-* Connect the first micro:bit to your computer using your USB cable and run the charting script on it.
-* Connect the second micro:bit to your computer using your USB cable and run the charting script on it.
-* The first person and second person take turns tilting the micro:bit in the "x" direction while the other player charts the data on the micro:bit!

docs/lessons/crocodile-clip/activity.md

@@ -1,41 +0,0 @@
-# crocodile clip activity 
-
-Use the crocodile clips 
-
-# micro:bit crocodile clip
-
-![](/static/mb/blocks/lessons/crocodile-clip-0.jpg)
-
-In this project, you will build a circuit with the micro:bit from crocodile clips. Project duration: 15 minutes.
-
-## Materials
-
-* micro:bit, battery holder and 2 AAA batteries
-* Crocodile clips
-
-## Steps
-
-### Step 1
-
-![](/static/mb/lessons/banana-keyboard-1.png)
-
-Using the 1st crocodile clip, connect the end of the crocodile clip onto GND pin on the micro:bit.
-
-### Step 2
-
-![](/static/mb/crocodile-clips-2.jpg)
-
-Using the 1st crocodile clip, connect the unattached end of the crocodile clip onto the 0 pin on the micro:bit.
-
-### Step 3
-
-![](/static/mb/blocks/lessons/crocodile-clip-0.jpg)
-
-Disconnect the end of the crocodile clip from the 0 pin of the micro:bit.
-
-Your circuit is complete!
-
-### Step 10
-
-Connect your micro:bit to your computer using your USB cable and run the [guess the number](/lhpkbr) script on it.
-

docs/lessons/glowing-sword.md

@@ -1,30 +0,0 @@
-# glowing sword blocks lesson
-
-make a glowing sword.
-
-### @video td/videos/glowing-sword-0
-
-## Topic
-
-Fade Out
-
-## Quick Links
-
-* [activity](/lessons/glowing-sword/activity)
-* [quiz](/lessons/glowing-sword/quiz)
-* [quiz answers](/lessons/glowing-sword/quiz-answers)
-* [challenges](/lessons/glowing-sword/challenges)
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to manipulate an image through **fade out**, `fade out` to gradually decrease the LED screen brightness until the LED lights are turned off. We will be learning how to fade an image using simple commands, such as image create image, image show image, LED fade out, basic pause, and fade in.
-
-## Documentation
-
-* **create image** : [read more...](/reference/images/create-image)
-* **show image** : [read more...](/reference/images/show-image)
-* **fade out** : [read more...](/reference/led/fade-out)
-* **pause** : [read more...](/reference/basic/pause)
-* **fade in** : [read more...](/reference/led/fade-in)
-
-

docs/lessons/hack-your-headphones.md

@@ -1,20 +0,0 @@
-# hack your headphones lesson
-
-display beautiful images on the BBC micro:bit.
-
-## Topic
-
-Hack your headphone
-
-## Quick Links
-
-* [activity](/lessons/hack-your-headphones/activity)
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to convert your BBC micro:bit into a music player using pins P0 and GND, headphones (or speakers), as well as crocodile clips (or spring clips).
-
-## Objectives
-
-* learn how to setup the BBC micro:bit with headphones to play music
-

docs/lessons/light-beatbox.md

@@ -1,21 +0,0 @@
-# light beatbox 
-
-display beautiful images on the BBC micro:bit.
-
-## Topic
-
-Music
-
-## Quick Links
-
-* [activity](/lessons/light-beatbox/activity)
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to make a light beatbox music player using the light sensor. We will be learning how to code musical notes using light level, a local variable, conditionals, on button pressed as well as simple commands such as ring tone and rest.
-
-## Objectives
-
-* learn how to control the light sensor on the BBC micro:bit
-* learn how to code music on the BBC micro:bit
-

docs/lessons/rock-paper-scissors.md

@@ -1,64 +0,0 @@
-# rock paper scissors lesson
-
-a game against the BBC micro:bit.
-
-### @video td/videos/rock-paper-scissors-0
-
-## Topic
-
-Local Variables
-
-## Quick Links
-
-* [activity](/lessons/rock-paper-scissors/activity)
-* [challenges](/lessons/rock-paper-scissors/challenges)
-
-## Class
-
-Year 7
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to create a **local variable**, `var t :=time` where you can store data, so that you can use it in your code. We will be learning how to create a classic rock paper scissors game using global variables, input on shake, local variables, math random as well as simple commands such as create image, show image, show string, and show number.
-
-## Documentation
-
-```cards
-input.onGesture(Gesture.Shake, () => {})
-Math.random(3)
-let x = 0
-basic.showLeds(`
-    . . . . .
-    . . . . .
-    . . # . .
-    . . . . .
-    . . . . .
-    `)
-```
-
-## Objectives
-
-* learn how to create a condition so the micro:bit will run code when it is shaken
-* learn how to create a local variable for a place where you can store data
-* learn how to create an image to show on the micro:bit's LED screen
-* learn how to show an image on the micro:bit's LED screen
-
-## Progression Pathways / Computational Thinking Framework
-
-#### Algorithms
-
-* Uses diagrams to express solutions.(AB)
-* Represents solutions using a structured notation (AL) (AB)
-
-#### Programming & Development
-
-* Creates programs that implement algorithms to achieve given goals (AL)
-*  Declares and assigns variables(AB)
-* Selects the appropriate data types(AL) (AB
-
-#### Data & Data Representation
-
-* Defines data types: real numbers and Boolean (AB)
-
-Computational Thinking Concept: AB = Abstraction; DE = Decomposition; AL = Algorithmic Thinking; EV = Evaluation; GE = Generalisation
-

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

@@ -1,121 +0,0 @@
-# rock paper scissors activity
-
-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!
-
-### ~
-
-We want the micro:bit to choose rock, paper, or scissors when it is shaken. Let's begin by creating an on shake condition so the micro:bit will run code when it is shaken.
-
-
-```blocks
-
-input.onGesture(Gesture.Shake, () => {
-    
-})
-
-```
-
-Next, create a variable and store pick random number from 0 to 2.  On shake, a number will be randomly picked from 0-2. We will randomly display an image based on the random number returned.
-
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(3)
-})
-
-```
-
-The micro:bit will look like it's showing 1 frame of the image by displaying the whole image when pick random is equal to 2. We can help the micro:bit randomly decide which image to use by pick random. The micro:bit will randomly pick the image to display with show LEDs and the pick random function.
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(3)
-    if (img == 2) {
-        basic.showLeds(`
-            # # # # #
-            # . . . #
-            # . . . #
-            # . . . #
-            # # # # #
-            `)
-
-    }
-})
-
-
-```
-
-The micro:bit will look like it's showing 1 frame of the image by displaying the whole image when pick random is equal to 1. We can help the micro:bit randomly decide which image to use by pick random. The micro:bit will randomly pick the image to display with show LEDs and the pick random function.
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(3)
-    if (img == 2) {
-        basic.showLeds(`
-            # # # # #
-            # . . . #
-            # . . . #
-            # . . . #
-            # # # # #
-            `)
-
-    } else if (img == 1) {
-        basic.showLeds(`
-            . . . . .
-            . # # # .
-            . # # # .
-            . # # # .
-            . . . . .
-            `)
-    }
-})
-```
-
-The micro:bit will look like it's showing 1 frame of the image by displaying the whole image when pick random is not equal to 2 and not equal to 1. We can help the micro:bit randomly decide which image to use by pick random. The micro:bit will randomly pick the image to display with show LEDs and the pick random function.
-
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(3)
-    if (img == 2) {
-        basic.showLeds(`
-            # # # # #
-            # . . . #
-            # . . . #
-            # . . . #
-            # # # # #
-            `)
-
-    } else if (img == 1) {
-        basic.showLeds(`
-            . . . . .
-            . # # # .
-            . # # # .
-            . # # # .
-            . . . . .
-            `)
-    } else {
-        basic.showLeds(`
-            . . . # #
-            # # . # .
-            . . # . .
-            # # . # .
-            . . . # #
-            `)
-    }
-})
-
-```
-
-### ~avatar avatar
-
-Excellent, you're ready to continue with the [challenges](/lessons/rock-paper-scissors/challenges)!
-
-### ~
-

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

@@ -1,133 +0,0 @@
-# rock paper scissors challenges
-
-Coding challenges for rock paper scissors. 
-
-## Before we get started
-
-Complete the following [guided activity](/lessons/rock-paper-scissors/activity) , your code should look like this:
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(3)
-    if (img == 2) {
-        basic.showLeds(`
-            # # # # #
-            # . . . #
-            # . . . #
-            # . . . #
-            # # # # #
-            `)
-
-    } else if (img == 1) {
-        basic.showLeds(`
-            . . . . .
-            . # # # .
-            . # # # .
-            . # # # .
-            . . . . .
-            `)
-    } else {
-        basic.showLeds(`
-            . . . # #
-            # # . # .
-            . . # . .
-            # # . # .
-            . . . # #
-            `)
-    }
-})
-
-```
-
-### Challenge 1
-
-When the A button is pressed, increment the score by 1. You can select Game drawer then add change score by 1.
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(2)
-    if (img == 2) {
-        basic.showLeds(`
-            # # # # #
-            # . . . #
-            # . . . #
-            # . . . #
-            # # # # #
-            `)
-
-    } else if (img == 1) {
-        basic.showLeds(`
-            . . . . .
-            . # # # .
-            . # # # .
-            . # # # .
-            . . . . .
-            `)
-    } else {
-        basic.showLeds(`
-            . . . # #
-            # # . # .
-            . . # . .
-            # # . # .
-            . . . # #
-            `)
-    }
-})
-input.onButtonPressed(Button.A, () => {
-    game.addScore(1)
-})
-
-```
-
-* Click *run* to execute your code in the simulator
-
-### Challenge 2
-
-After incrementing the score, display the total number of wins you have.
-
-
-```blocks
-input.onGesture(Gesture.Shake, () => {
-    let img = Math.random(2)
-    if (img == 2) {
-        basic.showLeds(`
-            # # # # #
-            # . . . #
-            # . . . #
-            # . . . #
-            # # # # #
-            `)
-
-    } else if (img == 1) {
-        basic.showLeds(`
-            . . . . .
-            . # # # .
-            . # # # .
-            . # # # .
-            . . . . .
-            `)
-    } else {
-        basic.showLeds(`
-            . . . # #
-            # # . # .
-            . . # . .
-            # # . # .
-            . . . # #
-            `)
-    }
-})
-input.onButtonPressed(Button.A, () => {
-    game.addScore(1)
-    basic.showString("WINS:")
-    basic.showNumber(game.score())
-})
-
-```
-
-* Run and compile the code to see if it works as expected.
-
-### Challenge 3
-
-You have successfully tracked and displayed the number of wins on the micro:bit! However, what about losses? Use the Game drawer to change score by -1 when button `B` is pressed.
-
-* Run and compile the code to see if it works as expected.

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

@@ -1,74 +0,0 @@
-# rock paper scissors quiz
-
-shift an image horizontally across the display with offset.
-
-## Name
-
-## Directions
-
-Use this activity document to guide your work in the [rock paper scissors tutorial](/lessons/rock-paper-scissors/activity).
-
-Answer the questions while completing the tutorial. Pay attention to the dialogues!
-
-## 1. Describe what `offset` does? 
-
-<br/>
-
-## 2. Draw which LEDs are ON after running this code and the random number returned is 0
-
-```blocks
-let img = images.createImage(`
-. . . . . # # # # # . . . . #
-. # # # . # . . . # # # . # .
-. # # # . # . . . # . # # . .
-. # # # . # . . . # # # . # .
-. . . . . # # # # # . . . . #
-`)
-let offset = Math.random(3) * 5
-img.showImage(offset)
-```
-
-![](/static/mb/lessons/night-light-2.png)
-
-<br/>
-
-<br/>
-
-## 3. Draw which LEDs are ON after running this code with an offset of 5. This would occur if the random number returned is 1.
-
-```blocks
-let img_ = images.createImage(`
-. . . . . # # # # # . . . . #
-. # # # . # . . . # # # . # .
-. # # # . # . . . # . # # . .
-. # # # . # . . . # # # . # .
-. . . . . # # # # # . . . . #
-`)
-let offset_ = Math.random(3) * 5
-img.showImage(offset)
-```
-
-![](/static/mb/lessons/night-light-2.png)
-
-<br/>
-
-<br/>
-
-## 4. Draw which LEDs are ON after running this code with an offset of 10. This would occur if the random number returned is 2.
-
-```blocks
-let img_1 = images.createImage(`
-. . . . . # # # # # . . . . #
-. # # # . # . . . # # # . # .
-. # # # . # . . . # . # # . .
-. # # # . # . . . # # # . # .
-. . . . . # # # # # . . . . #
-`)
-let offset_1 = Math.random(3) * 5
-img.showImage(offset)
-```
-
-![](/static/mb/lessons/night-light-2.png)
-
-<br/>
-

docs/lessons/telegraph.md

@@ -1,23 +0,0 @@
-# telegraph lesson
-
-display beautiful images on the BBC micro:bit.
-
-## Topic
-
-Telegraph
-
-## Quick Links
-
-* [activity](/lessons/telegraph/activity)
-* [challenges](/lessons/telegraph/challenges)
-
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to convert your BBC micro:bit into a telegraph using a second BBC micro:bit as well as pin P1, P2, 3V, GND, and crocodile clips (or spring clips). The connect BBC micro:bit uses pins P1, P2, 3V, GND.
-
-## Objectives
-
-* learn how to setup the BBC micro:bit with crocodile clips
-* learn how to telegraph to another BBC micro:bit
-

docs/lessons/the-watch.md

@@ -1,23 +0,0 @@
-# the watch lesson
-
-display beautiful images on the BBC micro:bit.
-
-![](/static/mb/lessons/the-watch-0.png)
-
-## Topic
-
-The Watch
-
-## Quick Links
-
-* [activity](/lessons/the-watch/activity)
-
-
-
-## Prior learning/place of lesson in scheme of work
-
-Learn how to design the BBC micro:bit watch with household supplies.
-
-## Objectives
-
-* learn how to design and make the watch with the BBC micro:bit

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
+
+* [microsoft/pxt-microbit](https://github.com/Microsoft/pxt-microbit), PXT target for BBC micro:bit, also includes the documentation.
+* [microbit/pxt](https://github.com/Microsoft/pxt), programming experience toolkit (PXT)
+* [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,46 @@
+# Projects
+
+![](/static/mb/projects/all10.png)
+
+## [Flashing Heart](/projects/flashing-heart)
+
+![](/static/mb/projects/a1-display.png)
+
+## [Smiley Buttons](/projects/smiley-buttons)
+
+![](/static/mb/projects/a2-buttons.png)
+
+## [Love Meter](/projects/love-meter)
+
+![](/static/mb/projects/a3-pins.png)
+
+## [Rock Paper Scissors](/projects/rock-paper-scissors)
+
+![](/static/mb/projects/a4-motion.png)
+
+## [Compass](/projects/compass)
+
+![](/static/mb/projects/a5-compass.png)
+
+## [Hack your headphones](/projects/hack-your-headphones)
+
+![](/static/mb/projects/a6-music.png)
+
+## [Banana keyboard](/projects/banana-keyboard)
+
+![](/static/mb/projects/a7-conductive.png)
+
+## [Telegraph](/projects/telegraph)
+
+![](/static/mb/projects/a8-network.png)
+
+## [Radio](/projects/radio)
+
+![](/static/mb/projects/a9-radio.png)
+
+## [Watch](/projects/the-watch)
+
+![](/static/mb/projects/a10-watch.png)
+
+
+

docs/projects/banana-keyboard.md

@@ -79,11 +79,22 @@ Your banana keyboard is ready!
 
 ### Step 10
 
-Connect your micro:bit to your computer using your USB cable and run the [banana keyboard](/lhpkbr) script on it. Tap your banana instrument to play sound against... the fruit!
+Connect your micro:bit to your computer using your USB cable and run this script:
+```blocks
+let sound = music.noteFrequency(Note.C);
+input.onPinPressed(TouchPin.P1, () => {
+    for (let i = 0; i < 5; i++) {
+        sound = sound + 25;
+        music.playTone(sound, music.beat(BeatFraction.Sixteenth));
+    }
+});
+```
+
+Tap your banana instrument to play sound against... the fruit!
 
 
 ### ~avatar boothing
 
-Excellent, you're ready to continue with the [challenges](/lessons/banana-keyboard/challenges)!
+Excellent, you're ready to continue with the [challenges](/banana-keyboard-challenges)!
 
 ### ~

docs/projects/compass.md

@@ -0,0 +1,112 @@
+# compass
+
+![](/static/mb/projects/a5-compass.png)
+
+Display the direction that the micro:bit is facing using the compass 
+
+### ~avatar avatar
+
+Welcome! This guided tutorial will show you how to program a script that displays the direction the micro:bit is pointing. Let's get started!
+
+### ~
+
+
+## Step 1
+
+Create a loop that will continuously update the reading of the compass.
+
+
+```blocks
+basic.forever(() => {
+    
+})
+```
+
+## Step 2
+
+Store the reading of the micro:bit in a variable called `degrees`.
+
+```blocks
+basic.forever(() => {
+    let degrees = input.compassHeading()
+})
+```
+
+## Step 3
+
+If `degrees` is less than `45`, then the compass heading is mostly pointing toward North. Display `N` on the micro:bit.
+
+```blocks
+basic.forever(() => {
+    let degrees = input.compassHeading();
+    if (degrees < 45) {
+        basic.showString("N");
+    }
+});
+```
+
+## Step 4
+
+If `degrees` is less than 135, the micro:bit is mostly pointing East. Display `E` on the micro:bit.
+
+
+```blocks
+basic.forever(() => {
+    let degrees = input.compassHeading();
+    if (degrees < 45) {
+        basic.showString("N");
+    }
+    else if (degrees < 135) {
+        basic.showString("E");
+    }
+});
+```
+
+## Step 5
+
+If `degrees` is less than 225, the micro:bit is mostly pointing South. Display `S` on the micro:bit.
+
+
+```blocks
+basic.forever(() => {
+    let degrees = input.compassHeading();
+    if (degrees < 45) {
+        basic.showString("N");
+    }
+    else if (degrees < 135) {
+        basic.showString("E");
+    }
+    else if (degrees < 225) {
+        basic.showString("S");
+    }
+});
+```
+
+## Step 6
+
+If none of these conditions returned true, then the micro:bit must be pointing West. Display `W` on the micro:bit.
+
+```blocks
+basic.forever(() => {
+    let degrees = input.compassHeading();
+    if (degrees < 45) {
+        basic.showString("N");
+    }
+    else if (degrees < 135) {
+        basic.showString("E");
+    }
+    else if (degrees < 225) {
+        basic.showString("S");
+    }
+    else {
+        basic.showString("W");
+    }
+});
+```
+
+### ~avatar avatar
+
+Excellent, you're ready to continue with the [challenges](/lessons/compass/challenges)!
+
+### ~
+

docs/projects/flashing-heart.md

@@ -0,0 +1,117 @@
+# flashing heart
+
+![](/static/mb/projects/a1-display.png)
+
+### ~avatar avatar
+
+```sim
+basic.forever(() => {
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+basic.pause(500);
+basic.clearScreen();
+basic.pause(500);
+})
+```
+
+Use the LEDs to display a flashing heart, and then create
+an animation of a broken heart. :(
+
+## [START PROJECT](/#follow:/projects/flashing-heart)
+
+### ~
+
+## Step 1
+
+Use [show leds](/reference/basic/showLeds) and make your code look like this:
+
+```blocks
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+```
+
+## 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();
+```
+
+## Step 3
+
+Put a [forever loop](/reference/basic/forever) around it.
+
+```blocks
+basic.forever(() => {
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+basic.pause(500);
+basic.clearScreen();
+})
+```
+
+## Step 4
+
+Add a [pause](/reference/basic/pause) to wait after clearing the screen.
+
+```blocks
+basic.forever(() => {
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+basic.pause(500);
+basic.clearScreen();
+basic.pause(500);
+})
+```
+
+## Step 5
+
+Add a second image of a broken heart. 
+
+
+```blocks
+basic.forever(() => {
+basic.showLeds(`
+. # . # .
+# # # # #
+# # # # #
+. # # # .
+. . # . .`);
+basic.pause(500);
+basic.clearScreen();
+basic.pause(500);
+basic.showLeds(`
+. # . # .
+# . # # #
+# . . . #
+. # # # .
+. . # . .`);
+basic.pause(500);
+basic.clearScreen();
+basic.pause(500);
+})
+```

docs/projects/hack-your-headphones-challenges.md

@@ -1,4 +1,4 @@
-# light beatbox activity
+# hack your headphones challenges
 
 Control sound with the light level. 
 
@@ -71,10 +71,3 @@ input.onButtonPressed(Button.A, () => {
 
 * click *compile* and run your code on the micro:bit.
 
-
-### ~avatar avatar
-
-Excellent, you're ready to continue by connecting your headphones with these [challenges](/lessons/hack-your-headphones/activity)!
-
-### ~
-

docs/projects/hack-your-headphones.md

@@ -1,4 +1,4 @@
-# hack your headphones activity 
+# hack your headphones 
 
 Hack your headphones
 
@@ -52,10 +52,10 @@ You hacked your headphones!
 
 ### Step 6
 
-Connect your micro:bit to your computer using your USB cable and program  [light beatbox](/lessons/light-beatbox/activity) music on it. Press the reset button to restart your music player!
+Connect your micro:bit to your computer using your USB cable and program  [light beatbox](/projects/hack-your-headphones-challenges) music on it. Press the reset button to restart your music player!
 
 ### ~avatar avatar
 
-Excellent, you're ready to continue with the [challenges](/lessons/light-beatbox/activity)!
+Excellent, you're ready to continue with the [challenges](/projects/hack-your-headphones-challenges)!
 
 ### ~

docs/projects/love-meter.md

@@ -0,0 +1,50 @@
+# love meter
+
+![](/static/mb/projects/a3-pins.png)
+
+Use pins P0, P1 and P2 to change the display by creating a circuit with your body.
+
+## Step 1
+
+Use [on pin pressed](/reference/input/on-pin-pressed) to show a random number
+when pin P0 is pressed (hold the GND pin with other hand):
+
+```blocks
+input.onPinPressed(TouchPin.P0, () => {
+    basic.showNumber(Math.random(11));
+});
+```
+## Step 2
+
+Show a string when pin P1 is pressed:
+
+```blocks
+input.onPinPressed(TouchPin.P0, () => {
+    basic.showNumber(Math.random(11));
+});
+input.onPinPressed(TouchPin.P1, () => {
+    basic.showString("LOVE?");
+});
+```
+
+## Step 3
+
+Show a heart when pin P2 is pressed:
+
+```blocks
+input.onPinPressed(TouchPin.P0, () => {
+    basic.showNumber(Math.random(11));
+});
+input.onPinPressed(TouchPin.P1, () => {
+    basic.showString("LOVE?");
+});
+input.onPinPressed(TouchPin.P2, () => {
+    basic.showLeds(`
+        . # # # .
+        # # # # #
+        # # # # #
+        . # # # .
+        . . # . .
+        `);
+});
+```

docs/projects/radio-challenges.md

@@ -0,0 +1,88 @@
+# Challenge 
+
+### ~avatar avatar 
+
+Welcome! The activity will teach you how to use the acceleration of the 1st micro:bit and to visualize the acceleration on the 2nd micro:bit. 
+Let's get started!
+
+### ~
+Let's measure `acceleration (mg)` and then `send number`. `Acceleration` is measured in **milli-gravities**, so a value of -1000 is equivalent to -1g or -9.81m/s^2. We will be able to get the acceleration value (g-force), in the specified "x" dimension. `Send number` will broadcast a number data packet to other micro:bits connected via radio.
+
+```blocks
+radio.sendNumber(input.acceleration(Dimension.X));
+```
+### ~
+We want to display the acceleration forever. In order to do so, we need a `forever` loop. A forever loop will repeat code in the background forever.
+
+```blocks
+basic.forever(() => {
+    radio.sendNumber(input.acceleration(Dimension.X));
+});
+
+
+```
+### ~
+We want to register code to run when a packet is received over radio. We can implement this code by adding `on data received`.
+
+```blocks
+basic.forever(() => {
+    radio.sendNumber(input.acceleration(Dimension.X))
+})
+radio.onDataReceived(() => {
+    
+})
+```
+### ~
+Finally, we want to chart the acceleration. So we must first implement `plot bar graph`. `Plot Bar Graph` will display a vertical bar graph based on the value and high value. In order to transfer the receive the number from the 1st micro:bit, we must implement `receive number` to constantly display a vertical bar graph based on the value. Remember, the value will equal to the micro:bit's acceleration in the "x" direction.
+
+```blocks
+basic.forever(() => {
+    radio.sendNumber(input.acceleration(Dimension.X))
+})
+radio.onDataReceived(() => {
+    led.plotBarGraph(radio.receiveNumber(), 1023)
+})
+
+```
+### ~
+Notice that moving the micro:bit the farthest direction in the x direction will be -1023 on the charting beneath the simulator. The second observation will be that the LEDs will be full brightness on the 2nd micro:bit. There is a single LED turned on with the 1st micro:bit. Additionally, the graphs will reflect 0 acceleation for the 1st micro:bit. In this scenario, if you are adjusting the acceleration in the simualator, you are also changing your chart that will be produced.  
+
+![](/static/mb/acc.png)
+
+### ~
+NOTE: The colors of the charts reflect the color of the micro:bit simulator. In this instance, the micro:bits are blue and green. So the colors of the line graphs reflect the colors of the micro:bit
+ 
+ ### ~
+After running this simulation several seconds by moving the micro:bit side to side in the x direction, you are ready to graph or chart the accceleration of the micro:bit.  We want a printout of our acceleration on Excel. We will graph the fluctuating acceleration of the simulation experiment. 
+
+![](/static/mb/acc2.png)
+
+### ~
+Finally, you must open the Excel CSV file by clicking on the data.xls file that was downloaded to Downloads Folder. 
+
+![](/static/mb/data3.png)
+
+Use the Recommended Charts command on the Insert tab to quickly create a chart that’s just right for your data.
+
+* Select the data that you want to include in your chart.
+
+* Click Insert > Recommended Charts.
+
+![](/static/mb/lessons/chart1.png)
+
+* On the Recommended Charts tab, scroll through the list of chart types that Excel recommends for your data. Pick the **scatter plot**.
+
+![](/static/mb/chart_title.png)
+
+* Use the Chart Elements, Chart Styles, and Chart Filters buttons next to the upper-right corner of the chart to add chart elements like axis titles or data labels, to customize the look of your chart
+
+![](/static/mb/elements_styles_filters.png)
+
+### ~
+Have fun reviewing your simulation and analyze the acceleration by chart the Excel data using Excel.
+
+* Connect the first micro:bit to your computer using your USB cable and run the charting script on it.
+* Connect the second micro:bit to your computer using your USB cable and run the charting script on it.
+* The first person and second person take turns tilting the micro:bit in the "x" direction while the other player charts the data on the micro:bit!
+* Review and analyze the actual micro:bit device acceleration data on Excel
+* Display acceleration with y or z using plot bar graph by changing acceleration from "x" to "y" or "z" 

docs/projects/radio.md

@@ -0,0 +1,68 @@
+# radio 
+
+Measure the acceleration on the micro:bit in the "x" direction. 
+
+### ~avatar avatar
+
+Welcome! This activity will teach how to use the micro:bit to chart the acceleration in the "x" direction. Let's get started!
+
+
+### ~
+Let's measure `acceleration (mg)` in the "x" direction. Get the acceleration value (milli g-force), in one of three specified dimensions.
+
+
+```blocks
+input.acceleration(Dimension.X)
+```
+
+### ~
+Use the plot bar chart to visualize the acceleration on the LED screen of the micro:bit in the specified range. You implement plot Bar Graph to display a vertical bar graph based on the "value" and "high" value. Then you must insert acceleration in the X dimension to measure the acceleration. 
+
+```blocks
+basic.forever(() => {
+    led.plotBarGraph(input.acceleration(Dimension.X), 0)
+})
+
+```
+
+### ~
+Notice that moving the micro:bit in the simulator from left to right (x direction) changes the values beneath the micro:bit in a range from 1023 to -1023 as measured in milli-gravities. By hovering over the micro:bit from left to right, you can observe changing values beneath the micro:bit simulator. Also, the LEDs shown on the Bar Graph fluctates based on the movement of the micro:bit simulator in the x direction. The line underneath the micro:bit simulator reflect the acceleration in the x direction. 
+
+NOTE: The colors of the charts reflect the color of the micro:bit simulator. In this instance, the micro:bit is yellow. So the color of the data line reflects the color of the micro:bit
+
+![](/static/mb/data4.png)
+
+### ~
+ 
+Vigorously move the micro:bit in the micro:bit simulatator by moving the micro:bit image from side to side. Every time the micro:bit moves in the x direction in the simulator,  you are generating data points that can be reviewed in Excel. The more attempts to move the micro:bit from side to side, the more data being saved in Excel. After you have vigarously moved the micro:bit simulator from side to side for a sufficient amount of time, you are ready to graph or chart the accceleration of the micro:bit. We want a printout of our acceleration on Excel that can be graphed in Excel. 
+
+### ~
+
+We want to chart the data collected by using a tool in Excel. 
+
+The final part of this experiment is opening and reviewing the data in the Excel CSV file. Simply click on the line beneath the simulator. A CSV file will be generated to display the data points collected by moving the micro:bit in the X direction. Then click or tap on the data Excel file that was downloaded to your local ``Downloads`` Folder. 
+
+
+### ~
+
+
+First, click or tap on the first two columns (A, B) to  include the time of the data being collected; b) the results of acceleration data on the micro:bit  
+
+![](/static/mb/data7.png)
+
+Use the Recommended Charts command on the Insert tab to quickly create a chart that’s just right for your data.
+
+* Select the data that you want to include in your chart.
+
+* Click Insert > Recommended Charts.
+
+![](/static/mb/lessons/chart1.png)
+
+* On the Recommended Charts tab, scroll through the list of chart types that Excel recommends for your data. Pick the **scatter plot**.
+
+### ~avatar avatar
+
+Excellent, you're ready to continue with the [challenges](/projects/radio-challenges)
+
+### ~
+

docs/projects/rock-paper-scissors.md

@@ -0,0 +1,239 @@
+# rock paper scissors
+
+![](/static/mb/projects/a4-motion.png)
+
+### ~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.
+
+## [START PROJECT](/#follow:/projects/rock-paper-scissors)
+
+### ~
+
+
+## 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/projects/smiley-buttons.md

@@ -0,0 +1,69 @@
+# smiley buttons
+
+![](/static/mb/projects/a2-buttons.png)
+
+Use buttons to show a smiley or frowny face. 
+
+## Step 1
+
+Use [show leds](/reference/basic/showLeds) to make a smiley face:
+
+```blocks
+basic.showLeds(`
+. # . # .
+. # . # .
+. . . . .
+# . . . #
+. # # # .`);
+```
+
+## Step 2
+
+Add an input block for when [button A is pressed](/reference/input/button-is-pressed), and put a
+frowny face inside it:
+
+```blocks
+basic.showLeds(`
+. # . # .
+. # . # .
+. . . . .
+# . . . #
+. # # # .`);
+input.onButtonPressed(Button.A, () => { 
+    basic.showLeds(`
+    . # . # .
+    . # . # .
+    . . . . .
+    . # # # .
+    # . . . #`);
+});
+```
+
+## Step 3
+
+Now add blocks so that when [button B is pressed](/reference/input/button-is-pressed), a smiley appears:
+
+```blocks
+basic.showLeds(`
+. # . # .
+. # . # .
+. . . . .
+# . . . #
+. # # # .`);
+input.onButtonPressed(Button.A, () => { 
+    basic.showLeds(`
+    . # . # .
+    . # . # .
+    . . . . .
+    . # # # .
+    # . . . #`);
+});
+input.onButtonPressed(Button.B, () => { 
+    basic.showLeds(`
+    . # . # .
+    . # . # .
+    . . . . .
+    # . . . #
+    . # # # .`);
+});
+```

docs/projects/telegraph.md

@@ -70,6 +70,6 @@ Using the 4th crocodile clip, connect the unattached end of the crocodile clip o
 
 ### ~avatar avatar
 
-Excellent, you're ready to continue with the [challenges](/lessons/telegraph/challenges)!
+Excellent, you're ready to continue with the [challenges](/projects/telegraph-challenges)!
 
 ### ~

docs/projects/the-watch.md

@@ -1,8 +1,6 @@
-# The watch activity
+![](/static/mb/projects/a10-watch.png)
 
-Control images with variables. 
-
-# micro:bit watch
+# the watch
 
 ![](/static/mb/lessons/the-watch-0.png)
 
@@ -152,7 +150,7 @@ Your watch is ready!
 
 ### ~avatar avatar
 
-Excellent, you're ready to continue with the [challenges](/lessons/rock-paper-scissors/activity)!
+Excellent, you're ready to continue with the [challenges](/projects/rock-paper-scissors)!
 
 ### ~
 

docs/reference.md

@@ -1,17 +1,24 @@
 # Reference
 
 ```namespaces
-basic.showString("Hello!");
-input.onButtonPressed(Button.A, () => {});
-for (let i = 0;i<5;++i) {}
-if (true){}
-let x = 0;
-Math.random(5);
-led.plot(0,0);
+basic.showNumber(0);
+input.onButtonPressed(Button.A, () => {
+    
+});
+music.playTone(0, 0);
+led.plot(0, 0);
 radio.sendNumber(0);
-music.playTone(music.noteFrequency(Note.C), music.beat(BeatFraction.Whole));
-game.createSprite(2,2);
+game.addScore(1);
+images.createImage(`
+. . . . .
+. . . . .
+. . # . .
+. . . . .
+. . . . .
+`);
 pins.digitalReadPin(DigitalPin.P0);
-serial.writeLine("Hello!");
-control.inBackground(() => {});
-```
+serial.writeNumber(0);
+control.inBackground(() => {
+    
+});
+```

docs/reference/String.md

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

docs/reference/basic.md

@@ -2,7 +2,6 @@
 
 Provides access to basic micro:bit functionality.
 
-
 ```cards
 basic.showNumber(0);
 basic.showLeds(`

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(`
@@ -21,11 +21,7 @@ basic.showLeds(`
 basic.clearScreen()
 ```
 
-### Lessons
-
-[blink](/lessons/blink), [flashing heart](/lessons/flashing-heart), [screen wipe](/lessons/screen-wipe)
-
 ### See also
 
-[set brightness](/reference/led/set-brightness), [unplot](/reference/led/unplot), [plot](/reference/led/plot), [Image](/reference/image/image), [clear](/reference/basic/clear-screen)
+[set brightness](/reference/led/set-brightness), [unplot](/reference/led/unplot), [plot](/reference/led/plot), [Image](/reference/images/image), [clear](/reference/basic/clear-screen)
 

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(() => {
@@ -55,11 +63,7 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-### Lessons
-
-[blink](/lessons/blink), [bounce-image](/lessons/bounce-image),  [snowflake-fall](/lessons/snowflake-fall), [flashing-heart](/lessons/flashing-heart)
-
 ### See also
 
-[while](/js/while), [on button pressed](/reference/input/on-button-pressed), [in background](/reference/control/in-background)
+[while](/reference/loops/while), [on button pressed](/reference/input/on-button-pressed), [in background](/reference/control/in-background)
 

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++) {
@@ -21,11 +24,7 @@ for (let i = 0; i < 5; i++) {
 }
 ```
 
-### Lessons
-
-[blink](/lessons/blink), [lucky 7](/lessons/lucky-7), [smiley](/lessons/smiley), [flashing heart](/lessons/flashing-heart)
-
 ### See also
 
-[while](/js/while), [running time](/reference/input/running-time), [for](/reference/loops/for)
+[while](/reference/loops/while), [running time](/reference/input/running-time), [for](/reference/loops/for)
 

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,11 +59,6 @@ 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.
 
 ### ~
-
-### Lessons
-
-[smiley](/lessons/smiley), [bounce image](/lessons/bounce-image), [snowflake fall](/lessons/snowflake-fall), [rotation animation](/lessons/rotation-animation)
-

docs/reference/basic/show-leds.md

@@ -1,6 +1,6 @@
 # Show LEDs
 
-Display an image on the BBC micro:bit's [LED screen](/device/screen).
+Shows a picture on the [LED screen](/device/screen).
 
 ```sig
 basic.showLeds(`
@@ -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 controls which LEDs are on and off.
+* `interval` is an optional [number](/reference/types/number) that means how many milliseconds to wait after showing a picture.
+If you are programming with blocks, `interval` is set at 400 milliseconds.
 
-### Example - Block Editor
+### Example
 
-1. Open the `basic` category and select the `show leds` blocks.
+This program shows a picture with the ``show leds`` function.
 
 ```blocks
 basic.showLeds(`
@@ -33,13 +34,14 @@ basic.showLeds(`
 )
 ```
 
-In JavaScript, the led off is represented by a `.` and the led on by a `#` character.
+### ~hint
 
-### Lessons
+If you are programming in JavaScript, `#` means an LED that is turned
+on and `.` means an LED that is turned off.
 
-[smiley](/lessons/smiley), [flashing heart](/lessons/flashing-heart), [magic logo](/lessons/magic-logo)
+### ~
 
 ### See also
 
-[plot leds](/reference/led/plot-leds), [show animation](/reference/led/show-animation)
+[plot leds](/reference/led/plot-leds), [show animation](/reference/basic/show-animation)
 

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,25 +28,21 @@ 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
-
-### Lessons
-
-* [lucky 7](/lessons/lucky-7)
+* 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.
 
 ### See also
 
-[show string](/reference/basic/show-string), [show animation](/reference/basic/show-animation), [Number](/reference/types/number), [math library](/js/math)
+[show string](/reference/basic/show-string), [show animation](/reference/basic/show-animation), [Number](/reference/types/number), [math library](/reference/math)
 

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,14 +28,10 @@ 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
-
-### Lessons
-
-[answering machine](/lessons/answering-machine), [rock paper scissors](/lessons/rock-paper-scissors), [love meter](/lessons/love-meter), [digital pet](/lessons/digital-pet)
+* 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.
 
 ### See also
 
-[String](/reference/types/string), [string functions](/reference/types/string-functions), [show number](/reference/basic/show-number), [show animation](/reference/basic/show-animation)
+[String](/reference/types/string), [show number](/reference/basic/show-number), [show animation](/reference/basic/show-animation)
 

docs/reference/comment.md

@@ -1,38 +0,0 @@
-# Comment
-
-A note in code.
-
-### @parent blocks/statement
-
-A comment is a line of code that contains text, usually an explanation or a note. All comments are ignored during script execution.
-
-### Block
-
-Right click on any block and add a comment
-
-### ~hint 
-
-To find out how to insert comments using the Blocks editor, see [the Blocks editor](/blocks/editor).
-
-### ~
-
-### Sample code with comments
-
-![](/static/mb/blocks/comment-0.png)
-
-### Commenting out code
-
-During the debugging process, you may want to comment out a section of your code so that it doesn't run.
-
-To comment out a block of code:
-
-1. Right click on any block of code that you want to comment out.
-
-1. Select add comment
-
-When you want to uncomment your code, right click the on the comment, and then click delete block.
-
-### See also
-
-[Block editor](/blocks/editor)
-

docs/reference/control.md

@@ -1,7 +1,6 @@
 # Control
 
-
-
+Runtime and event utilities.
 
 ```cards
 control.inBackground(() => {

docs/reference/devices/on-gamepad-button.md

@@ -8,14 +8,9 @@ The functions in the ``devices`` namespace allow the BBC micro:bit to communicat
 
 The set of supported events will depend on the remote device and the BBC micro:bit apps available for the remote device.
 
-### Block Editor
 
-![](/static/mb/on-gamepad-button-0.png)
-
-### KindScript
-
-```
-export function onGamepadButton(name: string, body:td.Action)
+```sig
+devices.onGamepadButton(MesDpadButtonInfo.ADown, () => {})
 ```
 
 ### Parameters
@@ -24,5 +19,4 @@ export function onGamepadButton(name: string, body:td.Action)
 
 ### See Also
 
-[tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [on notified](/reference/devices/on-notified), [signal strength](/reference/devices/signal-strength), [on signal strength changed](/reference/devices/on-signal-strength-changed)
-
+[tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [signal strength](/reference/devices/signal-strength), [on signal strength changed](/reference/devices/on-signal-strength-changed)

docs/reference/devices/on-signal-strength-changed.md

@@ -10,14 +10,8 @@ The functions in the ``devices`` namespace allow the BBC micro:bit to communicat
 
 The set of supported events will depend on the remote device and the BBC micro:bit apps available for the remote device.
 
-### Block Editor
-
-![](/static/mb/on-signal-strength-changed-0.png)
-
-### KindScript
-
-```
-export function onSignalStrengthChanged(body:td.Action)
+```sig
+devices.onSignalStrengthChanged(() => {})
 ```
 
 ### Parameters

docs/reference/devices/raise-alert-to.md

@@ -4,19 +4,14 @@ The raise alert to function.
 
 Raise an alert on a remote device.
 
-## 
+## Bluetooth required
 
 The functions in the ``devices`` namespace allow the BBC micro:bit to communicate with a separate (remote) device, such as a smartphone, over Bluetooth (Smart).
 
 The set of supported events will depend on the remote device and the BBC micro:bit apps available for the remote device.
 
-### KindScript
 
-![](/static/mb/raise-alert-to-0.png)
-
-### KindScript
-
-```
+```sig
 export function raiseAlertTo(event: string)
 ```
 

docs/reference/devices/receive-number.md

@@ -12,14 +12,8 @@ This API does not contain any form of encryption, authentication or authorizatio
 
 For serious applications, BLE should be considered a substantially more secure alternative.
 
-### Block Editor
-
-![](/static/mb/receive-number-0.png)
-
-### KindScript
-
-```
-export function receiveNumber() : number
+```sig
+radio.receiveNumber();
 ```
 
 ### Returns

docs/reference/devices/signal-strength.md

@@ -4,20 +4,14 @@ The `signal strength` function.
 
 Returns the signal strength reported by the paired device from ``0`` (no signal) to ``4`` (full strength).
 
-## Bluetooth required
+## Important Security Consideration
 
 The functions in the ``devices`` namespace allow the BBC micro:bit to communicate with a separate (remote) device, such as a smartphone, over Bluetooth (Smart).
 
 The set of supported events will depend on the remote device and the BBC micro:bit apps available for the remote device.
 
-### Block Editor
-
-![](/static/mb/signal-strength-0.png)
-
-### KindScript
-
 ```
-export function signalStrength() : number
+devices.signalStrength() : number
 ```
 
 ### Returns

docs/reference/devices/tell-camera-to.md

@@ -14,7 +14,7 @@ The set of supported events will depend on the remote device and the BBC micro:b
 
 ![](/static/mb/tell-camera-to-0.png)
 
-### KindScript
+### JavaScript
 
 ```
 export function tellCameraTo(event: string)

docs/reference/devices/tell-microphone-to.md

@@ -10,7 +10,7 @@ The functions in the antenna namespace allow the BBC micro:bit to communicate wi
 
 ![](/static/mb/tell-microphone-to-0.png)
 
-### KindScript
+### JavaScript
 
 ```
 export function tellMicrophoneTo(event: string)
@@ -37,13 +37,13 @@ export function tellMicrophoneTo(event: string)
 To tell the connected device to start recording audio
 
 ```
-antenna.tellMicrophoneTo("start capture")
+devices.tellMicrophoneTo("start capture")
 ```
 
 To tell the connected device to stop recording audio
 
 ```
-antenna.tellMicrophoneTo("stop capture")
+devices.tellMicrophoneTo("stop capture")
 ```
 
 ### Other show functions
@@ -54,5 +54,5 @@ antenna.tellMicrophoneTo("stop capture")
 
 ### See also
 
-[Antenna](/js/antenna)
+[Devices](/reference/devices)
 

docs/reference/devices/tell-remote-control-to.md

@@ -14,7 +14,7 @@ The set of supported events will depend on the remote device and the BBC micro:b
 
 ![](/static/mb/tell-remote-control-to-0.png)
 
-### KindScript
+### JavaScript
 
 ```
 export function tellRemoteControlTo(event: string)

docs/reference/event-handler.md

@@ -0,0 +1,59 @@
+# event handler
+
+Event handlers - how they work.
+
+An event handler is code that is associated with a particular event, such as "button A pressed". You create (or register) the association between an event and an event handler by calling a function named "on <event>".  After registering an event handler with an event, then whenever that event occurs, the event handler code executes.
+
+### Registering an event handler
+
+Functions named "on <event>" create an association between an event and the event handler code.  For example, the following code registers the event handler (the code between the `do` and `end` keywords) with the event of a press of button A:
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    basic.showString("hello", 150)
+})
+```
+
+After this code executes, then whenever button A is pressed in the future, the string "hello" will be printed.
+
+### Event handlers are active for the entire program execution
+
+Once you have registered an event handler for an event, like above, that event handler is active for the rest of the program execution. If you want to stop the string "hello" from printing each time button A is pressed then you need to arrange for the following code to execute:
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+})
+```
+
+The above code associated an event handler that does nothing with the event of a press of button A.
+
+### There is only one event handler per event
+
+The above example also illustrates that there is only one event handler for each event. What is the result of the following code?
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    basic.showString("hello", 150)
+})
+input.onButtonPressed(Button.A, () => {
+    basic.showString("goodbye", 150)
+})
+```
+
+The answer is that whenever button A is pressed, the string "goodbye" will be printed. If you want both the strings "hello" and "goodbye" to be printed, you need to write the code like this:
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    basic.showString("hello", 150)
+    basic.showString("goodbye", 150)
+})
+```
+
+### To learn more
+
+To learn more about how the BBC micro:bit queues up and schedules event handlers, see [the BBC micro:bit - a reactive system](/device/reactive)
+
+### see also
+
+[on button pressed](/reference/input/on-button-pressed), [on pin up](/reference/input/on-pin-pressed), [on shake](/reference/input/on-gesture)
+

docs/reference/game.md

@@ -1,7 +1,6 @@
 # Game
 
-
-
+A single-LED sprite game engine
 
 ```cards
 game.addScore(1);

docs/reference/game/change-score-by.md

@@ -1,20 +1,8 @@
 # Change Score By
 
-The game library 
-
-The game library supports simple single-player time-based games. The player will ** add points to score**.
-
-## Block Editor
-
 The code below shows a simple game where the user gets to press the button ``A`` as much times as possible and the score will display on the screen.
 
-![](/static/mb/change-score-by-0.png)
-
-## KindScript
-
-The code below shows a simple game where the user gets to press the button ``A`` as much times as possible in 10 seconds.
-
-```
+```blocks
 input.onButtonPressed(Button.A, () => {
     game.addScore(1)
 })
@@ -36,8 +24,3 @@ export function addScore(points: number)
 ```
 export function score() : number
 ```
-
-### Lessons
-
-[bop it](/lessons/bop-it) | [game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/change.md

@@ -1,16 +1,12 @@
 # Change
 
-The game library
-
-### Change
-
 Sprite will change the x position by this number
 
-## Block Editor
+### Block Editor
 
 ![](/static/mb/change-0.png)
 
-## KindScript
+### JavaScript
 
 Sprite will change the x position by this number
 
@@ -23,8 +19,3 @@ Sprite will change the y position by this number
 ```
 export function changeYBy(_this: micro_bitSprites.LedSprite, y: number)
 ```
-
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/clear.md

@@ -2,9 +2,9 @@
 
 The clear function for images.
 
-Turn off all the pixels in an [Image](/reference/image/image).
+Turn off all the pixels in an [Image](/reference/images/image).
 
-### KindScript
+### JavaScript
 
 ```
 export function clear(img: micro_bit.Image)
@@ -35,5 +35,5 @@ input.onButtonPressed(Button.A, () => {
 
 ### See also
 
-[Image](/reference/image/image), [show animation](/reference/basic/show-animation), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image), [create image](/reference/images/create-image)
+[Image](/reference/images/image), [show animation](/reference/basic/show-animation), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image), [create image](/reference/images/create-image)
 

docs/reference/game/game-library.md

@@ -1,18 +1,10 @@
 # Game Library
 
-The game library #docs
-
 The game library supports simple single-player time-based games. The player has a **sprite**, number of **lives** and a **score**. The game has a sprite, number of **levels** and a **countdown clock**.  The general goal of a game will be to move the sprite and achieve a top score before time runs out or the number of lives goes to zero.
 
-## Block Editor
-
-![](/static/mb/game-library/pic0.png)
-
-## KindScript
-
 The code below shows a simple game where the user gets to press the button ``A`` as much times as possible in 10 seconds.
 
-```
+```blocks
 input.onButtonPressed(Button.A, () => {
     game.addScore(1)
 })
@@ -154,8 +146,3 @@ You can also end the game by calling the `game -> game over` function:
 ```
 game.gameOver()
 ```
-
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/game-over.md

@@ -18,7 +18,3 @@ You can end the game by calling the `game -> game over` function:
 game.gameOver()
 ```
 
-### Lessons
-
-[game of chance](/lessons/game-of-chance)
-

docs/reference/game/move.md

@@ -1,22 +1,7 @@
 # Move
 
-The game library 
-
-### Move
-
-Sprite move by a certain number
-
-## Block Editor
-
-![](/static/mb/game-library/move-0.png)
-
-## KindScript
+Sprite move by a certain number of LEDs
 
 ```
 export function move(_this: micro_bitSprites.LedSprite, leds: number)
 ```
-
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/position.md

@@ -1,19 +1,5 @@
 # Position
 
-The game library 
-
-### Create sprite
-
-Reports the x or y position of a sprite on the LED screen
-
-## Block Editor
-
-Reports the x position of a sprite on the LED screen
-
-![](/static/mb/game-library/position-0.png)
-
-## KindScript
-
 Reports the x position of a sprite on the LED screen
 
 ```
@@ -25,8 +11,3 @@ Reports the y position of a sprite on the LED screen
 ```
 export function y(_this: micro_bitSprites.LedSprite) : number
 ```
-
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/reports.md

@@ -1,31 +1,7 @@
 # Reports
 
-The game library
-
-### Reports
-
 Reports the x or y position,  the current direction of a sprite, or the brightness of a sprite on the LED screen
 
-## Block Editor
-
-Reports the x position of a sprite on the LED screen
-
-![](/static/mb/game-library/position-0.png)
-
-Reports the y position of a sprite on the LED screen
-
-![](/static/mb/game-library/reports-0.jpg)
-
-Reports the brightness of a sprite on the LED screen
-
-![](/static/mb/game-library/reports-1.jpg)
-
-Reports the direction of a sprite on the LED screen
-
-![](/static/mb/game-library/reports-2.jpg)
-
-## KindScript
-
 Reports the x position of a sprite on the LED screen
 
 ```
@@ -49,8 +25,3 @@ Reports the current direction of a sprite on the LED screen
 ```
 export function direction(_this: micro_bitSprites.LedSprite) : number
 ```
-
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/score.md

@@ -1,20 +1,10 @@
 # Score
 
-The game library #docs
-
 The game library supports simple single-player games. The player has a **score**.
 
-## Block Editor
-
-The code below shows a simple game where the user gets to press the button ``A`` and adds 1 point to score that will be displayed on the BBC micro:bit screen
-
-![](/static/mb/game-library/add-point-to-score-0.png)
-
-## KindScript
-
 The code below shows a simple game where the user gets to press the button ``A`` as much times as possible in 10 seconds.
 
-```
+```blocks
 input.onButtonPressed(Button.A, () => {
     game.addScore(1)
 })
@@ -53,7 +43,3 @@ If your game has a time limit, you can start a countdown in which case `game->cu
 export function startCountdown(ms: number)
 ```
 
-### Lessons
-
-[bop it](/lessons/bop-it) | [game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/start-countdown.md

@@ -1,15 +1,5 @@
 # Start Countdown
 
-The game library #docs
-
-The game library supports simple single-player time-based games. The general goal of a game will be to achieve a top score before time runs out of time.
-
-## Block Editor
-
-![](/static/mb/game-library/start-countdown-0.png)
-
-## KindScript
-
 The code below shows a simple game where the user gets to press the button ``A`` as much times as possible in 10 seconds.
 
 ```
@@ -50,8 +40,3 @@ If your game has a time limit, you can start a countdown in which case `game->cu
 ```
 export function startCountdown(ms: number)
 ```
-
-### Lessons
-
-[bop it](/lessons/bop-it) | [game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/touching.md

@@ -1,24 +1,8 @@
 # Touching
 
-The game library 
-
-### Touching
-
-Reports true if sprite is touching specified sprite
-
-## Block Editor
-
-![](/static/mb/game-library/touching-0.png)
-
-## KindScript
-
 Reports true if sprite is touching specified sprite
 
 ```
 export function isTouching(_this: micro_bitSprites.LedSprite, other: micro_bitSprites.LedSprite) : boolean
 ```
 
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/game/turn.md

@@ -1,17 +1,5 @@
 # Turn
 
-The game library 
-
-Rotates a sprite to the right by a certain number of degrees
-
-## Block Editor
-
-Rotates a sprite to the right by a certain number of degrees
-
-![](/static/mb/game-library/turn-0.png)
-
-## KindScript
-
 Rotates a sprite to the right by a certain number of degrees
 
 ```
@@ -24,7 +12,3 @@ Rotates a sprite to the left by a certain number of degrees
 export function turnLeft(_this: micro_bitSprites.LedSprite, degrees: number)
 ```
 
-### Lessons
-
-[game of chance](/lessons/game-of-chance) | [game counter](/lessons/game-counter)
-

docs/reference/images.md

@@ -1,7 +1,6 @@
 # Images
 
-
-
+Creation, manipulation and display of LED images.
 
 ```cards
 images.createImage(`

docs/reference/images/create-image.md

@@ -1,6 +1,6 @@
 # Create Image
 
-Create an [Image](/reference/image/image) to show on the [LED screen](/device/screen).
+Create an [Image](/reference/images/image) to show on the [LED screen](/device/screen).
 
 ```sig
 images.createImage(`
@@ -29,11 +29,7 @@ input.onGesture(Gesture.Shake, () => {
 })
 ```
 
-### Lessons
-
-[rock paper scissors](/lessons/rock-paper-scissors), [digital pet](/lessons/digital-pet), [offset-image](/lessons/offset-image)
-
 ### See also
 
-[show animation](/reference/basic/show-animation), [image](/reference/image/image), [show image](/reference/image/show-image), [scroll image](/reference/image/scroll-image)
+[show animation](/reference/basic/show-animation), [image](/reference/images/image), [show image](/reference/image/show-image), [scroll image](/reference/image/scroll-image)
 

docs/reference/images/image.md

@@ -46,10 +46,6 @@ You should see code similar to this:
 * [show image](/reference/images/show-image): show an image on the screen
 * [scroll image](/reference/images/scroll-image): scroll an image on the screen
 
-### Lessons
-
-* [smiley](/lessons/smiley)
-
 ### See also
 
 [Show LEDs](/reference/basic/show-leds), [create image](/reference/images/create-image), [show image](/reference/images/show-image), [LED screen](/device/screen)

docs/reference/images/pixel.md

@@ -2,9 +2,9 @@
 
 The pixel function.
 
-Get the state of a pixel in an [Image](/reference/image/image).
+Get the state of a pixel in an [Image](/reference/images/image).
 
-### KindScript
+### JavaScript
 
 ```
 export function pixel(_this: micro_bit.Image, x: number, y: number) : boolean
@@ -12,8 +12,8 @@ export function pixel(_this: micro_bit.Image, x: number, y: number) : boolean
 
 ### Parameters
 
-* x - [Number](/reference/types/number); the *x coordinate* or horizontal position of a pixel in an [image](/reference/image/image)
-* y - [Number](/reference/types/number); the *y coordinate* or vertical position of a pixel in an [image](/reference/image/image)
+* x - [Number](/reference/types/number); the *x coordinate* or horizontal position of a pixel in an [image](/reference/images/image)
+* y - [Number](/reference/types/number); the *y coordinate* or vertical position of a pixel in an [image](/reference/images/image)
 
 ### x, y coordinates?
 
@@ -47,5 +47,5 @@ let state = img.pixel(0, 0)
 
 ### See also
 
-[set pixel](/reference/images/set-pixel), [show image](/reference/images/show-image), [image](/reference/image/image), [create image](/reference/images/create-image), [scroll image](/reference/images/scroll-image)
+[set pixel](/reference/images/set-pixel), [show image](/reference/images/show-image), [image](/reference/images/image), [create image](/reference/images/create-image), [scroll image](/reference/images/scroll-image)
 

docs/reference/images/plot-frame.md

@@ -2,9 +2,9 @@
 
 The plot frame function.
 
-Display an [Image](/reference/image/image) on the BBC micro:bit's [LED screen](/device/screen)
+Display an [Image](/reference/images/image) on the BBC micro:bit's [LED screen](/device/screen)
 
-### KindScript
+### JavaScript
 
 ```
 export function plotFrame(_this: micro_bit.Image, index: number)
@@ -31,11 +31,7 @@ let img = images.createImage(`
 img.plotFrame(1)
 ```
 
-### Lessons
-
-[smiley](/lessons/smiley), [flashing heart](/lessons/flashing-heart), [magic logo](/lessons/magic-logo)
-
 ### See also
 
-[create image](/reference/images/create-image), [show animation](/reference/basic/show-animation), [image](/reference/image/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
+[create image](/reference/images/create-image), [show animation](/reference/basic/show-animation), [image](/reference/images/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
 

docs/reference/images/plot-image.md

@@ -2,9 +2,9 @@
 
 The plot image function.
 
-Display an [Image](/reference/image/image) on the BBC micro:bit's [LED screen](/device/screen)
+Display an [Image](/reference/images/image) on the BBC micro:bit's [LED screen](/device/screen)
 
-### KindScript
+### JavaScript
 
 ```
 export function plotImage(_this: micro_bit.Image, xOffset: number)
@@ -31,11 +31,7 @@ let img = images.createImage(`
 img.plotImage(0)
 ```
 
-### Lessons
-
-[smiley](/lessons/smiley), [flashing heart](/lessons/flashing-heart), [magic logo](/lessons/magic-logo)
-
 ### See also
 
-[create image](/reference/images/create-image), [show animation](/reference/basic/show-animation), [image](/reference/image/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
+[create image](/reference/images/create-image), [show animation](/reference/basic/show-animation), [image](/reference/images/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
 

docs/reference/images/scroll-image.md

@@ -2,13 +2,13 @@
 
 The scroll image function.
 
-Scrolls the frames within an [Image](/reference/image/image) on the [LED screen](/device/screen).
+Scrolls the frames within an [Image](/reference/images/image) on the [LED screen](/device/screen).
 
 ### Block Editor
 
 ![](/static/mb/scroll-image-0.png)
 
-### KindScript
+### JavaScript
 
 ```
 export function scrollImage(_this: micro_bit.Image, xOffsetPerStep: number, interval: number)
@@ -69,5 +69,5 @@ img.scrollImage(5, 1000)
 
 ### See also
 
-[show image](/reference/images/show-image), [image](/reference/image/image), [create image](/reference/images/create-image), [show animation](/reference/basic/show-animation)
+[show image](/reference/images/show-image), [image](/reference/images/image), [create image](/reference/images/create-image), [show animation](/reference/basic/show-animation)
 

docs/reference/images/set-pixel.md

@@ -2,9 +2,9 @@
 
 The set pixel function. #set pixel.
 
-Set the on/off state of pixel in an [Image](/reference/image/image).
+Set the on/off state of pixel in an [Image](/reference/images/image).
 
-### KindScript
+### JavaScript
 
 ```
 export function setPixel(_this: micro_bit.Image, x: number, y: number, value: boolean)
@@ -12,8 +12,8 @@ export function setPixel(_this: micro_bit.Image, x: number, y: number, value: bo
 
 ### Parameters
 
-* x - [Number](/reference/types/number); the *x coordinate* or horizontal position of a pixel in an [image](/reference/image/image)
-* x - [Number](/reference/types/number); the *y coordinate* or vertical position of a pixel in an [image](/reference/image/image)
+* x - [Number](/reference/types/number); the *x coordinate* or horizontal position of a pixel in an [image](/reference/images/image)
+* x - [Number](/reference/types/number); the *y coordinate* or vertical position of a pixel in an [image](/reference/images/image)
 * value -[Boolean](/reference/types/boolean); the on/off state of a pixel; `true` for on, `false` for off
 
 ### x, y coordinates?
@@ -38,5 +38,5 @@ img.showImage(0)
 
 ### See also
 
-[pixel](/reference/images/pixel), [show image](/reference/images/show-image), [image](/reference/image/image), [create image](/reference/images/create-image), [scroll image](/reference/images/scroll-image)
+[pixel](/reference/images/pixel), [show image](/reference/images/show-image), [image](/reference/images/image), [create image](/reference/images/create-image), [scroll image](/reference/images/scroll-image)
 

docs/reference/images/show-frame.md

@@ -2,9 +2,9 @@
 
 The show frame function.
 
-Display an [Image](/reference/image/image) on the BBC micro:bit's [LED screen](/device/screen)
+Display an [Image](/reference/images/image) on the BBC micro:bit's [LED screen](/device/screen)
 
-### KindScript
+### JavaScript
 
 ```
 export function showFrame(img: micro_bit.Image, frame: number)
@@ -31,11 +31,7 @@ let img = images.createImage(`
 img.showFrame(1)
 ```
 
-### Lessons
-
-[smiley](/lessons/smiley), [flashing heart](/lessons/flashing-heart), [magic logo](/lessons/magic-logo)
-
 ### See also
 
-[create image](/reference/images/create-image), [show animation](/reference/basic/show-animation), [image](/reference/image/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
+[create image](/reference/images/create-image), [show animation](/reference/basic/show-animation), [image](/reference/images/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)
 

docs/reference/images/show-image.md

@@ -2,13 +2,7 @@
 
 The show image function.
 
-Show an [Image](/reference/image/image) on the [LED screen](/device/screen), followed by a 400ms pause.
-
-### Block Editor
-
-![](/static/mb/show-image-0.png)
-
-### KindScript
+Show an [Image](/reference/images/image) on the [LED screen](/device/screen), followed by a 400ms pause.
 
 ```
 export function showImage(_this: micro_bit.Image, xOffset: number)
@@ -20,7 +14,7 @@ export function showImage(_this: micro_bit.Image, xOffset: number)
 
 ### Create image and show image
 
-Use the [image editor](/reference/image/image) to create images using the [create image](/reference/image/create-image) function, and then use `show image` like this:
+Use the [image editor](/reference/images/image) to create images using the [create image](/reference/images/create-image) function, and then use `show image` like this:
 
 ```
 let img = images.createImage(`
@@ -51,11 +45,7 @@ for (let i = 0; i < 5; i++) {
 }
 ```
 
-### Lessons
-
-[rock paper scissors](/lessons/rock-paper-scissors), [digital pet](/lessons/digital-pet), [offset-image](/lessons/offset-image)
-
 ### See also
 
-[show animation](/reference/basic/show-animation), [image](/reference/image/image), [create image](/reference/images/create-image), [scroll image](/reference/images/scroll-image)
+[show animation](/reference/basic/show-animation), [image](/reference/images/image), [create image](/reference/images/create-image), [scroll image](/reference/images/scroll-image)
 

docs/reference/images/width.md

@@ -2,12 +2,10 @@
 
 The width function.
 
-Get the width of an [Image](/reference/image/image) in columns.
+Get the width of an [Image](/reference/images/image) in columns.
 
-### KindScript
-
-```
-export function width(_this: micro_bit.Image) : number
+```sig
+images.createImage().width();
 ```
 
 ### Parameters

docs/reference/input.md

@@ -1,7 +1,6 @@
 # Input
 
-
-
+Events and data from sensors
 
 ```cards
 input.onButtonPressed(Button.A, () => {

docs/reference/input/acceleration.md

@@ -2,48 +2,41 @@
 
 Get the acceleration value (milli g-force), in one of three specified dimensions.
 
+Find the acceleration of the micro:bit (how fast it is speeding up or slowing down).
+
 ```sig
 input.acceleration(Dimension.X);
 ```
 
+## ~hint
+
+You measure acceleration with the **milli-g**, which is 1/1000 of a **g**.
+A **g** is as much acceleration as you get from Earth's gravity.
+
+## ~
+
+
+
 ### Parameters
 
-* dimension : [String](/reference/types/string) - one of three values specifying the axis of acceleration: ``x`` (left/right); ``y`` (forward/backwards); ``z`` (up/down)
+* which direction you are checking for acceleration, either `Dimension.X` (left and right), `Dimension.Y` (forward and backward), or `Dimension.Z` (up and down)
 
 ### Returns
 
-* [Number](/reference/types/number) - acceleration, in milli-gravities. When the micro:bit is laying flat with the screen up, x=0, y=0 and z=-1023.
+* a [number](/reference/types/number) that means the amount of acceleration. When the micro:bit is lying flat on a surface with the screen pointing up, `x` is `0`, `y` is `0`, and `z` is `-1023`.
 
 ### Example: bar chart
 
-Use the ``plot bar chart`` to visual the acceleration on the LED screen.
+This example shows the acceleration of the micro:bit with a bar graph.
 
 ```blocks
 basic.forever(() => {
-    led.plotBarGraph(input.acceleration("x"), 1023)
+    led.plotBarGraph(input.acceleration(Dimension.X), 1023)
 })
 ```
 
-### Example: micro:bit leveller
-
-The following example uses the `acceleration` and the `plot` function to help you move the micro:bit until it's level (the centre LED is *on* when the device is level). When running this code in a web browser, move your mouse to simulate the accelerometer.
-
-```blocks
-basic.forever(() => {
-    let ax = input.acceleration(Dimension.X)
-    let x = pins.map(-1023, 1023, 0, 4, ax)
-    let ay = input.acceleration("y")
-    let y = pins.map(-1023, 1023, 0, 4, ay)
-    basic.clearScreen()
-    led.plot(x, y)
-})
-```
-
-### Lessons
-
-[zoomer](/lessons/zoomer)
 
 ### See also
 
-[compass-heading](/input/compass-heading), [lightlevel](/input/lightlevel)
+[compass-heading](/reference/input/compass-heading), [lightlevel](/reference/input/lightlevel)