2.1.28, initiation update to PXT v5.28.24 (#54)

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

@@ -1,45 +1,42 @@
 # On Data Packet Received
 
 Run part of a program when the @boardname@ receives a
-[number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
+[number](/types/number) or [string](/types/string) over radio.
 
+## ~ hint
 
-```sig
-radio.onDataPacketReceived(({receivedNumber, receivedString, time, serial, signal}) => { });
-```
+**Deprecated**
 
-### ~hint
+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!
 
-### ~
+## ~
 
-### Callback Parameters
+## Callback Parameters
 
 * ``packet`` - the [packet](/reference/radio/packet) that was received by the radio. The packet has the following properties:
-  * `receivedNumber` - The [number](/reference/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)
-  * `receivedString` - The [string](/reference/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)
+  * `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)
+  * `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)
   * `time` - The system time of the @boardname@ that sent this packet at the time the packet was sent.
   * `serial` - The serial number of the @boardname@ that sent this packet or `0` if the @boardname@ did not include its serial number.
-  * `signal` - How strong the radio signal is from `255` (weak) to `0` (strong).
+  * `signal` - How strong the radio signal is from `-128` (weak) to `-42` (strong).
 
-### Example
+## Troubleshooting
 
-This program keeps sending numbers that says 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).
+The on radio data event can only be created once, due to the hardware restrictions.
 
-```blocks
-basic.forever(() => {
-    radio.sendNumber(input.acceleration(Dimension.X));
-})
-radio.onDataPacketReceived(({ receivedNumber }) => {
-    led.plotBarGraph(receivedNumber, 1023);
-})
-```
+The radio set group might need to be set, synchronized , before the radio events will function.
 
-### See also
+## See also
 
 [send number](/reference/radio/send-number),
 [send string](/reference/radio/send-string),
