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

Updates for V4 (#197)

Browse Source 
* update yotta defaults for 16kb devices

* refactor deprecated blocks

* updates for button events

* update button events

* update refference

* update docs

* update docs

* update button event blocks

* update docs

* update block id
This commit is contained in:
Juri Wolf 2022-08-10 18:36:19 +02:00 committed by GitHub
parent 32783f38ba
commit 5f7a8e5301
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
107 changed files with 1218 additions and 706 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/basic.md
View File

@ -27,4 +27,4 @@ basic.showIcon(IconNames.ArrowNorth);
[showIcon](/reference/basic/show-icon),
[showLeds](/reference/basic/show-leds), [showString](/reference/basic/show-string),
[clearScreen](/reference/basic/clear-screen), [forever](/reference/basic/forever), [pause](/reference/basic/pause),
[showAnimation](/reference/basic/show-animation)
[showAnimation](/reference/basic/show-animation)

25
docs/reference/basic/forever.md
View File

@ -1,4 +1,4 @@
# Forever
# forever
Keep running part of a program
[in the background](/reference/control/in-background).
@ -8,7 +8,20 @@ basic.forever(() => {
})
```
## Example: compass
You can have part of a program continuously by placing it in an **forever** loop. The **forever** loop will _yield_ to the other code in your program though, allowing that code to have time to run when needs to.
### ~ reminder
#### Event-based loops
Both the **forever** loop and the **every** loop are _event-based_ loops where the code inside is run as part of a function. These are different from the [for](/blocks/loops/for) and [while](/blocks/loops/while) loops. Those are loops are part of the programming language and can have [break](/blocks/loops/break) and [continue](/blocks/loops/continue) statements in them.
You can NOT use **break** or **continue** in either a **forever** loop or an **every** loop.
### ~
## Examples
### Example: compass
The following example constantly checks the
[compass heading](/reference/input/compass-heading)
@ -32,7 +45,7 @@ basic.forever(() => {
})
```
## Example: counter
### Example: counter
The following example keeps showing the [number](/types/number) stored in a global variable.
When you press button `A`, the number gets bigger.
@ -43,7 +56,7 @@ let num = 0
basic.forever(() => {
basic.showNumber(num)
})
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
num = num + 1
})
```
@ -59,12 +72,12 @@ Try this on your @boardname@:
basic.forever(() => {
basic.showNumber(6789)
})
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
basic.showNumber(2)
})
```
## See also
[while](/blocks/loops/while), [on button pressed](/reference/input/on-button-pressed), [in background](/reference/control/in-background)
[while](/blocks/loops/while), [in background](/reference/control/in-background), [every](/reference/loops/every-interval)

4
docs/reference/basic/pause.md
View File

@ -24,6 +24,10 @@ for (let i = 0; i < 5; i++) {
}
```
## Advanced
If `ms` is `NaN` (not a number), it will default to `20` ms.
## See also
[while](/blocks/loops/while), [running time](/reference/input/running-time), [for](/blocks/loops/for)

34
docs/reference/basic/plot-leds.md
View File

@ -1,34 +0,0 @@
# Plot LEDs
Display an [Image](/reference/images/image) on the @boardname@'s [LED screen](/device/screen).
```sig
basic.showLeds(`
. . . . .
. # . # .
. . # . .
# . . . #
. # # # .
`)
```
## Parameters
* leds - a series of LED on/off states that form an image (see steps below)
## Example: smiley
```blocks
basic.showLeds(`
. . . . .
. # . # .
. . # . .
# . . . #
. # # # .
`)
```
## See also
[show animation](/reference/basic/show-animation), [image](/reference/images/image), [show image](/reference/images/show-image), [scroll image](/reference/images/scroll-image)

1
docs/reference/basic/rgb.md Normal file
View File

@ -0,0 +1 @@
# RGB

1
docs/reference/basic/set-led-color.md Normal file
View File

@ -0,0 +1 @@
# Set LED Color

64
docs/reference/basic/show-animation.md
View File

@ -1,64 +0,0 @@
# show Animation
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(`
. . # . . . # # # . . # # # .
. # # . . . . . # . . . . # .
. . # . . . . # . . . # # # .
. . # . . . # . . . . . . # .
. . # . . . # # # . . # # # .
`)
```
## Parameters
* `leds` is a [string](/types/string) that shows which LEDs are on and off, in groups one after another.
* `interval` is an optional [number](/types/number). It means the number of milliseconds to pause after each image frame.
## 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 @boardname@.
```blocks
basic.showAnimation(`
. . # . . . # # # . . # # # .
. # # . . . . . # . . . . # .
. . # . . . . # . . . # # # .
. . # . . . # . . . . . . # .
. . # . . . # # # . . # # # .
`)
```
## ~hint
If the animation is too fast, make `interval` bigger.
## ~
## Example: animating frames with a pause
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.
```blocks
basic.showAnimation(`
. . . . . # . . . . . . . . . . . . . # . . . . . # . . . .
. . # . . . . . . . . . # . . . . . . . . . # . . . . . . .
. # . # . . . # . . . # . # . . . # . . . # . # . . . # . .
. . # . . . . . . . . . # . . . . . . . . . # . . . . . . .
. . . . . . . . . # . . . . . # . . . . . . . . . . . . . #
`, 500)
```
## ~hint
Use [forever](/reference/basic/forever) to show an animation over and over.
## ~

1
docs/reference/basic/show-compass.md Normal file
View File

@ -0,0 +1 @@
# Show Compass

6
docs/reference/basic/show-number.md
View File

