merges with master

docs/blocks/math.md

@@ -1,37 +1,36 @@
 # Math
 
-[Numeric](/reference/types/number) values: 0, 1, 2, ...
+### [Numeric](/reference/types/number) values: 0, 1, 2, ...
 
-```blocks
+```block
 0;
 1;
 2;
 ```
 
-Arithmetic binary operation (+, -, *, /)
+### Arithmetic binary operation (+, -, *, /)
 
-```blocks
+```block
 0+1;
 0-1;
 1*2;
 3/4;
 ```
 
-Absolute value
+### Absolute value
 
-```blocks
+```block
 Math.abs(-5);
 ```
 
-Minimum/maximum of two values
+### Minimum/maximum of two values
 
-```blocks
+```block
 Math.min(0, 1);
-Math.max(0, 1);
 ```
 
-Random value
+### Random value
 
-```blocks
+```block
 Math.random(5);
 ```

docs/blocks/math/math.md

@@ -1,42 +0,0 @@
-# Math functions
-
-### @parent blocks/language
-
-The math library includes math related functions that you can use with [Numbers](/reference/types/number).
-
-### abs
-
-math `->` abs (x : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns the absolute value of input parameter `x`
-
-![](/static/mb/blocks/math-0.png)
-
-### max
-
-math `->` max (x : [Number](/reference/types/number), y : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns the larger of two input numbers (`x` and `y`)
-
-![](/static/mb/blocks/math-1.png)
-
-### min
-
-math `->` min (x : [Number](/reference/types/number), y : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns the smaller of two input numbers (`x` and `y`)
-
-![](/static/mb/blocks/math-2.png)
-
-### random
-
-math `->` random (limit : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns a random [Number](/reference/types/number) between 0 and the parameter *limit*
-
-![](/static/mb/blocks/math-3.png)
-
-### See also
-
-[Number](/reference/types/number)
-

docs/device/crocodile-clips.md

@@ -7,10 +7,16 @@ Register an event that will execute whenever the user attaches one side of the c
 
 This example displays a random number every time the crocodile clip holds  `GND` then connects and disconnects the `P0` pin. Each time the crocodile clip is firmly connected and disconnected from pin `P0`, the micro:bit will return a random Number between 0 and the parameter limit
 
-![](/static/mb/crocodile-clips-0.png)
+```blocks
+input.onPinPressed(TouchPin.P0, () => {
+    basic.showNumber(Math.random(10))
+})
+```
 
 ### Connecting Crocodile Clips
 
+![](/static/mb/crocodile-clips-2.jpg)
+
 ### 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/lessons/blocks-conditions.md

@@ -4,9 +4,11 @@ An introduction to conditions for the Block Editor.
 
 ## Introduction to conditions
 
-In the introduction to code, we made the BBC micro:bit automatically shows the message ‘hello, world!’:
+In the introduction to code, we made the BBC micro:bit automatically shows the message ‘hello world!’:
 
-![](/static/mb/blocks/lessons/blocks-conditions-0.png)
+```blocks
+basic.showString("hello world!")
+```
 
 This statement, or code, will happen as soon as the BBC micro:bit is activated. This means it is unconditional. We can add a condition to make code function in certain ways:
 
@@ -16,11 +18,13 @@ This statement, or code, will happen as soon as the BBC micro:bit is activated.
 
 In programming we use an ‘if’ statement: if this condition is met, do something. Lets add an if statement to the code we had before; the BBC Micro:bit will wait for the user to press a button before showing the image.
 
-### Write the code
-
-Click the **if** category and drag an `if/do` block. Drag the`show string` block we wrote previously into the `do` section of the block. Next click the **input** tab and drag a `button pressed` block, connect it to the open jigsaw of the `if` block. This is our criteria: `if A button is pressed`. We can change which button (button A or B) by clicking the arrow next to ‘A’ and changing the value. This means our BBC micro:bit is waiting for button A (the left button) to be pressed. Finally go to the **basic** tab and drag a `forever` block, and attach all our code inside. We add this block to ensure the BBC micro:bit is always waiting to show us this message, not just once. Your code should look like this:
-
-![](/static/mb/blocks/lessons/blocks-conditions-1.png)
+```blocks
+basic.forever(() => {
+    if (input.buttonIsPressed(Button.A)) {
+        basic.showString("hello world!")
+    }
+})
+```
 
 Again, test the code in the simulator. Try clicking **Button A** to display the "hello, world!" message every time the `button is pressed`.
 
@@ -40,7 +44,15 @@ For example, we could make it so our BBC Micro:bit tells us to press the A butto
 
 We want the message "Press A!" to scroll across the BBC micro:bit, so right-click the `show string` block and select **Duplicate**. Drag this new block into the `else` section and replace the “hello, world!” with "Press A!". Your code should look like this:
 
-![](/static/mb/blocks/lessons/blocks-conditions-2.png)
+```blocks
+basic.forever(() => {
+    if (input.buttonIsPressed(Button.A)) {
+        basic.showString("hello world!")
+    } else {
+        basic.showString("PRESS A")        
+    }
+})
+```
 
 So, to recap: the `forever` block makes sure our code runs forever. The BBC micro:bit checks if the user is pressing the left button, if the user is not then the “Press the button!” message will scroll across the LEDs. If the user is pressing the button then the “hello, world!” message will scroll across the screen. Check this in the simulator or attach the BBC micro:bit to the computer then click **Download** to send the code onto the BBC micro:bit.
 

docs/lessons/challenges.md

@@ -1,88 +0,0 @@
-# blocks - challenges
-
-Extra stuff for the Block Editor - an introduction to GPIO
-
-## Before we get started
-
-This section details challenges for the BBC micro:bit. Ensure you have completed all other sections of the Microsoft Block Editor tutorials before attempting these challenges!
-
-## Quiz Challenge [1]
-
-Using if statements, try to add more statements to create a simple quiz. The user will be told if the question is right or not, and will have two options (button A and button B).
-
-Here is some sample code for a simple quiz:
-
-![](/static/mb/blocks/lessons-0.png)
-
-## Timer Challenge [2]
-
-Create a timer that runs out after a certain amount of time (using the *count* loop). For an extra challenge, let the user input the amount of seconds they want the timer to run for using variables and the buttons as input. The solution is below.
-
-![](/static/mb/blocks/lessons-1.png)
-
-## Graphics Challenges [3]
-
-Using the knowledge you have learnt from the [rendering graphics](/lessons/graphics) section, try creating an algorithm to draw these shapes. Before you write the code try to figure out how the BBC micro:bit will be thinking to plot these points. For example, with our diagonal line – “count up from 0 to 4 by 1, and plot points x=i and y=i”.
-
-* Another diagonal line
-* A square going around the board
-* A filled square
-* A square which unplots itself after
-* A filled square which then unplots itself
-
-The solutions are below.
-
-### Square [3.1]
-
-![](/static/mb/blocks/lessons-2.png)
-
-### Filled square [3.2]
-
-![](/static/mb/blocks/lessons-3.png)
-
-### Vanishing square [3.3]
-
-Use the same code and algorithm for the square solution, only use the ‘unplot’ block to make this LED turn off again. You could also reverse the algorithm.
-
-### Vanishing filled square [3.4]
-
-Use the same code and algorithm for the filled square solution, only use the `unplot` block to make this LED turn off again. You could also reverse the algorithm.
-
-## Animation Challenge [4]
-
-Use your new knowledge of animations and algorithms to program your BBC micro:bit to act human: for example, you could make your BBC micro:bit smile and wink. Remember you can display images with the `show image` and `create image` blocks. Sample code is below.
-
-![](/static/mb/blocks/lessons-4.png)
-
-## Electronic Dice Challenge [5]
-
-Using the code in the Random Numbers tutorial in Section 6, or your own algorithm, create an electronic dice that displays the values appropriate for a dice (so 1 shows a single LED on in the center, two shows two LEDs on at each corner, etc.). You may want to declare image variables to do this, then check what it is equal to using an ‘if’ statement. Sample code is below.
-
-![](/static/mb/blocks/lessons-4.png)
-
-## Calculator Challenge [6]
-
-Using your knowledge of loops, counters and math, create a calculator.
-
-The calculator should:
-
-* Count the amount of times the user presses the left button before pressing the right button (this is the first value, or valueOne)
-* Count the amount of times the user presses the left button before the right button again (this is the second value, or valueTwo)
-* Scroll through operations (+,-, x and divide) until the user presses the right button to make a choice
-* Perform the calculation
-* Show the entire calculation, for example: 5 + 10 = 15
-
-Sample code is below.
-
-![](/static/mb/blocks/lessons-5.png)
-
-## Smart watch Challenge [8]
-
-Create a smart watch using the BBC micro:bit. Create a menu where the user presses one button to cycle through options and another button to choose this option. Add applications to this smart watch:
-
-* Calculators
-* Games
-* Random number generators
-
-And any other applications you can think of.
-

docs/lessons/graphics.md

@@ -6,7 +6,9 @@ An introduction to graphics for the Block Editor.
 
 Ensure you have completed the 'Hello, world!' and Loop tutorials and tested them on a simulator or on BBC micro:bit.
 
-![](/static/mb/blocks/lessons/blocks-conditions-0.png)
+```blocks
+basic.showString("HI!");
+```
 
 The BBC micro:bit has a grid of 25 LEDs, so we can use these to display images.
 
@@ -24,9 +26,16 @@ We can also code our bug to plot a point by giving an x (horizontal) and y (vert
 
 We can also unplot a point (turn the LED off again) using the `unplot` block. So we could create a flashing LED program, using the `pause` block to create a delay.
 
-![](/static/mb/blocks/lessons/graphics-1.png)
+```blocks
+basic.forever(() => {
+    led.plot(2,2)
+    basic.pause(100)
+    led.unplot(2,2)
+    basic.pause(100)
+})
+```
 
-We can also use the `clear screen` block to turn off all LEDs.
+We can also use the `basic.clearScreen` block to turn off all LEDs.
 
 ## Tip
 
@@ -34,26 +43,35 @@ The pause block is in milliseconds, so setting it to 1000 will have a pause of a
 
 ### Devising algorithms for shapes
 
-An algorithm is a set of steps to follow to solve a problem. We can begin to draw shapes on the BBC micro:bit using an algorithm. For example, we could draw a straight line with this code:
+An algorithm is a set of steps to follow to solve a problem. We can begin to draw shapes on the BBC micro:bit using an algorithm. 
+For example, we could draw a straight line with this code:
 
-![](/static/mb/blocks/lessons/graphics-2.png)
+```blocks
+for(let i = 0; i <=4; i++) {
+    led.plot(i, 0);
+    basic.pause(200)
+}
+```
 
 Our algorithm is: increase **i** by 1 **from 0** to **4**, and **plot** the point **x=i**, **y=0**. The pause block allows this line to be animated (drawn frame by frame).
 
-Try devising an algorithm for a diagonal line using the code above and the variable **i**. Your code should look like this; as our variable increases, so does the location that the BBC micro:bit is plotting at:
-
-![](/static/mb/blocks/lessons/graphics-3.png)
-
-We can create more complex algorithms for more complex shapes, too. See the [challenges](/lessons/challenges) section for additional graphical challenges and solutions.
+Try devising an algorithm for a diagonal line using the code above and the variable **i**.
+```sim
+basic.forever(() => {
+    for(let i = 0; i <=4; i++) {
+        led.plot(i, i);
+        basic.pause(200)
+    }
+    basic.clearScreen();
+})
+```
 
 ### Animations
 
-Animations are changes happening at a certain rate. For example, we could add the `delay` block from the **Basic** drawer with our square algorithm – this will slowly draw a square (as an animation).
+Animations are changes happening at a certain rate. For example, we could add the `pause` block from the **Basic** drawer with our square algorithm – this will slowly draw a square (as an animation).
 
 We could create more complex animations, for example we could make our BBC micro:bit display an explosion or fireworks.
 
-See the [challenges](/lessons/challenges) section for some animation tasks.
-
 ### Image variables
 
 We can create image variables so we can easily display an image at a later point. For example:

docs/lessons/loops.md

@@ -1,59 +0,0 @@
-# blocks - loops
-
-An introduction to Loops for the Block Editor.
-
-We may want to handle the user’s input multiple times or remain waiting for their input for a long time. We use loops to make sure that our code runs multiple times. These can be found in the **Loops** drawer.
-
-### Forever loops
-
-In the Variables tutorial we utilised a forever loop to create a counter:
-
-![](/static/mb/blocks/lessons/blocks-conditions-2.png)
-
-This allows our BBC micro:bit to wait for the user to do something forever, for example wait for the user to press the correct button as the example above shows. If you were creating a quiz, you may want to loop forever until the user presses the correct button or answers the question.
-
-### Repeat Loops
-
-Repeat loops allow code to happen a certain amount of times. You may want to create a quiz that only gives the user a few tries to get the correct answer, for example. The number can be changed to facilitate your code.
-
-![](/static/mb/blocks/lessons/loops-0.png)
-
-The code above will scroll the message, “Hello world” three times.
-
-### While & Until loops
-
-The ‘repeat while’ loop allows you to continue looping some code until a condition is met. The empty socket next to the while loop allows you to connect some Logic and construct a statement.
-
-![](/static/mb/blocks/lessons/loops-1.png)
-
-The code above will scroll the message, “Press it!”, while the user hasn’t pressed the button.
-
-* Drag a `set item` block from the **Variables** drawer. Click the **down arrow** and click **New Variable**, and type "pressed". Drag a `0` block from **Maths** to set the variable **pressed** to 0.
-* Drag a `repeat while` block from the **Loops** drawer and attach an `=` block from the **Logic** drawer. Drag `item` from the **Variables** drawer and click the **down arrow**, select ‘pressed’. Drag a `0` block from Maths and connect it to the other side of the equals. This will carry out the code until ‘pressed’ does not equal 0.
-* Add a `show string` block from the **Basic** drawer and change the message to "Press it!"
-* Add an `if` block from the **Logic** drawer, connect a `button pressed` block from the **Input** drawer, and add text from the **Basic** drawer. Change this to A to show we are waiting for button A.
-* Inside the ‘do’ part of the if statement, add a `set` block from the Variables drawer, click the **down arrow** to change it to **pressed** and drag a `1` from the Maths drawer
-* Lastly underneath the while loop, add another `show string` block and fill in the gaps.
-
-Test the code above on actual hardware or on the simulator window.
-
-We can also change the code in subtle ways to have a completely different effect:
-
-![](/static/mb/blocks/lessons/loops-2.png)
-
-This time we have to press the button three times to leave the while loop.
-
-## Tip
-
-You can press the arrow next to a word in a block to change it. For example, you can change Math functions or change a Logic statement.
-
-### Count or for loops
-
-A count loop allows you to loop a certain amount of times and to change a variable as you do so. For example, we can create a simple counting program:
-
-![](/static/mb/blocks/lessons/loops-3.png)
-
-The count loop will repeat a certain amount of times whilst changing a variable. You can click the arrow next to **i** to replace it with any of your own variables. So this program will display numbers 1 to 10.
-
-This loop allows you to repeat code for the amount of times you want to without worrying about manually changing variables. You could use this for a counting program or a timer.
-

docs/lessons/seismograph/activity.md

@@ -94,8 +94,6 @@ Connect a micro:bit to your computer using your USB cable
 
 Click or tap the **Download** button for the seismograph program to run the program on the micro:bit. 
 
-![](/static/mb/lessons/seismograph22.png)
-
 ## 9. 
 
 A black line should appear directly beneath the colored line. The black line measures the micro:bit acceleration.  And the colored line measures micro:bit simulator acceleration. 

docs/offline.md

@@ -0,0 +1,18 @@
+# Offline editing
+
+## Web application
+
+**https://codethemicrobit.com is an HTML5 web application** that automatically gets cached locally by your browser. 
+Once the web app is loaded and you have compiled at least once, you will have all the code needed to work without an internet connection.
+
+## Command line interface
+
+For more experience users, you can download the entire toolchain and use the [command line interface](/cli) (CLI) to compile 
+and deploy your scripts locally. PXT provides a great out-of-the-box experience using [Visual Studio Code](/code), 
+a lightweight cross-platform code editor.
+
+![](/static/mb/vscode.png)
+
+## Native clients
+
+There are no native clients available yet.

docs/reference/String.md

@@ -1,9 +0,0 @@
-# String
-
-```cards
-String.fromCharCode(0);
-```
-
-### See Also
-
-[fromCharCode](/reference//math/string-from-char-code)

docs/reference/images/image.md

@@ -11,11 +11,16 @@ An *Image* is a matrix of pixels to show on the [LED screen](/device/screen)
 To display an image:
 
 * click `Basic` , `Show LEDs`, and tap on the LEDs`
