Deprecating old radio APIs and fixing docs (#289)

docs/lessons/charting.md

@@ -22,9 +22,8 @@ Learn the functions of **on data received**, **send number** and **receive numbe
 input.acceleration(Dimension.X)
 led.plotBarGraph(0, 1023)
 basic.showNumber(0)
-radio.onDataReceived(() => {})
+radio.onDataPacketReceived(() => {})
 radio.sendNumber(0)
-radio.receiveNumber()
 ```
 
 ## Objectives

docs/lessons/charting/challenge.md

@@ -28,7 +28,7 @@ We want to register code to run when a packet is received over radio. We can imp
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.X))
 })
-radio.onDataReceived(() => {
+radio.onDataPacketReceived(() => {
 
 })
 ```
@@ -39,8 +39,8 @@ Finally, we want to chart the acceleration. So we must first implement `plot bar
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.X))
 })
-radio.onDataReceived(() => {
-    led.plotBarGraph(radio.receiveNumber(), 1023)
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    led.plotBarGraph(receivedNumber, 1023)
 })
 
 ```

docs/lessons/pogo.md

@@ -19,7 +19,6 @@ Learn how to use running time. We will be learning how to create a pogo game usi
 let jumps = 0
 let acc = input.acceleration(Dimension.Y)
 basic.showNumber(0)
-radio.receiveNumber()
 led.stopAnimation()
 radio.sendNumber(0)
 basic.forever(() => { })
@@ -32,7 +31,7 @@ basic.showLeds(`
     `)
 basic.clearScreen()
 if (true) {}
-radio.onDataReceived(() => { })
+radio.onDataPacketReceived(() => { })
 ```
 ## Objectives
 

docs/lessons/pogo/activity.md

@@ -120,8 +120,8 @@ input.onButtonPressed(Button.AB, () => {
     let jumps = 0
     basic.showNumber(jumps)
 })
-radio.onDataReceived(() => {
-    basic.showNumber(radio.receiveNumber())
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    basic.showNumber(receivedNumber)
 })
 
 ```
@@ -151,8 +151,8 @@ input.onButtonPressed(Button.AB, () => {
     let jumps = 0
     basic.showNumber(jumps)
 })
-radio.onDataReceived(() => {
-    basic.showNumber(radio.receiveNumber())
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    basic.showNumber(receivedNumber)
     led.stopAnimation()
 })
 

docs/lessons/seismograph.md

@@ -21,9 +21,8 @@ Learn how to **show LEDs** to turn on a LED light pattern on the LED screen. We
 basic.forever(() => {});
 radio.sendNumber(0);
 input.acceleration(Dimension.Strength)
-radio.onDataReceived(() => {});
+radio.onDataPacketReceived(() => {});
 led.plotBarGraph(0, 0);
-radio.receiveNumber();
 ```
 
 ## Objectives

docs/lessons/seismograph/challenge.md

@@ -78,7 +78,7 @@ Your finished code will look like this:
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.Strength) - 1023);
 });
-radio.onDataReceived(() => {
+radio.onDataPacketReceived(() => {
 });
 
 ```
@@ -92,8 +92,8 @@ Your finished code will look like this:
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.Strength) - 1023);
 });
-radio.onDataReceived(() => {
-    led.plotBarGraph(radio.receiveNumber(), 0);
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    led.plotBarGraph(receivedNumber, 0);
 });
 ```
 

docs/projects/messenger.md

@@ -16,13 +16,13 @@ input.onButtonPressed(Button.A, () => {
 
 ## Step 2
 
-Use [radio on data received](/reference/radio/on-data-received) display "YO" when the number ``0`` is received
+Use [radio on data packet received](/reference/radio/on-data-packet-received) display "YO" when the number ``0`` is received
 by radio.
 
 ```blocks
 let message = 0;