@ -8,7 +8,7 @@ basic.showNumber(2)
## Parameters
* `value` is a [Number](/types/number).
* `value` is a [Number](/types/number). If the number is not single-digit number, it will scroll on the display.
* `interval` is an optional [Number](/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:
@ -37,6 +37,10 @@ for (let i = 0; i < 6; i++) {
}
```
## Advanced
If `value` is `NaN` (not a number), `?` is displayed.
## Other show functions
* Use [show string](/reference/basic/show-string) to show a [String](/types/string) with letters on the screen.

1
docs/reference/basic/turn-rgb-led-off.md Normal file
View File

@ -0,0 +1 @@
# Turn RGB Led Off

13
docs/reference/bluetooth.md
View File

@ -3,6 +3,7 @@
Support for additional Bluetooth services.
## ~hint
![](/static/bluetooth/Bluetooth_SIG.png)
For another device like a smartphone to use any of the Bluetooth "services" which the @boardname@ has, it must first be [paired with the @boardname@](/reference/bluetooth/bluetooth-pairing). Once paired, the other device may connect to the @boardname@ and exchange data relating to many of the @boardname@'s features.
@ -34,14 +35,6 @@ bluetooth.uartWriteValue("", 0);
bluetooth.onUartDataReceived(",", () => {})
```
## Eddystone
```cards
bluetooth.advertiseUid(42, 1, 7, true);
bluetooth.advertiseUrl("https://makecode.microbit.org/", 7, true);
bluetooth.stopAdvertising();
```
## Advanced
For more advanced information on the @boardname@ Bluetooth UART service including information on using a smartphone, see the [Lancaster University @boardname@ runtime technical documentation](http://lancaster-university.github.io/microbit-docs/ble/uart-service/)
@ -56,9 +49,7 @@ For more advanced information on the @boardname@ Bluetooth UART service includin
[uartWriteNumber](/reference/bluetooth/uart-write-number),
[uartWriteValue](/reference/bluetooth/uart-write-value),
[onBluetoothConnected](/reference/bluetooth/on-bluetooth-connected),
[onBluetoothDisconnected](/reference/bluetooth/on-bluetooth-disconnected),
[advertiseUrl](/reference/bluetooth/advertise-url),
[stopAdvertising](/reference/bluetooth/stop-advertising)
[onBluetoothDisconnected](/reference/bluetooth/on-bluetooth-disconnected)
```package
bluetooth

16
docs/reference/bluetooth/advertise-uid-buffer.md
View File

@ -2,6 +2,18 @@
Advertises a UID via the Eddystone protocol over Bluetooth.
```sig
bluetooth.advertiseUidBuffer(pins.createBuffer(16), 7, true);
```
### ~ reminder
#### Deprecated
This API is deprecated. The Eddystone beacon format is no longer supported, see [Google Beacon format (Deprecated)](https://developers.google.com/beacons/eddystone).
### ~
## ~hint
## Eddystone
@ -17,10 +29,6 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
## ~
```sig
bluetooth.advertiseUidBuffer(pins.createBuffer(16), 7, true);
```
## Parameters
* ``buffer`` - a 16 bytes buffer containing the namespace (first 10 bytes) and instance (last 6 bytes).

16
docs/reference/bluetooth/advertise-uid.md
View File

@ -2,6 +2,18 @@
Advertises a UID via the Eddystone protocol over Bluetooth.
```sig
bluetooth.advertiseUid(42, 1, 7, true);
```
### ~ reminder
#### Deprecated
This API is deprecated. The Eddystone beacon format is no longer supported, see [Google Beacon format (Deprecated)](https://developers.google.com/beacons/eddystone).
### ~
## ~hint
## Eddystone
@ -17,10 +29,6 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
## ~
```sig
bluetooth.advertiseUid(42, 1, 7, true);
```
## Parameters
* ``namespace`` last 4 bytes of the namespace uid (6 to 9)

16
docs/reference/bluetooth/advertise-url.md
View File

@ -2,6 +2,18 @@
Advertises a URL via the Eddystone protocol over Bluetooth.
```sig
bluetooth.advertiseUrl("https://makecode.microbit.org/", 7, true);
```
### ~ reminder
#### Deprecated
This API is deprecated. The Eddystone beacon format is no longer supported, see [Google Beacon format (Deprecated)](https://developers.google.com/beacons/eddystone).
### ~
## ~hint
## Eddystone
@ -17,10 +29,6 @@ Read more at https://lancaster-university.github.io/microbit-docs/ble/eddystone/
## ~
```sig
bluetooth.advertiseUrl("https://makecode.microbit.org/", 7, true);
```
## Parameters
* ``url`` - a [string](/types/string) containing the URL to broadcast, at most 17 characters long, excluding the protocol (eg: ``https://``) which gets encoded as 1 byte.

41
docs/reference/bluetooth/on-uart-data-received.md
View File

@ -1,21 +1,50 @@
# Bluetooth On UART Data Received
Registers an event to be fired when one of the delimiter is matched.
Runs some code in an event when a delimiter is matched in the received data.
```sig
bluetooth.onUartDataReceived(",", () => {})
bluetooth.onUartDataReceived(serial.delimiters(Delimiters.NewLine), function() {})
```
## Parameters
* `delimiters` is a [string](/types/string) containing any of the character to match
* **delimiters**: a [string](/types/string) containing the delimiter characters to match in the received data.
### ~ hint
#### Delimiters
Delimiters are characters in a received data string which divide the string into smaller strings to form separate data items.
Although multiple delimiter characters can be set in the **delimiters** string, it is common to have received data separated using just one delimiter character, such as a comma:
``"data1,data2,data3,data4"``
So, you can specify a delimiter character using the ``||serial:serial delimiters||`` which create a single character delimiter string for you...
```block
bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), function () {
})
```
Or, maybe...
```block
let delim = serial.delimiters(Delimiters.NewLine)
basic.showString(bluetooth.uartReadUntil(delim))
```
### ~
## Example
Read values separated by `,`:
Read the data items separated by a comma (`,`):
```blocks
bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), () => {
basic.showString(serial.readUntil(serial.delimiters(Delimiters.Comma)))
bluetooth.onUartDataReceived(serial.delimiters(Delimiters.Comma), function () {
basic.showString(bluetooth.uartReadUntil(serial.delimiters(Delimiters.Space)))
})
```
```package
bluetooth
```

2
docs/reference/control.md
View File

@ -4,7 +4,7 @@ Runtime and event utilities.
```cards
control.inBackground(() => {
});
control.reset();
control.waitMicros(4);

33
docs/reference/devices.md
View File

@ -1,33 +0,0 @@
# Devices
Control a phone with the @boardname@ via Bluetooth.
## ~ hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```cards
devices.tellCameraTo(MesCameraEvent.TakePhoto);
devices.tellRemoteControlTo(MesRemoteControlEvent.play);
devices.raiseAlertTo(MesAlertEvent.DisplayToast);
devices.onNotified(MesDeviceInfo.IncomingCall, () => {
});
devices.onGamepadButton(MesDpadButtonInfo.ADown, () => {
});
devices.signalStrength();
devices.onSignalStrengthChanged(() => {
});
```
```package
devices
```
## See Also
[tellCameraTo](/reference/devices/tell-camera-to), [tellRemoteControlTo](/reference/devices/tell-remote-control-to), [raiseAlertTo](/reference/devices/raise-alert-to), [onNotified](/reference/devices/on-notified), [onGamepadButton](/reference/devices/on-gamepad-button), [signalStrength](/reference/devices/signal-strength), [onSignalStrengthChanged](/reference/devices/on-signal-strength-changed)

25
docs/reference/devices/on-gamepad-button.md
View File

@ -1,25 +0,0 @@
# On Gamepad Button
Register code to run when the @boardname@ receives a command from the paired gamepad.
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.onGamepadButton(MesDpadButtonInfo.ADown, () => {})
```
## Parameters
* ``body``: Action code to run when the the @boardname@ receives a command from the paired gamepad.
## See Also
[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)
```package
devices
```

35
docs/reference/devices/on-notified.md
View File

@ -1,35 +0,0 @@
# On Notified
Register code to run when the signal strength of the paired device changes.
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.onNotified(MesDeviceInfo.IncomingCall, () => {})
```
## Parameters
* ``body``: code to run when the signal strength changes.
## Examples
Display the signal strength on screen:
```blocks
devices.onNotified(MesDeviceInfo.IncomingCall, () => {
basic.showString("RING RING")
})
```
## See Also
[tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [signal strength](/reference/devices/signal-strength)
```package
devices
```

37
docs/reference/devices/on-signal-strength-changed.md
View File

@ -1,37 +0,0 @@
# On Signal Strength Changed
Register code to run when the signal strength of the paired device changes.
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.onSignalStrengthChanged(() => {})
```
## Parameters
* ``body``: code to run when the signal strength changes.
## Examples
Display the signal strength on screen:
```blocks
devices.onSignalStrengthChanged(() => {
basic.showNumber(devices.signalStrength())
})
```
## See Also
[tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [signal strength](/reference/devices/signal-strength)
```package
devices
```

65
docs/reference/devices/raise-alert-to.md
View File

@ -1,65 +0,0 @@
# raise alert to
Raise an alert on a remote device.
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.raiseAlertTo(MesAlertEvent.Vibrate)
```
## Parameters
* event - an event identifier
## Examples
To tell the connected device to display toast
```blocks
devices.raiseAlertTo(MesAlertEvent.DisplayToast)
```
To tell the connected device to vibrate
```blocks
devices.raiseAlertTo(MesAlertEvent.Vibrate)
```
To tell the connected device to play a sound
```blocks
devices.raiseAlertTo(MesAlertEvent.PlaySound)
```
To tell the connected device to play a ringtone
```blocks
devices.raiseAlertTo(MesAlertEvent.PlayRingtone)
```
To tell the connected device to find my phone
```blocks
devices.raiseAlertTo(MesAlertEvent.FindMyPhone)
```
To tell the connected device to ring alarm
```blocks
devices.raiseAlertTo(MesAlertEvent.RingAlarm)
```
## See also
[tell remote control to](/reference/devices/tell-remote-control-to), [tell camera to](/reference/devices/tell-camera-to)
```package
devices
```

36
docs/reference/devices/signal-strength.md
View File

@ -1,36 +0,0 @@
# Signal Strength
Returns the signal strength reported by the paired device from ``0`` (no signal) to ``4`` (full strength).
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.signalStrength();
```
## Returns
* the signal strength from ``0`` (no signal) to ``4`` (full strength).
## Examples
Display the signal strength on screen:
```blocks
devices.onSignalStrengthChanged(() => {
basic.showNumber(devices.signalStrength())
})
```
## See Also
[tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to), [on signal strength changed](/reference/devices/on-signal-strength-changed)
```package
devices
```

76
docs/reference/devices/tell-camera-to.md
View File

@ -1,76 +0,0 @@
# tell camera to
Access the photo/video-taking functionality of a remote device using the ``tell camera to`` function.
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.tellCameraTo(MesCameraEvent.TakePhoto)
```
## Parameters
* event - an event identifier
## Examples
To tell the connected device to take a picture:
```blocks
devices.tellCameraTo(MesCameraEvent.TakePhoto)
```
To tell the connected device to start recording a video:
```blocks
devices.tellCameraTo(MesCameraEvent.StartVideoCapture)
```
To tell the connected device to stop recording a video:
```blocks
devices.tellCameraTo(MesCameraEvent.StopVideoCapture)
```
To tell the connected device to toggle front-rear:
```blocks
devices.tellCameraTo(MesCameraEvent.ToggleFrontRear)
```
To tell the connected device to launch photo mode:
```blocks
devices.tellCameraTo(MesCameraEvent.LaunchPhotoMode)
```
To tell the connected device to launch video mode:
```blocks
devices.tellCameraTo(MesCameraEvent.LaunchVideoMode)
```
To tell the connected device to stop photo mode:
```blocks
devices.tellCameraTo(MesCameraEvent.StopPhotoMode)
```
To tell the connected device to stop video mode:
```blocks
devices.tellCameraTo(MesCameraEvent.StopVideoMode)
```
## See Also
[tell remote control to](/reference/devices/tell-remote-control-to), [raise alert to](/reference/devices/raise-alert-to)
```package
devices
```

89
docs/reference/devices/tell-remote-control-to.md
View File

@ -1,89 +0,0 @@
# tell remote control to
Control the presentation of media content available on a remote device using the `tell remote control` to function.
## ~hint
**App required** You must use one of the [micro:bit apps](https://microbit.org/guide/mobile/) to use this functionality.
## ~
```sig
devices.tellRemoteControlTo(MesRemoteControlEvent.play)
```
## Parameters
* event - an event identifier
## Event values
* play
* stop
* pause
* forward
* rewind
* volume up
* volume down
* previous track
* next track
## Examples
To tell the connected device to start playing:
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.play)
```
To tell the connected device to stop playing
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.stop)
```
To tell the connected device to go to next track
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.nextTrack)
```
To tell the connected device to go to previous track
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.previousTrack)
```
To tell the connected device to go forward
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.forward)
```
To tell the connected device to rewind
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.rewind)
```
To tell the connected device volume up
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.volumeUp)
```
To tell the connected device volume down
```blocks
devices.tellRemoteControlTo(MesRemoteControlEvent.volumeDown)
```
## See also
[tell camera to](/reference/devices/tell-camera-to), [raise alert to](/reference/devices/raise-alert-to)
```package
devices
```

10
docs/reference/event-handler.md
View File

