From ed8f8bafa720c0b131733f6dd526127caefa4a90 Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Wed, 21 Feb 2018 22:35:51 -0800 Subject: [PATCH] Add 'infrared beacon' api topics (#330) * Add 'infrared beacon' api topics * Include note about channel selection --- docs/SUMMARY.md | 16 ++++-- docs/reference/sensors.md | 10 ++++ .../docs/reference/sensors/beacon.md | 17 ++++++ .../reference/sensors/beacon/is-pressed.md | 44 +++++++++++++++ .../docs/reference/sensors/beacon/on-event.md | 46 ++++++++++++++++ .../reference/sensors/beacon/pause-until.md | 53 +++++++++++++++++++ .../sensors/beacon/set-remote-channel.md | 35 ++++++++++++ .../reference/sensors/beacon/was-pressed.md | 47 ++++++++++++++++ libs/infrared-sensor/ir.ts | 21 ++++---- .../sensors/touch-sensor/on-event.md | 4 +- .../sensors/touch-sensor/pause-until.md | 2 +- .../sensors/touch-sensor/was-pressed.md | 2 +- 12 files changed, 278 insertions(+), 19 deletions(-) create mode 100644 libs/infrared-sensor/docs/reference/sensors/beacon.md create mode 100644 libs/infrared-sensor/docs/reference/sensors/beacon/is-pressed.md create mode 100644 libs/infrared-sensor/docs/reference/sensors/beacon/on-event.md create mode 100644 libs/infrared-sensor/docs/reference/sensors/beacon/pause-until.md create mode 100644 libs/infrared-sensor/docs/reference/sensors/beacon/set-remote-channel.md create mode 100644 libs/infrared-sensor/docs/reference/sensors/beacon/was-pressed.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 39197377..645a9292 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -91,17 +91,23 @@ * [rate](/reference/sensors/gyro/rate) * [reset](/reference/sensors/gyro/reset) * [Ultrasonic](/reference/sensors/ultrasonic) - * [on event](/reference/sensors/ultrasonic/on-event), - * [distance](reference/sensors/ultrasonic/distance), + * [on event](/reference/sensors/ultrasonic/on-event) + * [distance](reference/sensors/ultrasonic/distance) * [pause until](reference/sensors/ultrasonic/pause-until) * [Infrared](/reference/sensors/infrared) - * [on event](/reference/sensors/infrared/on-event), - * [distance](reference/sensors/infrared/proximity), + * [on event](/reference/sensors/infrared/on-event) + * [distance](reference/sensors/infrared/proximity) * [pause until](reference/sensors/infrared/pause-until) + * [Infrared beacon](/reference/sensors/beacon) + * [on event](/reference/sensors/beacon/on-event) + * [pause until](/reference/sensors/beacon/pause-until) + * [is pressed](/reference/sensors/beacon/is-pressed) + * [was pressed](/reference/sensors/beacon/was-pressed) + * [set remote channel](/reference/sensors/beacon/set-remote-channel) * [Color](/reference/sensors/color-sensor) * [on color detected](/reference/sensors/color-sensor/on-color-detected) * [pause for color](/reference/sensors/color-sensor/pause-for-color) * [on light changed](/reference/sensors/color-sensor/on-light-changed) * [pause for light](/reference/sensors/color-sensor/pause-for-light) * [color](/reference/sensors/color-sensor/color) - * [light](/reference/sensors/color-sensor/ambient-light) \ No newline at end of file + * [light](/reference/sensors/color-sensor/ambient-light) diff --git a/docs/reference/sensors.md b/docs/reference/sensors.md index cba0e8d2..8dd183be 100644 --- a/docs/reference/sensors.md +++ b/docs/reference/sensors.md @@ -45,3 +45,13 @@ sensors.infraredSensor1.pauseUntil(null); sensors.infraredSensor1.proximity(); ``` + +## Infrared beacon button + +```cards +sensors.remoteButtonCenter.onEvent(ButtonEvent.Pressed, function () {}) +sensors.remoteButtonCenter.pauseUntil(ButtonEvent.Pressed); +sensors.remoteButtonCenter.isPressed() +sensors.remoteButtonCenter.wasPressed() +sensors.infraredSensor1.setRemoteChannel(null) +``` diff --git a/libs/infrared-sensor/docs/reference/sensors/beacon.md b/libs/infrared-sensor/docs/reference/sensors/beacon.md new file mode 100644 index 00000000..20a3a95f --- /dev/null +++ b/libs/infrared-sensor/docs/reference/sensors/beacon.md @@ -0,0 +1,17 @@ +# Infrared beacon + +```cards +sensors.remoteButtonCenter.onEvent(ButtonEvent.Pressed, function () {}) +sensors.remoteButtonCenter.pauseUntil(ButtonEvent.Pressed); +sensors.remoteButtonCenter.isPressed() +sensors.remoteButtonCenter.wasPressed() +sensors.infraredSensor1.setRemoteChannel(null) +``` + +## See also + +[on event](/reference/sensors/beacon/on-event), +[pause until](/reference/sensors/beacon/pause-until), +[is pressed](/reference/sensors/beacon/is-pressed) +[was pressed](/reference/sensors/beacon/was-pressed) +[set remote channel](/reference/sensors/beacon/set-remote-channel) diff --git a/libs/infrared-sensor/docs/reference/sensors/beacon/is-pressed.md b/libs/infrared-sensor/docs/reference/sensors/beacon/is-pressed.md new file mode 100644 index 00000000..61cde0de --- /dev/null +++ b/libs/infrared-sensor/docs/reference/sensors/beacon/is-pressed.md @@ -0,0 +1,44 @@ +# is Pressed + +Check to see if a remote beacon button is currently pressed or not. + +```sig +sensors.remoteButtonBottomLeft.isPressed() +``` + +An [infrared beacon][lego beacon] works with an infrared sensor connected to the @boardname@. The beacon sends a signal over infrared with information about button presses on the beacon. The infrared sensor receives the signal from the beacon and records a button event. + +## Returns + +* a [boolean](/types/boolean) value that is `true` if the beacon button is currently pressed. It's `false` if the button is not pressed. + +## ~hint + +**Remote channel** + +In order to recognize a button event signalled from a remote beacon, an infrared sensor must know what channel to listen on for messages from that beacon. An infrared sensor needs to set the channel first, then it can receive messages transmitted by the beacon. Before waiting for, or checking on an button event from a beacon, use [set remote channel](/reference/sensors/beacon/set-remote-channel). + +## ~ + +## Example + +If the beacon button ``center`` is pressed, show a `green` status light. Otherwise, set the status light to `orange`. + +```blocks +sensors.infraredSensor1.setRemoteChannel(InfraredRemoteChannel.Ch0) +forever(function () { + if (sensors.remoteButtonCenter.isPressed()) { + brick.setStatusLight(StatusLight.Green) + } else { + brick.setStatusLight(StatusLight.Orange) + } +}) +``` + +## See also + +[was pressed](/reference/sensors/beacon/was-pressed), [on event](/reference/sensors/beacon/on-event) + +[EV3 Infrared Beacon][lego beacon] + +[lego beacon]: https://education.lego.com/en-us/products/ev3-infrared-beacon/45508 \ No newline at end of file diff --git a/libs/infrared-sensor/docs/reference/sensors/beacon/on-event.md b/libs/infrared-sensor/docs/reference/sensors/beacon/on-event.md new file mode 100644 index 00000000..cac6ab00 --- /dev/null +++ b/libs/infrared-sensor/docs/reference/sensors/beacon/on-event.md @@ -0,0 +1,46 @@ +# on Event + +Run some code when a remote beacon button is pressed, bumped, or released. + +```sig +sensors.remoteButtonBottomLeft.onEvent(ButtonEvent.Bumped, function () {}); +``` + +An [infrared beacon][lego beacon] works with an infrared sensor connected to the @boardname@. The beacon sends a signal over infrared with information about button presses on the beacon. The infrared sensor receives the signal from the beacon and records a button event. + +## Parameters + +* **ev**: the beacon button action to run some code for. The button actions (events) are: +> * ``pressed``: the button was pressed, or pressed and released +> * ``bumped``: the button was just bumped +> * ``released``: the button was just released +* **body**: the code you want to run when something happens to the beacon button. + +## ~hint + +**Remote channel** + +In order to recognize a button event signalled from a remote beacon, an infrared sensor must know what channel to listen on for messages from that beacon. An infrared sensor needs to set the channel first, then it can receive messages transmitted by the beacon. Before waiting for, or checking on an button event from a beacon, use [set remote channel](/reference/sensors/beacon/set-remote-channel). + +## ~ + +## Example + +Check for an event on beacon button sensor ``center``. Put an expression on the screen when the button is released. + +```blocks +sensors.infraredSensor1.setRemoteChannel(InfraredRemoteChannel.Ch0) +sensors.remoteButtonCenter.onEvent(ButtonEvent.Released, function () { + brick.showImage(images.expressionsSick) +}) +``` + +### See also + +[is pressed](/reference/sensors/beacon/is-pressed), +[was pressed](/reference/sensors/beacon/was-pressed), +[pause until](/reference/sensors/beacon/pause-until) + +[EV3 Infrared Beacon][lego beacon] + +[lego beacon]: https://education.lego.com/en-us/products/ev3-infrared-beacon/45508 \ No newline at end of file diff --git a/libs/infrared-sensor/docs/reference/sensors/beacon/pause-until.md b/libs/infrared-sensor/docs/reference/sensors/beacon/pause-until.md new file mode 100644 index 00000000..422e82fc --- /dev/null +++ b/libs/infrared-sensor/docs/reference/sensors/beacon/pause-until.md @@ -0,0 +1,53 @@ +# pause Until + +Make your program wait until a button event from a remote beacon happens. + +```sig +sensors.remoteButtonBottomLeft.pauseUntil(ButtonEvent.Bumped); +``` + +An [infrared beacon][lego beacon] works with an infrared sensor connected to the @boardname@. The beacon sends a signal over infrared with information about button presses on the beacon. The infrared sensor receives the signal from the beacon and records a button event. + +## Parameters + +* **ev**: the beacon button action to wait for. The button actions (events) are: +> * ``pressed``: the button was pressed, or pressed and released +> * ``bumped``: the button was just bumped +> * ``released``: the button was just released + +## ~hint + +**Remote channel** + +In order to recognize a button event signalled from a remote beacon, an infrared sensor must know what channel to listen on for messages from that beacon. An infrared sensor needs to set the channel first, then it can receive messages transmitted by the beacon. Before waiting for, or checking on an button event from a beacon, use [set remote channel](/reference/sensors/beacon/set-remote-channel). + +## ~ + +## Example + +Wait for a bump to beacon button `center` before continuing with displaying a message on the screen. + +```blocks +let waitTime = 0; +brick.clearScreen(); +brick.showString("We're going to wait", 1); +brick.showString("for you to bump the", 2); +brick.showString("touch sensor on port 1", 3); +waitTime = control.millis(); +sensors.infraredSensor1.setRemoteChannel(InfraredRemoteChannel.Ch0) +sensors.remoteButtonCenter.pauseUntil(ButtonEvent.Bumped); +brick.clearScreen(); +if (control.millis() - waitTime > 5000) { + brick.showString("Ok, that took awhile!", 1); +} else { + brick.showString("Ah, you let go!", 1); +} +``` + +## See also + +[on event](/reference/sensors/beacon/on-event) + +[EV3 Infrared Beacon][lego beacon] + +[lego beacon]: https://education.lego.com/en-us/products/ev3-infrared-beacon/45508 \ No newline at end of file diff --git a/libs/infrared-sensor/docs/reference/sensors/beacon/set-remote-channel.md b/libs/infrared-sensor/docs/reference/sensors/beacon/set-remote-channel.md new file mode 100644 index 00000000..0a2f1e2c --- /dev/null +++ b/libs/infrared-sensor/docs/reference/sensors/beacon/set-remote-channel.md @@ -0,0 +1,35 @@ +# set Remote Channel + +Set the remote infrared signal channel for an infrared sensor. + +```sig +sensors.infraredSensor1.setRemoteChannel(InfraredRemoteChannel.Ch0) +``` +An infrared sensor connected to the @boardname@ can receive messages (signals for button events) from a remote infrared beacon. In order for the sensor to know which beacon to receive messages from, a _channel_ is used. The beacon has a switch on it to select a particular channel to transmit on. The sensor needs to know which channel to receive ("listen" for) messages from the beacon. + +A sensor is not automatically set to listen for infrared messages on a channel. To avoid confusion on which sensor receives signals from a beacon, each sensor (if you have more than one), sets a remote channel for itself. The channel number matches the channel selected on the beacon. + +## Parameters + +* **channel**: the channel for the infrared sensor to "listen" on. You can choose to use one of 4 channels: ``0``, ``1``, ``2``, and ``3``. + +## Example + +Select channel **2** on an infrared beacon. Set the remote channel for infrared sensor ``infrared 3`` to channel ``2``. Wait for the ``center`` button press on the beacon using channel ``2``. + +```blocks +sensors.infraredSensor3.setRemoteChannel(InfraredRemoteChannel.Ch2); +sensors.remoteButtonCenter.pauseUntil(ButtonEvent.Pressed); +brick.clearScreen(); +brick.showString("Center button on", 1); +brick.showString("channel 2 beacon", 2); +brick.showString("was pressed.", 3); +``` + +## See also + +[was pressed](/reference/sensors/beacon/was-pressed), [on event](/reference/sensors/beacon/on-event) + +[EV3 Infrared Beacon][lego beacon] + +[lego beacon]: https://education.lego.com/en-us/products/ev3-infrared-beacon/45508 \ No newline at end of file diff --git a/libs/infrared-sensor/docs/reference/sensors/beacon/was-pressed.md b/libs/infrared-sensor/docs/reference/sensors/beacon/was-pressed.md new file mode 100644 index 00000000..425404c2 --- /dev/null +++ b/libs/infrared-sensor/docs/reference/sensors/beacon/was-pressed.md @@ -0,0 +1,47 @@ +# was Pressed + +See if a button on a remote infrared beacon was pressed since the last time it was checked. + +```sig +sensors.remoteButtonBottomLeft.wasPressed() +``` + +An [infrared beacon][lego beacon] works with an infrared sensor connected to the @boardname@. The beacon sends a signal over infrared with information about button presses on the beacon. The infrared sensor receives the signal from the beacon and records a button event. + +If a button was pressed, then that event is remembered. Once you check if a beacon button **was pressed**, that status is set back to `false`. If you check again before the beacon button is pressed another time, the **was pressed** status is `false`. Only when the button is pressed will the **was pressed** status go to `true`. + +## Returns + +* a [boolean](/types/boolean) value that is `true` if the beacon button was pressed before. It's `false` if the button was not pressed. + +## ~hint + +**Remote channel** + +In order to recognize a button event signalled from a remote beacon, an infrared sensor must know what channel to listen on for messages from that beacon. An infrared sensor needs to set the channel first, then it can receive messages transmitted by the beacon. Before waiting for, or checking on an button event from a beacon, use [set remote channel](/reference/sensors/beacon/set-remote-channel). + +## ~ + +## Example + +If the beacon button ``top left`` was pressed, show a `green` status light. Otherwise, set the status light to `orange`. + +```blocks +sensors.infraredSensor1.setRemoteChannel(InfraredRemoteChannel.Ch0) +forever(function () { + if (sensors.remoteButtonTopLeft.wasPressed()) { + brick.setStatusLight(StatusLight.Green) + } else { + brick.setStatusLight(StatusLight.Orange) + } + pause(500) +}) +``` + +## See also + +[is pressed](/reference/sensors/beacon/is-pressed), [on event](/reference/sensors/beacon/on-event) + +[EV3 Infrared Beacon][lego beacon] + +[lego beacon]: https://education.lego.com/en-us/products/ev3-infrared-beacon/45508 \ No newline at end of file diff --git a/libs/infrared-sensor/ir.ts b/libs/infrared-sensor/ir.ts index 42ba9251..9112afe8 100644 --- a/libs/infrared-sensor/ir.ts +++ b/libs/infrared-sensor/ir.ts @@ -83,7 +83,7 @@ namespace sensors { * Check if a remote button is currently pressed or not. * @param button the remote button to query the request */ - //% help=input/remote-infrared-beacon/is-pressed + //% help=sensors/beacon/is-pressed //% block="%button|is pressed" //% blockId=remoteButtonIsPressed //% parts="remote" @@ -98,7 +98,7 @@ namespace sensors { * See if the remote button was pressed again since the last time you checked. * @param button the remote button to query the request */ - //% help=input/remote-infrared-beacon/was-pressed + //% help=sensors/beacon/was-pressed //% block="%button|was pressed" //% blockId=remotebuttonWasPressed //% parts="remote" @@ -110,12 +110,12 @@ namespace sensors { } /** - * Do something when a button or sensor is clicked, up or down + * Do something when a remote button is pressed, bumped, or released * @param button the button that needs to be clicked or used * @param event the kind of button gesture that needs to be detected * @param body code to run when the event is raised */ - //% help=input/remote-infrared-beacon/on-event + //% help=sensors/beacon/on-event //% blockId=remotebuttonEvent block="on %button|%event" //% parts="remote" //% blockNamespace=sensors @@ -126,10 +126,10 @@ namespace sensors { } /** - * Pauses until the given event is raised + * Pause until a remote button event happens * @param ev the event to wait for */ - //% help=input/remote-infrared-beacon/pause-until + //% help=sensors/beacon/pause-until //% blockId=remoteButtonPauseUntil block="pause until %button|%event" //% parts="remote" //% blockNamespace=sensors @@ -181,7 +181,7 @@ namespace sensors { } /** - * Registers code to run when an object is getting near. + * Register code to run when an object is getting near. * @param handler the code to run when detected */ //% help=sensors/infrared/on-event @@ -197,7 +197,7 @@ namespace sensors { } /** - * Waits for the event to occur + * Wait until the infrared sensor detects something */ //% help=sensors/infrared/pause-until //% block="pause until %sensor| %event" @@ -228,13 +228,14 @@ namespace sensors { } /** - * Sets the remote channel to listen from + * Set the remote channel to listen to * @param channel the channel to listen */ //% blockNamespace=sensors //% blockId=irSetRemoteChannel block="set %sensor|remote channel to %channel" //% weight=99 //% group="Remote Infrared Beacon" + //% help=sensors/beacon/set-remote-channel setRemoteChannel(channel: InfraredRemoteChannel) { this.setMode(InfraredSensorMode.RemoteControl) channel = Math.clamp(0, 3, channel | 0) @@ -257,7 +258,7 @@ namespace sensors { } /** - * Gets the threshold value + * Get a threshold value * @param condition the proximity condition */ //% blockId=irGetThreshold block="%sensor|%condition" diff --git a/libs/touch-sensor/docs/reference/sensors/touch-sensor/on-event.md b/libs/touch-sensor/docs/reference/sensors/touch-sensor/on-event.md index 15db5a3e..9846fe15 100644 --- a/libs/touch-sensor/docs/reference/sensors/touch-sensor/on-event.md +++ b/libs/touch-sensor/docs/reference/sensors/touch-sensor/on-event.md @@ -10,7 +10,7 @@ sensors.touch1.onEvent(ButtonEvent.Bumped, function () { ## Parameters -* **ev**: the touch sensor action to run some code for. The the touch actions (events) are: +* **ev**: the touch sensor action to run some code for. The touch actions (events) are: > * ``pressed``: the sensor was pressed, or pressed and released > * ``bumped``: the sensor was just bumped > * ``released``: the sensor was just released @@ -18,7 +18,7 @@ sensors.touch1.onEvent(ButtonEvent.Bumped, function () { ## Example -Check for an event on touch sensor ``touch 1``. Put an expression on the screen when the senosr is released. +Check for an event on touch sensor ``touch 1``. Put an expression on the screen when the sensor is released. ```blocks sensors.touch1.onEvent(ButtonEvent.Released, function () { diff --git a/libs/touch-sensor/docs/reference/sensors/touch-sensor/pause-until.md b/libs/touch-sensor/docs/reference/sensors/touch-sensor/pause-until.md index 22b99b9d..3141e620 100644 --- a/libs/touch-sensor/docs/reference/sensors/touch-sensor/pause-until.md +++ b/libs/touch-sensor/docs/reference/sensors/touch-sensor/pause-until.md @@ -8,7 +8,7 @@ sensors.touch1.pauseUntil(ButtonEvent.Bumped); ## Parameters -* **ev**: the touch sensor action to wait for. The the touch actions (events) are: +* **ev**: the touch sensor action to wait for. The touch actions (events) are: > * ``pressed``: the sensor was pressed, or pressed and released > * ``bumped``: the sensor was just bumped > * ``released``: the sensor was just released diff --git a/libs/touch-sensor/docs/reference/sensors/touch-sensor/was-pressed.md b/libs/touch-sensor/docs/reference/sensors/touch-sensor/was-pressed.md index 7942f34d..305b2d3e 100644 --- a/libs/touch-sensor/docs/reference/sensors/touch-sensor/was-pressed.md +++ b/libs/touch-sensor/docs/reference/sensors/touch-sensor/was-pressed.md @@ -10,7 +10,7 @@ If a touch sensor was pressed, then that event is remembered. Once you check if ## Returns -* a [boolean](/types/boolean) value that is `true` if the sensor is was pressed before. It's `false` if the sensor was not pressed. +* a [boolean](/types/boolean) value that is `true` if the sensor was pressed before. It's `false` if the sensor was not pressed. ## Example