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

docs/reference/control/raise-event.md

@@ -8,3 +8,7 @@ control.raiseEvent(control.eventSourceId(EventBusSource.MICROBIT_ID_BUTTON_A), c
 
 **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
+
+[radio raise event](/reference/radio/raise-event)

docs/reference/radio.md

@@ -14,6 +14,7 @@ radio.setTransmitPower(7);
 radio.setTransmitSerialNumber(false);
 radio.writeReceivedPacketToSerial();
 radio.sendBuffer(null);
+radio.raiseEvent(0, 0);
 ```
 
 ```package
@@ -32,4 +33,5 @@ radio
 [setGroup](/reference/radio/set-group),
 [setTransmitPower](/reference/radio/set-transmit-power),
 [setTransmitSerialNumber](/reference/radio/set-transmit-serial-number),
-[writeReceivedPacketToSerial](/reference/radio/write-received-packet-to-serial)
+[writeReceivedPacketToSerial](/reference/radio/write-received-packet-to-serial),
+[raiseEvent](/reference/radio/raise-event)

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)

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.
      */

package.json

@@ -42,6 +42,6 @@
   },
   "dependencies": {
     "pxt-common-packages": "0.24.2",
-    "pxt-core": "4.1.20"
+    "pxt-core": "4.1.21"
   }
 }

pxtarget.json

@@ -10,7 +10,8 @@
         "libs/radio",
         "libs/devices",
         "libs/bluetooth",