@ -9,7 +9,7 @@ An event handler is code that is associated with a particular event, such as "bu
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.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
basic.showString("hello", 150)
})
```
@ -21,7 +21,7 @@ After this code executes, then whenever button A is pressed in the future, the s
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.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
})
```
@ -32,10 +32,10 @@ The above code associated an event handler that does nothing with the event of a
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.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
basic.showString("hello", 150)
})
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
basic.showString("goodbye", 150)
})
```
@ -43,7 +43,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
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.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
basic.showString("hello", 150)
basic.showString("goodbye", 150)
})

16
docs/reference/game/change.md
View File

@ -1,19 +1,23 @@
# change (Sprite Property)
Change the kind of [number](/types/number) you say for a [sprite](/reference/game/create-sprite).
Change a value for a [sprite](/reference/game/create-sprite) property by some amount.
```sig
game.createSprite(0,0).change(LedSpriteProperty.X, 0);
```
The value of a sprite propery is changed by using either a positive or negative number. Giving `1` will increase a property value by `1` and giving a `-1` will decrease it by `1`.
## Parameters
* **property**: the property of the **Sprite** you want to change, like:
>* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
>* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
>* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
>* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
>* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
>* ``x`` - the change in horizontal location to set the sprite at on the LED screen (`0`-`4`)
>* ``y`` - the change vertical location to set the sprite at on the LED screen (`0`-`4`)
>* ``direction`` - the change of direction in degrees for the sprite to go when the next [move](/reference/game/move) happens. Direction degree range is from `-180` to `180`.
>* ``brightness`` - the change in brightness for the LED sprite. Completely dark is `0` and very bright is `255`.
>* ``blink`` - the change in how fast the sprite is will blink on and off. The blink rate is in milliseconds.
* **value**: a [number](/types/number) value that is the amount of change for the property.
## Example

12
docs/reference/game/get.md
View File

@ -1,6 +1,6 @@
# get (Sprite Property)
Find something out about a [sprite](/reference/game/create-sprite).
Get a value for a [sprite](/reference/game/create-sprite) property.
```sig
game.createSprite(0,0).get(LedSpriteProperty.X);
@ -9,11 +9,11 @@ game.createSprite(0,0).get(LedSpriteProperty.X);
## Parameters
* **property**: the property of the **Sprite** you want to know about, like:
>* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
>* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
>* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
>* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
>* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
>* ``x`` - the horizontal location to set the sprite at on the LED screen (`0`-`4`)
>* ``y`` - the vertical location to set the sprite at on the LED screen (`0`-`4`)
>* ``direction`` - the direction in degrees for the sprite to go when the next [move](/reference/game/move) happens. The degree range is from `-180` to `180`.
>* ``brightness`` - how bright the LED sprite is. Completely dark is `0` and very bright is `255`.
>* ``blink`` - how fast the sprite is will blink on and off. The blink rate is in milliseconds.
## Returns

2
docs/reference/game/is-running.md
View File

@ -15,7 +15,7 @@ game.isRunning()
If the game is currently running, end the game if button **B** is pressed.
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, function () {
input.onButtonEvent(Button.B, input.buttonEventClick(), function () {
if (game.isRunning()) {
game.gameOver()
}

4
docs/reference/game/set-score.md
View File

@ -16,11 +16,11 @@ Press button ``A`` as much as possible to increase the score.
Press ``B`` to display the score and reset the score.
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
basic.showNumber(game.score())
game.setScore(0)
})
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
game.addScore(1)
})
```

41
docs/reference/game/set.md
View File

@ -1,6 +1,6 @@
# set (Sprite Property)
Make a [sprite](/reference/game/create-sprite) store the kind of [number](/types/number) you say.
Set a value for a [sprite](/reference/game/create-sprite) property.
```sig
game.createSprite(0,0).set(LedSpriteProperty.X, 0);
@ -9,22 +9,39 @@ game.createSprite(0,0).set(LedSpriteProperty.X, 0);
## Parameters
* **property**: the property of the **Sprite** you want to store a value for, like:
>* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
>* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
>* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
>* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
>* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
>* ``x`` - the horizontal location to set the sprite at on the LED screen (`0`-`4`)
>* ``y`` - the vertical location to set the sprite at on the LED screen (`0`-`4`)
>* ``direction`` - the direction in degrees for the sprite to go when the next [move](/reference/game/move) happens. The degree range is from `-180` to `180`.
>* ``brightness`` - how bright the LED sprite is. Completely dark is `0` and very bright is `255`.
>* ``blink`` - how fast the sprite is will blink on and off. The blink rate is in milliseconds.
* **value**: the a [number](/types/number) value to set for the property.
## Example
This program makes a sprite on the left side of the screen,
waits two seconds (2000 milliseconds),
and then moves it to the right side of the screen.
Make an LED sprite move to random locations on the screen. Use button **A** to freeze and unfreeze the sprite while it's moving. When the sprite is frozen, it will blink and dim to half brightness.
```blocks
let ball = game.createSprite(0, 2);
basic.pause(2000);
ball.set(LedSpriteProperty.X, 4);
input.onButtonEvent(Button.A, input.buttonEventClick(), function () {
if (freeze) {
sprite.set(LedSpriteProperty.Brightness, 255)
sprite.set(LedSpriteProperty.Blink, 0)
} else {
sprite.set(LedSpriteProperty.Brightness, 128)
sprite.set(LedSpriteProperty.Blink, 200)
}
freeze = !(freeze)
})
let freeze = false
let sprite: game.LedSprite = null
sprite = game.createSprite(0, 0)
basic.forever(function () {
if (!(freeze)) {
sprite.set(LedSpriteProperty.X, randint(0, 4))
sprite.set(LedSpriteProperty.Y, randint(0, 4))
}
basic.pause(500)
})
```
## See also

2
docs/reference/game/start-countdown.md
View File

@ -17,7 +17,7 @@ Press button ``A`` as much as possible.
At the end of 10 seconds, the program will show your score.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
game.addScore(1)
})
game.startCountdown(10000)

4
docs/reference/images/create-big-image.md
View File

@ -36,10 +36,10 @@ let arrows = images.createBigImage(`
. . # . . . # # # .
. . # . . . . # . .
`);
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
arrows.showImage(0);
});
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
arrows.showImage(5);
});
```

4
docs/reference/images/create-image.md
View File

@ -25,7 +25,7 @@ arrow and show it on the LED screen. If you press button `B`, the
program will show a picture of the arrow upside-down.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
images.createImage(`
. . # . .
. # # # .
@ -34,7 +34,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
. . # . .
`).showImage(0);
});
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
images.createImage(`
. . # . .
. . # . .

8
docs/reference/images/icon-image.md
View File

@ -20,14 +20,10 @@ Show a happy face when button A is pressed or a sad face when button B is presse
let iamHappy = images.iconImage(IconNames.Happy)
let iamSad = images.iconImage(IconNames.Sad)
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
iamHappy.showImage(0);
});
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
iamSad.showImage(0);
});
```
## See also
[arrow image](/reference/images/arrow-image)

4
docs/reference/images/show-image.md
View File

@ -31,10 +31,10 @@ let arrows = images.createBigImage(`
. . # . . . # # # .
. . # . . . . # . .
`);
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
arrows.showImage(0);
});
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
arrows.showImage(5);
});
```

46
docs/reference/input.md
View File

@ -3,31 +3,31 @@
Events and data from sensors
```cards
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
});
input.onGesture(Gesture.Shake, () => {
});
input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
});
input.buttonIsPressed(Button.A);
input.isGesture(Gesture.Shake);
input.compassHeading();
input.pinIsPressed(TouchPin.P0);
input.temperature();
input.acceleration(Dimension.X);
input.lightLevel();
input.rotation(Rotation.Pitch);
input.magneticForce(Dimension.X);
input.runningTime();
input.runningTimeMicros();
input.setAccelerometerRange(AcceleratorRange.OneG);
input.onButtonEvent(Button.A, input.buttonEventClick(), function () {})
input.onGesture(Gesture.Shake, function () {})
input.onPinEvent(TouchPin.P0, input.buttonEventDown(), function() {})
input.buttonIsPressed(Button.A)
input.pinIsPressed(TouchPin.P0)
input.isGesture(Gesture.Shake)
input.compassHeading()
input.temperature()
input.acceleration(Dimension.X)
input.lightLevel()
input.rotation(Rotation.Pitch)
input.magneticForce(Dimension.X)
input.runningTime()
input.runningTimeMicros()
input.setAccelerometerRange(AcceleratorRange.OneG)
```
## See also
[onButtonPressed](/reference/input/on-button-pressed), [onGesture](/reference/input/on-gesture), [onPinPressed](/reference/input/on-pin-pressed), [buttonIsPressed](/reference/input/button-is-pressed),
[On Button Event](/reference/input/on-button-event), [onGesture](/reference/input/on-gesture),
[On Pin Event](/reference/input/on-pin-event),
[buttonIsPressed](/reference/input/button-is-pressed), [pinIsPressed](/reference/input/pin-is-pressed),
[is gesture](/reference/input/is-gesture),
[compassHeading](/reference/input/compass-heading), [pinIsPressed](/reference/input/pin-is-pressed), [temperature](/reference/input/temperature), [acceleration](/reference/input/acceleration), [lightLevel](/reference/input/light-level), [rotation](/reference/input/rotation), [magneticForce](/reference/input/magnetic-force), [runningTime](/reference/input/running-time), [setAccelerometerRange](/reference/input/set-accelerometer-range), [calibrate-compass](/reference/input/calibrate-compass)
[compassHeading](/reference/input/compass-heading), [temperature](/reference/input/temperature),
[acceleration](/reference/input/acceleration), [lightLevel](/reference/input/light-level),
[rotation](/reference/input/rotation), [magneticForce](/reference/input/magnetic-force),
[runningTime](/reference/input/running-time), [setAccelerometerRange](/reference/input/set-accelerometer-range),
[calibrate-compass](/reference/input/calibrate-compass)

62
docs/reference/input/button-event.md Normal file
View File

