Add radio methods to replace the radio mutator (#773)

* Add radio methods to replace the object destructing behaviour

libs/radio/_locales/radio-jsdoc-strings.json

@@ -6,9 +6,14 @@
   "radio.Packet.serial": "The serial number of the sender of the packet or 0 if the sender did not sent their serial number.",
   "radio.Packet.signal": "The received signal strength indicator (RSSI) of the packet.",
   "radio.Packet.time": "The system time of the sender of the packet at the time the packet was sent.",
-  "radio.onReceivedNumber": "Registers code to run when the radio receives a packet. Also takes the\nreceived packet from the radio queue.",
+  "radio._packetProperty": "Gets a packet property.",
-  "radio.onReceivedString": "Registers code to run when the radio receives a packet. Also takes the\nreceived packet from the radio queue.",
+  "radio._packetProperty|param|type": "the packet property type, eg: PacketProperty.time",
-  "radio.onReceivedValue": "Registers code to run when the radio receives a packet. Also takes the\nreceived packet from the radio queue.",
+  "radio.getReceivedPacketProperty": "Returns properties of the last radio packet received.",
+  "radio.getReceivedPacketProperty|param|type": "the type of property to retrieve from the last packet",
+  "radio.onReceivedBuffer": "Registers code to run when the radio receives a buffer.",
+  "radio.onReceivedNumber": "Registers code to run when the radio receives a number.",
+  "radio.onReceivedString": "Registers code to run when the radio receives a string.",
+  "radio.onReceivedValue": "Registers code to run when the radio receives a key value pair.",
   "radio.receivedBuffer": "Returns the buffer payload from the last packet taken from the radio queue\n(via ``receiveNumber``, ``receiveString``, etc) or the empty string if that\npacket did not contain a string.",
   "radio.receivedNumber": "Returns the number payload from the last packet taken from the radio queue\n(via ``receiveNumber``, ``receiveString``, etc) or 0 if that packet did not\ncontain a number.",
   "radio.receivedSerial": "Returns the serial number of the sender micro:bit from the last packet taken\nfrom the radio queue (via ``receiveNumber``, ``receiveString``, etc) or 0 if\nthat packet did not send a serial number.",

libs/radio/_locales/radio-strings.json

@@ -1,6 +1,12 @@
 {
-  "radio.onReceivedNumber|block": "on radio received number",
+  "radio.PacketProperty.SerialNumber|block": "serial number",
-  "radio.onReceivedString|block": "on radio received string",
+  "radio.PacketProperty.SignalStrength|block": "signal strength",
+  "radio.PacketProperty.Time|block": "time",
+  "radio._packetProperty|block": "%note",
+  "radio.getReceivedPacketProperty|block": "received packet %type=radio_packet_property",
+  "radio.onReceivedBuffer|block": "on radio received",
+  "radio.onReceivedNumber|block": "on radio received",
+  "radio.onReceivedString|block": "on radio received",
   "radio.onReceivedValue|block": "on radio received",
   "radio.sendNumber|block": "radio send number %value",
   "radio.sendString|block": "radio send string %msg",

libs/radio/radio.ts

@@ -33,6 +33,18 @@ namespace radio {
         public signal: number;
     }
 
+    export enum PacketProperty {
+        //% blockIdentity=radio._packetProperty
+        //% block="time"
+        Time,
+        //% block="serial number"
+        //% blockIdentity=radio._packetProperty
+        SerialNumber,
+        //% blockIdentity=radio._packetProperty
+        //% block="signal strength"
+        SignalStrength
+    }
+
     /**
      * Registers code to run when the radio receives a packet. Also takes the
      * received packet from the radio queue.
@@ -52,63 +64,109 @@ namespace radio {
             packet.receivedString = receivedString();
             packet.receivedBuffer = receivedBuffer();
             packet.signal = receivedSignalStrength();
+            lastPacket = packet;
             cb(packet)
         });
     }
 
     /**
-     * Registers code to run when the radio receives a packet. Also takes the
+     * Registers code to run when the radio receives a number.
-     * received packet from the radio queue.
      */
     //% help=radio/on-radio-received-number
-    //% blockId=radio_on_number block="on radio received number" blockGap=8
+    //% blockId=radio_on_number block="on radio received" blockGap=8
-    export function onReceivedNumber(cb: (num: number, time?: number, serial?: number, signal?: number) => void) {
+    export function onReceivedNumber(cb: (receivedNumber: number) => void) {
         onDataReceived(() => {
             receiveNumber();
             const packet = new Packet();
+            packet.time = receivedTime();
+            packet.serial = receivedSerial();
+            packet.signal = receivedSignalStrength();
             packet.receivedNumber = receivedNumber();
-            packet.time = receivedTime();
+            lastPacket = packet;
-            packet.serial = receivedSerial();
+            cb(packet.receivedNumber);
-            packet.signal = receivedSignalStrength();
-            cb(packet.receivedNumber, packet.time, packet.serial, packet.signal);
         });
     }
 
     /**
-     * Registers code to run when the radio receives a packet. Also takes the
+     * Registers code to run when the radio receives a key value pair.
-     * received packet from the radio queue.
-     */
-    //% help=radio/on-radio-received-string
-    //% blockId=radio_on_string block="on radio received string" blockGap=8
-    export function onReceivedString(cb: (received: string, time?: number, serial?: number, signal?: number) => void) {
-        onDataReceived(() => {
-            receiveNumber();
-            const packet = new Packet();
-            packet.time = receivedTime();
-            packet.serial = receivedSerial();
-            packet.signal = receivedSignalStrength();
-            packet.receivedString = receivedString();
-            cb(packet.receivedString, packet.time, packet.serial, packet.signal);
-        });
-    }
-
-    /**
-     * Registers code to run when the radio receives a packet. Also takes the
-     * received packet from the radio queue.
      */
     //% help=radio/on-radio-received-value
     //% blockId=radio_on_value block="on radio received" blockGap=8
-    export function onReceivedValue(cb: (packet: Packet) => void) {
+    export function onReceivedValue(cb: (name: string, value: number) => void) {
         onDataReceived(() => {
             receiveNumber();
             const packet = new Packet();
+            packet.time = receivedTime();
+            packet.serial = receivedSerial();
+            packet.signal = receivedSignalStrength();
             packet.receivedNumber = receivedNumber();
+            packet.receivedString = receivedString();
+            lastPacket = packet;
+            cb(packet.receivedString, packet.receivedNumber)
+        });
+    }
+
+    /**
+     * Registers code to run when the radio receives a string.
+     */
+    //% help=radio/on-radio-received-string
+    //% blockId=radio_on_string block="on radio received" blockGap=8
+    export function onReceivedString(cb: (receivedString: string) => void) {
+        onDataReceived(() => {
+            receiveNumber();
+            const packet = new Packet();
             packet.time = receivedTime();
             packet.serial = receivedSerial();
             packet.signal = receivedSignalStrength();
             packet.receivedString = receivedString();
-            cb(packet)
+            lastPacket = packet;
+            cb(packet.receivedString);
         });
+    }
 
+    /**
+     * Registers code to run when the radio receives a buffer.
+     */
+    //% help=radio/on-radio-received-buffer blockHidden=1
+    //% blockId=radio_on_buffer block="on radio received" blockGap=8
+    export function onReceivedBuffer(cb: (buffer: Buffer) => void) {
+        onDataReceived(() => {
+            receiveNumber();
+            const packet = new Packet();
+            packet.time = receivedTime();
+            packet.serial = receivedSerial();
+            packet.signal = receivedSignalStrength();
+            packet.receivedBuffer = receivedBuffer();
+            lastPacket = packet;
+            cb(packet.receivedBuffer)
+        });
+    }
+
+    let lastPacket: Packet;
+    /**
+     * Returns properties of the last radio packet received.
+     * @param type the type of property to retrieve from the last packet
+     */
+    //% help=radio/get-received-packet-property advanced=true
+    //% blockId=radio_received_packet_property block="received packet %type=radio_packet_property" blockGap=8
+    export function getReceivedPacketProperty(type: number) {
+        if (lastPacket) {
+            switch(type) {
+                case PacketProperty.Time: return lastPacket.time;
+                case PacketProperty.SerialNumber: return lastPacket.serial;
+                case PacketProperty.SignalStrength: return lastPacket.signal;
+            }
+        }
+        return 0;
+    }
+
+    /**
+     * Gets a packet property.
+     * @param type the packet property type, eg: PacketProperty.time
+     */
+    //% blockId=radio_packet_property block="%note"
+    //% shim=TD_ID blockHidden=1
+    export function _packetProperty(type: PacketProperty): number {
+        return type;
     }
 }

package.json

@@ -43,6 +43,6 @@
     "@types/node": "8.0.53"
   },
   "dependencies": {
-    "pxt-core": "3.10.16"
+    "pxt-core": "3.14.4"
   }
 }

pxtarget.json

@@ -32,50 +32,55 @@
         "flashEnd": 245760,
         "flashCodeAlign": 1024,
         "floatingPoint": true,
-        "upgrades": [
+        "patches": {
-            {
+            "0.0.0 - 1.0.0": [
-                "type": "package",
+                {
-                "map": {
+                    "type": "package",
-                    "microbit": "core",
+                    "map": {
-                    "microbit-bluetooth": "bluetooth",
+                        "microbit": "core",
-                    "microbit-radio": "radio",
+                        "microbit-bluetooth": "bluetooth",
-                    "microbit-devices": "devices",
+                        "microbit-radio": "radio",
-                    "microbit-led": "",
+                        "microbit-devices": "devices",
-                    "microbit-music": "",
+                        "microbit-led": "",
-                    "microbit-game": "",
+                        "microbit-music": "",
-                    "microbit-pins": "",
+                        "microbit-game": "",
-                    "microbit-serial": ""
+                        "microbit-pins": "",
+                        "microbit-serial": ""
+                    }
+                },
+                {
+                    "type": "missingPackage",
+                    "map": {
+                        "radio\\s*\\.": "radio",
+                        "bluetooth\\s*\\.": "bluetooth",
+                        "devices\\s*\\.": "devices"
+                    }
+                },
+                {
+                    "type": "api",
+                    "map": {
+                        "bluetooth\\s*\\.uartRead\\s*\\((.*?)\\)": "bluetooth.uartReadUntil($1)",
+                        "bluetooth\\s*\\.uartWrite\\s*\\((.*?)\\)": "bluetooth.uartWriteUntil($1)",
+                        "input\\s*\\.calibrate\\s*\\(": "input.calibrateCompass(",
+                        "radio\\s*\\.onDataPacketReceived\\(\\s*\\(\\{\\s*receivedNumber\\s*\\}\\)\\s*=>\\s*\\{": "radio.onReceivedNumber(function (receivedNumber) {",
+                        "radio\\s*\\.onDataPacketReceived\\(\\s*\\(\\{\\s*receivedString: name, receivedNumber: value\\s*\\}\\)\\s*=>\\s*\\{": "radio.onReceivedValue(function (name, value) {",
+                        "radio\\s*\\.onDataPacketReceived\\(\\s*\\(\\{\\s*receivedString\\s*\\}\\)\\s*=>\\s*\\{": "radio.onReceivedString(function (receivedString) {"
+                    }
+                },
+                {
+                    "type": "blockId",
+                    "map": {
+                        "device_get_acceleration": "device_acceleration"
+                    }
+                },
+                {
+                    "type": "blockValue",
+                    "map": {
+                        "device_print_message.message": "text"
+                    }
                 }
-            },
+            ]
-            {
+        },
-                "type": "missingPackage",
-                "map": {
-                    "radio\\s*\\.": "radio",
-                    "bluetooth\\s*\\.": "bluetooth",
-                    "devices\\s*\\.": "devices"
-                }
-            },
-            {
-                "type": "api",
-                "map": {
-                    "bluetooth\\s*\\.uartRead\\s*\\((.*?)\\)": "bluetooth.uartReadUntil($1)",
-                    "bluetooth\\s*\\.uartWrite\\s*\\((.*?)\\)": "bluetooth.uartWriteUntil($1)",
-                    "input\\s*\\.calibrate\\s*\\(": "input.calibrateCompass("
-                }
-            },
-            {
-                "type": "blockId",
-                "map": {
-                    "device_get_acceleration": "device_acceleration"
-                }
-            },
-            {
-                "type": "blockValue",
-                "map": {
-                    "device_print_message.message": "text"
-                }
-            }
-        ],
         "hidSelectors": [
             {
                 "usagePage": "0xFF00",