-        "libs/servo"
+        "libs/servo",
+        "libs/radio-broadcast"
     ],
     "cloud": {
         "workspace": false,

sim/dalboard.ts

@@ -102,15 +102,15 @@ namespace pxsim {
 
             switch (msg.type || "") {
                 case "eventbus":
-                    let ev = <SimulatorEventBusMessage>msg;
+                    const ev = <SimulatorEventBusMessage>msg;
                     this.bus.queue(ev.id, ev.eventid, ev.value);
                     break;
                 case "serial":
-                    let data = (<SimulatorSerialMessage>msg).data || "";
+                    const data = (<SimulatorSerialMessage>msg).data || "";
                     this.serialState.receiveData(data);
                     break;
                 case "radiopacket":
-                    let packet = <SimulatorRadioPacketMessage>msg;
+                    const packet = <SimulatorRadioPacketMessage>msg;
                     this.radioState.receivePacket(packet);
                     break;
             }

sim/state/radio.ts

@@ -30,7 +30,7 @@ namespace pxsim {
             Runtime.postMessage(<SimulatorRadioPacketMessage>{
                 type: "radiopacket",
                 rssi: -42, // -42 is the strongest signal
-                serial: b.radioState.bus.transmitSerialNumber ? pxsim.control.deviceSerialNumber() : 0,
+                serial: b.radioState.transmitSerialNumber ? pxsim.control.deviceSerialNumber() : 0,
                 time: new Date().getTime(),
                 payload
             })
@@ -52,15 +52,20 @@ namespace pxsim {
         }
     }
 
-    export class RadioBus {
-        // uint8_t radioDefaultGroup = MICROBIT_RADIO_DEFAULT_GROUP;
+    export class RadioState {
         power = 0;
         transmitSerialNumber = false;
         datagram: RadioDatagram;
+        groupId: number;
 
-        constructor(private runtime: Runtime) {
+        constructor(runtime: Runtime) {
             this.datagram = new RadioDatagram(runtime);
             this.power = 6; // default value
+            this.groupId = 0;
+        }
+
+        public setGroup(id: number) {
+            this.groupId = id & 0xff; // byte only
         }
 
         setTransmitPower(power: number) {
@@ -71,37 +76,19 @@ namespace pxsim {
             this.transmitSerialNumber = !!sn;
         }
 
-        broadcast(msg: number, groupId: number) {
+        raiseEvent(id: number, eventid: number) {
             Runtime.postMessage(<SimulatorEventBusMessage>{
-                type: "event",
-                id: DAL.MES_BROADCAST_GENERAL_ID,
-                eventid: msg,
+                type: "eventbus",
+                id,
+                eventid,
                 power: this.power,
-                group: groupId
+                group: this.groupId
             })
         }
-    }
 
-    export class RadioState {
-        bus: RadioBus;
-        groupId: number;
-
-        constructor(runtime: Runtime) {
-            this.bus = new RadioBus(runtime);
-            this.groupId = 0;
-        }
-
-        public setGroup(id: number) {
-            this.groupId = id & 0xff; // byte only
-        }
-
-        public broadcast(msg: number) {
-            this.bus.broadcast(msg, this.groupId)
-        }
-
-        public receivePacket(packet: SimulatorRadioPacketMessage) {
+        receivePacket(packet: SimulatorRadioPacketMessage) {
             if (this.groupId == packet.payload.groupId)
-                this.bus.datagram.queue(packet)
+                this.datagram.queue(packet)
         }
     }
 }
@@ -114,12 +101,8 @@ namespace pxsim.radio {
         BUFFER = 3
     }
 
-    export function broadcastMessage(msg: number): void {
-        board().radioState.broadcast(msg);
-    }
-
-    export function onBroadcastMessageReceived(msg: number, handler: RefAction): void {
-        pxtcore.registerWithDal(DAL.MES_BROADCAST_GENERAL_ID, msg, handler);
+    export function raiseEvent(id: number, eventid: number): void {
+        board().radioState.raiseEvent(id, eventid);
     }
 
     export function setGroup(id: number): void {
@@ -127,15 +110,15 @@ namespace pxsim.radio {
     }
 
     export function setTransmitPower(power: number): void {
-        board().radioState.bus.setTransmitPower(power);
+        board().radioState.setTransmitPower(power);
     }
 
     export function setTransmitSerialNumber(transmit: boolean): void {
-        board().radioState.bus.setTransmitSerialNumber(transmit);
+        board().radioState.setTransmitSerialNumber(transmit);
     }
 
     export function sendNumber(value: number): void {
-        board().radioState.bus.datagram.send({
+        board().radioState.datagram.send({
             type: PacketPayloadType.NUMBER,
             groupId: board().radioState.groupId,
             numberData: value,
@@ -146,7 +129,7 @@ namespace pxsim.radio {
         if (msg === undefined) return;
 
         msg = msg.substr(0, 19);
-        board().radioState.bus.datagram.send({
+        board().radioState.datagram.send({
             type: PacketPayloadType.STRING,
             groupId: board().radioState.groupId,
             stringData: msg,
@@ -157,7 +140,7 @@ namespace pxsim.radio {
         if (!buf) return;
 
         const data = buf.data.slice(0, 18);
-        board().radioState.bus.datagram.send({
+        board().radioState.datagram.send({
             type: PacketPayloadType.STRING,
             groupId: board().radioState.groupId,
             bufferData: data
@@ -166,19 +149,19 @@ namespace pxsim.radio {
 
     export function writeValueToSerial(): void {
         const b = board();
-        writePacketToSerial(b, b.radioState.bus.datagram.recv())
+        writePacketToSerial(b, b.radioState.datagram.recv())
     }
 
     export function writeReceivedPacketToSerial(): void {
         const b = board();
-        writePacketToSerial(b, b.radioState.bus.datagram.lastReceived);
+        writePacketToSerial(b, b.radioState.datagram.lastReceived);
     }
 
     export function sendValue(name: string, value: number) {
         name = name.substr(0, 12);
         const msg: number[] = [];
         msg.push()
-        board().radioState.bus.datagram.send({
+        board().radioState.datagram.send({
             type: PacketPayloadType.VALUE,
             groupId: board().radioState.groupId,
             stringData: name,
@@ -187,17 +170,17 @@ namespace pxsim.radio {
     }
 
     export function receiveNumber(): number {
-        const packet = board().radioState.bus.datagram.recv();
+        const packet = board().radioState.datagram.recv();
         return receivedNumber();
     }
 
     export function receiveString(): string {
-        const packet = board().radioState.bus.datagram.recv();
+        const packet = board().radioState.datagram.recv();
         return receivedString();
     }
 
     export function receivedSignalStrength(): number {
-        return board().radioState.bus.datagram.lastReceived.rssi;
+        return board().radioState.datagram.lastReceived.rssi;
     }
 
     export function onDataReceived(handler: RefAction): void {
@@ -206,23 +189,23 @@ namespace pxsim.radio {
     }
 
     export function receivedNumber(): number {
-        return board().radioState.bus.datagram.lastReceived.payload.numberData || 0;
+        return board().radioState.datagram.lastReceived.payload.numberData || 0;
     }
 
     export function receivedSerial(): number {
-        return board().radioState.bus.datagram.lastReceived.serial;
+        return board().radioState.datagram.lastReceived.serial;
     }
 
     export function receivedString(): string {
-        return initString(board().radioState.bus.datagram.lastReceived.payload.stringData || "");
+        return initString(board().radioState.datagram.lastReceived.payload.stringData || "");
     }
 
     export function receivedBuffer(): RefBuffer {
-        return new RefBuffer(board().radioState.bus.datagram.lastReceived.payload.bufferData || new Uint8Array(0))
+        return new RefBuffer(board().radioState.datagram.lastReceived.payload.bufferData || new Uint8Array(0))
     }
 
     export function receivedTime(): number {
-        return board().radioState.bus.datagram.lastReceived.time;
+        return board().radioState.datagram.lastReceived.time;
     }
 
     function writePacketToSerial(b: DalBoard, p: PacketBuffer) {

sim/visuals/microbit.ts

@@ -854,6 +854,9 @@ path.sim-board {
                 switch (msg.type || "") {
                     case "serial": this.flashSystemLed(); break;
                     case "radiopacket": this.flashAntenna(); break;
+                    case "eventbus":
+                        if ((<pxsim.SimulatorEventBusMessage>msg).id == DAL.MES_BROADCAST_GENERAL_ID)
+                            this.flashAntenna(); break;
                 }
             }
             let tiltDecayer = 0;