diff --git a/docs/reference/radio.md b/docs/reference/radio.md index 6289f3fb..f0965a67 100644 --- a/docs/reference/radio.md +++ b/docs/reference/radio.md @@ -1,6 +1,6 @@ # Radio -Communicate data using radio packets +Send and receive data using radio packets. ```cards radio.sendNumber(0); @@ -9,11 +9,16 @@ radio.sendString(""); radio.onReceivedNumber(function (receivedNumber) { }); radio.onReceivedValue(function (name, value) { }); radio.onReceivedString(function (receivedString) { }); +radio.receivedPacket(RadioPacketProperty.SignalStrength) radio.setGroup(0); +``` + +## Advanced + +```cards +radio.writeReceivedPacketToSerial(); radio.setTransmitPower(7); radio.setTransmitSerialNumber(false); -radio.writeReceivedPacketToSerial(); -radio.sendBuffer(null); radio.raiseEvent(0, 0); ``` @@ -23,15 +28,15 @@ radio ## See Also -[sendNumber](/reference/radio/send-number), -[sendValue](/reference/radio/send-value), -[sendString](/reference/radio/send-string), -[sendBuffer](/reference/radio/send-buffer), -[onReceivedNumber](/reference/radio/on-received-number), -[onReceivedValue](/reference/radio/on-received-value), -[onReceivedString](/reference/radio/on-received-string), -[setGroup](/reference/radio/set-group), -[setTransmitPower](/reference/radio/set-transmit-power), -[setTransmitSerialNumber](/reference/radio/set-transmit-serial-number), -[writeReceivedPacketToSerial](/reference/radio/write-received-packet-to-serial), -[raiseEvent](/reference/radio/raise-event) +[send number](/reference/radio/send-number), +[send value](/reference/radio/send-value), +[send string](/reference/radio/send-string), +[on received number](/reference/radio/on-received-number), +[on received value](/reference/radio/on-received-value), +[on received string](/reference/radio/on-received-string), +[received packet](/reference/radio/received-packet), +[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-data-packet-received.md b/docs/reference/radio/on-data-packet-received.md index 7996f113..c7b0ab58 100644 --- a/docs/reference/radio/on-data-packet-received.md +++ b/docs/reference/radio/on-data-packet-received.md @@ -1,13 +1,24 @@ # On Data Packet Received Run part of a program when the @boardname@ receives a -[number](/types/number) or [string](/types/string) over ``radio``. - +[number](/types/number) or [string](/types/string) over radio. ```sig radio.onDataPacketReceived(({receivedNumber, receivedString, time, serial, signal}) => { }); ``` +## ~ hint + +**Deprecated** + +This API has been deprecated! + +* To receive a [string](/types/string) use [on received string](/reference/radio/on-received-string) instead. +* To receive a [number](/types/number) use [on received number](/reference/radio/on-received-number) instead. +* To receive a name-value pair use [on received value](/reference/radio/on-received-value) instead. + +## ~ + ## ~hint To add or remove the parts of the packet from the block, try clicking the blue gear in the corner! diff --git a/docs/reference/radio/on-data-received.md b/docs/reference/radio/on-data-received.md index 7c2c2c07..ad18a561 100644 --- a/docs/reference/radio/on-data-received.md +++ b/docs/reference/radio/on-data-received.md @@ -1,10 +1,19 @@ -# On Data Received - -> Note: This API has been deprecated! Use [on received number](/reference/radio/on-received-number) instead. +# on Data Received Run part of a program when the @boardname@ receives a -[number](/types/number) or [string](/types/string) over ``radio``. +[number](/types/number) or [string](/types/string) over radio. +```sig +radio.onDataReceived(() => { }); +``` + +## ~ hint + +**Deprecated** + +This API has been deprecated! Use [on received number](/reference/radio/on-received-number) instead. + +## ~ ```sig radio.onDataReceived(() => { }); diff --git a/docs/reference/radio/on-received-number.md b/docs/reference/radio/on-received-number.md index 8a7114d3..8557319a 100644 --- a/docs/reference/radio/on-received-number.md +++ b/docs/reference/radio/on-received-number.md @@ -55,6 +55,7 @@ The radio set group might need to be set, synchronized, before the radio events ## See also [on received string](/reference/radio/on-received-string), +[received packet](/reference/radio/received-packet), [send number](/reference/radio/send-number), [send string](/reference/radio/send-string), [send value](/reference/radio/send-value), diff --git a/docs/reference/radio/on-received-string.md b/docs/reference/radio/on-received-string.md index 93c5f496..048fc6c6 100644 --- a/docs/reference/radio/on-received-string.md +++ b/docs/reference/radio/on-received-string.md @@ -32,6 +32,7 @@ The radio set group might need to be set, synchronized, before the radio events ## See also [on received number](/reference/radio/on-received-number), +[received packet](/reference/radio/received-packet), [send number](/reference/radio/send-number), [send string](/reference/radio/send-string), [send value](/reference/radio/send-value), diff --git a/docs/reference/radio/on-received-value.md b/docs/reference/radio/on-received-value.md index a1495de9..f85b675b 100644 --- a/docs/reference/radio/on-received-value.md +++ b/docs/reference/radio/on-received-value.md @@ -38,6 +38,7 @@ The radio set group might need to be set, synchronized , before the radio events ## See also [on received number](/reference/radio/on-received-number), +[received packet](/reference/radio/received-packet), [send number](/reference/radio/send-number), [send string](/reference/radio/send-string), [send value](/reference/radio/send-value), diff --git a/docs/reference/radio/raise-event.md b/docs/reference/radio/raise-event.md index f7862528..947f8d77 100644 --- a/docs/reference/radio/raise-event.md +++ b/docs/reference/radio/raise-event.md @@ -1,4 +1,4 @@ -# Raise Event +# raise Event Sends an event over radio to be raised in the event bus of other @boardname@. diff --git a/docs/reference/radio/receive-number.md b/docs/reference/radio/receive-number.md index d6fcbfbb..83e00a40 100644 --- a/docs/reference/radio/receive-number.md +++ b/docs/reference/radio/receive-number.md @@ -1,13 +1,19 @@ -# Receive Number +# receive Number -> Note: This API has been deprecated! Use [on received number](/reference/radio/on-received-number) instead. - -Receives the next number sent by a @boardname@ in the same ``radio`` group. +Receive the next number sent by a @boardname@ in the same ``radio`` group. ```sig radio.receiveNumber(); ``` +## ~ hint + +**Deprecated** + +This API has been deprecated! Use [on received number](/reference/radio/on-received-number) instead. + +## ~ + ## Returns * the first [number](/types/number) that the @boardname@ received. If it did not receive any numbers, this function will return `0`. diff --git a/docs/reference/radio/receive-string.md b/docs/reference/radio/receive-string.md index 190e6d10..3c6ae814 100644 --- a/docs/reference/radio/receive-string.md +++ b/docs/reference/radio/receive-string.md @@ -1,12 +1,17 @@ -# Receive String +# receive String -> Note: This API has been deprecated! Use [on received string](/reference/radio/on-received-string) instead. - -Find the next string sent by `radio` from another @boardname@. +Find the next string sent by radio from another @boardname@. ```sig radio.receiveString() ``` +## ~ hint + +**Deprecated** + +This API has been deprecated! Use [on received string](/reference/radio/on-received-string) instead. + +## ~ ## Returns diff --git a/docs/reference/radio/received-packet.md b/docs/reference/radio/received-packet.md index 4c198d23..3dd95504 100644 --- a/docs/reference/radio/received-packet.md +++ b/docs/reference/radio/received-packet.md @@ -1,4 +1,4 @@ -# Received Packet Property +# received Packet Get one of the properties from the last received radio packet. @@ -6,6 +6,8 @@ Get one of the properties from the last received radio packet. radio.receivedPacket(RadioPacketProperty.SignalStrength) ``` +In addition to a [number](types/number), [string](/types/string), or name-value pair, the packet received also contains other information about the transmission of the packet. You can get this additional information by selecting a property from the packet. + ## Parameters * **type**: the property type to get from the packet. These are: @@ -15,7 +17,10 @@ radio.receivedPacket(RadioPacketProperty.SignalStrength) ## Returns -* a [number](/types/number) that is the property selected in the **type** parameter. +* 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.) +>* ``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. ## Example diff --git a/docs/reference/radio/received-signal-strength.md b/docs/reference/radio/received-signal-strength.md index 9545cf5c..95516040 100644 --- a/docs/reference/radio/received-signal-strength.md +++ b/docs/reference/radio/received-signal-strength.md @@ -1,6 +1,18 @@ -# Received Signal Strength +# received Signal Strength -> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead. +Find how strong the radio signal is. + +```sig +radio.receivedSignalStrength(); +``` + +## ~ hint + +**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.) @@ -10,9 +22,7 @@ the last time it ran the [on received number](/reference/radio/on-received-number) function. That means it needs to run **receive number** first. -```sig -radio.receivedSignalStrength(); -``` + ## Returns diff --git a/docs/reference/radio/send-number.md b/docs/reference/radio/send-number.md index a8e46794..b90ae729 100644 --- a/docs/reference/radio/send-number.md +++ b/docs/reference/radio/send-number.md @@ -11,7 +11,9 @@ radio.sendNumber(0); * **value**: a [number](/types/number) to send. -## Example: Broadcasting acceleration +## Examples + +### Broadcasting acceleration This example broadcasts the value of your @boardname@'s ``acceleration`` in the `x` direction (left and right) to other @boardname@s. This kind @@ -23,7 +25,7 @@ input.onButtonPressed(Button.A, () => { }) ``` -## Light level sender +### Light level sender 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 diff --git a/docs/reference/radio/send-string.md b/docs/reference/radio/send-string.md index 1c1833ba..e6f1e2e5 100644 --- a/docs/reference/radio/send-string.md +++ b/docs/reference/radio/send-string.md @@ -9,7 +9,7 @@ radio.sendString("Hello!") ## Parameters -* `msg` is a [string](/types/string) to send by radio. +* **msg**: a [string](/types/string) to send by radio. ## Example: Two-way radio diff --git a/docs/reference/radio/send-value.md b/docs/reference/radio/send-value.md index 7a6a4d28..0441cd08 100644 --- a/docs/reference/radio/send-value.md +++ b/docs/reference/radio/send-value.md @@ -9,8 +9,8 @@ radio.sendValue("name", 0); ## Parameters -* ``name`` is a [string](/types/string) to send by radio -* ``value`` a [number](/types/number) to send by radio +* **name**: a [string](/types/string) that is the name of the value to send. +* **value**: a [number](/types/number) that is the value to send. ## Example: Broadcasting acceleration diff --git a/docs/reference/radio/set-group.md b/docs/reference/radio/set-group.md index ed968555..6c640441 100644 --- a/docs/reference/radio/set-group.md +++ b/docs/reference/radio/set-group.md @@ -1,7 +1,13 @@ # 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 +with radio. + +```sig +radio.setGroup(0); +``` + +A group is like a cable channel (a @boardname@ can only send or receive in one group at a time). A group ID is like the cable channel number. @@ -10,10 +16,6 @@ function, it will figure out its own group ID by itself. If you load the very same program onto two different @boardname@s, they will be able to talk to each other because they will have the same group ID. -```sig -radio.setGroup(0); -``` - ## Parameters * **id**: a [number](/types/number) from ``0`` to ``255``. diff --git a/docs/reference/radio/set-transmit-power.md b/docs/reference/radio/set-transmit-power.md index f680116e..b5143aa2 100644 --- a/docs/reference/radio/set-transmit-power.md +++ b/docs/reference/radio/set-transmit-power.md @@ -1,16 +1,18 @@ # 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`. Default is ``6``. +Make the ``radio`` signal of the @boardname@ stronger or weaker. + +```sig +radio.setTransmitPower(7); +``` + +The signal can be as weak as `0` and as strong as `7`. Default is ``6``. The scientific name for the strength of the ``radio`` signal is **dBm**, or **decibel-milliwatts**. A signal strength of `0` can be measured as -30 dBm, and a strength of `7` can be measured as +4 dBm. -```sig -radio.setTransmitPower(7); -``` - ## Range If your @boardname@ is sending with a strength of `7`, and you are in diff --git a/docs/reference/radio/set-transmit-serial-number.md b/docs/reference/radio/set-transmit-serial-number.md index 186b6cf5..f52ce7cb 100644 --- a/docs/reference/radio/set-transmit-serial-number.md +++ b/docs/reference/radio/set-transmit-serial-number.md @@ -1,6 +1,6 @@ # set Transmit Serial Number -Make the ``radio`` packet embed the board serial number with each packet of data. +Make the radio packet embed the board serial number with each packet of data. ```sig radio.setTransmitSerialNumber(true); @@ -8,7 +8,7 @@ radio.setTransmitSerialNumber(true); ## Parameters -* ``transmit`` is a [boolean](/types/boolean) that, when ``true``, means that the board serial number is included in each transmitted packet. If ``false``, the serial number value is set to `0`. +* **transmit**: a [boolean](/types/boolean) that, when ``true``, means that the board serial number is included in each transmitted packet. If ``false``, the serial number value is set to `0`. ## Example diff --git a/docs/reference/radio/write-received-packet-to-serial.md b/docs/reference/radio/write-received-packet-to-serial.md index abdeac78..8d06fe8b 100644 --- a/docs/reference/radio/write-received-packet-to-serial.md +++ b/docs/reference/radio/write-received-packet-to-serial.md @@ -1,13 +1,14 @@ -# Write Received Packet To Serial +# write Received Packet To Serial Writes the last packet received by the ``radio`` to serial in JSON format. -Should be called within a callback to -[on data packet received](/reference/radio/on-data-packet-received). ```sig radio.writeReceivedPacketToSerial(); ``` +This should be called within a callback to +[on data packet received](/reference/radio/on-data-packet-received). + ## Data received format The format for received data when these send functions are used: diff --git a/docs/reference/radio/write-value-to-serial.md b/docs/reference/radio/write-value-to-serial.md index 64a21c87..d3feb48e 100644 --- a/docs/reference/radio/write-value-to-serial.md +++ b/docs/reference/radio/write-value-to-serial.md @@ -1,13 +1,19 @@ -# Write Value To Serial +# write Value To Serial -> Note: This API has been deprecated! Use [write received packet to serial](/reference/radio/write-received-packet-to-serial) instead. - -Writes the data received by ``radio`` to serial in JSON format. +Write the data received by radio to serial in JSON format. ```sig radio.writeValueToSerial(); ``` +## ~ hint + +**Deprecated** + +This API has been deprecated! Use [write received packet to serial](/reference/radio/write-received-packet-to-serial) instead. + +## ~ + ## Data received format The format for received data printed to serial is as follows: