c_meyer/pxt-calliope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

2.1.28, initiation update to PXT v5.28.24 (#54)

Browse Source
This commit is contained in:
Amerlander
2019-12-02 05:58:26 +01:00
committed by Peli de Halleux
parent 38a964516e
commit 5c114a0c57
1261 changed files with 50692 additions and 21604 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/reference/input/acceleration.md
View File

@ -1,6 +1,6 @@
# Acceleration
Get the acceleration value (milli g-force), in one of three specified dimensions.
Get the acceleration value (milli g-force) in one of three dimensions, or the combined force in all directions (x, y, and z).
Find the acceleration of the @boardname@ (how fast it is speeding up or slowing down).
@ -15,17 +15,41 @@ A **g** is as much acceleration as you get from Earth's gravity.
## ~
Watch this video to learn how the accelerometer on the @boardname@ works:
https://www.youtube.com/watch?v=byngcwjO51U
### Parameters
## Parameters
* ``dimension`` means which direction you are checking for acceleration, either `Dimension.X` (left and right), `Dimension.Y` (forward and backward), or `Dimension.Z` (up and down)
* **dimension**: the direction you are checking for acceleration, or the total strength of force.
>`x`: acceleration in the left and right direction.<br/>
`y`: acceleration in the forward and backward direction.<br/>
`z`: acceleration in the up and down direction.<br/>
`strength`: the resulting strength of acceleration from all three dimensions (directions).
### Returns
### ~hint
* a [number](/reference/types/number) that means the amount of acceleration. When the @boardname@ is lying flat on a surface with the screen pointing up, `x` is `0`, `y` is `0`, and `z` is `-1023`.
**Forces in space**
### Example: bar chart
Since we don't live on a flat world, forces happen in three dimensional space. If the movement of an object isn't exactly in the direction of one axis, we need a way to calculate its acceleration from the values measured for all the axes together.
If you put your @boardname@ on a level table and push it diagonally, you have an acceleration in two dimensions. You can find the acceleration in that direction just like how you calculate the long side of a triangle using the two shorter sides (**X** and **Y**):
```strength2D = Math.sqrt((accelX * accelX) + (accelY * accelY))```
If you decide to lift your @boardname@ off the table, then you've just added another dimension, so insert the acceleration value for the **Z** axis into the equation:
```strength3D = Math.sqrt((accelX * accelX) + (accelY * accelY) + (accelZ * accelZ))```
This calculation is called the [Euclidean norm](https://en.wikipedia.org/wiki/Euclidean_norm) of acceleration.
### ~
## Returns
* a [number](/types/number) that means the amount of acceleration. When the @boardname@ is lying flat on a surface with the screen pointing up, `x` is `0`, `y` is `0`, `z` is `-1023`, and `strength` is `1023`.
## Example: bar chart
This example shows the acceleration of the @boardname@ with a bar graph.
@ -34,9 +58,18 @@ basic.forever(() => {
led.plotBarGraph(input.acceleration(Dimension.X), 1023)
})
```
### Example: quake meter
Every 5 seconds, with the @boardname@ facing upward on a flat surface, show how much the earth is shaking (if at all).
### See also
```blocks
basic.forever(() => {
basic.showNumber(input.acceleration(Dimension.Strength))
basic.pause(5000)
})
```
## See also
[set accelerometer range](/reference/input/set-accelerometer-range),
[compass heading](/reference/input/compass-heading),

22
docs/reference/input/button-is-pressed.md
View File

@ -6,17 +6,17 @@ Check whether a button is pressed right now. The @boardname@ has two buttons: bu
input.buttonIsPressed(Button.A);
```
### Parameters
## Parameters
* ``button`` is a [String](/reference/types/string). You should store `A` in it to check the left button, `B` to check the right button, or `A+B` to check both at the same time.
* ``button`` is a [String](/types/string). You should store `A` in it to check the left button, `B` to check the right button, or `A+B` to check both at the same time.
### Returns
## Returns
* [Boolean](/blocks/logic/boolean) that is `true` if the button you are checking is pressed, `false` if it is not pressed.
* a [boolean](/blocks/logic/boolean) value that is `true` if the button you are checking is pressed, `false` if it is not pressed.
### Example
## Example
This program uses an [if](/blocks/logic/if) to run
This program uses an [``||logic:if||``](/blocks/logic/if) to run
one part of the program if the `A` button is pressed, and
another part if it is not pressed.
@ -25,15 +25,19 @@ basic.forever(() => {
let pressed = input.buttonIsPressed(Button.A)
if (pressed) {
// this part runs if the A button is pressed
basic.showNumber(1, 150)
basic.showNumber(1)
} else {
// this part runs if the A button is *not* pressed
basic.showNumber(0, 150)
basic.showNumber(0)
}
})
```
### See also
Find out how buttons provide input to the @boardname@ in this video:
https://www.youtube.com/watch?v=t_Qujjd_38o
## See also
[on button pressed](/reference/input/on-button-pressed), [if](/blocks/logic/if), [forever](/reference/basic/forever)

33
docs/reference/input/calibrate-compass.md Normal file
View File

@ -0,0 +1,33 @@
# Calibrate Compass
Runs the compass calibration sequence.
```sig
input.calibrateCompass();
```
## Calibration
The calibration will ask you to draw a circle or fill the LED screen by tilting the
@boardname@.
The compass calibration is stored in memory by the @boardname@, so next time you press the reset button or remove and replace the power the calibration will be remembered.
When you flash a new program to your @boardname@ via USB, this memory is cleared so you will have to re-calibrate it.
If you are calibrating or using the compass near metal, it might
confuse the @boardname@.
## Example
This example runs the calibration when the user presses **A+B** buttons.
```blocks
input.onButtonPressed(Button.AB, () => {
input.calibrateCompass();
})
```
## See also
[compassHeading](/reference/input/compass-heading)

55
docs/reference/input/compass-heading.md
View File

@ -2,7 +2,7 @@
Find which direction on a compass the @boardname@ is facing.
The @boardname@ measures the **compass heading** from `0` to `360`
The @boardname@ measures the **compass heading** from `0` to `359`
degrees with its **magnetometer** chip. Different numbers mean north,
east, south, and west.
@ -10,11 +10,11 @@ east, south, and west.
input.compassHeading();
```
### Returns
## Returns
* a [number](/reference/types/number) from `0` to `360` degrees, which means the compass heading. If the compass isn't ready, it returns `-1003`.
* a [number](/types/number) from `0` to `359` degrees, which means the compass heading. If the compass isn't ready, it returns `-1003`.
### Example
## Example
This program finds the compass heading and stores it in the
`degrees` variable.
@ -23,42 +23,59 @@ This program finds the compass heading and stores it in the
let degrees = input.compassHeading()
```
### ~hint
## ~hint
When you run a program that uses this function in a browser, click and drag
the compass needle on the screen to change the compass heading.
### ~
## ~
### Example: compass
## Example: compass
This program finds the compass heading and then shows a letter
that means whether the @boardname@ is facing north (N), south (S),
east (E), or west (W).
```blocks
let degrees = 0
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")
degrees = input.compassHeading()
if (degrees < 45) {
basic.showArrow(ArrowNames.North)
} else if (degrees < 135) {
basic.showArrow(ArrowNames.East)
} else if (degrees < 225) {
basic.showArrow(ArrowNames.South)
} else if (degrees < 315) {
basic.showArrow(ArrowNames.West)
} else {
basic.showArrow(ArrowNames.North)
}
})
```
### Calibration
## Calibration
Every time you start to use the compass (for example, if you have just
turned the @boardname@ on), the @boardname@ will start to **calibrate**
turned the @boardname@ on), the @boardname@ will start to [calibrateCompass](/reference/input/calibrate-compass)
(adjust itself). It will ask you to draw a circle by tilting the
@boardname@.
If you are calibrating or using the compass near metal, it might
confuse the @boardname@.
### See also
## ~ hint
[acceleration](/reference/input/acceleration)
Keep the calibration handy by running it when the user pressed **A+B**.
```block
input.onButtonPressed(Button.AB, () => {
input.calibrateCompass();
})
```
## ~
## See also
[acceleration](/reference/input/acceleration), [calibrateCompass](/reference/input/calibrate-compass)

28
docs/reference/input/is-gesture.md Normal file
View File

@ -0,0 +1,28 @@
# Is Gesture
Tests if a gesture is currently detected.
```sig
input.isGesture(Gesture.Shake)
```
## Parameters
* ``gesture`` means the way you hold or move the @boardname@. This can be `shake`, `logo up`, `logo down`, `screen up`, `screen down`, `tilt left`, `tilt right`, `free fall`, `3g`, or `6g`.
## Example: random number
This program shows a number from `2` to `9` when you shake the @boardname@.
```blocks
forever(function() {
if (input.isGesture(Gesture.Shake)) {
let x = Math.randomRange(2, 9)
basic.showNumber(x)
}
})
```
## See Also
[on gesture](/reference/input/on-gesture)

14
docs/reference/input/light-level.md
View File

@ -14,11 +14,15 @@ has to be turned on first.
input.lightLevel();
```
### Returns
Learn more about how light level is detected in this light sensor video:
* a [Number](/reference/types/number) that means a light level from ``0`` (dark) to ``255`` (bright).
https://www.youtube.com/watch?v=TKhCr-dQMBY.
### Example: show light level
## Returns
* a [Number](/types/number) that means a light level from ``0`` (dark) to ``255`` (bright).
## Example: show light level
When you press button `B` on the microbit, this
program shows the light level
@ -31,7 +35,7 @@ input.onButtonPressed(Button.B, () => {
})
```
### Example: chart light level
## Example: chart light level
This program shows the light level with a [bar chart](/reference/led/plot-bar-graph) on the @boardname@ screen.
If you carry the @boardname@ around to different places with different light levels,
@ -43,7 +47,7 @@ basic.forever(() => {
})
```
### See also
## See also
[acceleration](/reference/input/acceleration), [compass-heading](/reference/input/compass-heading)

