Simulator iframe API changes (#40)

Breaking API change to accommodate radio/data log.

See updated README.md for detail.

A corresponding editor PR will be merged shortly.

Author: microbit-matt-hillsdon

README.md

@@ -64,15 +64,24 @@ The following sections documents the messages supported via postMessage.
 ```javascript
 {
   "kind": "ready",
-  "sensors": [
-    {
+  "state": {
+    "lightLevel": {
       "id": "lightLevel",
       "type": "range",
       "min": 0,
       "max": 255
+    },
+    "soundLevel": {
+      "id": "soundLevel",
+      "type": "range",
+      "min": 0,
+      "max": 255
+      // Microphone sensor has low (quiet) and high (loud) thresholds:
+      "lowThreshold": 50,
+      "highThreshold": 150
     }
-    // More sensors here.
-  ]
+    // Full state continues here.
+  }
 }
 ```
 
@@ -84,20 +93,36 @@ The following sections documents the messages supported via postMessage.
 
 ```javascript
 {
-  "kind": "sensor_change",
-  "sensors": [
-    {
-      "id": "lightLevel",
-      "type": "range",
-      "min": 0,
-      "max": 255
-    }
-    // More sensors here.
+  "kind": "state_change",
+  "change": {
+      "soundLevel": {
+        "id": "soundLevel",
+        "type": "range",
+        "min": 0,
+        "max": 255
+        // Microphone sensor has low (quiet) and high (loud) thresholds:
+        "lowThreshold": 50,
+        "highThreshold": 150
+      }
+      // Optionally, further top-level keys here.
+  }
   ]
 }
 ```
 
-<td>Sent when one or more sensors change. Note min/max and threshold values can change.
+<td>Sent when the simulator state changes. The keys are a subset of the original state. The values are always sent in full.
+
+<tr>
+<td>request_flash
+<td>
+
+```javascript
+{
+  "kind": "request_flash",
+}
+```
+
+<td>Sent when the user requests the simulator starts. The embedder should flash the latest code via the <code>flash</code> message.
 
 <tr>
 <td>serial_output
@@ -112,6 +137,20 @@ The following sections documents the messages supported via postMessage.
 
 <td>Serial output suitable for a terminal or other use.
 
+<tr>
+<td>radio_output
+<td>
+
+```javascript
+{
+  "kind": "radio_output",
+  "data": new Uint8Array([])
+}
+```
+
+<td>Radio output (sent from the user's program) as bytes.
+If you send string data from the program then it will be prepended with the three bytes 0x01, 0x00, 0x01.
+
 </table>
 
 ## Messages supported by the iframe
@@ -197,20 +236,36 @@ The following sections documents the messages supported via postMessage.
 }
 ```
 
-<td>Serial input. If the REPL is active it will echo this text via `serial_write`.
+<td>Serial input. If the REPL is active it will echo this text via <code>serial_write</code>.
 <tr>
 <td>sensor_set
 <td>
 
 ```javascript
 {
-  "kind": "sensor_set",
-  "sensor": "lightLevel",
+  "kind": "set_value",
+  "id": "lightLevel",
   "value": 255
 }
 ```
 
-<td>Set a sensor value.
+<td>Set a sensor, button or pin value. The sensor, button or pin is identified by the top-level key in the state. Buttons and pins (touch state) have 0 and 1 values. In future, analog values will be supported for pins.
+
+<tr>
+<td>radio_input
+<td>
+
+```javascript
+{
+  "kind": "radio_input",
+  "data": new Uint8Array([])
+}
+```
+
+<td>Radio input (received by the user's program as if sent from another micro:bit) as bytes.
+If you want to send string data then prepend the byte array with the three bytes <code>0x01</code>, <code>0x00</code>, <code>0x01</code>.
+Otherwise, the user will need to use <code>radio.receive_bytes</code> or <code>radio.receive_full</code>. The input is assumed to be sent to the currently configured radio group.
+
 </table>
 
 ## Web Assembly debugging

src/board/accelerometer.ts

@@ -1,57 +1,81 @@
 import { convertAccelerometerStringToNumber } from "./conversions";
-import { EnumSensor, RangeSensor } from "./sensors";
+import { EnumSensor, RangeSensor, State } from "./state";
 import { clamp } from "./util";
 
+type StateKeys =
+  | "accelerometerX"
+  | "accelerometerY"
+  | "accelerometerZ"
+  | "gesture";
+
+type GestureCallback = (v: number) => void;
+
 export class Accelerometer {
-  private gesture: EnumSensor;
-  private x: RangeSensor;
-  private y: RangeSensor;
-  private z: RangeSensor;
-  constructor(private onSensorChange: () => void) {
-    this.gesture = new EnumSensor(
-      "gesture",
-      [
-        "none",
-        "up",
-        "down",
-        "left",
-        "right",
-        "face up",
-        "face down",
-        "freefall",
-        "3g",
-        "6g",
-        "8g",
-        "shake",
-      ],
-      "none"
-    );
+  state: Pick<
+    State,
+    "accelerometerX" | "accelerometerY" | "accelerometerZ" | "gesture"
+  >;
+
+  private gestureCallback: GestureCallback | undefined;
+
+  constructor(private onChange: (changes: Partial<State>) => void) {
     const min = -2000;
     const max = 2000;
-    this.x = new RangeSensor("accelerometerX", min, max, 0, "mg");
-    this.y = new RangeSensor("accelerometerY", min, max, 0, "mg");
-    this.z = new RangeSensor("accelerometerZ", min, max, 0, "mg");
+    this.state = {
+      accelerometerX: new RangeSensor("accelerometerX", min, max, 0, "mg"),
+      accelerometerY: new RangeSensor("accelerometerY", min, max, 0, "mg"),
+      accelerometerZ: new RangeSensor("accelerometerZ", min, max, 0, "mg"),
+      gesture: new EnumSensor(
+        "gesture",
+        [
+          "none",
+          "up",
+          "down",
+          "left",
+          "right",
+          "face up",
+          "face down",
+          "freefall",
+          "3g",
+          "6g",
+          "8g",
+          "shake",
+        ],
+        "none"
+      ),
+    };
   }
 
-  get sensors() {
-    return [this.gesture, this.x, this.y, this.z];
+  setValue(id: StateKeys, value: any) {
+    this.state[id].setValue(value);
+    if (id === "gesture") {
+      this.gestureCallback!(
+        convertAccelerometerStringToNumber(this.state.gesture.value)
+      );
+    }
   }
 
   setRange(range: number) {
     const min = -1000 * range;
     const max = +1000 * range;
-    for (const sensor of [this.x, this.y, this.z]) {
+    const { accelerometerX, accelerometerY, accelerometerZ } = this.state;
+    for (const sensor of [accelerometerX, accelerometerY, accelerometerZ]) {
       sensor.value = clamp(sensor.value, min, max);
       sensor.min = min;
       sensor.max = max;
     }
-    this.onSensorChange();
+    this.onChange({
+      accelerometerX,
+      accelerometerY,
+      accelerometerZ,
+    });
   }
 
-  initialize(gestureCallback: (v: number) => void) {
-    this.gesture.onchange = (v: string) =>
-      gestureCallback(convertAccelerometerStringToNumber(v));
+  initialize(gestureCallback: GestureCallback) {
+    this.gestureCallback = gestureCallback;
   }
 
-  dispose() {}
+  dispose() {
+    this.gestureCallback = undefined;
+  }
 }

src/board/buttons.ts

@@ -1,32 +1,24 @@
-import { RangeSensor } from "./sensors";
+import { RangeSensor, State } from "./state";
 
 export class Button {
-  public button: RangeSensor;
+  public state: RangeSensor;
+
   private _presses: number = 0;
   private _mouseDown: boolean = false;
-  private _internalChange: boolean = false;
+
   private keyListener: (e: KeyboardEvent) => void;
   private mouseDownListener: (e: MouseEvent) => void;
   private mouseUpListener: (e: MouseEvent) => void;
   private mouseLeaveListener: (e: MouseEvent) => void;
 
   constructor(
+    private id: "buttonA" | "buttonB",
     private element: SVGElement,
     label: string,
-    private onSensorChange: () => void
+    private onChange: (change: Partial<State>) => void
   ) {
     this._presses = 0;
-    this.button = new RangeSensor(label, 0, 1, 0, undefined);
-    this.button.onchange = (_, curr: number): void => {
-      if (this._internalChange == true) {
-        this.onSensorChange();
-        this._internalChange = false;
-      }
-      if (curr) {
-        this._presses++;
-      }
-      this.render();
-    };
+    this.state = new RangeSensor(id, 0, 1, 0, undefined);
 
     this.element.setAttribute("role", "button");
     this.element.setAttribute("tabindex", "0");
@@ -39,10 +31,8 @@ export class Button {
         case " ":
           e.preventDefault();
           if (e.type === "keydown") {
-            this._internalChange = true;
             this.press();
           } else {
-            this._internalChange = true;
             this.release();
           }
       }
@@ -51,21 +41,18 @@ export class Button {
     this.mouseDownListener = (e) => {
       e.preventDefault();
       this._mouseDown = true;
-      this._internalChange = true;
       this.press();
     };
     this.mouseUpListener = (e) => {
       e.preventDefault();
       if (this._mouseDown) {
         this._mouseDown = false;
-        this._internalChange = true;
         this.release();
       }
     };
     this.mouseLeaveListener = (e) => {
       if (this._mouseDown) {
         this._mouseDown = false;
-        this._internalChange = true;
         this.release();
       }
     };
@@ -77,24 +64,43 @@ export class Button {
     this.element.addEventListener("mouseleave", this.mouseLeaveListener);
   }
 
+  setValue(value: any) {
+    this.setValueInternal(value, false);
+  }
+
+  private setValueInternal(value: any, internalChange: boolean) {
+    this.state.setValue(value);
+    if (value) {
+      this._presses++;
+    }
+    if (internalChange) {
+      this.onChange({
+        [this.id]: this.state,
+      });
+    }
+    this.render();
+  }
+
   press() {
-    this.button.setValue(
-      this.button.value === this.button.min ? this.button.max : this.button.min
+    this.setValueInternal(
+      this.state.value === this.state.min ? this.state.max : this.state.min,
+      true
     );
   }
 
   release() {
-    this.button.setValue(
-      this.button.value === this.button.max ? this.button.min : this.button.max
+    this.setValueInternal(
+      this.state.value === this.state.max ? this.state.min : this.state.max,
+      true
     );
   }
 
   isPressed() {
-    return !!this.button.value;
+    return !!this.state.value;
   }
 
   render() {
-    const fill = !!this.button.value ? "#d3b12c" : "none";
+    const fill = !!this.state.value ? "#d3b12c" : "none";
     this.element.querySelectorAll("circle").forEach((c) => {
       c.style.fill = fill;
     });

src/board/display.ts

@@ -1,13 +1,13 @@
 // This mapping is designed to give a set of 10 visually distinct levels.
 
-import { RangeSensor } from "./sensors";
+import { RangeSensor } from "./state";
 import { clamp } from "./util";
 
 // Carried across from microbit_hal_display_set_pixel.
 const brightMap = [0, 20, 40, 60, 80, 120, 160, 190, 220, 255];
 
 export class Display {
-  public lightLevel: RangeSensor = new RangeSensor(
+  lightLevel: RangeSensor = new RangeSensor(
     "lightLevel",
     0,
     255,