From f5c44a3d4bb68b718e4f9a0ac988ff77a546c97e Mon Sep 17 00:00:00 2001
From: Galen Nickel <v-ganick@microsoft.com>
Date: Mon, 9 Jul 2018 11:17:32 -0700
Subject: [PATCH] Update 'radio' docs for v1 (#937)

---
 .../radio/get-received-packet-property.md     | 39 +++++++++++
 docs/reference/radio/on-received-number.md    | 65 +++++++++++++++++++
 docs/reference/radio/on-received-string.md    | 42 ++++++++++++
 docs/reference/radio/on-received-value.md     | 48 ++++++++++++++
 docs/reference/radio/send-number.md           |  8 +--
 docs/reference/radio/send-string.md           |  9 ++-
 docs/reference/radio/send-value.md            | 11 ++--
 docs/reference/radio/set-group.md             |  8 ++-
 docs/reference/radio/set-transmit-power.md    | 10 ++-
 .../radio/set-transmit-serial-number.md       |  4 +-
 libs/radio/radio.ts                           |  8 +--
 11 files changed, 223 insertions(+), 29 deletions(-)
 create mode 100644 docs/reference/radio/get-received-packet-property.md
 create mode 100644 docs/reference/radio/on-received-number.md
 create mode 100644 docs/reference/radio/on-received-string.md
 create mode 100644 docs/reference/radio/on-received-value.md

diff --git a/docs/reference/radio/get-received-packet-property.md b/docs/reference/radio/get-received-packet-property.md
new file mode 100644
index 00000000..dd21787f
--- /dev/null
+++ b/docs/reference/radio/get-received-packet-property.md
@@ -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)
diff --git a/docs/reference/radio/on-received-number.md b/docs/reference/radio/on-received-number.md
new file mode 100644
index 00000000..5243f2de
--- /dev/null
+++ b/docs/reference/radio/on-received-number.md
@@ -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
+```
diff --git a/docs/reference/radio/on-received-string.md b/docs/reference/radio/on-received-string.md
new file mode 100644
index 00000000..ef8ed1e4
--- /dev/null
+++ b/docs/reference/radio/on-received-string.md
@@ -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
+```
diff --git a/docs/reference/radio/on-received-value.md b/docs/reference/radio/on-received-value.md
new file mode 100644
index 00000000..a1495de9
--- /dev/null
+++ b/docs/reference/radio/on-received-value.md
@@ -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
+```
diff --git a/docs/reference/radio/send-number.md b/docs/reference/radio/send-number.md
index 8972f254..a8e46794 100644
--- a/docs/reference/radio/send-number.md
+++ b/docs/reference/radio/send-number.md
@@ -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
diff --git a/docs/reference/radio/send-string.md b/docs/reference/radio/send-string.md
index b2da7d98..1c1833ba 100644
--- a/docs/reference/radio/send-string.md
+++ b/docs/reference/radio/send-string.md
@@ -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
diff --git a/docs/reference/radio/send-value.md b/docs/reference/radio/send-value.md
index f6e83b13..d7cc74e6 100644
--- a/docs/reference/radio/send-value.md
+++ b/docs/reference/radio/send-value.md
@@ -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
diff --git a/docs/reference/radio/set-group.md b/docs/reference/radio/set-group.md
index 9d683f3e..ed968555 100644
--- a/docs/reference/radio/set-group.md
+++ b/docs/reference/radio/set-group.md
@@ -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)
diff --git a/docs/reference/radio/set-transmit-power.md b/docs/reference/radio/set-transmit-power.md
index 01af2b85..023a52c9 100644
--- a/docs/reference/radio/set-transmit-power.md
+++ b/docs/reference/radio/set-transmit-power.md
@@ -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)
diff --git a/docs/reference/radio/set-transmit-serial-number.md b/docs/reference/radio/set-transmit-serial-number.md
index b37433b4..0afe876a 100644
--- a/docs/reference/radio/set-transmit-serial-number.md
+++ b/docs/reference/radio/set-transmit-serial-number.md
@@ -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)
diff --git a/libs/radio/radio.ts b/libs/radio/radio.ts
index a2c91f64..0995479b 100644
--- a/libs/radio/radio.ts
+++ b/libs/radio/radio.ts
@@ -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(() => {