@@ -48,4 +45,4 @@ radio.onDataPacketReceived(({ receivedNumber }) => {
 
 ```package
 radio
-```
+```

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

@@ -1,16 +1,25 @@
-# On Data Received
-
-> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
+# on Data Received
 
 Run part of a program when the @boardname@ receives a
-[number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
-
+[number](/types/number) or [string](/types/string) over radio.
 
 ```sig
 radio.onDataReceived(() => { });
 ```
 
-### Example
+## ~ hint
+
+**Deprecated**
+
+This API has been deprecated! Use [on received number](/reference/radio/on-received-number) instead.
+
+## ~
+
+```sig
+radio.onDataReceived(() => { });
+```
+
+## Example
 
 This program keeps sending numbers that says how fast the @boardname@ is
 slowing down or speeding up.  It also receives numbers for the same
@@ -26,9 +35,9 @@ radio.onDataReceived(() => {
 })
 ```
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received),
+[on received number](/reference/radio/on-received-number),
 [send number](/reference/radio/send-number), [set group](/reference/radio/set-group)
 
 ```package

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

@@ -0,0 +1,61 @@
+# on Received Buffer
+
+Run part of a program when the @boardname@ receives a buffer over ``radio``.
+
+```sig
+radio.onReceivedBuffer(function (receivedBuffer) {})
+```
+
+The data contained in **receivedBuffer** is put there as a data [type](/types). The data might be a [number](/types/number) or a [string](/types/string). When using buffers though, the way the data is placed in the buffer must have a specific format. In particular, numbers must have a certain order when their individual _bytes_ are placed into the buffer. The numbers must also be retrieved from the buffer using the order that they were placed in when set there. You can read more about [number formats](/types/buffer/number-format).
+
+## Parameters
+
+* **receivedBuffer**: The buffer that was sent in this packet or the empty string if this packet did not contain a string. See [send buffer](/reference/radio/send-buffer)
+
+## Example: Remote level
+
+Two @boardname@s work like remote levels. They lie flat and detect any change in the horizontal position of the plane that they sit in. Each board sends its level measurements to the other. Each level measurement is shown on the screen.
+
+```typescript
+let ax = 0;
+let ay = 0;
+basic.forever(() => {
+    ax = input.acceleration(Dimension.X);
+    ay = input.acceleration(Dimension.Y);
+
+    // encode data in buffer
+    let buf = pins.createBuffer(4)
+    buf.setNumber(NumberFormat.Int16LE, 0, ax)
+    buf.setNumber(NumberFormat.Int16LE, 2, ay)
+    radio.sendBuffer(buf)
+})
+
+radio.onReceivedBuffer(function (receivedBuffer) {
+    // decode data from buffer
+    ax = receivedBuffer.getNumber(NumberFormat.Int16LE, 0);
+    ay = receivedBuffer.getNumber(NumberFormat.Int16LE, 2);
+
+    // display
+    basic.clearScreen()
+    led.plot(
+        pins.map(ax, -1023, 1023, 0, 4),
+        pins.map(ay, -1023, 1023, 0, 4)
+    )
+});
+```
+
+
+## ~hint
+
+A radio that can both transmit and receive is called a _transceiver_.
+
+## ~
+
+## See also
+
+[send buffer](/reference/radio/send-buffer),
+[number formats](/types/buffer/number-format)
+
+```package
+radio
+```

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

@@ -0,0 +1,74 @@
+# 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)
+
+## ~ hint
+
+Watch this video to see how the radio hardware works on the @boardname@:
+
+https://www.youtube.com/watch?v=Re3H2ISfQE8
+
+## ~
+
+## 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.receivedPacket(RadioPacketProperty.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 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),
+[set group](/reference/radio/set-group)
+
+```package
+radio
+```

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

@@ -0,0 +1,51 @@
+# 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)
+
+## ~ hint
+
+Watch this video to see how the radio hardware works on the @boardname@:
+
+https://www.youtube.com/watch?v=Re3H2ISfQE8
+
+## ~
+
+## 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),
+[received packet](/reference/radio/received-packet),
+[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-received-value.md

@@ -0,0 +1,57 @@
+# 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.
+
+## ~ hint
+
+Watch this video to see how the radio hardware works on the @boardname@:
+
+https://www.youtube.com/watch?v=Re3H2ISfQE8
+
+## ~
+
+## 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),
+[received packet](/reference/radio/received-packet),
+[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/packet.md

@@ -4,13 +4,52 @@ A packet that was received by the radio.
 
 ## Properties
 
-* `receivedNumber` - The [number](/reference/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)
-* `receivedString` - The [string](/reference/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)
+* `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)
+* `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)
 * `time` - The system time of the @boardname@ that sent this packet at the time the packet was sent.
 * `serial` - The serial number of the @boardname@ that sent this packet or `0` if the @boardname@ did not include its serial number.
-* `signal` - How strong the radio signal is from `255` (weak) to `0` (strong).
+* `signal` - How strong the radio signal is. The exact range of values varies, but it goes approximately from `-128` dB (weak) to `-42` dB (strong).
 
-### See also
+## Packet layout
+
+This section documents the data layout of the packet if you need to interpret the data outside of MakeCode.
+
+    Packet byte layout
+    | 0              | 1 ... 4       | 5 ... 8           | 9 ... 28
+    ----------------------------------------------------------------
+    | packet type    | system time   | serial number     | payload
+
+* Serial number defaults to 0 unless enabled by user
+* system time is milli-seconds since started, it will wrap around after a month or so
+
+### Packet types
+
+* PACKET_TYPE_NUMBER 0
+
+    payload: number (9 ... 12)
+
+
+* PACKET_TYPE_VALUE 1
+
+    payload: number (9 ... 12), name length (13), name (14 ... 26)
+
+* PACKET_TYPE_STRING 2
+
+    payload: string length (9), string (10 ... 28)
+
+* PACKET_TYPE_BUFFER 3
+
+    payload: buffer length (9), buffer (10 ... 28)
+
+* PACKET_TYPE_DOUBLE 4
+
+    payload: number (9 ... 16)
+
+* PACKET_TYPE_DOUBLE_VALUE 5
+
+    payload: number (9 ... 16), name length (17), name (18 ... 26)
+
+## See also
 
 [on data packet received](/reference/radio/on-data-packet-received),
 

docs/reference/radio/raise-event.md

@@ -0,0 +1,14 @@
+# raise Event
+
+Sends an event over radio to be raised in the event bus of other @boardname@. 
+
+```sig
+radio.raiseEvent(control.eventSourceId(EventBusSource.MICROBIT_ID_BUTTON_A), control.eventValueId(EventBusValue.MICROBIT_EVT_ANY));
+```
+
+**This is an advanced API.**  For more information, see the
+[@boardname@ runtime messageBus documentation](https://lancaster-university.github.io/microbit-docs/ubit/messageBus/)
+
+## See Also
+
+[control raise event](/reference/control/raise-event)

docs/reference/radio/receive-number.md

@@ -1,18 +1,24 @@
-# Receive Number
+# 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 @boardname@ in the same ``radio`` group.
+Receive the next number sent by a @boardname@ in the same ``radio`` group.
 
 ```sig
 radio.receiveNumber();
 ```
 
-### Returns
+## ~ hint
 
-* the first  [number](/reference/types/number) that the @boardname@ received. If it did not receive any numbers, this function will return `0`.
+**Deprecated**
 
-### Example: Simple number receiver
+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`.
+
+## Example: Simple number receiver
 
 This example receives the number broadcasted another @boardname@ and shows it
 as a bar graph.