10
docs/reference/input/magnetic-force.md
View File

@ -13,18 +13,18 @@ The @boardname@ measures magnetic force with **microteslas**.
## ~
### Parameters
## Parameters
* ``dimension`` means which direction the @boardname@ should measure
magnetic force in: either `Dimension.X` (the left-right direction),
`Dimension.Y` (the forward/backward direction), or `Dimension.Z`
(the up/down direction)
### Returns
## Returns
* a [number](/reference/types/number) of microteslas that means the strength of the magnet
* a [number](/types/number) of microteslas that means the strength of the magnet
### Example: metal detector
## Example: metal detector
This program makes the center LED of the @boardname@ get brighter when
the magnetic force is stronger, and dimmer when it is weaker.
@ -37,6 +37,6 @@ basic.forever(() => {
})
```
### See also
## See also
[compass heading](/reference/input/compass-heading)

21
docs/reference/input/on-button-pressed.md
View File

@ -5,11 +5,18 @@ This handler works when button `A` or `B` is pressed, or `A` and `B` together.
When you are using this function in a web browser, click the buttons on the screen instead of the ones
on the @boardname@.
* For button `A` or `B`: This handler works when the button is pushed down and released within 1 second.
* For `A` and `B` together: This handler works when `A` and `B` are both pushed down, then one of them is released within 1.5 seconds of pushing down the second button.
```sig
input.onButtonPressed(Button.A, () => {})
```
### Example: count button clicks
Find out how buttons provide input to the @boardname@ in this video:
https://www.youtube.com/watch?v=t_Qujjd_38o
## Example: count button clicks
This example counts how many times you press the `A` button.
Each time you press the button, the [LED screen](/device/screen) shows the `count` variable getting bigger.
@ -23,25 +30,25 @@ input.onButtonPressed(Button.A, () => {
})
```
### Example: roll dice
## Example: roll dice
This example shows a number from 1 to 6 when you press the `B` button.
```blocks
input.onButtonPressed(Button.B, () => {
let dice = Math.random(6) + 1
let dice = Math.randomRange(0, 5) + 1
basic.showNumber(dice)
})
```
### ~hint
## ~hint
This program adds a `1` to `random(6)` so the numbers on the dice will come out right.
This program adds a `1` to `random(5)` so the numbers on the dice will come out right.
Otherwise, sometimes they would show a `0`.
### ~
## ~
### See also
## See also
[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/blocks/math)

