diff --git a/docs/reference/basic.md b/docs/reference/basic.md index c42fc82d..bdcf6055 100644 --- a/docs/reference/basic.md +++ b/docs/reference/basic.md @@ -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) \ No newline at end of file diff --git a/docs/reference/basic/forever.md b/docs/reference/basic/forever.md index 4babcb0a..586aacef 100644 --- a/docs/reference/basic/forever.md +++ b/docs/reference/basic/forever.md @@ -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) diff --git a/docs/reference/basic/pause.md b/docs/reference/basic/pause.md index 4c962a73..1da40c43 100644 --- a/docs/reference/basic/pause.md +++ b/docs/reference/basic/pause.md @@ -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) diff --git a/docs/reference/basic/plot-leds.md b/docs/reference/basic/plot-leds.md deleted file mode 100644 index db6b2649..00000000 --- a/docs/reference/basic/plot-leds.md +++ /dev/null @@ -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) - diff --git a/docs/reference/basic/rgb.md b/docs/reference/basic/rgb.md new file mode 100644 index 00000000..4d4897b4 --- /dev/null +++ b/docs/reference/basic/rgb.md @@ -0,0 +1 @@ +# RGB \ No newline at end of file diff --git a/docs/reference/basic/set-led-color.md b/docs/reference/basic/set-led-color.md new file mode 100644 index 00000000..ef250ba8 --- /dev/null +++ b/docs/reference/basic/set-led-color.md @@ -0,0 +1 @@ +# Set LED Color \ No newline at end of file diff --git a/docs/reference/basic/show-animation.md b/docs/reference/basic/show-animation.md deleted file mode 100644 index b91554e7..00000000 --- a/docs/reference/basic/show-animation.md +++ /dev/null @@ -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. - -## ~ diff --git a/docs/reference/basic/show-compass.md b/docs/reference/basic/show-compass.md new file mode 100644 index 00000000..b75fb839 --- /dev/null +++ b/docs/reference/basic/show-compass.md @@ -0,0 +1 @@ +# Show Compass \ No newline at end of file diff --git a/docs/reference/basic/show-number.md b/docs/reference/basic/show-number.md index 804b96ad..51806f03 100644 --- a/docs/reference/basic/show-number.md +++ b/docs/reference/basic/show-number.md @@ -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. diff --git a/docs/reference/basic/turn-rgb-led-off.md b/docs/reference/basic/turn-rgb-led-off.md new file mode 100644 index 00000000..1e34f1ae --- /dev/null +++ b/docs/reference/basic/turn-rgb-led-off.md @@ -0,0 +1 @@ +# Turn RGB Led Off \ No newline at end of file diff --git a/docs/reference/bluetooth.md b/docs/reference/bluetooth.md index 1a20ac00..a691b9b8 100644 --- a/docs/reference/bluetooth.md +++ b/docs/reference/bluetooth.md @@ -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 diff --git a/docs/reference/bluetooth/advertise-uid-buffer.md b/docs/reference/bluetooth/advertise-uid-buffer.md index f4219e85..c703c74c 100644 --- a/docs/reference/bluetooth/advertise-uid-buffer.md +++ b/docs/reference/bluetooth/advertise-uid-buffer.md @@ -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). diff --git a/docs/reference/bluetooth/advertise-uid.md b/docs/reference/bluetooth/advertise-uid.md index 710b677d..e2192f5c 100644 --- a/docs/reference/bluetooth/advertise-uid.md +++ b/docs/reference/bluetooth/advertise-uid.md @@ -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) diff --git a/docs/reference/bluetooth/advertise-url.md b/docs/reference/bluetooth/advertise-url.md index 45a687f1..f876c9c0 100644 --- a/docs/reference/bluetooth/advertise-url.md +++ b/docs/reference/bluetooth/advertise-url.md @@ -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. diff --git a/docs/reference/bluetooth/on-uart-data-received.md b/docs/reference/bluetooth/on-uart-data-received.md index 48d7202f..4c1b23f8 100644 --- a/docs/reference/bluetooth/on-uart-data-received.md +++ b/docs/reference/bluetooth/on-uart-data-received.md @@ -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 +``` diff --git a/docs/reference/control.md b/docs/reference/control.md index eb644622..5aac3602 100644 --- a/docs/reference/control.md +++ b/docs/reference/control.md @@ -4,7 +4,7 @@ Runtime and event utilities. ```cards control.inBackground(() => { - + }); control.reset(); control.waitMicros(4); diff --git a/docs/reference/devices.md b/docs/reference/devices.md deleted file mode 100644 index 487d4cb1..00000000 --- a/docs/reference/devices.md +++ /dev/null @@ -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) diff --git a/docs/reference/devices/on-gamepad-button.md b/docs/reference/devices/on-gamepad-button.md deleted file mode 100644 index 14e74931..00000000 --- a/docs/reference/devices/on-gamepad-button.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/reference/devices/on-notified.md b/docs/reference/devices/on-notified.md deleted file mode 100644 index 8f86bb19..00000000 --- a/docs/reference/devices/on-notified.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/reference/devices/on-signal-strength-changed.md b/docs/reference/devices/on-signal-strength-changed.md deleted file mode 100644 index 14db9594..00000000 --- a/docs/reference/devices/on-signal-strength-changed.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/reference/devices/raise-alert-to.md b/docs/reference/devices/raise-alert-to.md deleted file mode 100644 index 9371ffe7..00000000 --- a/docs/reference/devices/raise-alert-to.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/reference/devices/signal-strength.md b/docs/reference/devices/signal-strength.md deleted file mode 100644 index 5eb2b6a6..00000000 --- a/docs/reference/devices/signal-strength.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/reference/devices/tell-camera-to.md b/docs/reference/devices/tell-camera-to.md deleted file mode 100644 index 3870d785..00000000 --- a/docs/reference/devices/tell-camera-to.md +++ /dev/null @@ -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 -``` diff --git a/docs/reference/devices/tell-remote-control-to.md b/docs/reference/devices/tell-remote-control-to.md deleted file mode 100644 index 51639734..00000000 --- a/docs/reference/devices/tell-remote-control-to.md +++ /dev/null @@ -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 -``` diff --git a/docs/reference/event-handler.md b/docs/reference/event-handler.md index 65fcdde3..5712985d 100644 --- a/docs/reference/event-handler.md +++ b/docs/reference/event-handler.md @@ -9,7 +9,7 @@ An event handler is code that is associated with a particular event, such as "bu Functions named "on " 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) }) diff --git a/docs/reference/game/change.md b/docs/reference/game/change.md index 00d9a231..704e178c 100644 --- a/docs/reference/game/change.md +++ b/docs/reference/game/change.md @@ -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 diff --git a/docs/reference/game/get.md b/docs/reference/game/get.md index d2608e3e..7e615871 100644 --- a/docs/reference/game/get.md +++ b/docs/reference/game/get.md @@ -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 diff --git a/docs/reference/game/is-running.md b/docs/reference/game/is-running.md index 2ceba3f3..c9d20578 100644 --- a/docs/reference/game/is-running.md +++ b/docs/reference/game/is-running.md @@ -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() } diff --git a/docs/reference/game/set-score.md b/docs/reference/game/set-score.md index b51e3a1a..6212a631 100644 --- a/docs/reference/game/set-score.md +++ b/docs/reference/game/set-score.md @@ -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) }) ``` diff --git a/docs/reference/game/set.md b/docs/reference/game/set.md index 7a6ccb1b..04a7eda9 100644 --- a/docs/reference/game/set.md +++ b/docs/reference/game/set.md @@ -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 diff --git a/docs/reference/game/start-countdown.md b/docs/reference/game/start-countdown.md index d5cc0178..ae8f8e89 100644 --- a/docs/reference/game/start-countdown.md +++ b/docs/reference/game/start-countdown.md @@ -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) diff --git a/docs/reference/images/create-big-image.md b/docs/reference/images/create-big-image.md index 5fd3ced8..8a6a791d 100644 --- a/docs/reference/images/create-big-image.md +++ b/docs/reference/images/create-big-image.md @@ -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); }); ``` diff --git a/docs/reference/images/create-image.md b/docs/reference/images/create-image.md index ce44163d..5fe8cb13 100644 --- a/docs/reference/images/create-image.md +++ b/docs/reference/images/create-image.md @@ -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(` . . # . . . . # . . diff --git a/docs/reference/images/icon-image.md b/docs/reference/images/icon-image.md index b6d48f51..c6f92ef9 100644 --- a/docs/reference/images/icon-image.md +++ b/docs/reference/images/icon-image.md @@ -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) \ No newline at end of file diff --git a/docs/reference/images/show-image.md b/docs/reference/images/show-image.md index ae8dd6cf..a44ba0dc 100644 --- a/docs/reference/images/show-image.md +++ b/docs/reference/images/show-image.md @@ -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); }); ``` diff --git a/docs/reference/input.md b/docs/reference/input.md index cb86edb4..a412e874 100644 --- a/docs/reference/input.md +++ b/docs/reference/input.md @@ -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) diff --git a/docs/reference/input/button-event.md b/docs/reference/input/button-event.md new file mode 100644 index 00000000..9ba6c12b --- /dev/null +++ b/docs/reference/input/button-event.md @@ -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) \ No newline at end of file diff --git a/docs/reference/input/calibrate-compass.md b/docs/reference/input/calibrate-compass.md index 71e86dcc..4a8c5f51 100644 --- a/docs/reference/input/calibrate-compass.md +++ b/docs/reference/input/calibrate-compass.md @@ -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(); }) ``` diff --git a/docs/reference/input/compass-heading.md b/docs/reference/input/compass-heading.md index f13e2962..6327ac4b 100644 --- a/docs/reference/input/compass-heading.md +++ b/docs/reference/input/compass-heading.md @@ -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(); }) ``` diff --git a/docs/reference/input/light-level.md b/docs/reference/input/light-level.md index 52360fb5..0d35f4ab 100644 --- a/docs/reference/input/light-level.md +++ b/docs/reference/input/light-level.md @@ -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) }) diff --git a/docs/reference/input/logo-is-pressed.md b/docs/reference/input/logo-is-pressed.md new file mode 100644 index 00000000..7e29a0e8 --- /dev/null +++ b/docs/reference/input/logo-is-pressed.md @@ -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) \ No newline at end of file diff --git a/docs/reference/input/on-button-event.md b/docs/reference/input/on-button-event.md index e4ea2520..4fd4a1ee 100644 --- a/docs/reference/input/on-button-event.md +++ b/docs/reference/input/on-button-event.md @@ -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) diff --git a/docs/reference/input/on-logo-event.md b/docs/reference/input/on-logo-event.md new file mode 100644 index 00000000..180bdbaf --- /dev/null +++ b/docs/reference/input/on-logo-event.md @@ -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) diff --git a/docs/reference/input/on-pin-event.md b/docs/reference/input/on-pin-event.md index 4ae790f8..09819a7c 100644 --- a/docs/reference/input/on-pin-event.md +++ b/docs/reference/input/on-pin-event.md @@ -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) diff --git a/docs/reference/input/on-sound.md b/docs/reference/input/on-sound.md new file mode 100644 index 00000000..5c559c12 --- /dev/null +++ b/docs/reference/input/on-sound.md @@ -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 +``` diff --git a/docs/reference/input/running-time.md b/docs/reference/input/running-time.md index 6cc79d57..581d982f 100644 --- a/docs/reference/input/running-time.md +++ b/docs/reference/input/running-time.md @@ -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) }) diff --git a/docs/reference/input/set-sound-threshold.md b/docs/reference/input/set-sound-threshold.md new file mode 100644 index 00000000..7b5357c0 --- /dev/null +++ b/docs/reference/input/set-sound-threshold.md @@ -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 +``` \ No newline at end of file diff --git a/docs/reference/input/sound-level.md b/docs/reference/input/sound-level.md new file mode 100644 index 00000000..529296d6 --- /dev/null +++ b/docs/reference/input/sound-level.md @@ -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 +``` \ No newline at end of file diff --git a/docs/reference/led.md b/docs/reference/led.md index 105b865b..1776027b 100644 --- a/docs/reference/led.md +++ b/docs/reference/led.md @@ -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) diff --git a/docs/reference/led/enable.md b/docs/reference/led/enable.md index 4e02db14..686d8b2a 100644 --- a/docs/reference/led/enable.md +++ b/docs/reference/led/enable.md @@ -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) }); ``` diff --git a/docs/reference/led/stop-animation.md b/docs/reference/led/stop-animation.md index 1cd9159f..cd197488 100644 --- a/docs/reference/led/stop-animation.md +++ b/docs/reference/led/stop-animation.md @@ -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) diff --git a/docs/reference/loops/every-interval.md b/docs/reference/loops/every-interval.md new file mode 100644 index 00000000..ab1c487b --- /dev/null +++ b/docs/reference/loops/every-interval.md @@ -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) \ No newline at end of file diff --git a/docs/reference/math/int.md b/docs/reference/math/int.md new file mode 100644 index 00000000..5ebffcfb --- /dev/null +++ b/docs/reference/math/int.md @@ -0,0 +1,2 @@ +# Int + diff --git a/docs/reference/math/random-boolean.md b/docs/reference/math/random-boolean.md new file mode 100644 index 00000000..229e5e75 --- /dev/null +++ b/docs/reference/math/random-boolean.md @@ -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) \ No newline at end of file diff --git a/docs/reference/music.md b/docs/reference/music.md index 02be446d..4a223b7e 100644 --- a/docs/reference/music.md +++ b/docs/reference/music.md @@ -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) + diff --git a/docs/reference/music/begin-melody.md b/docs/reference/music/begin-melody.md index 84d6970d..6a9af12d 100644 --- a/docs/reference/music/begin-melody.md +++ b/docs/reference/music/begin-melody.md @@ -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``. diff --git a/docs/reference/music/builtin-sound-effect.md b/docs/reference/music/builtin-sound-effect.md new file mode 100644 index 00000000..160d6b72 --- /dev/null +++ b/docs/reference/music/builtin-sound-effect.md @@ -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) \ No newline at end of file diff --git a/docs/reference/music/create-sound-effect.md b/docs/reference/music/create-sound-effect.md new file mode 100644 index 00000000..b9587c32 --- /dev/null +++ b/docs/reference/music/create-sound-effect.md @@ -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) diff --git a/docs/reference/music/note-frequency.md b/docs/reference/music/note-frequency.md new file mode 100644 index 00000000..9b9d21bb --- /dev/null +++ b/docs/reference/music/note-frequency.md @@ -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) diff --git a/docs/reference/music/on-event.md b/docs/reference/music/on-event.md index 00ecfbe8..f5f6cdd0 100644 --- a/docs/reference/music/on-event.md +++ b/docs/reference/music/on-event.md @@ -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) diff --git a/docs/reference/music/play-melody.md b/docs/reference/music/play-melody.md new file mode 100644 index 00000000..1d9df391 --- /dev/null +++ b/docs/reference/music/play-melody.md @@ -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) diff --git a/docs/reference/music/play-sound-effect.md b/docs/reference/music/play-sound-effect.md new file mode 100644 index 00000000..53dd6a98 --- /dev/null +++ b/docs/reference/music/play-sound-effect.md @@ -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) diff --git a/docs/reference/music/play-until-done.md b/docs/reference/music/play-until-done.md new file mode 100644 index 00000000..1ff5798c --- /dev/null +++ b/docs/reference/music/play-until-done.md @@ -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) \ No newline at end of file diff --git a/docs/reference/music/play.md b/docs/reference/music/play.md new file mode 100644 index 00000000..4b2ff1dd --- /dev/null +++ b/docs/reference/music/play.md @@ -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) \ No newline at end of file diff --git a/docs/reference/music/set-built-in-speaker-enabled.md b/docs/reference/music/set-built-in-speaker-enabled.md new file mode 100644 index 00000000..b26456e7 --- /dev/null +++ b/docs/reference/music/set-built-in-speaker-enabled.md @@ -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 +``` diff --git a/docs/reference/music/set-play-tone.md b/docs/reference/music/set-play-tone.md index 8d8f5347..441c18f3 100644 --- a/docs/reference/music/set-play-tone.md +++ b/docs/reference/music/set-play-tone.md @@ -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)); }) diff --git a/docs/reference/music/set-silence-level.md b/docs/reference/music/set-silence-level.md new file mode 100644 index 00000000..ab253d8c --- /dev/null +++ b/docs/reference/music/set-silence-level.md @@ -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 +``` diff --git a/docs/reference/music/stop-all-sounds.md b/docs/reference/music/stop-all-sounds.md new file mode 100644 index 00000000..e2e6d3dc --- /dev/null +++ b/docs/reference/music/stop-all-sounds.md @@ -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) diff --git a/docs/reference/pins/digital-read-pin.md b/docs/reference/pins/digital-read-pin.md index 9b0d6955..d4af8aa0 100644 --- a/docs/reference/pins/digital-read-pin.md +++ b/docs/reference/pins/digital-read-pin.md @@ -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); diff --git a/docs/reference/pins/digital-write-pin.md b/docs/reference/pins/digital-write-pin.md index 2cc7a861..e7bfad3a 100644 --- a/docs/reference/pins/digital-write-pin.md +++ b/docs/reference/pins/digital-write-pin.md @@ -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); diff --git a/docs/reference/pins/neopixel-matrix-width.md b/docs/reference/pins/neopixel-matrix-width.md new file mode 100644 index 00000000..1f733e26 --- /dev/null +++ b/docs/reference/pins/neopixel-matrix-width.md @@ -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() +``` + diff --git a/docs/reference/pins/set-audio-pin.md b/docs/reference/pins/set-audio-pin.md new file mode 100644 index 00000000..458f0bac --- /dev/null +++ b/docs/reference/pins/set-audio-pin.md @@ -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) diff --git a/docs/reference/radio.md b/docs/reference/radio.md index f0965a67..7735ae1d 100644 --- a/docs/reference/radio.md +++ b/docs/reference/radio.md @@ -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) diff --git a/docs/reference/radio/on-received-buffer.md b/docs/reference/radio/on-received-buffer.md index bd07af47..3429a65e 100644 --- a/docs/reference/radio/on-received-buffer.md +++ b/docs/reference/radio/on-received-buffer.md @@ -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); diff --git a/docs/reference/radio/on-received-number.md b/docs/reference/radio/on-received-number.md index ffa2e4e4..0b76dd00 100644 --- a/docs/reference/radio/on-received-number.md +++ b/docs/reference/radio/on-received-number.md @@ -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) }) diff --git a/docs/reference/radio/on-received-string.md b/docs/reference/radio/on-received-string.md index cb22faf6..63f19e86 100644 --- a/docs/reference/radio/on-received-string.md +++ b/docs/reference/radio/on-received-string.md @@ -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"); }) diff --git a/docs/reference/radio/on-received-value.md b/docs/reference/radio/on-received-value.md index 8b61fb40..66fc1d34 100644 --- a/docs/reference/radio/on-received-value.md +++ b/docs/reference/radio/on-received-value.md @@ -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)) }) diff --git a/docs/reference/radio/receive-string.md b/docs/reference/radio/receive-string.md index c5ecbb2c..ad89d7e2 100644 --- a/docs/reference/radio/receive-string.md +++ b/docs/reference/radio/receive-string.md @@ -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(() => { diff --git a/docs/reference/radio/received-packet.md b/docs/reference/radio/received-packet.md index 3dd95504..bc25c2ae 100644 --- a/docs/reference/radio/received-packet.md +++ b/docs/reference/radio/received-packet.md @@ -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) }) diff --git a/docs/reference/radio/received-signal-strength.md b/docs/reference/radio/received-signal-strength.md index 95516040..de96300f 100644 --- a/docs/reference/radio/received-signal-strength.md +++ b/docs/reference/radio/received-signal-strength.md @@ -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 diff --git a/docs/reference/radio/send-buffer.md b/docs/reference/radio/send-buffer.md index 5d4975de..2d9c27dc 100644 --- a/docs/reference/radio/send-buffer.md +++ b/docs/reference/radio/send-buffer.md @@ -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); diff --git a/docs/reference/radio/send-number.md b/docs/reference/radio/send-number.md index a396efab..f97affcc 100644 --- a/docs/reference/radio/send-number.md +++ b/docs/reference/radio/send-number.md @@ -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)) }) ``` diff --git a/docs/reference/radio/send-string.md b/docs/reference/radio/send-string.md index 75e295e1..99564689 100644 --- a/docs/reference/radio/send-string.md +++ b/docs/reference/radio/send-string.md @@ -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"); }) diff --git a/docs/reference/radio/send-value.md b/docs/reference/radio/send-value.md index bbcf4fd5..cc084a63 100644 --- a/docs/reference/radio/send-value.md +++ b/docs/reference/radio/send-value.md @@ -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)) }) ``` diff --git a/docs/reference/radio/set-group.md b/docs/reference/radio/set-group.md index 6c640441..1134d6c2 100644 --- a/docs/reference/radio/set-group.md +++ b/docs/reference/radio/set-group.md @@ -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. diff --git a/docs/reference/radio/write-received-packet-to-serial.md b/docs/reference/radio/write-received-packet-to-serial.md index 7d7ca22a..c14722cc 100644 --- a/docs/reference/radio/write-received-packet-to-serial.md +++ b/docs/reference/radio/write-received-packet-to-serial.md @@ -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") diff --git a/docs/reference/radio/write-value-to-serial.md b/docs/reference/radio/write-value-to-serial.md index c3b0815e..8c6a25d7 100644 --- a/docs/reference/radio/write-value-to-serial.md +++ b/docs/reference/radio/write-value-to-serial.md @@ -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(() => { diff --git a/docs/reference/serial/read-buffer.md b/docs/reference/serial/read-buffer.md index 7a31fe33..a6a841f8 100644 --- a/docs/reference/serial/read-buffer.md +++ b/docs/reference/serial/read-buffer.md @@ -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) diff --git a/docs/reference/serial/redirect.md b/docs/reference/serial/redirect.md index 8a688b84..90c8358f 100644 --- a/docs/reference/serial/redirect.md +++ b/docs/reference/serial/redirect.md @@ -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); }); ``` diff --git a/docs/reference/storage/get-number.md b/docs/reference/storage/get-number.md new file mode 100644 index 00000000..782e956a --- /dev/null +++ b/docs/reference/storage/get-number.md @@ -0,0 +1 @@ +# Get Number \ No newline at end of file diff --git a/docs/reference/storage/put-number.md b/docs/reference/storage/put-number.md new file mode 100644 index 00000000..0b8a8ff5 --- /dev/null +++ b/docs/reference/storage/put-number.md @@ -0,0 +1 @@ +# Put Number \ No newline at end of file diff --git a/docs/reference/storage/remove-number.md b/docs/reference/storage/remove-number.md new file mode 100644 index 00000000..d9cf44f4 --- /dev/null +++ b/docs/reference/storage/remove-number.md @@ -0,0 +1 @@ +# Remove Number \ No newline at end of file diff --git a/editor/patch.ts b/editor/patch.ts index ddb1361d..01a68a67 100644 --- a/editor/patch.ts +++ b/editor/patch.ts @@ -19,7 +19,7 @@ export function patchBlocks(pkgTargetVersion: string, dom: Element) { Button.B - + ButtonEvent.Click @@ -27,7 +27,7 @@ export function patchBlocks(pkgTargetVersion: string, dom: Element) { TouchPin.P2 - + ButtonEvent.Up @@ -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") diff --git a/libs/bluetooth/pxt.json b/libs/bluetooth/pxt.json index 188aa9b6..1cac2468 100644 --- a/libs/bluetooth/pxt.json +++ b/libs/bluetooth/pxt.json @@ -24,10 +24,6 @@ "enabled": 1 } } - }, - "optionalConfig": { - }, - "userConfigs": [ - ] + } } } diff --git a/libs/core/_locales/core-jsdoc-strings.json b/libs/core/_locales/core-jsdoc-strings.json index 0a923049..4bb375cf 100644 --- a/libs/core/_locales/core-jsdoc-strings.json +++ b/libs/core/_locales/core-jsdoc-strings.json @@ -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.", diff --git a/libs/core/_locales/core-strings.json b/libs/core/_locales/core-strings.json index 56cbaa8f..642c9d0b 100644 --- a/libs/core/_locales/core-strings.json +++ b/libs/core/_locales/core-strings.json @@ -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)", diff --git a/libs/core/basic.cpp b/libs/core/basic.cpp index daa7ee2c..c95f873a 100644 --- a/libs/core/basic.cpp +++ b/libs/core/basic.cpp @@ -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 diff --git a/libs/core/basic.ts b/libs/core/basic.ts index cb84c6d3..febe05a6 100644 --- a/libs/core/basic.ts +++ b/libs/core/basic.ts @@ -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 { diff --git a/libs/core/blocks-test/input.blocks b/libs/core/blocks-test/input.blocks index cf58b748..50f59d1d 100644 --- a/libs/core/blocks-test/input.blocks +++ b/libs/core/blocks-test/input.blocks @@ -6,7 +6,7 @@ Button.AB - + @@ -129,13 +129,13 @@ TouchPin.P0 - + TouchPin.P0 - + \ No newline at end of file diff --git a/libs/core/blocks-test/test.blocks b/libs/core/blocks-test/test.blocks index d3d9ba59..2c46d36b 100644 --- a/libs/core/blocks-test/test.blocks +++ b/libs/core/blocks-test/test.blocks @@ -133,7 +133,7 @@ - + @@ -435,7 +435,7 @@ Button.AB - + @@ -512,7 +512,7 @@ - + diff --git a/libs/core/compass.ts b/libs/core/compass.ts index 7afae7cf..2c18badd 100644 --- a/libs/core/compass.ts +++ b/libs/core/compass.ts @@ -124,6 +124,7 @@ namespace basic { * @param interval the amount of time (milliseconds) to show the needle. Default is 600. */ //% weight=50 blockGap=8 + //% help=basic/show-compass //% blockId=basic_show_compass //% block="show compass needle for $interval|ms" //% interval.shadow=timePicker diff --git a/libs/core/enums.d.ts b/libs/core/enums.d.ts index d945d5a3..7dbbd022 100644 --- a/libs/core/enums.d.ts +++ b/libs/core/enums.d.ts @@ -41,17 +41,20 @@ declare namespace basic { declare const enum ButtonEvent { //% blockIdentity="input.buttonEventValueId" + //% block="pressed down" + Down = 1, // MICROBIT_BUTTON_EVT_DOWN + //% blockIdentity="input.buttonEventValueId" + //% block="released up" + Up = 2, // MICROBIT_BUTTON_EVT_UP + //% blockIdentity="input.buttonEventValueId" //% block="clicked" Click = 3, // MICROBIT_BUTTON_EVT_CLICK //% blockIdentity="input.buttonEventValueId" //% block="long clicked" LongClick = 4, // MICROBIT_BUTTON_EVT_LONG_CLICK //% blockIdentity="input.buttonEventValueId" - //% block="pressed down" - Down = 1, // MICROBIT_BUTTON_EVT_DOWN - //% blockIdentity="input.buttonEventValueId" - //% block="released up" - Up = 2, // MICROBIT_BUTTON_EVT_UP + //% block="hold" + Hold = 5, // MICROBIT_BUTTON_EVT_HOLD } diff --git a/libs/core/input.cpp b/libs/core/input.cpp index d1b41273..71d65462 100644 --- a/libs/core/input.cpp +++ b/libs/core/input.cpp @@ -8,6 +8,12 @@ enum class Button { }; enum class ButtonEvent { + //% blockIdentity="input.buttonEventValueId" + //% block="pressed down" + Down = MICROBIT_BUTTON_EVT_DOWN, + //% blockIdentity="input.buttonEventValueId" + //% block="released up" + Up = MICROBIT_BUTTON_EVT_UP, //% blockIdentity="input.buttonEventValueId" //% block="clicked" Click = MICROBIT_BUTTON_EVT_CLICK, @@ -15,11 +21,8 @@ enum class ButtonEvent { //% block="long clicked" LongClick = MICROBIT_BUTTON_EVT_LONG_CLICK, //% blockIdentity="input.buttonEventValueId" - //% block="pressed down" - Down = MICROBIT_BUTTON_EVT_DOWN, - //% blockIdentity="input.buttonEventValueId" - //% block="released up" - Up = MICROBIT_BUTTON_EVT_UP, + //% block="hold" + Hold = MICROBIT_BUTTON_EVT_HOLD, }; enum class Dimension { @@ -176,6 +179,8 @@ enum class MesDpadButtonInfo { //% color=#B4009E weight=99 icon="\uf192" namespace input { + + /** * Do something when a button (A, B or both A+B) receives an event. * @param button the button @@ -183,7 +188,8 @@ namespace input { * @param eventType event Type */ //% help=input/on-button-event weight=100 blockGap=16 - //% blockId=device_button_selected_event block="on button %NAME| %eventType=control_button_event_value_id" + //% blockId=device_button_selected_event block="on button %NAME| %eventType" + //% eventType.shadow="control_button_event_click" //% parts="buttonpair" //% group="Events" void onButtonEvent(Button button, int eventType, Action body) { @@ -231,7 +237,8 @@ namespace input { * @param body the code to run when event is fired on pin */ //% help=input/on-pin-event weight=99 blockGap=16 - //% blockId=device_pin_custom_event block="on pin %name| %eventType=control_button_event_value_id" + //% blockId=device_pin_custom_event block="on pin %name| %eventType" + //% eventType.shadow="control_button_event_down" //% group="Events" void onPinTouchEvent(TouchPin name, int eventType, Action body) { auto pin = getPin((int)name); @@ -273,7 +280,7 @@ namespace input { //% deprecated=true //% group="Events" void onButtonPressed(Button button, Action body) { - registerWithDal((int)button, MICROBIT_BUTTON_EVT_CLICK, body); + onButtonEvent(button, MICROBIT_BUTTON_EVT_CLICK, body); } /** @@ -286,12 +293,7 @@ namespace input { //% group="Events" //% deprecated=true void onPinPressed(TouchPin name, Action body) { - auto pin = getPin((int)name); - if (!pin) return; - - // Forces the PIN to switch to makey-makey style detection. - pin->isTouched(); - registerWithDal((int)name, MICROBIT_BUTTON_EVT_CLICK, body); + onPinTouchEvent(name, MICROBIT_BUTTON_EVT_CLICK, body); } /** @@ -305,12 +307,7 @@ namespace input { //% group="Events" //% deprecated=true void onPinReleased(TouchPin name, Action body) { - auto pin = getPin((int)name); - if (!pin) return; - - // Forces the PIN to switch to makey-makey style detection. - pin->isTouched(); - registerWithDal((int)name, MICROBIT_BUTTON_EVT_UP, body); + onPinTouchEvent(name, MICROBIT_BUTTON_EVT_UP, body); } /** @@ -366,6 +363,7 @@ namespace input { /** * gets the level of loudness from 0 (silent) to 255 (loud) */ + //% help=input/sound-level //% blockId="soundLevel" weight=58 //% block="soundLevel" blockGap=8 //% group="Sensors" diff --git a/libs/core/input.ts b/libs/core/input.ts index 4a6186db..d7809594 100644 --- a/libs/core/input.ts +++ b/libs/core/input.ts @@ -4,16 +4,38 @@ //% color=#C90072 weight=99 icon="\uf192" //% groups=['Events', 'States', 'Sensors', 'Configuration', 'System', 'others'] namespace input { + /** - * Returns the value of a C++ runtime constant + * Returns the ID of an Button Event */ - //% weight=1 weight=19 blockId="control_button_event_value_id" block="%id" + //% help=input/button-event + //% weight=19 blockId="control_button_event_value" block="%id" //% shim=TD_ID advanced=true - //% blockHidden=true - export function buttonEventValueId(id: ButtonEvent): number { + //% group="Events" + export function buttonEventValue(id: ButtonEvent): number { return id; } + /** + * Returns the ID of an Click Event + */ + //% blockId="control_button_event_click" block="clicked" + //% advanced=true + //% blockHidden=true + export function buttonEventClick(): number { + return ButtonEvent.Click; + } + + /** + * Returns the ID of an Down Event + */ + //% blockId="control_button_event_down" block="pressed down" + //% advanced=true + //% blockHidden=true + export function buttonEventDown(): number { + return ButtonEvent.Down; + } + /** * Gets the number of milliseconds elapsed since power on. */ diff --git a/libs/core/pxt.json b/libs/core/pxt.json index 1dc9d66a..9628af19 100644 --- a/libs/core/pxt.json +++ b/libs/core/pxt.json @@ -116,17 +116,15 @@ "pairing_mode": 1, "private_addressing": 0, "open": 1, - "partial_flashing": 1, + "partial_flashing": 0, "security_level": null, - "whitelist": 1, + "whitelist": 0, "advertising_timeout": 0, "tx_power": 6, - "dfu_service": 1, - "event_service": 0, - "device_info_service": 0 + "event_service": 0 }, "stack_size": 1280, - "gatt_table_size": "0x200", + "gatt_table_size": "0x300", "panic_on_heap_full": 0, "debug": 0, "heap_debug": 0, @@ -139,8 +137,15 @@ "description": "32K RAM (mini v2 and some v1.3)", "config": { "microbit-dal": { + "bluetooth": { + "pairing_mode": 1, + "partial_flashing": 1, + "dfu_service": 1, + "event_service": 1, + "device_info_service": 1 + }, "stack_size": 2048, - "gatt_table_size": "0x700", + "gatt_table_size": "0x800", "sram_end": "0x20008000", "RAM_SIZE": "\"32K\"" } @@ -150,8 +155,13 @@ "description": "16K RAM (mini v1.3 and below)", "config": { "microbit-dal": { + "bluetooth": { + "pairing_mode": 1, + "partial_flashing": 0, + "event_service": 0 + }, "stack_size": 1280, - "gatt_table_size": "0x200", + "gatt_table_size": "0x300", "sram_end": "0x20004000", "RAM_SIZE": "\"16K\"" } diff --git a/libs/core/shims.d.ts b/libs/core/shims.d.ts index 99eac323..263de3ec 100644 --- a/libs/core/shims.d.ts +++ b/libs/core/shims.d.ts @@ -215,6 +215,7 @@ declare 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" //% @@ -226,6 +227,7 @@ declare 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 shim=basic::turnRgbLedOff @@ -244,7 +246,8 @@ declare namespace input { * @param eventType event Type */ //% help=input/on-button-event weight=100 blockGap=16 - //% blockId=device_button_selected_event block="on button %NAME| %eventType=control_button_event_value_id" + //% blockId=device_button_selected_event block="on button %NAME| %eventType" + //% eventType.shadow="control_button_event_click" //% parts="buttonpair" //% group="Events" shim=input::onButtonEvent function onButtonEvent(button: Button, eventType: int32, body: () => void): void; @@ -278,7 +281,8 @@ declare namespace input { * @param body the code to run when event is fired on pin */ //% help=input/on-pin-event weight=99 blockGap=16 - //% blockId=device_pin_custom_event block="on pin %name| %eventType=control_button_event_value_id" + //% blockId=device_pin_custom_event block="on pin %name| %eventType" + //% eventType.shadow="control_button_event_down" //% group="Events" shim=input::onPinTouchEvent function onPinTouchEvent(name: TouchPin, eventType: int32, body: () => void): void; @@ -361,6 +365,7 @@ declare namespace input { /** * gets the level of loudness from 0 (silent) to 255 (loud) */ + //% help=input/sound-level //% blockId="soundLevel" weight=58 //% block="soundLevel" blockGap=8 //% group="Sensors" shim=input::soundLevel diff --git a/libs/core/storage.ts b/libs/core/storage.ts index a847ecf6..c9292c86 100644 --- a/libs/core/storage.ts +++ b/libs/core/storage.ts @@ -30,6 +30,7 @@ namespace storage { * @param key the key for accesing the value * @param value value to store */ + //% help=storage/put-number //% weight=90 blockGap=16 //% block="Save into number %key a value of %value" //% blockId=storage_put_number @@ -43,6 +44,7 @@ namespace storage { * Reads a key value pair from the non volatile storage as a number * @param key the key for accesing the value */ + //% help=storage/get-number //% weight=70 blockGap=16 //% block="read from number %key" //% blockId=storage_get_number @@ -56,6 +58,7 @@ namespace storage { * Deletes the key from the non volatile storage * @param key the key for accesing the value */ + //% help=storage/remove-number //% weight=50 blockGap=16 //% block="Clear number %key" //% blockId=storage_remove_key_int