Add 'infrared beacon' api topics (#330)
* Add 'infrared beacon' api topics * Include note about channel selection
This commit is contained in:
Galen Nickel
committed by
Peli de Halleux
Peli de Halleux
parent
8cfb70c97b
commit
ed8f8bafa7
17
libs/infrared-sensor/docs/reference/sensors/beacon.md
Normal file
17
libs/infrared-sensor/docs/reference/sensors/beacon.md
Normal file
@ -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)
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
Reference in New Issue
Block a user