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

Update 'radio' docs for v1 (#937)

Browse Source
This commit is contained in:
Galen Nickel
2018-07-09 11:17:32 -07:00
committed by GitHub
parent 5d6481a4e8
commit f5c44a3d4b
11 changed files with 223 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/reference/radio/get-received-packet-property.md Normal file
View File

@@ -0,0 +1,39 @@
# get Received Packet Property
Get one of the properties from the last received radio packet.
```sig
radio.getReceivedPacketProperty(radio.PacketProperty.SignalStrength)
```
## Parameters
* **type**: the property type to get from the packet. These are:
>* ``signal strength``: the strength of the radio signal when the packet was received.
>* ``serial number``: the serial number of the board sending the packet.
>* ``time``: the time when the packet was sent.
## Returns
* a [number](/types/number) that is the property selected in the **type** parameter.
## Example
This program uses the signal strength from received packets to graph the
approximate distance between two @boardname@s.
```blocks
basic.forever(() => {
radio.sendNumber(0)
})
radio.onReceivedNumber(function (receivedNumber) {
led.plotBarGraph(
Math.abs(radio.getReceivedPacketProperty(radio.PacketProperty.SignalStrength) + 42),
128 - 42
)
})
```
## See also
[set transmit serial number](/reference/radio/set-transmit-serial-number)

65
docs/reference/radio/on-received-number.md Normal file
View File

@@ -0,0 +1,65 @@
# on Received Number
Run part of a program when the @boardname@ receives a
[number](/types/number) over ``radio``.
```sig
radio.onReceivedNumber(function (receivedNumber) {})
```
## Parameters
* **receivedNumber**: The [number](/types/number) that was sent in this packet or `0` if this packet did not contain a number. See [send number](/reference/radio/send-number) and [send value](/reference/radio/send-value)
## Examples
### Tell me how fast
This program keeps sending numbers that say how fast the @boardname@ is
slowing down or speeding up. It also receives numbers for the same
thing from nearby @boardname@s. It shows these numbers as a
[bar graph](/reference/led/plot-bar-graph).
```blocks
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X));
})
radio.onReceivedNumber(function (receivedNumber) {
led.plotBarGraph(receivedNumber, 1023);
})
```
### What's the distance?
This program uses the signal strength from received packets to graph the
approximate distance between two @boardname@s.
```blocks
basic.forever(() => {
radio.sendNumber(0)
})
radio.onReceivedNumber(function (receivedNumber) {
led.plotBarGraph(
Math.abs(radio.getReceivedPacketProperty(radio.PacketProperty.SignalStrength) + 42),
128 - 42
)
})
```
## Troubleshooting
The ``||radio:onReceivedNumber||`` event can only be created once, due to the hardware restrictions.
The radio set group might need to be set, synchronized , before the radio events will function.
## See also
[on received strig](/reference/radio/on-received-string),
[send number](/reference/radio/send-number),
[send string](/reference/radio/send-string),
[send value](/reference/radio/send-value),
[set group](/reference/radio/set-group)
```package
radio
```

42
docs/reference/radio/on-received-string.md Normal file
View File

@@ -0,0 +1,42 @@
# on Received String
Run part of a program when the @boardname@ receives a [string](/types/string) over ``radio``.
```sig
radio.onReceivedString(function (receivedString) {})
```
## Parameters
* **receivedString**: The [string](/types/string) that was sent in this packet or the empty string if this packet did not contain a string. See [send string](/reference/radio/send-string) and [send value](/reference/radio/send-value)
## Example
This program continuously sends a cheerful message. It also receives a messages from nearby @boardname@s. It shows these messages on the screen.
```blocks
basic.forever(() => {
radio.sendString("I'm happy");
})
radio.onReceivedString(function (receivedString) {
basic.showString(receivedString)
})
```
## Troubleshooting
The ``||radio:on received string||`` event can only be created once, due to the hardware restrictions.
The radio set group might need to be set, synchronized , before the radio events will function.
## See also
[on received number](/reference/radio/on-received-number),
[send number](/reference/radio/send-number),
[send string](/reference/radio/send-string),
[send value](/reference/radio/send-value),
[set group](/reference/radio/set-group)
```package
radio
```

48
docs/reference/radio/on-received-value.md Normal file
View File

@@ -0,0 +1,48 @@
# on Received Value
Run part of a program when the @boardname@ receives a name-value-pair over ``radio``.
```sig
radio.onReceivedValue(function (name, value) {})
```
## Parameters
* **name**: a [string](/types/string) that is a name for the value received.
* **value**: a [number](/types/number) that is the value received.
## Example
This program keeps sending numbers that say how fast the @boardname@ is
slowing down or speeding up. When it receives numbers for the same
thing from nearby @boardname@s, show the numbers as a
[bar graph](/reference/led/plot-bar-graph).
```blocks
basic.forever(() => {
radio.sendValue("accel-x", input.acceleration(Dimension.X))
})
radio.onReceivedValue(function (name, value) {
if (name == "accel-x") {
led.plotBarGraph(value, 1023);
}
})
```
## Troubleshooting
The ``||radio:on received value||`` event can only be created once, due to the hardware restrictions.
The radio set group might need to be set, synchronized , before the radio events will function.
## See also
[on received number](/reference/radio/on-received-number),
[send number](/reference/radio/send-number),
[send string](/reference/radio/send-string),
[send value](/reference/radio/send-value),
[set group](/reference/radio/set-group)
```package
radio
```

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

@@ -1,4 +1,4 @@
# Send Number
# send Number
Broadcast a [number](/types/number) to other @boardname@s connected via ``radio``.
@@ -8,7 +8,7 @@ radio.sendNumber(0);
## Parameters
* ``value`` - a [number](/types/number) to send.
* **value**: a [number](/types/number) to send.
## Example: Broadcasting acceleration
@@ -27,7 +27,7 @@ input.onButtonPressed(Button.A, () => {
This example broadcasts the level of the light around it.
You can do some interesting things with it if you use it along with the
[on data packet received](/reference/radio/on-data-packet-received) example.
[on received number](/reference/radio/on-received-number) example.
```blocks
radio.setGroup(99)
@@ -39,7 +39,7 @@ basic.forever(() => {
## See also
[on data packet received](/reference/radio/on-data-packet-received)
[on received number](/reference/radio/on-received-number)
```package
radio

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

@@ -1,4 +1,4 @@
# Send String
# send String
Sends a string to other @boardname@s in the area connected by radio. The
maximum string length is 19 characters.
@@ -23,10 +23,9 @@ input.onButtonPressed(Button.A, () => {
radio.sendString("Codeword: TRIMARAN")
basic.showString("SENT");
})
radio.onDataPacketReceived(({ receivedString }) => {
radio.onReceivedString(function (receivedString) {
basic.showString(receivedString);
});
})
```
## ~hint
@@ -37,7 +36,7 @@ A radio that can both transmit and receive is called a _transceiver_.
## See also
[on data packet received](/reference/radio/on-data-packet-received)
[on received string](/reference/radio/on-received-string)
```package
radio

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

@@ -1,4 +1,4 @@
# Send Value
# send Value
Send a [string]() and [number]() together by ``radio`` to other @boardname@s.
The maximum [string]() length is 12 characters.
@@ -31,15 +31,16 @@ Then it shows them on the LED screen.
```blocks
radio.setGroup(99)
radio.onDataPacketReceived(({ receivedString, receivedNumber }) => {
basic.showString(receivedString);
basic.showNumber(receivedNumber);
radio.onReceivedValue(function (name, value) {
radio.onDataPacketReceived(({ name, value }) => {
basic.showString(name);
basic.showNumber(value);
});
```
## See also
[on data packet received](/reference/radio/on-data-packet-received)
[on received value](/reference/radio/on-received-value)
```package
radio

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

@@ -1,4 +1,4 @@
# Set Group
# set Group
Make a program have the group ID you tell it for sending and receiving
with ``radio``. A group is like a cable channel (a @boardname@ can only
@@ -16,7 +16,7 @@ radio.setGroup(0);
## Parameters
* ``id`` is a [number](/types/number) from ``0`` to ``255``.
* **id**: a [number](/types/number) from ``0`` to ``255``.
## Simulator
@@ -32,7 +32,9 @@ radio.setGroup(128)
## See also
[on data packet received](/reference/radio/on-data-packet-received),
[on received number](/reference/radio/on-received-number),
[on received string](/reference/radio/on-received-string),
[on received value](/reference/radio/on-received-value),
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[send string](/reference/radio/send-string)

10
docs/reference/radio/set-transmit-power.md
View File

@@ -1,7 +1,6 @@
# Set Transmit Power
# set Transmit Power
Make the ``radio`` signal of the @boardname@ stronger or weaker.
It can be as weak as `0` and as strong as `7`.
Make the ``radio`` signal of the @boardname@ stronger or weaker. It can be as weak as `0` and as strong as `7`.
The scientific name for the strength of the ``radio`` signal is
**dBm**, or **decibel-milliwatts**. A signal strength of `0`
@@ -20,8 +19,7 @@ can reach as far as 70 meters (about 230 feet).
## Parameters
* ``power`` is a [number](/types/number) between ``0`` and ``7`` that
means how strong the signal is.
* ``power`` is a [number](/types/number) between ``0`` and ``7`` that means how strong the signal is.
## Simulator
@@ -37,7 +35,7 @@ radio.setTransmitPower(7)
## See also
[on data packet received](/reference/radio/on-data-packet-received),
[get received packet property](/reference/radio/get-received-packet-property),
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[send string](/reference/radio/send-string)

4
docs/reference/radio/set-transmit-serial-number.md
View File

@@ -1,4 +1,4 @@
# Set Transmit Serial Number
# set Transmit Serial Number
Make the ``radio`` packet embed the board serial number with each packet of data.
@@ -20,7 +20,7 @@ radio.setTransmitSerialNumber(true);
## See also
[on data packet received](/reference/radio/on-data-packet-received),
[get received packet property](/reference/radio/get-received-packet-property),
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[send string](/reference/radio/send-string)

8
libs/radio/radio.ts
View File

@@ -72,7 +72,7 @@ namespace radio {
/**
* Registers code to run when the radio receives a number.
*/
//% help=radio/on-radio-received-number blockHandlerKey="radioreceived"
//% help=radio/on-received-number blockHandlerKey="radioreceived"
//% blockId=radio_on_number block="on radio received" blockGap=8
export function onReceivedNumber(cb: (receivedNumber: number) => void) {
onDataReceived(() => {
@@ -90,7 +90,7 @@ namespace radio {
/**
* Registers code to run when the radio receives a key value pair.
*/
//% help=radio/on-radio-received-value blockHandlerKey="radioreceived"
//% help=radio/on-received-value blockHandlerKey="radioreceived"
//% blockId=radio_on_value block="on radio received" blockGap=8
export function onReceivedValue(cb: (name: string, value: number) => void) {
onDataReceived(() => {
@@ -109,7 +109,7 @@ namespace radio {
/**
* Registers code to run when the radio receives a string.
*/
//% help=radio/on-radio-received-string blockHandlerKey="radioreceived"
//% help=radio/on-received-string blockHandlerKey="radioreceived"
//% blockId=radio_on_string block="on radio received" blockGap=8
export function onReceivedString(cb: (receivedString: string) => void) {
onDataReceived(() => {
@@ -127,7 +127,7 @@ namespace radio {
/**
* Registers code to run when the radio receives a buffer.
*/
//% help=radio/on-radio-received-buffer blockHandlerKey="radioreceived" blockHidden=1
//% help=radio/on-received-buffer blockHandlerKey="radioreceived" blockHidden=1
//% blockId=radio_on_buffer block="on radio received" blockGap=8
export function onReceivedBuffer(cb: (buffer: Buffer) => void) {
onDataReceived(() => {