13
docs/reference/input/on-gesture.md
View File

@ -9,18 +9,21 @@ input.onGesture(Gesture.Shake,() => {
})
```
### Parameters
## Parameters
* ``gesture`` means the way you hold or move the @boardname@. This can be `shake`, `logo up`, `logo down`, `screen up`, `screen down`, `tilt left`, `tilt right`, `free fall`, `3g`, or `6g`.
### Example: random number
## Example: random number
This program shows a number from `0` to `9` when you shake the @boardname@.
This program shows a number from `2` to `9` when you shake the @boardname@.
```blocks
input.onGesture(Gesture.Shake,() => {
let x = Math.random(10)
basic.showNumber(x, 100)
let x = Math.randomRange(2, 9)
basic.showNumber(x)
})
```
## See Also
[is gesture](/reference/input/is-gesture)

19
docs/reference/input/on-pin-pressed.md
View File

@ -2,8 +2,9 @@
Start an [event handler](/reference/event-handler) (part of the
program that will run when something happens, like when a button is
pressed). This handler works when you press pin `0`, `1`, or `2`
together with `GND`. When you are using this function in a web
pressed). This handler works when you touch pin `0`, `1`, or `2`
together with `GND`, and release it within 1 second.
When you are using this function in a web
browser, click the pins on the screen instead of the ones on the
@boardname@.
@ -28,21 +29,27 @@ instead of the USB cable.
* ``name`` means the pin that is being pressed, either `P0`, `P1`, or `P2`
### Example: pin pressed counter
## Pin presses in action
See how the @boardname@ detects a press at a pin or on something connected to a pin in this video:
https://www.youtube.com/watch?v=GEpZrvbsO7o
## Example: pin pressed counter
This program counts how many times you press the `P0` pin.
Every time you press the pin, the program shows the number of times on the screen.
```blocks
let count = 0
basic.showNumber(count, 100)
basic.showNumber(count)
input.onPinPressed(TouchPin.P0, () => {
count = count + 1
basic.showNumber(count, 100)
basic.showNumber(count)
})
```
### See also
## See also
[@boardname@ 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)

4
docs/reference/input/on-pin-released.md
View File

@ -28,7 +28,7 @@ instead of the USB cable.
* ``name`` means the pin that is being released, either `P0`, `P1`, or `P2`
### Example: pin pressed counter
## Example: pin pressed counter
This program counts how many times you release the `P0` pin.
Every time you release the pin, the program shows the number of times on the screen.
@ -42,7 +42,7 @@ input.onPinReleased(TouchPin.P0, () => {
})
```
### See also
## See also
[@boardname@ 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)

