scratch like broadcast api (#1358)

* scratch like broadcast api

* always register handler

* adding docs

* added icon

* updated block name

* adding DAL support "radio.raiseEvent"

* typo

* implemented using radiobus

* adding docs

* adding raise event block

* updated shims

* updated pxt

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

@@ -0,0 +1,6 @@
+{
+  "radio": "Communicate data using radio packets",
+  "radio.onReceivedMessage": "Registers code to run for a particular message",
+  "radio.onReceivedMessage|param|msg": "@param handler ",
+  "radio.sendMessage": "Broadcasts a message over radio"
+}

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

@@ -0,0 +1,6 @@
+{
+  "radio.onReceivedMessage|block": "on radio $msg received",
+  "radio.sendMessage|block": "radio send $msg",
+  "radio|block": "radio",
+  "{id:category}Radio": "Radio"
+}

libs/radio-broadcast/docs/reference/radio/on-received-message.md

@@ -0,0 +1,45 @@
+# on Received Message
+
+Run part of a program when the @boardname@ receives a
+message over ``radio``.
+
+```sig
+radio.onReceivedMessage(0, function() {})
+```
+
+## Parameters
+
+* **msg**: The message to listen for. See [send message](/reference/radio/send-message)
+
+## Examples
+
+## Example: Broadcasting heart or skull
+
+Sends a ``heart`` message when ``A`` is pressed, ``skull`` when ``B`` is pressed. On the side, display heart or skull for the message.
+
+```blocks
+enum RadioMessage {
+    heart,
+    skull
+}
+input.onButtonPressed(Button.A, function () {
+    radio.sendMessage(RadioMessage.heart)
+})
+input.onButtonPressed(Button.B, function () {
+    radio.sendMessage(RadioMessage.skull)
+})
+radio.onReceivedMessage(RadioMessage.heart, function () {
+    basic.showIcon(IconNames.Heart)
+})
+radio.onReceivedMessage(RadioMessage.skull, function () {
+    basic.showIcon(IconNames.Skull)
+})
+```
+
+## See also
+
+[send message](/reference/radio/send-message),
+
+```package
+radio-broadcast
+```

libs/radio-broadcast/docs/reference/radio/send-message.md

@@ -0,0 +1,43 @@
+# send Message
+
+Broadcast a coded message to other @boardname@s connected via ``radio``.
+
+```sig
+radio.sendMessage(0);
+```
+
+## Parameters
+
+* **msg**: a coded message.
+
+
+## Example: Broadcasting heart or skull
+
+Sends a ``heart`` message when ``A`` is pressed, ``skull`` when ``B`` is pressed. On the side, display heart or skull for the message.
+
+```blocks
+enum RadioMessage {
+    heart,
+    skull
+}
+input.onButtonPressed(Button.A, function () {
+    radio.sendMessage(RadioMessage.heart)
+})
+input.onButtonPressed(Button.B, function () {
+    radio.sendMessage(RadioMessage.skull)
+})
+radio.onReceivedMessage(RadioMessage.heart, function () {
+    basic.showIcon(IconNames.Heart)
+})
+radio.onReceivedMessage(RadioMessage.skull, function () {
+    basic.showIcon(IconNames.Skull)
+})
+```
+
+## See also
+
+[on received number](/reference/radio/on-received-number)
+
+```package
+radio-broadcast
+```

libs/radio-broadcast/pxt.json

@@ -0,0 +1,11 @@
+{
+    "name": "radio-broadcast",
+    "files": [
+        "pxt.json",
+        "radio-broadcast.ts"
+    ],
+    "dependencies": {
+        "core": "file:../core",
+        "radio": "file:../radio"
+    }
+}

libs/radio-broadcast/radio-broadcast.ts

@@ -0,0 +1,38 @@
+namespace radio {
+    /**
+     * Gets the message code
+     */
+    //% blockHidden=1 shim=ENUM_GET
+    //% blockId=radioMessageCode block="$msg" enumInitialMembers="message1"
+    //% enumName=RadioMessage enumMemberName=msg enumPromptHint="e.g. Start, Stop, Jump..."
+    export function __message(msg: number): number {
+        return msg;
+    }
+
+    /**
+     * Broadcasts a message over radio
+     * @param msg 
+     */
+    //% blockId=radioBroadcastMessage block="radio send $msg"
+    //% msg.shadow=radioMessageCode draggableParameters
+    //% weight=200
+    //% blockGap=8
+    //% help=radio/send-message
+    export function sendMessage(msg: number): void {
+        // 0 is MICROBIT_EVT_ANY, shifting by 1
+        radio.raiseEvent(DAL.MES_BROADCAST_GENERAL_ID, msg + 1);
+    }
+
+    /**
+     * Registers code to run for a particular message
+     * @param msg 
+     * @param handler 
+     */
+    //% blockId=radioOnMessageReceived block="on radio $msg received"
+    //% msg.shadow=radioMessageCode draggableParameters
+    //% weight=199
+    //% help=radio/on-received-message
+    export function onReceivedMessage(msg: number, handler: () => void) {
+        control.onEvent(DAL.MES_BROADCAST_GENERAL_ID, msg + 1, handler);
+    }
+}

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

@@ -16,6 +16,7 @@
   "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.raiseEvent": "Sends an event over radio to neigboring devices",
   "radio.receiveNumber": "Reads the next packet from the radio queue and returns the packet's number\npayload or 0 if the packet did not contain a number.",
   "radio.receiveString": "Reads the next packet from the radio queue and returns the packet's string\npayload or the empty string if the packet did not contain a string.",
   "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.",

libs/radio/_locales/radio-strings.json

@@ -10,6 +10,7 @@
   "radio.onReceivedNumber|block": "on radio received",
   "radio.onReceivedString|block": "on radio received",
   "radio.onReceivedValue|block": "on radio received",
+  "radio.raiseEvent|block": "radio raise event|from source %src=control_event_source_id|with value %value=control_event_value_id",
   "radio.receiveNumber|block": "radio receive number",
   "radio.receiveString|block": "radio receive string",
   "radio.receivedSignalStrength|block": "radio received signal strength",

libs/radio/radio.cpp

@@ -59,14 +59,17 @@ namespace radio {
         return r;
     }
 
-    void broadcastMessage(int message) {
+    /**
+    * Sends an event over radio to neigboring devices
+    */
+    //% blockId=radioRaiseEvent block="radio raise event|from source %src=control_event_source_id|with value %value=control_event_value_id" 
+    //% blockExternalInputs=1
+    //% advanced=true
+    //% weight=1
+    //% help=radio/raise-event
+    void raiseEvent(int src, int value) {
         if (radioEnable() != MICROBIT_OK) return;
-        uBit.radio.event.eventReceived(MicroBitEvent(MES_BROADCAST_GENERAL_ID, message, CREATE_ONLY));
-    }
-
-    void onBroadcastMessageReceived(int message, Action f) {
-        if (radioEnable() != MICROBIT_OK) return;
-        registerWithDal(MES_BROADCAST_GENERAL_ID, message, f);
+        uBit.radio.event.eventReceived(MicroBitEvent(src, value, CREATE_ONLY));
     }
 
     void setPacketPrefix(uint8_t* buf, int type) {

libs/radio/shims.d.ts

@@ -5,6 +5,16 @@
     //% color=#E3008C weight=96 icon="\uf012"
 declare namespace radio {
 
+    /**
+     * Sends an event over radio to neigboring devices
+     */
+    //% blockId=radioRaiseEvent block="radio raise event|from source %src=control_event_source_id|with value %value=control_event_value_id" 
+    //% blockExternalInputs=1
+    //% advanced=true
+    //% weight=1
+    //% help=radio/raise-event shim=radio::raiseEvent
+    function raiseEvent(src: int32, value: int32): void;
+
     /**
      * Broadcasts a number over radio to any connected micro:bit in the group.
      */