Updating radio JSON writing API (#290)

docs/reference/radio.md

@@ -12,7 +12,7 @@ radio.onDataPacketReceived(() => {
 radio.setGroup(0);
 radio.setTransmitPower(7);
 radio.setTransmitSerialNumber(false);
-radio.writeValueToSerial();
+radio.writeReceivedPacketToSerial();
 ```
 
 ```package
@@ -28,4 +28,4 @@ radio
 [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)
+[writeReceivedPacketToSerial](/reference/radio/write-received-packet-to-serial)

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

@@ -0,0 +1,48 @@
+# 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
+
+The format for received data printed to serial is as follows:
+
+- [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
+
+When ```radio``` data is received (after pressing the ``A`` button on
+the second micro:bit), this program sends temperature data to
+serial.
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    radio.sendNumber(input.temperature());
+});
+radio.onDataPacketReceived(() => {
+    radio.writeReceivedPacketToSerial();
+});
+```
+Sample output to serial when ``A`` button pressed:
+
+```Text
+{v:27,t:323,s:0}
+```
+
+### 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)
+
+```package
+radio
+```

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

@@ -1,5 +1,7 @@
 # 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.
 
 ```sig

libs/radio/radio.cpp

@@ -100,6 +100,25 @@ namespace radio {
         return ManagedString().leakData();
     }
 
+    void writePacketAsJSON(uint8_t tp, int v, int s, int t, StringData* m) {
+        // Convert the packet to JSON and send over serial
+        uBit.serial.send("{");
+        uBit.serial.send("\"t\":");
+        uBit.serial.send(t);
+        uBit.serial.send(",\"s\":");
+        uBit.serial.send(s);
+        if (tp == PACKET_TYPE_STRING || tp == PACKET_TYPE_VALUE) {
+            uBit.serial.send(",\"n\":\"");
+            uBit.serial.send(m);
+            uBit.serial.send("\"");
+        }
+        if (tp == PACKET_TYPE_NUMBER || tp == PACKET_TYPE_VALUE) {
+            uBit.serial.send(",\"v\":");
+            uBit.serial.send(v);
+        }
+        uBit.serial.send("}\r\n");
+    }
+
     /**
      * Takes a packet from the micro:bit radio queue.
      * @param writeToSerial if true, write the received packet to serial without updating the global packet;
@@ -144,22 +163,7 @@ namespace radio {
             msg = m;
         }
         else {
-            // Convert the packet to JSON and send over serial
-            uBit.serial.send("{");
-            uBit.serial.send("\"t\":");
-            uBit.serial.send(t);
-            uBit.serial.send(",\"s\":");
-            uBit.serial.send(s);
-            if (tp == PACKET_TYPE_STRING || tp == PACKET_TYPE_VALUE) {
-                uBit.serial.send(",\"n\":\"");
-                uBit.serial.send(m);
-                uBit.serial.send("\"");
-            }
-            if (tp == PACKET_TYPE_NUMBER || tp == PACKET_TYPE_VALUE) {
-                uBit.serial.send(",\"v\":");
-                uBit.serial.send(v);
-            }
-            uBit.serial.send("}\r\n");
+            writePacketAsJSON(tp, v, s, t, m);
         }
     }
 
@@ -231,12 +235,25 @@ namespace radio {
     //% help=radio/write-value-to-serial
     //% weight=3
     //% blockId=radio_write_value_serial block="radio write value to serial"
-    //% advanced=true
+    //% deprecated=true
     void writeValueToSerial() {
         if (radioEnable() != MICROBIT_OK) return;
         receivePacket(true);
     }
 
+    /**
+    * Writes the last received packet to serial as JSON. This should be called
+    * within an ``onDataPacketReceived`` callback.
+    */
+    //% help=radio/write-received-packet-to-serial
+    //% weight=3
+    //% blockId=radio_write_packet_serial block="radio write received packet to serial"
+    //% advanced=true
+    void writeReceivedPacketToSerial() {
+        if (radioEnable() != MICROBIT_OK) return;
+        writePacketAsJSON(type, value, (int) serial, (int) time, msg);
+    }
+
     /**
      * Reads the next packet from the radio queue and returns the packet's number
      * payload or 0 if the packet did not contain a number.

libs/radio/shims.d.ts

@@ -40,9 +40,19 @@ declare namespace radio {
     //% help=radio/write-value-to-serial
     //% weight=3
     //% blockId=radio_write_value_serial block="radio write value to serial"
-    //% advanced=true shim=radio::writeValueToSerial
+    //% deprecated=true shim=radio::writeValueToSerial
     function writeValueToSerial(): void;
 
+    /**
+     * Writes the last received packet to serial as JSON. This should be called
+     * within an ``onDataPacketReceived`` callback.
+     */
+    //% help=radio/write-received-packet-to-serial
+    //% weight=3
+    //% blockId=radio_write_packet_serial block="radio write received packet to serial"
+    //% advanced=true shim=radio::writeReceivedPacketToSerial
+    function writeReceivedPacketToSerial(): void;
+
     /**
      * Reads the next packet from the radio queue and returns the packet's number
      * payload or 0 if the packet did not contain a number.

sim/state/radio.ts

@@ -138,21 +138,13 @@ namespace pxsim.radio {
     }
 
     export function writeValueToSerial(): void {
-        let b = board();
-        let p = b.radioState.bus.datagram.recv();
+        const b = board();
+        writePacketToSerial(b, b.radioState.bus.datagram.recv())
+    }
 
-        switch(p.payload.type) {
-            case PacketPayloadType.NUMBER:
-                b.writeSerial(`{"t":${p.time},"s":${p.serial},"v":${p.payload.numberData}}`)
-                break;
-            case PacketPayloadType.VALUE:
-                b.writeSerial(`{"t":${p.time},"s":${p.serial},"n":"${p.payload.stringData}","v":${p.payload.numberData}}`)
-                break;
-            case PacketPayloadType.STRING:
-                b.writeSerial(`{"t":${p.time},"s":${p.serial},"n":"${p.payload.stringData}"}`)
-                break;
-            default:
-        }
+    export function writeReceivedPacketToSerial(): void {
+        const b = board();
+        writePacketToSerial(b, b.radioState.bus.datagram.lastReceived);
     }
 
     export function sendValue(name: string, value: number) {
@@ -200,4 +192,19 @@ namespace pxsim.radio {
     export function receivedTime(): number {
         return board().radioState.bus.datagram.lastReceived.time;
     }
+
+    function writePacketToSerial(b: DalBoard, p: PacketBuffer) {
+        switch(p.payload.type) {
+            case PacketPayloadType.NUMBER:
+                b.writeSerial(`{"t":${p.time},"s":${p.serial},"v":${p.payload.numberData}}\r\n`)
+                break;
+            case PacketPayloadType.VALUE:
+                b.writeSerial(`{"t":${p.time},"s":${p.serial},"n":"${p.payload.stringData}","v":${p.payload.numberData}}\r\n`)
+                break;
+            case PacketPayloadType.STRING:
+                b.writeSerial(`{"t":${p.time},"s":${p.serial},"n":"${p.payload.stringData}"}\r\n`)
+                break;
+            default:
+        }
+    }
 }