20
docs/reference/input/pin-is-pressed.md
View File

@ -17,29 +17,35 @@ instead of the USB cable.
## ~
### Parameters
## Parameters
* a [string](/reference/types/string) that holds the pin name (**P0**, **P1**, or **P2**)
* a [string](/types/string) that holds the pin name (**P0**, **P1**, or **P2**)
### returns
## returns
* a [boolean](/blocks/logic/boolean) that means whether the pin you say is pressed (`true` or `false`)
### Example
## Pin presses in action
See how the @boardname@ detects a press at a pin or on something connected to a pin in this video:
https://www.youtube.com/watch?v=GEpZrvbsO7o
## Example
This program shows `1` if `P0` is pressed, and `0` if `P0` is not pressed:
```blocks
basic.forever(() => {
if (input.pinIsPressed(TouchPin.P0)) {
basic.showNumber(1, 150)
basic.showNumber(1)
} else {
basic.showNumber(0, 150)
basic.showNumber(0)
}
})
```
### See also
## See also
[@boardname@ pins](/device/pins), [on pin pressed](/reference/input/on-pin-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)

21
docs/reference/input/rotation.md
View File

@ -9,26 +9,25 @@ input.rotation(Rotation.Roll);
## ~hint
The @boardname@ has a part called the **accelerometer** that can
check how the @boardname@ is moving.
check how the @boardname@ is moving. Watch this video to learn how the accelerometer works:
https://www.youtube.com/watch?v=byngcwjO51U
## ~
### Parameters
## Parameters
* ``kind`` means which direction you are checking: `Rotation.Pitch` (up and down) or `Rotation.Roll` (left and right)
### Returns
## Returns
* a [number](/reference/types/number) that means how much the microbit is tilted in the direction you say, from `0` to `360` degrees
* a [number](/types/number) that means how much the @boardname@ is tilted in the direction you ask for. This is a value in degrees between `-180` to `180` in either the `Rotation.Pitch` or the `Rotation.Roll` direction of rotation.
### Example: @boardname@ leveler
## Example: @boardname@ leveler
This program helps you move the @boardname@ until it is level. When
it is level, the @boardname@ shows a smiley.
If you are running this program in a browser, you can tilt the
@boardname@ with your mouse.
This program helps you move the @boardname@ until it is level. When it is level, the @boardname@ shows a smiley.
If you are running this program in a browser, you can tilt the @boardname@ with your mouse.
```blocks
let pitch = 0;
@ -55,7 +54,7 @@ basic.forever(() => {
});
```
### See also
## See also
[acceleration](/reference/input/acceleration), [compass-heading](/reference/input/compass-heading)