@@ -23,7 +29,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.
@@ -36,7 +42,7 @@ basic.forever(() => {
 })
 ```
 
-### Example: Mailbot
+## Example: Mailbot
 
 This example receives the light level from the [light level sender example](/reference/radio/send-number)
 and shows a text string like **ALERT** if the light level becomes much brighter.
@@ -58,7 +64,7 @@ basic.forever(() => {
 })
 ```
 
-### See also
+## See also
 
 [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
 

docs/reference/radio/receive-string.md

@@ -1,19 +1,24 @@
-# Receive String
+# 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 @boardname@.
+Find the next string sent by radio from another @boardname@.
 
 ```sig
 radio.receiveString()
 ```
+## ~ hint
 
-### Returns
+**Deprecated**
 
-* the first [string](/reference/types/string) that was sent. If no
+This API has been deprecated! Use [on received string](/reference/radio/on-received-string) instead.
+
+## ~
+
+## Returns
+
+* the first [string](/types/string) that was sent. If no
   string was sent, then this function returns an empty (blank) string.
 
-### Example: Simple receiver
+## Example: Simple receiver
 
 Show the string sent by another @boardname@.
 
@@ -23,7 +28,7 @@ radio.onDataReceived(() => {
 });
 ```
 
-### Example: Two-way radio
+## Example: Two-way radio
 
 If you load this program onto two or more @boardname@s, you can send a code word from one of them to the others by pressing button `A`.
 The other @boardname@s will receive the code word and then show it.
@@ -39,13 +44,13 @@ radio.onDataReceived(() => {
 });
 ```
 
-### ~hint
+## ~hint
 
 A radio that can both transmit and receive is called a _transceiver_.
 
-### ~
+## ~
 
-### Example: Mood radio
+## Example: Mood radio
 
 This is a simple program to send whether you are happy or sad over ```radio```.
 Use the `A` or `B` button to select an emotion.
@@ -84,7 +89,7 @@ radio.onDataReceived(() => {
 });
 ```
 
-### See also
+## See also
 
 [send string](/reference/radio/send-string), [on data received](/reference/radio/on-data-received)
 

docs/reference/radio/received-packet.md

@@ -0,0 +1,48 @@
+# received Packet
+
+Get one of the properties from the last received radio packet.
+
+```sig
+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:
+>* ``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:
+>* ``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
+
+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.receivedPacket(RadioPacketProperty.SignalStrength) + 42),
+        128 - 42
+    )
+})
+```
+
+## See also
+
+[set transmit serial number](/reference/radio/set-transmit-serial-number)
+
+```package
+radio
+```

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

@@ -1,29 +1,39 @@
-# 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, from `255` to `0`.
-(`255` means a weak signal and `0` means a strong one.)
-
-The @boardname@ finds the signal strength by checking how strong it was
-the last time it ran the
-[on data packet received](/reference/radio/on-data-packet-received) function. That means
-it needs to run **receive number** first.
+Find how strong the radio signal is.
 
 ```sig
 radio.receivedSignalStrength();
 ```
 
-### Returns
+## ~ hint
 
-* a [number](/reference/types/number) between `255` and `0` that means
+**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.)
+
+The @boardname@ finds the signal strength by checking how strong it was
+the last time it ran the
+[on received number](/reference/radio/on-received-number) function. That means
+it needs to run **receive number** first.
+
+
+
+## Returns
+
+* a [number](/types/number) between `-128` and `-42` that means
 how strong the signal is.
 
-### Simulator
+## Simulator
 
 This function only works on the @boardname@, not in browsers.
 
-### Example
+## Example
 
 This example shows how strong the radio signal of the
 [light level sender example](/reference/radio/send-number) is.
@@ -37,9 +47,9 @@ basic.forever(() => {
 });
 ```
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
+[on received number](/reference/radio/on-received-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
 
 ```package
 radio

docs/reference/radio/send-buffer.md

@@ -0,0 +1,59 @@
+# Send Buffer
+
+Sends a buffer to other @boardname@s in the area connected by radio. The
+maximum buffer length is 19 bytes.
+
+```sig
+radio.sendBuffer(pins.createBuffer(1))
+```
+
+## Parameters
+
+* `msg` is a [buffer](/types/buffer) to send by radio.
+
+
+## Example: Remote level
+
+If you load this program onto two @boardname@s, each board will send the level information to the other board.
+
+```typescript
+let ax = 0;
+let ay = 0;
+basic.forever(() => {
+    ax = input.acceleration(Dimension.X);
+    ay = input.acceleration(Dimension.Y);
+
+    // encode data in buffer
+    let buf = pins.createBuffer(4)
+    buf.setNumber(NumberFormat.Int16LE, 0, ax)
+    buf.setNumber(NumberFormat.Int16LE, 2, ay)
+    radio.sendBuffer(buf)
+})
+
+radio.onReceivedBuffer(function (receivedBuffer) {
+    // decode data from buffer
+    ax = receivedBuffer.getNumber(NumberFormat.Int16LE, 0);
+    ay = receivedBuffer.getNumber(NumberFormat.Int16LE, 2);
+
+    // display
+    basic.clearScreen()
+    led.plot(
+        pins.map(ax, -1023, 1023, 0, 4),
+        pins.map(ay, -1023, 1023, 0, 4)
+    )
+});
+```
+
+## ~hint
+
+A radio that can both transmit and receive is called a _transceiver_.
+
+## ~
+
+## See also
+
+[on received buffer](/reference/radio/on-received-buffer)
+
+```package
+radio
+```

docs/reference/radio/send-number.md

@@ -1,17 +1,26 @@
-# Send Number
+# send Number
 
-Broadcast a [number](/reference/types/number) to other @boardname@s connected via ``radio``.
+Broadcast a [number](/types/number) to other @boardname@s connected via ``radio``.
 
 ```sig
 radio.sendNumber(0);
 ```
 
-### Parameters
+## Parameters
 
-* ``value`` - a [number](/reference/types/number) to send.
+* **value**: a [number](/types/number) to send.
 
+## ~ hint
 
-### Example: Broadcasting acceleration
+Watch this video to see how the radio hardware works on the @boardname@:
+
+https://www.youtube.com/watch?v=Re3H2ISfQE8
+
+## ~
+
+## 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
@@ -27,7 +36,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)
@@ -37,9 +46,9 @@ basic.forever(() => {
 })
 ```
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received)
+[on received number](/reference/radio/on-received-number)
 
 ```package
 radio

docs/reference/radio/send-string.md

@@ -1,18 +1,25 @@
-# Send String
+# send String
 
 Sends a string to other @boardname@s in the area connected by radio. The
 maximum string length is 19 characters.
 
 ```sig
