Migrate docs from the other repo

docs/reference/input/acceleration.md

@@ -0,0 +1,49 @@
+# Acceleration
+
+Get the acceleration value (milli g-force), in one of three specified dimensions.
+
+```sig
+input.acceleration(Dimension.X);
+```
+
+### Parameters
+
+* dimension : [String](/microbit/reference/types/string) - one of three values specifying the axis of acceleration: ``x`` (left/right); ``y`` (forward/backwards); ``z`` (up/down)
+
+### Returns
+
+* [Number](/microbit/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.
+
+### Example: bar chart
+
+Use the ``plot bar chart`` to visual the acceleration on the LED screen.
+
+```blocks
+basic.forever(() => {
+    led.plotBarGraph(input.acceleration("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](/microbit/lessons/zoomer)
+
+### See also
+
+[compass-heading](/microbit/input/compass-heading), [lightlevel](/microbit/input/lightlevel)
+

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

@@ -0,0 +1,41 @@
+# Button Is Pressed
+
+Get the state of an input button. The micro:bit has two input buttons: A and B.
+
+```sig
+input.buttonIsPressed(Button.A);
+```
+
+### Parameters
+
+* name - [String](/microbit/reference/types/string); input button "A", "B", or "A+B" (both input buttons)
+
+### Returns
+
+* [Boolean](/microbit/reference/types/boolean) - `true` if pressed, `false` if not pressed
+
+### Example
+
+The following code uses an [if](/microbit/reference/logic/if) statement to run code, depending on whether or not the A button is pressed:
+
+```blocks
+basic.forever(() => {
+    let pressed = input.buttonIsPressed(Button.A)
+    if (pressed) {
+        // this code runs if the A button is pressed
+        basic.showNumber(1, 150)
+    } else {
+        // this code runs if the A button is *not* pressed
+        basic.showNumber(0, 150)
+    }
+})
+```
+
+### Lessons
+
+[zoomer](/microbit/lessons/zoomer)
+
+### See also
+
+[on button pressed](/microbit/input/on-button-pressed), [if](/microbit/reference/logic/if), [forever](/microbit/basic/forever)
+

docs/reference/input/compass-heading.md

@@ -0,0 +1,63 @@
+# Compass Heading
+
+Get the compass heading of the micro:bit in degrees. Your micro:bit has a built-in **magnetometer** so it can your direction with respect to the North Magnetic Pole.
+
+```sig
+input.compassHeading();
+```
+
+### Returns
+
+* [Number](/microbit/reference/types/number) - the heading in degrees (0 to 360 degrees). If the compass is calibrating, it returns ``-1003``.
+
+## Simulator
+
+Calibration does not work on the simulator.
+
+### Example
+
+The following code gets the compass heading and stores it in the `degrees` variable:
+
+```blocks
+let degrees = input.compassHeading()
+```
+
+### ~hint 
+
+When running code with this function in a web browser, click and drag the on-screen compass needle to change heading.
+
+### ~
+
+### Example: compass
+
+The following example gets the `compass heading` and then displays a letter depending on the value of `degrees`: N for north, E for East, S for South, and W for West.
+
+```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")
+})
+```
+
+### Calibration
+
+On the first use of the compass, the **calibration** procedure will automatically start. The user must draw a circle with the device until it is fully calibrated.
+
+An enclosure made from metal, or using in proximity of metal objects, might affect the accuracy of the reading and calibration.
+
+During calibration, ``compass heading`` returns ``-1003``.
+
+### Lessons
+
+[compass](/microbit/lessons/compass)
+
+### See also
+
+[acceleration](/microbit/reference/input/acceleration)
+

docs/reference/input/light-level.md

@@ -0,0 +1,30 @@
+# Light Level
+
+Gets the light level from ``0`` (dark) to ``255`` (bright). The light is measured by using various LEDs from the screen.
+
+This function will return ``0`` on the first call to this method, a light reading will be available after the display has activated the light sensor for the first time.
+
+```sig
+input.lightLevel();
+```
+
+### Returns
+
+* [Number](/microbit/reference/types/number) -  light level from ``0`` (dark) to ``255`` (bright).
+
+### Example: chart light level
+
+Use `plot bar chart` to visual the influence of various light source on the light level.
+
+```blocks
+basic.forever(() => {
+    led.plotBarGraph(input.lightLevel(), 255)
+})
+```
+
+### Lessons
+
+### See also
+
+[acceleration](/microbit/reference/input/acceleration), [compass-heading](/microbit/input/compass-heading)
+

docs/reference/input/magnetic-force.md

@@ -0,0 +1,32 @@
+# Magnetic Force
+
+Get the magnetic force (micro Teslas), in one of three specified dimensions.
+
+```sig
+input.magneticForce(Dimension.X);
+```
+
+### Parameters
+
+* dimension : [String](/microbit/reference/types/string) - one of three values specifying the axis of the force: ``x`` (left/right); ``y`` (forward/backwards); ``z`` (up/down); ``strength`` (the length of the vector)
+
+### Returns
+
+* [Number](/microbit/reference/types/number) - magnetic force, in micro-Teslas.
+
+### Example: metal detector
+
+The following example uses the `magnetic force` to control the brightness of the screen. When the magnetic force increases, the center LED will appear brighter.
+
+```blocks
+led.plot(2, 2)
+basic.forever(() => {
+    let f = input.magneticForce(Dimension.X)
+    led.setBrightness(f / 2000)
+})
+```
+
+### See also
+
+[compass heading](/microbit/input/compass-heading)
+

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

@@ -0,0 +1,40 @@
+# On Button Pressed
+
+Register an [event handler](/microbit/reference/event-handler) that will execute whenever an input button (A, B, or A and B together) is pressed during program execution. When [running code](/microbit/js/simulator) with this function in a web browser, click an on-screen input button - labelled A or B.
+
+```sig
+input.onButtonPressed(Button.A, () => {})
+```
+
+### Example: count button clicks
+
+This example counts how many times the left or right input button is pressed. Each time a button is pressed, the global count variable is increased by 1 and displayed on the screen.
+
+```blocks
+let count = 0
+basic.showNumber(count)
+input.onButtonPressed(Button.A, () => {
+    count++;
+    basic.showNumber(count);
+})
+```
+
+### Example: roll a dice
+
+This example generates a random number when you press the B input button, and then displays a random die image:
+
+```blocks
+input.onButtonPressed(Button.B, () => {
+    let dice = Math.random(6)
+    basic.showNumber(dice)
+})
+```
+
+### Lessons
+
+[smiley](/microbit/lessons/smiley), [answering machine](/microbit/lessons/answering-machine), [screen wipe](/microbit/lessons/screen-wipe), [rotation animation](/microbit/lessons/rotation-animation)
+
+### See also
+
+[button is pressed](/microbit/reference/input/button-is-pressed), [forever](/microbit/reference/basic/forever)
+

docs/reference/input/on-gesture.md

@@ -0,0 +1,45 @@
+# On Gesture
+
+Register an [event handler](/microbit/reference/event-handler) that will execute whenever the user executes a gesture withthe BBC micro:bit.
+
+```sig
+input.onGesture(Gesture.Shake,() => {
+})
+```
+
+## Gestures
+
+
+
+### Example: random number
+
+The following example displays a number from 0-9 on the screen when you shake the BBC micro:bit.
+
+```blocks
+input.onGesture(Gesture.Shake,() => {
+    let x = Math.random(10)
+    basic.showNumber(x, 100)
+})
+```
+
+### Example: rock, paper, scissors
+
+The following example shows one of three images (rock, paper, or scissors) when you shake the BBC micro:bit.
+
+```blocks
+input.onGesture(Gesture.Shake,() => {
+    let img = images.createImage(`
+. . . . . # # # # # . . . . #
+. # # # . # . . . # # # . # .
+. # # # . # . . . # . # # . .
+. # # # . # . . . # # # . # .
+. . . . . # # # # # . . . . #
+`)
+    img.showFrame(Math.random(3))
+})
+```
+
+### Lessons
+
+[bounce image](/microbit/lessons/bounce-image), [rock paper scissors](/microbit/lessons/rock-paper-scissors)
+

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

@@ -0,0 +1,32 @@
+# On Pin Pressed
+
+Register an [event handler](/microbit/reference/event-handler) that will execute whenever the user holds the `GND` pin with one hand, and presses pin `0`, `1`, or `2` with the other hand, thus completing a circuit; when you run a script with this function in a web browser, click pins 0 , 1, or 2 on the simulator.
+
+*Note* that this function works best when the BBC micro:bit is powered by AAA battery.
+
+```sig
+input.onPinPressed(TouchPin.P0, () => {
+})
+```
+
+### Example: pin pressed counter
+
+This example counts how many times the P0 pin is pressed. Each time the pin is pressed, the global count variable is increased by 1 and displayed on the screen.
+
+```blocks
+let count = 0
+basic.showNumber(count, 100)
+input.onPinPressed(TouchPin.P0, () => {
+    count = count + 1
+    basic.showNumber(count, 100)
+})
+```
+
+### Lessons
+
+[love meter](/microbit/lessons/love-meter)
+
+### See also
+
+[BBC micro:bit pins](/microbit/device/pins), [pin is pressed](/microbit/input/pin-is-pressed), [analog read pin](/microbit/pins/analog-read-pin), [analog write pin](/microbit/pins/analog-write-pin), [digital read pin](/microbit/pins/digital-read-pin), [digital write pin](/microbit/pins/digital-write-pin)
+

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

@@ -0,0 +1,36 @@
+# Pin Is Pressed
+
+Gets the pin state (pressed or not pressed), by detecting when the user holds the `GND` pin with one hand, and presses pin `0`, `1`, or `2` with the other hand, thus completing a circuit.
+
+*Note* that this function works best when the BBC micro:bit is powered by AAA battery.
+
+```sig
+input.pinIsPressed(TouchPin.P0);
+```
+
+### Parameters
+
+* name - [String](/microbit/reference/types/string); the pin name ("P0", "P1", or "P2")
+
+### returns
+
+* [Boolean](/microbit/reference/types/boolean) - `true` if pressed, `false` if not pressed
+
+### Example
+
+This example displays 1 if P0 is pressed, and 0 if P0 is not pressed:
+
+```blocks
+basic.forever(() => {
+    if (input.pinIsPressed(TouchPin.P0)) {
+        basic.showNumber(1, 150)
+    } else {
+        basic.showNumber(0, 150)
+    }
+})
+```
+
+### See also
+
+[BBC micro:bit pins](/microbit/device/pins), [on pin pressed](/microbit/input/on-pin-pressed), [analog read pin](/microbit/reference/pins/analog-read-pin), [analog write pin](/microbit/reference/pins/analog-write-pin), [digital read pin](/microbit/reference/pins/digital-read-pin), [digital write pin](/microbit/reference/pins/digital-write-pin)
+

docs/reference/input/rotation.md

@@ -0,0 +1,48 @@
+# Rotation
+
+Get a rotation angle in degrees inferred from the accelerometer readings.
+
+```sig
+input.rotation(Rotation.Roll);
+```
+
+### Parameters
+
+* kind: [String](/microbit/reference/types/string) - one of values specifying the kind of rotation: ``pitch`` (up/down around the ``x`` axis); ``roll`` (left/right around the ``y`` axis)
+
+### Returns
+
+* [Number](/microbit/reference/types/number) - angle, in degrees.
+
+### Example: micro:bit leveller
+
+The following example uses the `rotation` and the `plot leds` function to help you move the BBC micro:bit until it's level: when it is level, a smiley shows up on the screen. When running this code in a web browser, move your mouse to simulate the rotation.
+
+```sig
+basic.forever(() => {
+    let pitch = input.rotation(Rotation.Pitch)
+    let roll = input.rotation(Rotation.Roll)
+    if (Math.abs(pitch) < 10 && Math.abs(roll) < 10) {
+        basic.plotLeds(`
+. . . . .
+. # . # .
+. . . . .
+# . . . #
+. # # # .
+`)
+    } else {
+        basic.plotLeds(`
+# . . . #
+. # . # .
+. . # . .
+. # . # .
+# . . . #
+`)
+    }
+})
+```
+
+### See also
+
+[acceleration](/microbit/reference/input/acceleration), [compass-heading](/microbit/reference/input/compass-heading)
+

docs/reference/input/running-time.md

@@ -0,0 +1,29 @@
+# Running Time
+
+Get the number of milliseconds elapsed since the script began. 1,000 milliseconds = 1 second.
+
+```sig
+input.runningTime();
+```
+
+### Returns
+
+* [Number](/microbit/reference/types/number)
+
+### Example: elapsed time
+
+This code gets the elapsed time since the start of the program execution and displays it on the screen.
+
+```blocks
+let now = input.runningTime()
+basic.showNumber(now)
+```
+
+### Lessons
+
+[speed button](/microbit/lessons/speed-button)
+
+### See also
+
+[show number](/microbit/reference/basic/show-number), [pause](/microbit/reference/basic/pause)
+

docs/reference/input/temperature.md

@@ -0,0 +1,35 @@
+# Temperature
+
+Get the ambient temperature (degree Celsius °C). The temperature is inferred from the the surface temperature of the various chips on the micro:bit.
+
+```sig
+input.temperature();
+```
+
+### Returns
+
+* [Number](/microbit/reference/types/number) - temperature in degree Celsius °C.
+
+### How does it work?
+
+The BBC micro:bit does not have a dedicated temperature sensor. Instead, the temperature provided is actually the temperature of the silicon die on the main CPU. As the processor generally runs cold though (it is a high efficiency ARM core), the temperature is a good approximation of the ambient temperature... you might warm up if you give the processor a lot of work to do though, and don't [sleep](/microbit/reference/basic/pause)!
+
+The temperature sensor has a high precision, but isn't trimmed for accuracy. In other words, it can sense changes in temperature very well, but there may be (and probably is) base line offset. i.e. it might return 20 degrees when it's actually 17, but it would return 21 when it is 18 etc.
+
+### Example: micro:bit thermometer
+
+The following example uses the `temperature` and the `show number` to display the room temperature.
+
+```sig
+basic.forever(() => {
+    let temp = input.temperature()
+    basic.showNumber(temp)
+})
+```
+
+### Lessons
+
+### See also
+
+[compass-heading](/microbit/reference/input/compass-heading), [acceleration](/microbit/reference/input/acceleration)
+