@ -0,0 +1,62 @@
# Button event
Returns the ID of one of these button event types:
* Pressed Down (1)
* Released Up (2)
* Clicked (3)
* Long clicked (4)
* Hold (5)
This block can be used to define the event type in [on button event](input/on-button-event) and [on pin event](input/on-pin-event).
Note, that by pressing a Button multiple events can raise at the same moment:
| # | User input | Event raised |
|---|--------------------------|--------------|
| 1 | Press A down | A.Down |
| 2 | Hold A for > 1.5 seconds | A.Hold |
| 3 | release A | A.Up |
| | | A.LongClick |
| # | User input | Event raised |
|---|--------------|--------------|
| 1 | Press A down | A.Down |
| 2 | Press B down | B.Down |
| 3 | | A+B.Down |
| | Release A up | A.Up |
| | | A+B.Up |
| | | A+B.Click |
| | Release B up | B.Up |
* Every Up-Event will always be followed by either a Click- OR Long-Click-Event, depending on how long the Down-Event has been ago.
## Pressed Down
* For button `A` or `B`: This handler works when the button is pushed down.
* For `A` and `B` together: This handler works when `A` and `B` are both pushed down, at the moment the second button is pressed.
## Released Up
* For button `A` or `B`: This handler works when the button is released up.
* For `A` and `B` together: This handler works at the moment the first button is released up while `A` and `B` are both pushed down.
## Clicked
* 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.
## Long clicked
* For button `A` or `B`: This handler works when the button is pushed down and released after more than 1 second.
* For `A` and `B` together: This handler works when `A` and `B` are both pushed down, then one of them is released after more than 1.5 seconds after pushing down the second button.
## Hold
* For button `A` or `B`: This handler works when the button is pushed down and hold for 1 second.
* For `A` and `B` together: This handler works when `A` and `B` are both pushed down and hold for 1.5 seconds after pushing down the second button.
**This is an advanced API.** For more information, see the
[@boardname@ runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/).
## See also
[on button event](input/on-button-event), [on pin event](input/on-pin-event)

2
docs/reference/input/calibrate-compass.md
View File

@ -23,7 +23,7 @@ confuse the @boardname@.
This example runs the calibration when the user presses **A+B** buttons.
```blocks
input.onButtonEvent(Button.AB, ButtonEvent.Click, () => {
input.onButtonEvent(Button.AB, input.buttonEventClick(), () => {
input.calibrateCompass();
})
```

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

@ -70,7 +70,7 @@ confuse the @boardname@.
Keep the calibration handy by running it when the user pressed **A+B**.
```block
input.onButtonEvent(Button.AB, ButtonEvent.Click, () => {
input.onButtonEvent(Button.AB, input.buttonEventClick(), () => {
input.calibrateCompass();
})
```

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

@ -29,7 +29,7 @@ program shows the light level
on the [LED screen](/device/screen).
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
let level = input.lightLevel()
basic.showNumber(level)
})

42
docs/reference/input/logo-is-pressed.md Normal file
View File

@ -0,0 +1,42 @@
# logo Is Pressed
Check if the @boardname@ logo is currently being pressed.
```sig
input.logoIsPressed()
```
## ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
## ~
The logo on the @boardname@ works just like a touch pin. You can check the whether or not the logo is currently being pressed. You use the [boolean](/types/boolean) value for the status of the logo press to make a logical decision in your program.
## Returns
* a [boolean](types/boolean) value that is `true` if the logo is pressed, `false` if the logo is not pressed.
## Example
Show an icon on the LEDs while the logo is pressed.
```blocks
basic.forever(function () {
if (input.logoIsPressed()) {
basic.showIcon(IconNames.Diamond)
} else {
basic.clearScreen()
}
})
```
## See also
[micro:bit V2](/device/v2),
[on logo event](/reference/input/on-logo-event),
[pin is pressed](/referene/inpu/pin-is-pressed),
[touch set mode](/referene/inpu/touch-set-mode)

12
docs/reference/input/on-button-event.md
View File

@ -1,7 +1,9 @@
# On Button Event
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 button `A` or `B` is pressed, or `A` and `B` together.
This handler works when button `A` or `B` is clicked, or `A` and `B` together. You can choose another event type by using
the [button event block](/reference/input/button-event). Possible event types are `pressed down` (1), `released up` (2), `clicked` (3), `long clicked` (4) or `hold` (5).
When you are using this function in a web browser, click the buttons on the screen instead of the ones
on the @boardname@.
@ -9,7 +11,7 @@ on the @boardname@.
* 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.onButtonEvent(Button.A, ButtonEvent.Click, () => {})
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {})
```
Find out how buttons provide input to the @boardname@ in this video:
@ -24,7 +26,7 @@ Each time you press the button, the [LED screen](/device/screen) shows the `coun
```blocks
let count = 0
basic.showNumber(count)
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
count++;
basic.showNumber(count);
})
@ -35,7 +37,7 @@ input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
This example shows a number from 1 to 6 when you press the `B` button.
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
let dice = randint(0, 5) + 1
basic.showNumber(dice)
})
@ -50,5 +52,5 @@ Otherwise, sometimes they would show a `0`.
## See also
[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/blocks/math)
[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/blocks/math), [button event block](/reference/input/button-event)

38
docs/reference/input/on-logo-event.md Normal file
View File

@ -0,0 +1,38 @@
# on Logo Event
Run some code in your program when the @boardname@ logo is pressed, touched, or released.
```sig
input.onLogoEvent(TouchButtonEvent.Pressed, function () {})
```
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
The logo on the @boardname@ works just like a touch pin. The logo will detect your touch. You can have code inside an event that will run when the logo is pressed.
## Parameters
* **action**: the logo event to run your code for. The events are ``released``, ``pressed``, ``touched`` or ``long pressed``.
## Example
Show a message on the LEDs when the @boardname@ logo is pressed.
```blocks
input.onLogoEvent(TouchButtonEvent.Pressed, function () {
basic.showString("I was pressed!")
})
```
## See also
[micro:bit V2](/device/v2),
[logo is pressed](/reference/input/logo-is-pressed),
[on pin pressed](/reference/input/on-logo-released),
[touch set mode](/referene/inpu/touch-set-mode)

11
docs/reference/input/on-pin-event.md
View File

@ -3,18 +3,19 @@
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 touch pin `0`, `1`, or `2`
together with `GND`, and release it within 1 second.
together with `GND`, and release it within 1 second. You can choose another event type by using
the [button event block](/reference/input/button-event). Possible event types are `pressed down` (1), `released up` (2), `clicked` (3), `long clicked` (4) or `hold` (5).
When you are using this function in a web
browser, click the pins on the screen instead of the ones on the
@boardname@.
If you hold the `GND` pin with one hand and touch pin `0`, `1`, or `2`
If you hold the `GND` pin with one hand and touch pin `0`, `1`, `2` or `3`
with the other, a very small (safe) amount of electricity will flow
through your body and back into the @boardname@. This is called
**completing a circuit**. It's like you're a big wire!
```sig
input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
input.onPinTouchEvent(TouchPin.P0, input.buttonEventClick(), () => {
})
```
@ -43,7 +44,7 @@ Every time you press the pin, the program shows the number of times on the scree
```blocks
let count = 0
basic.showNumber(count)
input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
input.onPinTouchEvent(TouchPin.P0, input.buttonEventClick(), () => {
count = count + 1
basic.showNumber(count)
})
@ -51,5 +52,5 @@ input.onPinTouchEvent(TouchPin.P0, ButtonEvent.Click, () => {
## 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)
[@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), [button event block](/reference/input/button-event)

46
docs/reference/input/on-sound.md Normal file
View File

@ -0,0 +1,46 @@
# on Sound
Run some code when the microphone hears a sound.
```sig
input.onSound(DetectedSound.Loud, function () {})
```
The microphone will detect sounds that are quiet or loud. You can have the microphone detect
a sound at a certain level and run some code in and event when it hears the sound. There are
two sound ranges you can detect for: `loud` or `quiet`.
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
## Parameters
* **sound**: the type of sound to detect: `loud` or `quiet`.
* **handler**: the code to run when a sound is heard.
## Example
Show an icon animation when the microphone detects a sound.
```blocks
input.onSound(DetectedSound.Loud, function () {
basic.showIcon(IconNames.Square)
basic.showIcon(IconNames.SmallSquare)
basic.showIcon(IconNames.SmallDiamond)
basic.clearScreen()
})
```
# See also #seealso
[sound level](/reference/input/sound-level),
[set sound threshold](/reference/input/sound-level)
```package
microphone
```

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

@ -18,7 +18,7 @@ program finds the number of milliseconds since the program started
and shows it on the [LED screen](/device/screen).
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
let now = input.runningTime()
basic.showNumber(now)
})

48
docs/reference/input/set-sound-threshold.md Normal file
View File

@ -0,0 +1,48 @@
# set Sound Threshold
Tell how loud it should be for your board to detect a loud sound.
```sig
input.setSoundThreshold(SoundThreshold.Loud, 0)
```
When the microphone hears a sound, it sets a number for how loud the sound was at that moment.
This number is the sound level and has a value from `0` (low sound) to `255` (loud sound). You can use
a sound level number as a _threshold_ (just the right amount of sound) to make the
[on sound](/reference/input/on-sound) event happen. To set a threshold, you choose the type of sound
to detect, `loud` or `quiet`, and then the sound level for that type.
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
## Parameters
* **sound**: the type of sound to dectect: `loud` or `quiet`.
* **threshold**: the sound level [number](/types/number) which makes a sound event happen.
## Example #example
Show an icon animation when the microphone detects a sound louder than a sound level of `200`.
```blocks
input.setSoundThreshold(SoundThreshold.Loud, 200)
input.onSound(DetectedSound.Loud, function () {
basic.showIcon(IconNames.Square)
basic.showIcon(IconNames.SmallSquare)
basic.showIcon(IconNames.SmallDiamond)
basic.clearScreen()
})
```
# See also #seealso
[on sound](/reference/input/on-sound), [sound level](/reference/input/sound-level)
```package
microphone
```

32
docs/reference/input/sound-level.md Normal file
View File