-radio.sendString("Hello!")
+radio.sendString("hi!")
 ```
 
-### Parameters
+## Parameters
 
-* `msg` is a [string](/reference/types/string) to send by radio.
+* **msg**: a [string](/types/string) to send by radio.
 
+## ~ hint
 
-### Example: Two-way radio
+Watch this video to see how the radio hardware works on the @boardname@:
+
+https://www.youtube.com/watch?v=Re3H2ISfQE8
+
+## ~
+
+## Example: Two-way radio
 
 If you load this program onto two or more @boardname@s, you can send a
 code word from one of them to the others by pressing button `A`.  The
@@ -23,21 +30,20 @@ input.onButtonPressed(Button.A, () => {
     radio.sendString("Codeword: TRIMARAN")
     basic.showString("SENT");
 })
-
-radio.onDataPacketReceived(({ receivedString }) => {
+radio.onReceivedString(function (receivedString) {
     basic.showString(receivedString);
-});
+})
 ```
 
-### ~hint
+## ~hint
 
 A radio that can both transmit and receive is called a _transceiver_.
 
-### ~
+## ~
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received)
+[on received string](/reference/radio/on-received-string)
 
 ```package
 radio

docs/reference/radio/send-value.md

@@ -1,18 +1,26 @@
-# Send Value
+# send Value
 
 Send a [string]() and [number]() together by ``radio`` to other @boardname@s.
-The maximum [string]() length is 12 characters.
+The maximum [string]() length is 8 characters.
 
 ```sig
 radio.sendValue("name", 0);
 ```
 
-### Parameters
+## Parameters
 
-* ``name`` is a [string](/reference/types/string) to send by radio
-* ``value`` a [number](/reference/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
+## ~ hint
+
+Watch this video to see how the radio hardware works on the @boardname@:
+
+https://www.youtube.com/watch?v=Re3H2ISfQE8
+
+## ~
+
+## Example: Broadcasting acceleration
 
 This program sends your @boardname@'s **acceleration** (amount it is
 speeding up or slowing down) in the `x` direction (left and right) to
@@ -31,15 +39,15 @@ 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) {
+	basic.showString(name);
+    basic.showNumber(value);
 });
 ```
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received)
+[on received value](/reference/radio/on-received-value)
 
 ```package
 radio

docs/reference/radio/set-frequency-band.md

@@ -0,0 +1,34 @@
+# set Frequency Band
+
+Change the transmission and reception band of the radio to the given channel. Default is 7.
+
+```sig
+radio.setFrequencyBand(50);
+```
+
+## Parameters
+
+* ``band`` is a [number](/types/number) between ``0`` and ``83``. Each step is 1MHz wide, based at 2400MHz.
+
+## Simulator
+
+This function only works on the @boardname@, not in browsers.
+
+## Example
+
+This program makes the ``radio`` use frequency band 50.
+
+```blocks
+radio.setFrequencyBand(50)
+```
+
+## See also
+
+[received packet](/reference/radio/received-packet),
+[send number](/reference/radio/send-number),
+[send value](/reference/radio/send-value),
+[send string](/reference/radio/send-string)
+
+```package
+radio
+```

docs/reference/radio/set-group.md

@@ -1,7 +1,13 @@
-# 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
+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,19 +16,15 @@ 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
 
-### Parameters
+* **id**: a [number](/types/number) from ``0`` to ``255``.
 
-* ``id`` is a [number](/reference/types/number) from ``0`` to ``255``.
-
-### Simulator
+## Simulator
 
 This function only works on the @boardname@, not in browsers.
 
-### Example
+## Example
 
 This program makes the group ID equal 128.
 
@@ -30,9 +32,11 @@ This program makes the group ID equal 128.
 radio.setGroup(128)
 ```
 