17
docs/reference/input/running-time-micros.md Normal file
View File

@ -0,0 +1,17 @@
# Running Time Micros
Find how long it has been since the program started in micro-seconds.
```sig
input.runningTimeMicros();
```
## Returns
* the [Number](/types/number) of microseconds since the program started.
(One second is 1000000 microseconds.)
## See also
[show number](/reference/basic/show-number), [pause](/reference/basic/pause)

10
docs/reference/input/running-time.md
View File

@ -1,17 +1,17 @@
# Running Time
Find how long it has been since the program started.
Find how long it has been since the program started in milli-seconds.
```sig
input.runningTime();
```
### Returns
## Returns
* the [Number](/reference/types/number) of milliseconds since the program started.
* the [Number](/types/number) of milliseconds since the program started.
(One second is 1000 milliseconds.)
### Example: elapsed time
## Example: elapsed time
When you press button `B` on the microbit, this
program finds the number of milliseconds since the program started
@ -25,7 +25,7 @@ input.onButtonPressed(Button.B, () => {
```
### See also
## See also
[show number](/reference/basic/show-number), [pause](/reference/basic/pause)

14
docs/reference/input/set-accelerometer-range.md
View File

@ -9,17 +9,17 @@ or low acceleration.
input.setAccelerometerRange(AcceleratorRange.OneG);
```
### Parameters
## Parameters
* ``range`` means the biggest number of gravities of acceleration you
will be measuring (either `1g`, `2g`, `4g`, or `8g`). Any bigger numbers
will be ignored by your @boardname@, both when you are picking a
number of gravities, and when you are measuring acceleration.
### Example
## Example
This program says the highest acceleration that your @boardname@
will measure is 4G. Then it measures acceleration from side to side
This program sets the highest acceleration that your @boardname@
will measure is 4G. Then it shows acceleration from side to side
until you stop the program.
```blocks
@ -29,13 +29,13 @@ basic.forever(() => {
});
```
#### ~hint
### ~hint
This program does not work in the simulator, only in a @boardname@.
#### ~
### ~
### See Also
## See Also
[compass heading](/reference/input/compass-heading),
[light level](/reference/input/light-level)

25
docs/reference/input/temperature.md
View File

@ -7,18 +7,23 @@ The @boardname@ can find the temperature nearby by checking how hot its computer
input.temperature();
```
### Returns
## Returns
* a [Number](/reference/types/number) that means the Celsius temperature.
* a [number](/types/number) that is the temperature in degrees Celsius.
### How does it work?
## How does it work?
The @boardname@ checks how hot its CPU (main computer chip) is.
Because the @boardname@ does not usually get very hot, the temperature of the CPU
is usually close to the temperature of wherever you are.
The @boardname@ might warm up a little if you make it work hard, though!
### Example: @boardname@ thermometer
Learn more about how the @boardname@ can detect hot or cold in this video:
https://www.youtube.com/watch?v=_T4N8O9xsMA
## Example: @boardname@ thermometer
The following example uses `temperature` and `show number` to show the temperature of the room.
@ -28,31 +33,31 @@ basic.forever(() => {
basic.showNumber(temp)
})
```
### Example: Fahrenheit thermometer
## Example: Fahrenheit thermometer
This program measures the temperature using Fahrenheit degrees.
Fahrenheit is a way of measuring temperature that is commonly used in the United States.
To make a Celsius temperature into a Fahrenheit one, multiply the Celsius temperature by
``18``, divide by ``10`` and add ``32``.
``1.8`` and add ``32``.
```blocks
basic.forever(() => {
let c = input.temperature()
let f = (c * 18) / 10 + 32
let f = (1.8 * c) + 32
basic.showNumber(f)
})
```
### ~hint
## ~hint
Try comparing the temperature your @boardname@ shows to a real thermometer in the same place.
You might be able to figure out how much to subtract from the number the @boardname@
shows to get the real temperature. Then you can change your program so the @boardname@ is a
better thermometer.
### ~
## ~
### See also
## See also
[compass-heading](/reference/input/compass-heading), [acceleration](/reference/input/acceleration)