@ -0,0 +1,32 @@
# sound Level
Find out what the the level of sound heard by the microphone is.
```sig
input.soundLevel()
```
## Returns
* a ``number`` between `0` (low sound) and `255` (loud sound) which tells how loud the sounds are that the microphone hears.
## Example
Show a checkerboard icon while the sound level is greater than `100`.
```blocks
basic.forever(function () {
if (input.soundLevel() > 100) {
basic.showIcon(IconNames.Chessboard)
} else {
basic.clearScreen()
}
})
```
## See also
```package
microphone
```

2
docs/reference/led.md
View File

@ -19,4 +19,4 @@ led.enable(false)
## See Also
[plot](/reference/led/plot), [unplot](/reference/led/unplot), [point](/reference/led/point), [brightness](/reference/led/brightness), [setBrightness](/reference/led/set-brightness), [stopAnimation](/reference/led/stop-animation), [plotBarGraph](/reference/led/plot-bar-graph), [toggle](/reference/led/toggle), [setDisplayMode](/reference/led/set-display-mode), [enabled](/reference/led/enable),
[plotBrightness](/reference/led/plot-brightness),
[plotBrightness](/reference/led/plot-brightness)

2
docs/reference/led/enable.md
View File

@ -15,7 +15,7 @@ led.enable(false);
This program turns off the screen when pressing button ``B``
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
led.enable(false)
});
```

4
docs/reference/led/stop-animation.md
View File

@ -13,7 +13,7 @@ This program sets up the ``stop animation`` part of the program,
and then shows a string that you can stop with button ``B``.
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
led.stopAnimation();
});
basic.showString("STOP ME! STOP ME! PLEASE, WON'T SOMEBODY STOP ME?");
@ -29,4 +29,4 @@ to go.
## See Also
[show animation](/reference/basic/show-animation)
[show leds](/reference/basic/show-leds), [show icon](/reference/basic/show-icon), [plot](/reference/led/plot)

42
docs/reference/loops/every-interval.md Normal file
View File

@ -0,0 +1,42 @@
# every Interval
Run part of the program in a loop continuously at a time interval.
```sig
loops.everyInterval(500, function () {})
```
If you want to run some code continuously, but on a time interval, then use an **every** loop. You set the amount of time that the loop waits before the code inside runs again. This is similar to a [forever](/reference/basic/forever) loop, in that it runs continuously, except that there's a time interval set to wait on before the loop runs the next time. This loop is useful when you want some of a program's code run on a _schedule_.
## Parameters
* **interval**: a [number](/types/number) that is the amount of time in milliseconds to wait before running the loop again.
### ~ reminder
#### Event-based loops
Both the **every** loop and the **forever** loop are _event-based_ loops where the code inside is run as part of a function. These are different from the [for](/blocks/loops/for) and [while](/blocks/loops/while) loops. Those are loops are part of the programming language and can have [break](/blocks/loops/break) and [continue](/blocks/loops/continue) statements in them.
You can NOT use **break** or **continue** in either an **every** loop or a **forever** loop.
### ~
## Example
At every `200` milliseconds of time, check if either the **A** or **B** button is pressed. If so, show on the screen which one is pressed.
```blocks
loops.everyInterval(200, function () {
if (input.buttonIsPressed(Button.A)) {
basic.showString("A")
} else if (input.buttonIsPressed(Button.B)) {
basic.showString("B")
} else {
basic.clearScreen()
}
})
```
## See also
[forever](/reference/basic/forever)

2
docs/reference/math/int.md Normal file
View File

@ -0,0 +1,2 @@
# Int

39
docs/reference/math/random-boolean.md Normal file
View File

@ -0,0 +1,39 @@
# random Boolean
Returns a pseudo-random boolean value that is either `true` or `false`.
```sig
Math.randomBoolean()
```
## Returns
* a pseudo-random [boolean](types/boolean) that is either `true` or `false`.
### ~ hint
#### What is pseudo-random?
Random numbers generated on a computer are often called pseudo-random. This because the method to create the number is based on some starting value obtained from the computer itself. The formula for the random number could use some amount of mathematical operations on a value derived from a timer or some other input. The resulting "random" number isn’t considered entirely random because it started with some initial value and a repeatable set of operations on it. Therefore, it’s called a pseudo-random number.
A random boolean is created by choosing a [random int](/reference/math/randint) ranging from `0` to `1`.
### ~
## Example
Make your @boardname@ do a coin toss when it's dropped softly. Have the LEDs show 'heads' or 'tails' as the result of the toss.
```blocks
input.onGesture(Gesture.FreeFall, () => {
if (Math.randomBoolean()) {
basic.showIcon(IconNames.Happy)
} else {
basic.showIcon(IconNames.Sword)
}
})
```
## See Also
[random int](/reference/math/randint)

6
docs/reference/music.md
View File

@ -24,4 +24,8 @@ music.volume()
[stopMelody](/reference/music/stop-melody), [onEvent](/reference/music/on-event),
[beat](/reference/music/beat), [tempo](/reference/music/tempo),
[changeTempoBy](/reference/music/change-tempo-by), [setTempo](/reference/music/set-tempo),
[setVolume](/reference/music/set-volume), [volume](/reference/music/volume)
[setVolume](/reference/music/set-volume), [volume](/reference/music/volume),
[play sound effect](/reference/music/play-sound-effect),
[create sound effect](/reference/music/create-sound-effect),
[built-in sound effect](/reference/music/builtin-sound-effect)

2
docs/reference/music/begin-melody.md
View File

@ -22,7 +22,7 @@ Melodies are a sequence of notes, each played for some small amount time, one af
music.beginMelody(['g4:1', 'c5', 'e', 'g:2', 'e:1', 'g:3'], MelodyOptions.Once)
```
Melodies are played either in the _foreground_ or _background_. This allows more than one melody to be active at once. If a melody is set to play in the background, it can be interrupted, or paused, temporarily while a melody set for the foreground is played. If the foreground melody is not set to play ``forever``, then the background melody resumes when the foreground melody is finished.
Melodies are played either in the _foreground_ or _background_. This allows more than one melody to be active at once. If a melody is set to play in the background, it can be interrupeted, or paused, temporarily while a melody set for the foreground is played. If the foreground melody is not set to play ``forever``, then the background melody resumes when the foreground melody is finished.
You can set options for how you want the melody to play. You can ask that the melody plays just one time, ``once``, or have it keep repeating, ``forever``. With these options the melody will play in the foreground either once or continue to repeat. Of course, if you set ``forever``, any melody that was started in background will never play unless you [stop](/reference/music/stop-melody) the foreground melody. To make a background melody, set the option to ``once in background`` or ``forever in background``.

40
docs/reference/music/builtin-sound-effect.md Normal file
View File

@ -0,0 +1,40 @@
# builtin Sound Effect
Get a sound expression string for a built-in sound effect.
```sig
music.builtinSoundEffect(soundExpression.giggle)
```
A collection of built-in sound effects are available as sound expressions. You choose one by selecting the name of the effect
## Parameters
* **soundExpression**: A sound expression name. The available effects are:
>* `giggle`
>* `happy`
>* `hello`
>* `mysterious`
>* `sad`
>* `slide`
>* `soaring`
>* `spring`
>* `twinkle`
>* `yawn`
## Returns
* a [sound](/types/sound) expression [string](/types/string) with the the named sound effect.
## Example
Play the built-in sound effect for `giggle`.
```blocks
music.playSoundEffect(music.builtinSoundEffect(soundExpression.giggle), SoundExpressionPlayMode.UntilDone)
```
## See also
[play sound effect](/reference/music/play-sound-effect),
[create sound effect](/reference/music/create-sound-effect)

48
docs/reference/music/create-sound-effect.md Normal file
View File

@ -0,0 +1,48 @@
# create Sound Effect
Create a sound expression string for a sound effect.
```sig
music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
```
A sound expression is set of parameters that describe a **[Sound](/types/sound)** that will last for some amount of time. These parameters specify a base waveform, frequency range, sound volume, and effects. Sound data is created as a [Sound](/types/sound) object and can then be [played](/reference/music/play-sound-effect) to the speaker, headphones, or at an output pin.
## Parameters
* **waveShape**: the primary shape of the waveform:
>* `sine`: sine wave shape
>* `sawtooth`: sawtooth wave shape
>* `triangle`: triangle wave shape
>* `square`: square wave shape
>* `noise`: random noise generated wave shape
* **startFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression starts.
* **endFrequency**: a [number](/types/number) that is the frequency of the waveform when the sound expression stops.
* **startVolume**: a [number](/types/number) the initial volume of the sound expression.
* **endVolume**: a [number](/types/number) the ending volume of the sound expression.
* **duration**: a [number](/types/number) the duration in milliseconds of the sound expression.
* **effect**: an effect to add to the waveform. These are:
>* `tremolo`: add slight changes in volume of the sound expression.
>* `vibrato`: add slight changes in frequency to the sound expression.
>* `warble`: similar to `vibrato` but with faster variations in the frequency changes.
* **interpolation**: controls the rate of frequency change in the sound expression.
>* `linear`: the change in frequency is constant for the duration of the sound.
>* `curve`: the change in frequency is faster at the beginning of the sound and slows toward the end.
>* `logarithmic`: the change in frequency is rapid during the very first part of the sound.
## Returns
* a [sound](/types/sound) expression [string](/types/string) with the the desired sound effect parameters.
## Example
Create a sound expression string and assign it to a variable. Play the sound for the sound expression.
```blocks
let mySound = music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 500, SoundExpressionEffect.None, InterpolationCurve.Linear)
music.playSoundEffect(mySound, SoundExpressionPlayMode.UntilDone)
```
## See also
[play sound effect](/reference/music/play-sound-effect), [built-in sound effect](/reference/music/builtin-sound-effect)

31
docs/reference/music/note-frequency.md Normal file
View File