-* when you're done, return to your code
 
-![](/static/mb/show-leds-1.png)
-
-You should see code similar to this:
+```blocks
+basic.showLeds(`
+    . . . . .
+    . # . # .
+    . . . . .
+    # . . . #
+    . # # # .
+    `)
+```
 
 ### Creating an image
 

docs/reference/led/toggle-all.md

@@ -20,7 +20,11 @@ led.plot(2, 2)
 led.toggleAll()
 ```
 
-![](/static/mb/toggle-all-0.png)
+```sim
+basic.clearScreen()
+led.plot(2, 2)
+led.toggleAll()
+```
 
 ### See also
 

docs/reference/offline.md

@@ -1,26 +0,0 @@
-# Off-line support
-
-The micro:bit pins.
-
-## How to work offline
-
-If you have loaded the web app at some time in the past (by clicking on "my scripts" from the home page), then if you later open the same browser (whether you are online or offline) and type in [https://codethemicrobit.com/](https://codethemicrobit.com/), you will be able to access all the features of the web app. Note that it is important to end the URL with "/".
-
-## Save and load code using files
-
-![](/static/mb/offline-0.png)
-
-The micro:bit automatically saves and synchronises scripts for signed-in users through the cloud. We also decided to also support file save/load for offline support and sharing via email and other storage providers. Users are now able to import and export scripts as files. For example, they can simply email it or submit them in their classroom portal.
-
-![](/static/mb/offline-1.png)
-
-## The new in-browser compiler
-
-The compilation from a script to ARM machine code is now done entirely in the browser  (read the [in depth story](https://www.touchdevelop.com/docs/touch-develop-in-208-bits) about building the compiler). The new compiler is used by the Block Editor, Touch Develop and Code Kingdoms to create a .hex file solely within the confines of your web browser (no Internet connection is needed). The micro:bit compilation process is shown below:
-
-![](/static/mb/offline-2.png)
-
-The C++ compiler is now only used to compile the micro:bit runtime - this is done offline by the micro:bit team and the pre-compiled runtime is linked with your compiled script in the browser.
-
-Compiled .hex files can also be imported back into the web site. This make it easy for a teacher to review the source of a script by simply drag and dropping the file into the editor.
-