-### See also
+## 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)

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

@@ -1,33 +1,33 @@
-# 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`.
+
+```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
+## Range
 
 If your @boardname@ is sending with a strength of `7`, and you are in
 an open area without many other computers around, the @boardname@ signal
 can reach as far as 70 meters (about 230 feet).
 
-### Parameters
+## Parameters
 
-* ``power`` is a [number](/reference/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
+## Simulator
 
 This function only works on the @boardname@, not in browsers.
 
-### Example
+## Example
 
 This program makes the ``radio`` send at full strength.
 
@@ -35,9 +35,9 @@ This program makes the ``radio`` send at full strength.
 radio.setTransmitPower(7)
 ```
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received),
+[received packet](/reference/radio/received-packet),
 [send number](/reference/radio/send-number),
 [send value](/reference/radio/send-value),
 [send string](/reference/radio/send-string)

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

@@ -1,16 +1,16 @@
-# Set Transmit Serial Number
+# 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);
 ```
 
-### Parameters
+## Parameters
 
-* ``transmit`` is a [boolean](/reference/types/boolean) that represents whether the serial number needs to be transmitted.
+* **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
+## Example
 
 This program makes the ``radio`` send the serial number in each packet.
 
@@ -18,9 +18,9 @@ This program makes the ``radio`` send the serial number in each packet.
 radio.setTransmitSerialNumber(true);
 ```
 