@ -0,0 +1,31 @@
# note Frequency
Get the frequency of a musical note.
```sig
music.noteFrequency(Note.C)
```
## Parameters
* ``name`` is the name of the **Note** you want a frequency value for.
## Returns
* a [number](/types/number) that is the frequency (in [Hertz](https://wikipedia.org/wiki/Hertz))
of a note you chose.
## Example #example
Play a 'C' note for one second, rest for one second, and then play an 'A' note for one second.
```blocks
music.playTone(music.noteFrequency(Note.C), 1000)
music.rest(1000)
music.playTone(music.noteFrequency(Note.A), 1000)
```
## See also #seealso
[play tone](/reference/music/play-tone), [ring tone](/reference/music/ring-tone),
[rest](/reference/music/rest), [tempo](/reference/music/tempo),
[change tempo by](/reference/music/change-tempo-by)

2
docs/reference/music/on-event.md
View File

@ -43,7 +43,7 @@ music.onEvent(MusicEvent.BackgroundMelodyResumed, () => {
music.onEvent(MusicEvent.BackgroundMelodyRepeated, () => {
serial.writeLine("background repeated")
})
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
music.beginMelody(music.builtInMelody(Melodies.BaDing), MelodyOptions.Once)
})
music.setTempo(100)

38
docs/reference/music/play-melody.md Normal file
View File

@ -0,0 +1,38 @@
# play Melody
Play a short melody of notes composed in a string.
```sig
music.playMelody("", 120);
```
The melody is short series of notes composed in a string. The melody is played at a rate set by the **tempo** value you give. The melody string contains a sequence of notes formatted like this:
``"E B C5 A B G A F "``
The melody is shown in the ``||music:play melody||`` block as note symbols which also appear in the Melody Editor.
```block
music.playMelody("E B C5 A B G A F ", 120);
```
The melodies are most often created in the Melody Editor from the block so that valid notes are chosen and the correct melody length is set.
## Parameters
* **melody**: a [string](/types/string) which contains the notes of the melody.
* **tempo**: a [number](/types/number) which is the rate to play the melody at in beats per minute.
## Example #example
Play the ``Mystery`` melody continuously.
```blocks
basic.forever(function () {
music.playMelody("E F G F E G B C5 ", 120)
})
```
## See also #seealso
[set tempo](/reference/music/set-tempo), [play](/reference/music/play), [play until done](/reference/music/play-until-done)

40
docs/reference/music/play-sound-effect.md Normal file
View File

@ -0,0 +1,40 @@
# play Sound Effect
Play a sound that is generated from a sound expression.
```sig
music.playSoundEffect("", SoundExpressionPlayMode.UntilDone)
```
This will play a **[Sound](/types/sound)** object created from a sound expression. The sound will play for the duration that was set in the sound expression. The sound can play on the speaker or at a pin that is set for sound output.
Your program can wait for the sound to finish before it runs its next step. To do this, set the play mode to `until done`. Otherwise, use `background` for the program to continue immediately after the sound starts.
### ~ reminder
#### Works with micro:bit V2
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
## Parameters
* **sound**: a [string](/types/string) that is the sound expression for the sound you want to play.
* **mode**: the play mode for the sound, either `until done` or `background`.
## Example
Play a sound from a sound expression for `1` second.
```blocks
music.playSoundEffect(music.createSoundEffect(WaveShape.Sine, 2000, 0, 1023, 0, 1000, SoundExpressionEffect.None, InterpolationCurve.Linear), SoundExpressionPlayMode.UntilDone)
```
## See also
[create sound effect](/reference/music/create-sound-effect),
[built-in sound effect](/reference/music/builtin-sound-effect),
[analog set pitch pin](/reference/pins/analog-set-pitch-pin)

44
docs/reference/music/play-until-done.md Normal file
View File

@ -0,0 +1,44 @@
# play Until Done
Play a sound expression until it finishes.
```sig
soundExpression.giggle.playUntilDone()
```
A sound expression is a preformatted set of tones that create a certain sound. There are several sounds to choose from. The sound is started and your program waits until the sound stops playing.
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
## Parameters
In blocks, the sound is selected from the list in the ``||music:play sound until done||`` block.
```block
soundExpression.giggle.playUntilDone()
```
When coding in JavaScript or Python, the sound is a ``soundExpression`` object which from which you run the ``playUntilDone()`` function from. For example, to play the ``soaring`` sound, select ``soaring`` from the ``soundExpression`` namespace and run ``playUntilDone()``:
```typescript
soundExpression.soaring.playUntilDone()
```
## Example
Play the ``twinkle`` sound on the speaker and wait until it finishes.
```blocks
soundExpression.twinkle.playUntilDone()
basic.showString("twinkle has stopped")
```
## See also
[play](/reference/music/play)

43
docs/reference/music/play.md Normal file
View File

@ -0,0 +1,43 @@
# play
Play a sound expression.
```sig
soundExpression.giggle.play()
```
A sound expression is a preformatted set of tones that create a certain sound. There are several sounds to choose from. The sound is started and your program then continues.
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
## Parameters
In blocks, the sound is selected from the list in the ``||music:play sound||`` block.
```block
soundExpression.giggle.play()
```
When coding in JavaScript or Python, the sound is a ``soundExpression`` object which from which you run the ``play()`` function from. For example, to play the ``soaring`` sound, select ``soaring`` from the ``soundExpression`` namespace and run ``play()``:
```typescript
soundExpression.soaring.play()
```
## Example
Play the ``twinkle`` sound on the speaker.
```blocks
soundExpression.twinkle.play()
```
## See also
[play until done](/reference/music/play-until-done)

37
docs/reference/music/set-built-in-speaker-enabled.md Normal file
View File

@ -0,0 +1,37 @@
# set Built In Speaker Enabled
Enable the speaker on the @boardname@ to play music and sounds.
```sig
music.setBuiltInSpeakerEnabled(false)
```
The microbit v2 has a speaker on the board itself. You can enable the built-in speaker to play sounds instead having them an external speaker connected to the pitch pin.
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This block requires the [micro:bit V2](/device/v2) hardware. If you use this block with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
## Parameters
* **enabled**: a [boolean](/types/boolean) value that is ``true`` to enable the built-in speaker, or ``false`` to send sounds to the pitch pin.
## Example #example
Enable the built-in speaker play sounds.
```blocks
music.setBuiltInSpeakerEnabled(true)
```
## See also
[analog-set-pitch-pin](/reference/pins/analog-set-pitch-pin)
```package
music
```

4
docs/reference/music/set-play-tone.md
View File

@ -17,7 +17,7 @@ This example send the frequency and duration over radio
and plays it on the remote @boardname@.
```typescript
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
music.playTone(440, 120)
led.toggle(0, 0)
})
@ -26,7 +26,7 @@ radio.onReceivedNumber(function (receivedNumber) {
const duration = receivedNumber & 0xffff;
music.playTone(freq, duration);
})
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
music.setPlayTone((frequency: number, duration: number) => {
radio.sendNumber((frequency << 16) | (duration & 0xffff));
})

40
docs/reference/music/set-silence-level.md Normal file
View File

@ -0,0 +1,40 @@
# set Silence Level
Set the level for audio pin output during periods of silence.
```sig
music.setSilenceLevel(1000)
```
### ~ reminder
![works with micro:bit V2 only image](/static/v2/v2-only.png)
This function requires the [micro:bit V2](/device/v2) hardware. If you use this function with a micro:bit v1 board, you will see the **927** error code on the screen.
### ~
Normally the output signal level at the audio pin is `0` when no sounds are playing. This is the silence level and it stays constant since actual tones have varying levels over a period of time. Some devices (headphones, external speakers, etc.) which are sensitive to slight signal changes might play sounds from signal noise encountered along the connection between the audio pin and the audio device.
To reduce the effect of this signal noise it can be helpful to set an constant signal level for silence that is greater than `0`.
## Parameters
* **level**: a [number](/types/number) between `0` and `1024` to use as the silence level for the audio pin output when no sounds are playing. The default level is `0`.
## Example #example
Set silence level to `512` for the current audio pin.
```typescript
pins.setAudioPin(AnalogPin.P1)
music.setSilenceLevel(512)
```
## See also
[volume](/reference/music/volume), [set audio pin](/reference/pins/set-audio-pin)
```package
music
```

34
docs/reference/music/stop-all-sounds.md Normal file
View File

@ -0,0 +1,34 @@
# stop All Sounds
Stop all the sounds that are playing right now and any others waiting to play.
```sig
music.stopAllSounds()
```
If you play sounds or sound effects more than once, the sounds you asked to play later have to wait until the sounds played earlier finish. You can stop the sound that is playing now and all the sounds waiting to play with ``||music:stop all sounds||``.
## #simnote
### ~hint
#### Simulator
``||music:stop all sounds||`` works on the @boardname@. It might not work in the simulator on every browser.
### ~
## Example #example
Play a tone but stop it right away.
```blocks
let freq = music.noteFrequency(Note.C);
music.playTone(freq, 1000)
music.stopAllSounds()
```
## See also #seealso
[play melody](/reference/music/play-melody), [play](/reference/music/play),
[play tone](/reference/music/play-tone)

2
docs/reference/pins/digital-read-pin.md
View File

@ -48,7 +48,7 @@ keeper @boardname@, you can press button `B` on the remote to buzz and
make the score bigger on the other @boardname@.
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
pins.digitalWritePin(DigitalPin.P1, 1);
basic.pause(500);
pins.digitalWritePin(DigitalPin.P1, 0);

2
docs/reference/pins/digital-write-pin.md
View File

@ -46,7 +46,7 @@ will use ``digital write pin`` to make the other @boardname@ buzz and
make the score bigger.
```blocks
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
pins.digitalWritePin(DigitalPin.P1, 1);
basic.pause(500);
pins.digitalWritePin(DigitalPin.P1, 0);

35
docs/reference/pins/neopixel-matrix-width.md Normal file
View File

@ -0,0 +1,35 @@
# Neopixel matrix width
For Neopixel matrix (strip) on the specified [pin](/device/pins),
set the width of that matrix. This informs the simulator to display
the Neopixel strip as a matrix.
```sig
pins.setMatrixWidth(Digital.P1, 16)
```
## Parameters
* ``name``: The @boardname@ hardware pin to configure (``P0``-``P20``)
* ``width``: a [number](/types/number) (for example, from `2` through `16`)
## Example
To use the example below, you should add the Neopixel extension to your
project and then copy the JavaScript code below over to your project.
The example creates a strip of 25 neopixels corresponding to a 5x5 matrix and then draws
an `X` on the matrix. Try changing the value of the variable `width`
to get matrices of different sizes.
```blocks
let width = 5
let strip = neopixel.create(DigitalPin.P1, width * width, NeoPixelMode.RGB)
strip.setMatrixWidth(width)
pins.setMatrixWidth(DigitalPin.P1, width)
for (let i = 0; i <= width - 1; i++) {
strip.setMatrixColor(i, i, neopixel.colors(NeoPixelColors.Red))
strip.setMatrixColor(width - (i + 1), i, neopixel.colors(NeoPixelColors.Blue))
}
strip.show()
```

34
docs/reference/pins/set-audio-pin.md Normal file
View File

@ -0,0 +1,34 @@
# set Audio Pin
Set the [pin](/device/pins) (P0, P1, P2) that is used to play music and generate tones.
```sig
pins.setAudioPin(AnalogPin.P0)
```
### ~ hint
#### micro:bit V2 speaker
With the [micro:bit V2](/device/v2) hardware, the built-in speaker will play (mirror) the same tones and music sent to the audio pin.
### ~
## Parameters
* **name**: the pin to set for audio output: `P0`, `P1`, or `P2`.
## Example
Play a tone for the "A4" note at pin **P0** for 1 second.
```blocks
pins.setAudioPin(AnalogPin.P0)
let frequency = 440
let duration = 1000
pins.analogPitch(frequency, duration)
```
## See also
[@boardname@ pins](/device/pins), [analog set pitch pin](/reference/pins/analog-set-pitch-pin)

2
docs/reference/radio.md
View File

@ -16,7 +16,6 @@ radio.setGroup(0);
## Advanced
```cards
radio.writeReceivedPacketToSerial();
radio.setTransmitPower(7);
radio.setTransmitSerialNumber(false);
radio.raiseEvent(0, 0);
@ -38,5 +37,4 @@ radio
[set group](/reference/radio/set-group),
[set transmit power](/reference/radio/set-transmit-power),
[set transmit serial number](/reference/radio/set-transmit-serial-number),
[write received packet to serial](/reference/radio/write-received-packet-to-serial),
[raise event](/reference/radio/raise-event)

1
docs/reference/radio/on-received-buffer.md
View File

@ -19,6 +19,7 @@ Two @boardname@s work like remote levels. They lie flat and detect any change in
```typescript
let ax = 0;
let ay = 0;
radio.setGroup(3)
basic.forever(() => {
ax = input.acceleration(Dimension.X);
ay = input.acceleration(Dimension.Y);

2
docs/reference/radio/on-received-number.md
View File

@ -29,6 +29,7 @@ thing from nearby @boardname@s. It shows these numbers as a
[bar graph](/reference/led/plot-bar-graph).
```blocks
radio.setGroup(1)
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X));
})
@ -43,6 +44,7 @@ This program uses the signal strength from received packets to graph the
approximate distance between two @boardname@s.
```blocks
radio.setGroup(1)
basic.forever(() => {
radio.sendNumber(0)
})

1
docs/reference/radio/on-received-string.md
View File

@ -23,6 +23,7 @@ https://www.youtube.com/watch?v=Re3H2ISfQE8
This program continuously sends a cheerful message. It also receives a messages from nearby @boardname@s. It shows these messages on the screen.
```blocks
radio.setGroup(1)
basic.forever(() => {
radio.sendString("I'm happy");
})

1
docs/reference/radio/on-received-value.md
View File

@ -27,6 +27,7 @@ thing from nearby @boardname@s, show the numbers as a
[bar graph](/reference/led/plot-bar-graph).
```blocks
radio.setGroup(1)
basic.forever(() => {
radio.sendValue("accel-x", input.acceleration(Dimension.X))
})

6
docs/reference/radio/receive-string.md
View File

@ -34,7 +34,7 @@ If you load this program onto two or more @boardname@s, you can send a code word
The other @boardname@s will receive the code word and then show it.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
radio.sendString("Codeword: TRIMARAN")
basic.showString("SENT");
})
@ -59,10 +59,10 @@ This program will also receive your friend's mood.
```blocks
let data: string = "";
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
radio.sendString("H");
});
input.onButtonEvent(Button.B, ButtonEvent.Click, () => {
input.onButtonEvent(Button.B, input.buttonEventClick(), () => {
radio.sendString("S");
});
radio.onDataReceived(() => {

3
docs/reference/radio/received-packet.md
View File

@ -18,7 +18,7 @@ In addition to a [number](types/number), [string](/types/string), or name-value
## Returns
* a [number](/types/number) that is the property selected in the **type** parameter:
>* ``signal strength``: the value ranges from `-128` to `-42` (`-128` means a weak signal and `-42` means a strong one.)
>* ``signal strength``: the value ranges from `-128` up to `-28` (`-128` means a weak signal and `-28` means a strong one.)
>* ``serial number``: the value is the serial number of the board sending the packet.
>* ``time``: the value is the system time, in microseconds, of the sender at the time when the packet was sent.
@ -28,6 +28,7 @@ This program uses the signal strength from received packets to graph the
approximate distance between two @boardname@s.
```blocks
radio.setGroup(1)
basic.forever(() => {
radio.sendNumber(0)
})

25
docs/reference/radio/received-signal-strength.md
View File

@ -6,29 +6,35 @@ Find how strong the radio signal is.
radio.receivedSignalStrength();
```
## ~ hint
### ~ hint
**Deprecated**
#### Deprecated
This API has been deprecated! Use [received packet](/reference/radio/received-packet) instead.
## ~
### ~
Find how strong the ``radio`` signal is, from `-128` to `-42`.
(`-128` means a weak signal and `-42` means a strong one.)
Find how strong the ``radio`` signal is, from `-128` to `-28`.
(`-128` means a weak signal and `-28` means a strong one.)
The @boardname@ finds the signal strength by checking how strong it was
the last time it ran the
[on received number](/reference/radio/on-received-number) function. That means
it needs to run **receive number** first.
## Returns
* a [number](/types/number) between `-128` and `-42` that means
* a [number](/types/number) between `-128` and `-28` that means
how strong the signal is.
### ~ hint
#### Signal strength and board version
Measurement of the received signal strength is dependent on what version of @boardname@ you have. The @boardname@ boards prior to v2 can typically measure a signal strength up to `-42` dBm. Now, v2 boards will measure a signal strength up to `-28` dBm (typical).
### ~
## Simulator
This function only works on the @boardname@, not in browsers.
@ -49,7 +55,8 @@ basic.forever(() => {
## See also
[on received number](/reference/radio/on-received-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
[on received number](/reference/radio/on-received-number), [send number](/reference/radio/send-number),
[on data received](/reference/radio/on-data-received), [received packet](/reference/received-packet)
```package
radio

1
docs/reference/radio/send-buffer.md
View File

@ -19,6 +19,7 @@ If you load this program onto two @boardname@s, each board will send the level i
```typescript
let ax = 0;
let ay = 0;
radio.setGroup(6)
basic.forever(() => {
ax = input.acceleration(Dimension.X);
ay = input.acceleration(Dimension.Y);

2
docs/reference/radio/send-number.md
View File

@ -27,7 +27,7 @@ in the `x` direction (left and right) to other @boardname@s. This kind
of program might be useful in a model car or model rocket.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
radio.sendNumber(input.acceleration(Dimension.X))
})
```

3
docs/reference/radio/send-string.md
View File

@ -26,7 +26,8 @@ code word from one of them to the others by pressing button `A`. The
other @boardname@s will receive the code word and then show it.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
radio.setGroup(1)
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
radio.sendString("Codeword: TRIMARAN")
basic.showString("SENT");
})

