Deprecating old radio APIs and fixing docs (#289)

docs/reference/radio/on-data-packet-received.md

@@ -0,0 +1,40 @@
+# On Data Packet Received
+
+Run part of a program when the micro:bit receives a
+[number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
+
+
+```sig
+radio.onDataPacketReceived((packet: Packet) => { });
+```
+
+### Callback Parameters
+
+* ``packet`` - the [packet](/reference/radio/packet) that was received by the radio
+
+### Example
+
+This program keeps sending numbers that says how fast the micro:bit is
+slowing down or speeding up.  It also receives numbers for the same
+thing from nearby micro:bits. It shows these numbers as a
+[bar graph](/reference/led/plot-bar-graph).
+
+```blocks
+basic.forever(() => {
+    radio.sendNumber(input.acceleration(Dimension.X));
+})
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    led.plotBarGraph(receivedNumber, 1023);
+})
+```
+
+### See also
+
+[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
+```

docs/reference/radio/on-data-received.md

@@ -1,5 +1,7 @@
 # On Data Received
 
+> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
+
 Run part of a program when the micro:bit receives a
 [number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
 
@@ -8,10 +10,6 @@ Run part of a program when the micro:bit receives a
 radio.onDataReceived(() => { });
 ```
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
-
 ### Example
 
 This program keeps sending numbers that says how fast the micro:bit is
@@ -30,7 +28,7 @@ radio.onDataReceived(() => {
 
 ### See also
 
-[receive number](/reference/radio/receive-number),
+[on data packet received](/reference/radio/on-data-packet-received),
 [send number](/reference/radio/send-number), [set group](/reference/radio/set-group)
 
 ```package

docs/reference/radio/packet.md

@@ -0,0 +1,19 @@
+# Packet
+
+A packet that was received by the radio.
+
+## Properties
+
+* `receivedNumber` - The 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)
+* `text` - The 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)
+* `time` - The system time of the micro:bit that sent this packet at the time the packet was sent.
+* `serial` - The serial number of the micro:bit that sent this packet or `0` if the micro:bit did not include its serial number.
+* `signal` - How strong the radio signal is from `255` (weak) to `0` (strong).
+
+### See also
+
+[on data packet received](/reference/radio/on-data-packet-received),
+
+```package
+radio
+```

docs/reference/radio/receive-number.md

@@ -1,5 +1,7 @@
 # Receive Number
 
+> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
+
 Receives the next number sent by a micro:bit in the same ``radio`` group.
 
 ```sig
@@ -10,10 +12,6 @@ radio.receiveNumber();
 
 * the first  [number](/reference/types/number) that the micro:bit received. If it did not receive any numbers, this function will return `0`.
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
-
 ### Example: Simple number receiver
 
 This example receives the number broadcasted another micro:bit and shows it
@@ -25,7 +23,7 @@ radio.onDataReceived(() => {
 })
 ```
 
-### Example: Light level receiver 
+### Example: Light level receiver
 
 This example shows the light level from the [light level sender example](/reference/radio/send-number)
 as a number.

docs/reference/radio/receive-string.md

@@ -1,5 +1,7 @@
 # Receive String
 
+> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
+
 Find the next string sent by `radio` from another micro:bit.
 
 ```sig
@@ -11,10 +13,6 @@ radio.receiveString()
 * the first [string](/reference/types/string) that was sent. If no
   string was sent, then this function returns an empty (blank) string.
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
-
 ### Example: Simple receiver
 
 Show the string sent by another micro:bit.

docs/reference/radio/received-signal-strength.md

@@ -1,11 +1,13 @@
 # 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, from `255` to `0`.
 (`255` means a weak signal and `0` means a strong one.)
 
 The micro:bit finds the signal strength by checking how strong it was
 the last time it ran the
-[receive number](/reference/radio/receive-number) function. That means
+[on data packet received](/reference/radio/on-data-packet-received) function. That means
 it needs to run **receive number** first.
 
 ```sig
@@ -37,7 +39,7 @@ basic.forever(() => {
 
 ### See also
 
-[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
 
 ```package
 radio

docs/reference/radio/send-number.md

@@ -10,9 +10,6 @@ radio.sendNumber(0);
 
 * ``value`` - a [number](/reference/types/number) to send.
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
 
 ### Example: Broadcasting acceleration
 
@@ -30,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
-[Mailbot](/reference/radio/receive-number) example.
+[on data packet received](/reference/radio/on-data-packet-received) example.
 
 ```blocks
 radio.setGroup(99)
@@ -42,7 +39,7 @@ basic.forever(() => {
 
 ### See also
 
-[receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received)
 
 ```package
 radio

docs/reference/radio/send-string.md

@@ -1,6 +1,7 @@
 # Send String
 
-Sends a string to other micro:bits in the area connected by radio.
+Sends a string to other micro:bits in the area connected by radio. The
+maximum string length is 19 characters.
 
 ```sig
 radio.sendString("Hello!")
@@ -10,9 +11,6 @@ radio.sendString("Hello!")
 
 * `msg` is a [string](/reference/types/string) to send by radio.
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
 
 ### Example: Two-way radio
 
@@ -26,8 +24,8 @@ input.onButtonPressed(Button.A, () => {
     basic.showString("SENT");
 })
 
-radio.onDataReceived(() => {
-    basic.showString(radio.receiveString());
+radio.onDataPacketReceived(({ text }) => {
+    basic.showString(text);
 });
 ```
 
@@ -39,7 +37,7 @@ A radio that can both transmit and receive is called a _transceiver_.
 
 ### See also
 
-[receive string](/reference/radio/receive-string), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received)
 
 ```package
 radio

docs/reference/radio/send-value.md

@@ -1,6 +1,7 @@
 # Send Value
 
 Send a [string]() and [number]() together by ``radio`` to other micro:bits.
+The maximum [string]() length is 12 characters.
 
 ```sig
 radio.sendValue("data", 0);
@@ -11,10 +12,6 @@ radio.sendValue("data", 0);
 * ``name`` is a [string](/reference/types/string) to send by radio
 * ``value`` a [number](/reference/types/number) to send by radio
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
-
 ### Example: Broadcasting acceleration
 
 This program sends your micro:bit's **acceleration** (amount it is
@@ -34,15 +31,15 @@ Then it shows them on the LED screen.
 
 ```blocks
 radio.setGroup(99)
-radio.onDataReceived(() => {
-	basic.showString(radio.receiveString());
-    basic.showNumber(radio.receiveNumber());
+radio.onDataPacketReceived(({ text, receivedNumber }) => {
+	basic.showString(text);
+    basic.showNumber(receivedNumber);
 });
 ```
 
 ### See also
 
-[receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received)
 
 ```package
 radio

docs/reference/radio/set-group.md

@@ -32,7 +32,10 @@ radio.setGroup(128)
 
 ### See also
 
-[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received),
+[send number](/reference/radio/send-number),
+[send value](/reference/radio/send-value),
+[send string](/reference/radio/send-string)
 
 ```package
 radio

docs/reference/radio/set-transmit-power.md

@@ -13,7 +13,7 @@ radio.setTransmitPower(7);
 ```
 
 ### Range
-   
+
 If your micro:bit is sending with a strength of `7`, and you are in
 an open area without many other computers around, the micro:bit signal
 can reach as far as 70 meters (about 230 feet).
@@ -37,7 +37,10 @@ radio.setTransmitPower(7)
 
 ### See also
 
-[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received),
+[send number](/reference/radio/send-number),
+[send value](/reference/radio/send-value),
+[send string](/reference/radio/send-string)
 
 ```package
 radio

docs/reference/radio/set-transmit-serial-number.md

@@ -10,10 +10,6 @@ radio.setTransmitSerialNumber(true);
 
 * ``transmit`` is a [boolean](/reference/types/boolean) that represents whether the serial number needs to be transmitted.
 
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
-
 ### Example
 
 This program makes the ``radio`` send the serial number in each packet.
@@ -24,7 +20,10 @@ radio.setTransmitSerialNumber(true);
 
 ### See also
 
-[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
+[on data packet received](/reference/radio/on-data-packet-received),
+[send number](/reference/radio/send-number),
+[send value](/reference/radio/send-value),
+[send string](/reference/radio/send-string)
 
 ```package
 radio

docs/reference/radio/write-value-to-serial.md

@@ -6,25 +6,13 @@ Writes the data received by ``radio`` to serial in JSON format.
 radio.writeValueToSerial();
 ```
 
-### ~hint
-
-This method only works for [send number](/reference/radio/send-number)
-and [send value](/reference/radio/send-value). It does not work for
-[send string](/reference/radio/send-string), although you can send a
-string as part of [send value](/reference/radio/send-value).
-
-### ~
-
 ### Data received format
 
 The format for received data printed to serial is as follows:
 
-- [send number](/reference/radio/send-number): ```{v:ValueSent,t:MicrobitTimeAlive,s:Unused}```
-- [send value](/reference/radio/send-value): ```{v:ValueSent,t:MicrobitTimeAlive,s:Unused,n:"Name"}```
-
-### Simulator
-
-This function only works on the micro:bit, not in browsers.
+- [send number](/reference/radio/send-number): ```{v:ValueSent,t:MicrobitTimeAlive,s:SerialNumber}```
+- [send value](/reference/radio/send-value): ```{v:ValueSent,t:MicrobitTimeAlive,s:SerialNumber,n:"Name"}```
+- [send string](/reference/radio/send-string): ```{t:MicrobitTimeAlive,s:SerialNumber,n:"Text"}```
 
 ### Examples
 
@@ -50,7 +38,8 @@ Sample output to serial when ``A`` button pressed:
 
 [send number](/reference/radio/send-number),
 [send value](/reference/radio/send-value),
-[on data received](/reference/radio/on-data-received)
+[send string](/reference/radio/send-string),
+[on data packet received](/reference/radio/on-data-packet-received)
 
 ```package
 radio