-### See also
+## See also
 
-[on data packet received](/reference/radio/on-data-packet-received),
+[received packet property](/reference/radio/received-packet),
 [send number](/reference/radio/send-number),
 [send value](/reference/radio/send-value),
 [send string](/reference/radio/send-string)

docs/reference/radio/write-received-packet-to-serial.md

@@ -1,48 +1,66 @@
-# 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();
 ```
 
-### Data received format
+This should be called within a callback to
+[on data packet received](/reference/radio/on-data-packet-received).
 
-The format for received data printed to serial is as follows:
+## Data received format
+
+The format for received data when these send functions are used:
 
 - [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
+### ~hint
+
+The serial number value sent in the packet is set to `0` unless transmission of the serial number is enabled with ``||radio:radio set transmit serial number||``.
+
+### ~
+
+## Example
 
 When ```radio``` data is received (after pressing the ``A`` button on
-the second @boardname@), this program sends temperature data to
-serial.
+the second @boardname@), this program sends temperature data to the 
+serial port.
 
 ```blocks
-input.onButtonPressed(Button.A, () => {
-    radio.sendNumber(input.temperature());
-});
-radio.onDataPacketReceived(() => {
-    radio.writeReceivedPacketToSerial();
-});
+input.onButtonPressed(Button.A, function () {
+    radio.sendNumber(input.temperature())
+    radio.sendValue("temp", input.temperature())
+    radio.sendString("It's warm now")
+})
+radio.onReceivedNumber(function (receivedNumber) {
+    radio.writeReceivedPacketToSerial()
+})
+radio.onReceivedValue(function (name, value) {
+    radio.writeReceivedPacketToSerial()
+})
+radio.onReceivedString(function (receivedString) {
+    radio.writeReceivedPacketToSerial()
+})
 ```
 Sample output to serial when ``A`` button pressed:
 
-```Text
-{v:27,t:323,s:0}
+```json
+{"t":323,"s":0,"v":27}
+{"t":325,"s":0,"n":"temp","v":27}
+{"t":326,"s":0,"n":"It's warm now"}
 ```
 
-### See also
+## See also
 
 [send number](/reference/radio/send-number),
 [send value](/reference/radio/send-value),
 [send string](/reference/radio/send-string),
-[on data packet received](/reference/radio/on-data-packet-received)
+[on data packet received](/reference/radio/on-data-packet-received),
+[set transmit serial number](/reference/radio/set-transmit-serial-number)
 
 ```package
 radio
-```
+```

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

@@ -1,14 +1,20 @@
-# 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();
 ```
 
-### Data received format
+## ~ 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:
 
@@ -16,7 +22,7 @@ The format for received data printed to serial is as follows:
 - [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
+## Examples
 
 When ```radio``` data is received (after pressing the ``A`` button on
 the second @boardname@), this program sends temperature data to
@@ -36,7 +42,7 @@ Sample output to serial when ``A`` button pressed:
 {v:27,t:323,s:0}
 ```
 
-### See also
+## See also
 
 [send number](/reference/radio/send-number),
 [send value](/reference/radio/send-value),