2
docs/reference/radio/send-value.md
View File

@ -29,7 +29,7 @@ or model rocket.
```blocks
radio.setGroup(99)
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
radio.sendValue("acc", input.acceleration(Dimension.X))
})
```

8
docs/reference/radio/set-group.md
View File

@ -20,6 +20,14 @@ to talk to each other because they will have the same group ID.
* **id**: a [number](/types/number) from ``0`` to ``255``.
### ~ reminder
#### Default radio group
If you haven't set a radio group for the @boardname@, it will use one selected randomly. If you are transmiting data to a @boardname@ that has a different hardware version from the sending @boardname@, it will select a random default group that is not the same as the other @boardname@. To be certain that your program will send or receive data using the same radio group, you will need to first choose and set a radio group for your program if you want it to work between different versions of the @boardname@.
### ~
## Simulator
This function only works on the @boardname@, not in browsers.

13
docs/reference/radio/write-received-packet-to-serial.md
View File

@ -9,6 +9,14 @@ radio.writeReceivedPacketToSerial();
This should be called within a callback to
[on data packet received](/reference/radio/on-data-packet-received).
### ~ hint
#### Deprecated
This API has been deprecated! Use [serial write value](/reference/serial/write-value) instead.
### ~
## Data received format
The format for received data when these send functions are used:
@ -19,6 +27,8 @@ The format for received data when these send functions are used:
### ~hint
#### Default serial number
The serial number value sent in the packet is set to `0` unless transmission of the serial number is enabled with ``||radio:radio set transmit serial number||``.
### ~
@ -30,7 +40,8 @@ the second @boardname@), this program sends temperature data to the
serial port.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, function () {
radio.setGroup(44)
input.onButtonEvent(Button.A, input.buttonEventClick(), function () {
radio.sendNumber(input.temperature())
radio.sendValue("temp", input.temperature())
radio.sendString("It's warm now")

3
docs/reference/radio/write-value-to-serial.md
View File

@ -29,7 +29,8 @@ the second @boardname@), this program sends temperature data to
serial.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
radio.setGroup(1)
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
radio.sendNumber(input.temperature());
});
radio.onDataReceived(() => {

22
docs/reference/serial/read-buffer.md
View File

@ -9,17 +9,19 @@ serial.readBuffer(64);
## Parameters
* **length**: the [number](/types/number) of characters of serial data to read.
Use ``0`` to return the available buffered data.
## Returns
* a [buffer](/types/buffer) containing input from the serial port. The length of the buffer may be smaller than the requested length.
The length is 0 if any error occurs.
## ~hint
**Pause for more data**
If the desired number of characters are available, **readBuffer** returns a buffer with the expected size. If not, the calling fiber (the part of your program calling the **readBuffer** function) sleeps until the desired number of characters are finally read into the buffer.
The need to pause for more data is set by the @boardname@ **[serial mode](https://lancaster-university.github.io/microbit-docs/ubit/serial/#serial-modes)**.
To avoid waiting for data, set the length to ``0`` so that buffered data is returned immediately.
## ~
## Example
@ -27,13 +29,27 @@ The need to pause for more data is set by the @boardname@ **[serial mode](https:
Read character data from the serial port one row at a time. Write the rows to an LED display connected to the I2C pins.
```typescript
let rowData: Buffer = null;
serial.setRxBufferSize(10)
for (let i = 0; i < 24; i++) {
rowData = serial.readBuffer(80);
let rowData = serial.readBuffer(10);
pins.i2cWriteBuffer(65, rowData, false);
}
```
## Example Async
Read available data and process it as it comes.
```typescript
basic.forever(function() {
let rowData = serial.readBuffer(0);
if (rowData.length > 0) {
// do something!!!
}
})
```
## See Also
[write buffer](/reference/serial/write-buffer)

2
docs/reference/serial/redirect.md
View File

@ -32,7 +32,7 @@ serial port to use the pins. The new configuration uses pin ``P1`` to transmit a
``P2`` to receive. The baud rate is set to `9600`.
```blocks
input.onButtonEvent(Button.A, ButtonEvent.Click, () => {
input.onButtonEvent(Button.A, input.buttonEventClick(), () => {
serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
});
```

1
docs/reference/storage/get-number.md Normal file
View File

@ -0,0 +1 @@
# Get Number

1
docs/reference/storage/put-number.md Normal file
View File

@ -0,0 +1 @@
# Put Number

1
docs/reference/storage/remove-number.md Normal file
View File

@ -0,0 +1 @@
# Remove Number

6
editor/patch.ts
View File

@ -19,7 +19,7 @@ export function patchBlocks(pkgTargetVersion: string, dom: Element) {
<block type="device_button_selected_event" x="35" y="429">
<field name="NAME">Button.B</field>
<value name="eventType">
<shadow type="control_button_event_value_id">
<shadow type="control_button_event_value">
<field name="id">ButtonEvent.Click</field>
</shadow>
</value>
@ -27,7 +27,7 @@ export function patchBlocks(pkgTargetVersion: string, dom: Element) {
<block type="device_pin_custom_event" x="368" y="428">
<field name="NAME">TouchPin.P2</field>
<value name="eventType">
<shadow type="control_button_event_value_id">
<shadow type="control_button_event_value">
<field name="id">ButtonEvent.Up</field>
</shadow>
</value>
@ -51,7 +51,7 @@ const inputNodes = pxt.U.toArray(dom.querySelectorAll("block[type=device_button_
valueNode.setAttribute("name", "eventType")
const shadowNode = node.ownerDocument.createElement("shadow");
shadowNode.setAttribute("type", "control_button_event_value_id")
shadowNode.setAttribute("type", "control_button_event_value")
const fieldNode = node.ownerDocument.createElement("field");
fieldNode.setAttribute("name", "id")

6
libs/bluetooth/pxt.json
View File

@ -24,10 +24,6 @@
"enabled": 1
}
}
},
"optionalConfig": {
},
"userConfigs": [
]
}
}
}

4
libs/core/_locales/core-jsdoc-strings.json
View File

@ -426,7 +426,9 @@
"input.acceleration": "Get the acceleration value in milli-gravitys (when the board is laying flat with the screen up, x=0, y=0 and z=-1024)",
"input.acceleration|param|dimension": "x, y, or z dimension, eg: Dimension.X",
"input.assumeCalibrationCompass": "Obsolete, compass calibration is automatic.",
"input.buttonEventValueId": "Returns the value of a C++ runtime constant",
"input.buttonEventClick": "Returns the ID of an Click Event",
"input.buttonEventDown": "Returns the ID of an Down Event",
"input.buttonEventValue": "Returns the ID of an Button Event",
"input.buttonIsPressed": "Get the button state (pressed or not) for ``A`` and ``B``.",
"input.buttonIsPressed|param|button": "the button to query the request, eg: Button.A",
"input.calibrateCompass": "Obsolete, compass calibration is automatic.",

9
libs/core/_locales/core-strings.json
View File

@ -52,6 +52,7 @@
"Button.AB|block": "A+B",
"ButtonEvent.Click|block": "clicked",
"ButtonEvent.Down|block": "pressed down",
"ButtonEvent.Hold|block": "hold",
"ButtonEvent.LongClick|block": "long clicked",
"ButtonEvent.Up|block": "released up",
"Colors.Blue|block": "blue",
@ -335,7 +336,9 @@
"images|block": "images",
"input.acceleration|block": "acceleration (mg)|%NAME",
"input.assumeCalibrationCompass|block": "assume calibration compass",
"input.buttonEventValueId|block": "%id",
"input.buttonEventClick|block": "clicked",
"input.buttonEventDown|block": "pressed down",
"input.buttonEventValue|block": "%id",
"input.buttonIsPressed|block": "button|%NAME|is pressed",
"input.calibrateCompass|block": "calibrate compass",
"input.clearCalibrationCompass|block": "clear calibration compass",
@ -344,12 +347,12 @@
"input.isGesture|block": "is %gesture gesture",
"input.lightLevel|block": "light level",
"input.magneticForce|block": "magnetic force (µT)|%NAME",
"input.onButtonEvent|block": "on button %NAME| %eventType=control_button_event_value_id",
"input.onButtonEvent|block": "on button %NAME| %eventType",
"input.onButtonPressed|block": "on button|%NAME|pressed",
"input.onGesture|block": "on |%NAME",
"input.onPinPressed|block": "on pin %name|pressed",
"input.onPinReleased|block": "on pin %NAME|released",
"input.onPinTouchEvent|block": "on pin %name| %eventType=control_button_event_value_id",
"input.onPinTouchEvent|block": "on pin %name| %eventType",
"input.pinIsPressed|block": "pin %NAME|is pressed",
"input.rotation|block": "rotation (°)|%NAME",
"input.runningTimeMicros|block": "running time (micros)",

2
libs/core/basic.cpp
View File

@ -116,6 +116,7 @@ namespace basic {
/**
* Sets the color on the build-in LED. Set to 0 to turn off.
*/
//% help=basic/set-led-color
//% blockId=device_set_led_color
//% block="set led to %color=colorNumberPicker"
//% color.defl=0xff0000
@ -140,6 +141,7 @@ namespace basic {
* Sets the color on the build-in LED. Set to 0 to turn off.
*/
//% blockId=device_turn_rgb_led_off block="turn build-in LED off"
//% help=basic/turn-rgb-led-off
//% weight=10
//% group="RGB LED"
//% advanced=true

1
libs/core/basic.ts
View File

@ -76,6 +76,7 @@ namespace basic {
* @param blue value of the blue channel between 0 and 255. eg: 255
*/
//% weight=3
//% help=basic/rgb
//% blockId="core_rgb" block="red %red|green %green|blue %blue"
//% group="RGB LED"
export function rgb(red: number, green: number, blue: number): number {

6
libs/core/blocks-test/input.blocks
View File

@ -6,7 +6,7 @@
<block type="device_button_selected_event" x="0" y="0">
<field name="NAME">Button.AB</field>
<value name="eventType">
<shadow type="control_button_event_value_id"></shadow>
<shadow type="control_button_event_value"></shadow>
</value>
<statement name="HANDLER">
<block type="variables_set">
@ -129,13 +129,13 @@
<block type="device_pin_custom_event" x="556" y="156">
<field name="name">TouchPin.P0</field>
<value name="eventType">
<shadow type="control_button_event_value_id"></shadow>
<shadow type="control_button_event_value"></shadow>
</value>
</block>
<block type="device_pin_custom_event" x="560" y="274">
<field name="name">TouchPin.P0</field>
<value name="eventType">
<shadow type="control_button_event_value_id"></shadow>
<shadow type="control_button_event_value"></shadow>
</value>
</block>
</xml>

6
libs/core/blocks-test/test.blocks
View File

@ -133,7 +133,7 @@
</block>
<block type="device_pin_custom_event" x="2009" y="121">
<value name="eventType">
<shadow type="control_button_event_value_id"></shadow>
<shadow type="control_button_event_value"></shadow>
</value>
<statement name="HANDLER">
<block type="device_led_toggle">
@ -435,7 +435,7 @@
<block type="device_button_selected_event" x="896" y="634">
<field name="NAME">Button.AB</field>
<value name="eventType">
<shadow type="control_button_event_value_id"></shadow>
<shadow type="control_button_event_value"></shadow>
</value>
<statement name="HANDLER">
<block type="device_plot">
@ -512,7 +512,7 @@
</block>
<block type="device_pin_custom_event" x="478" y="950">
<value name="eventType">
<shadow type="control_button_event_value_id"></shadow>
<shadow type="control_button_event_value"></shadow>
</value>
<statement name="HANDLER"></statement>
</block>

Some files were not shown because too many files have changed in this diff Show More