-radio.onDataReceived(() => {
-    message = radio.receiveNumber();
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    message = receivedNumber;
     if (message == 0) {
         basic.showString("YO")
     }
@@ -43,13 +43,13 @@ input.onButtonPressed(Button.B, () => {
 
 ## Step 4
 
-Add blocks in [radio on data received](/reference/radio/on-data-received) to display "BYE" when the number ``1`` is received
+Add blocks in [radio on data packet received](/reference/radio/on-data-packet-received) to display "BYE" when the number ``1`` is received
 by radio.
 
 ```blocks
 let message = 0;
-radio.onDataReceived(() => {
-    message = radio.receiveNumber();
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    message = receivedNumber;
     if (message == 0) {
         basic.showString("YO")
     }

docs/projects/radio-challenges.md

@@ -28,7 +28,7 @@ We want to register code to run when a packet is received over radio. We can imp
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.X))
 })
-radio.onDataReceived(() => {
+radio.onDataPacketReceived(() => {
 
 })
 ```
@@ -39,8 +39,8 @@ Finally, we want to chart the acceleration. So we must first implement `plot bar
 basic.forever(() => {
     radio.sendNumber(input.acceleration(Dimension.X))
 })
-radio.onDataReceived(() => {
-    led.plotBarGraph(radio.receiveNumber(), 1023)
+radio.onDataPacketReceived(({ receivedNumber }) => {
+    led.plotBarGraph(receivedNumber, 1023)
 })
 
 ```

docs/reference/radio.md

@@ -6,13 +6,9 @@ Communicate data using radio packets
 radio.sendNumber(0);
 radio.sendValue("data", 0);
 radio.sendString("");
-radio.onDataReceived(() => {
+radio.onDataPacketReceived(() => {
 
 });
-radio.receiveNumber();
-radio.receivedNumberAt(0);
-radio.receiveString();
-radio.receivedSignalStrength();
 radio.setGroup(0);
 radio.setTransmitPower(7);
 radio.setTransmitSerialNumber(false);
@@ -25,4 +21,11 @@ radio
 
 ### See Also
 
-[sendNumber](/reference/radio/send-number), [sendValue](/reference/radio/send-value), [sendString](/reference/radio/send-string), [onDataReceived](/reference/radio/on-data-received), [receiveNumber](/reference/radio/receive-number), [receiveString](/reference/radio/receive-string), [receivedSignalStrength](/reference/radio/received-signal-strength), [setGroup](/reference/radio/set-group), [setTransmitPower](/reference/radio/set-transmit-power), [setTransmitSerialNumber](/reference/radio/set-transmit-serial-number), [writeValueToSerial](/reference/radio/write-value-to-serial)
+[sendNumber](/reference/radio/send-number),
+[sendValue](/reference/radio/send-value),
+[sendString](/reference/radio/send-string),
+[onDataPacketReceived](/reference/radio/on-data-packet-received),
+[setGroup](/reference/radio/set-group),
+[setTransmitPower](/reference/radio/set-transmit-power),
+[setTransmitSerialNumber](/reference/radio/set-transmit-serial-number),
+[writeValueToSerial](/reference/radio/write-value-to-serial)

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

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

@@ -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

libs/radio/radio.cpp

@@ -244,7 +244,7 @@ namespace radio {
     //% help=radio/receive-number
     //% weight=46
     //% blockId=radio_datagram_receive block="radio receive number" blockGap=8
-    //% advanced=true
+    //% deprecated=true
     int receiveNumber()
     {
         if (radioEnable() != MICROBIT_OK) return 0;
@@ -258,7 +258,7 @@ namespace radio {
     //% help=radio/on-data-received
     //% weight=50
     //% blockId=radio_datagram_received_event block="radio on data received" blockGap=8
-    //% advanced=true
+    //% deprecated=true
     void onDataReceived(Action body) {
         if (radioEnable() != MICROBIT_OK) return;
         registerWithDal(MICROBIT_ID_RADIO, MICROBIT_RADIO_EVT_DATAGRAM, body);
@@ -274,7 +274,7 @@ namespace radio {
     //% blockId=radio_datagram_receive_string block="radio receive string" blockGap=8
     //% weight=44
     //% help=radio/receive-string
-    //% advanced=true
+    //% deprecated=true
     StringData* receiveString() {
         if (radioEnable() != MICROBIT_OK) return ManagedString().leakData();
         receivePacket(false);
@@ -289,7 +289,7 @@ namespace radio {
     //% help=radio/received-signal-strength
     //% weight=40
     //% blockId=radio_datagram_rssi block="radio received signal strength"
-    //% advanced=true
+    //% deprecated=true
     int receivedSignalStrength() {
         if (radioEnable() != MICROBIT_OK) return 0;
         return packet.getRSSI();

libs/radio/radio.ts

@@ -32,6 +32,7 @@ namespace radio {
      * Registers code to run when the radio receives a packet. Also takes the
      * received packet from the radio queue.
      */
+    //% help=radio/on-data-packet-received
     //% mutate=true
     //% mutateText=Packet
     //% mutateDefaults="receivedNumber;text,receivedNumber;text"

libs/radio/shims.d.ts

@@ -50,7 +50,7 @@ declare namespace radio {
     //% help=radio/receive-number
     //% weight=46
     //% blockId=radio_datagram_receive block="radio receive number" blockGap=8
-    //% advanced=true shim=radio::receiveNumber
+    //% deprecated=true shim=radio::receiveNumber
     function receiveNumber(): number;
 
     /**
@@ -59,7 +59,7 @@ declare namespace radio {
     //% help=radio/on-data-received
     //% weight=50
     //% blockId=radio_datagram_received_event block="radio on data received" blockGap=8
-    //% advanced=true shim=radio::onDataReceived
+    //% deprecated=true shim=radio::onDataReceived
     function onDataReceived(body: () => void): void;
 
     /**
@@ -69,7 +69,7 @@ declare namespace radio {
     //% blockId=radio_datagram_receive_string block="radio receive string" blockGap=8
     //% weight=44
     //% help=radio/receive-string
-    //% advanced=true shim=radio::receiveString
+    //% deprecated=true shim=radio::receiveString
     function receiveString(): string;
 
     /**
@@ -80,7 +80,7 @@ declare namespace radio {
     //% help=radio/received-signal-strength
     //% weight=40
     //% blockId=radio_datagram_rssi block="radio received signal strength"
-    //% advanced=true shim=radio::receivedSignalStrength
+    //% deprecated=true shim=radio::receivedSignalStrength
     function receivedSignalStrength(): number;
 
     /**