radio.setFrequencyBand support (#2495)

* setfrequencyband support

* revert line change

* add bounds check

docs/reference/radio/set-frequency-band.md

@@ -0,0 +1,34 @@
+# set Frequency Band
+
+Change the transmission and reception band of the radio to the given channel. Default is 7.
+
+```sig
+radio.setFrequencyBand(50);
+```
+
+## Parameters
+
+* ``band`` is a [number](/types/number) between ``0`` and ``83``. Each step is 1MHz wide, based at 2400MHz.
+
+## Simulator
+
+This function only works on the @boardname@, not in browsers.
+
+## Example
+
+This program makes the ``radio`` use frequency band 50.
+
+```blocks
+radio.setFrequencyBand(50)
+```
+
+## See also
+
+[received packet](/reference/radio/received-packet),
+[send number](/reference/radio/send-number),
+[send value](/reference/radio/send-value),
+[send string](/reference/radio/send-string)
+
+```package
+radio
+```

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

@@ -37,6 +37,8 @@
   "radio.sendValue": "Broadcasts a name / value pair along with the device serial number\nand running time to any connected micro:bit in the group. The name can\ninclude no more than 8 characters.",
   "radio.sendValue|param|name": "the field name (max 8 characters), eg: \"name\"",
   "radio.sendValue|param|value": "the numeric value",
+  "radio.setFrequencyBand": "Change the transmission and reception band of the radio to the given channel",
+  "radio.setFrequencyBand|param|band": "a frequency band in the range 0 - 83. Each step is 1MHz wide, based at 2400MHz.",
   "radio.setGroup": "Sets the group id for radio communications. A micro:bit can only listen to one group ID at any time.",
   "radio.setGroup|param|id": "the group id between ``0`` and ``255``, eg: 1",
   "radio.setTransmitPower": "Change the output power level of the transmitter to the given value.",

libs/radio/_locales/radio-strings.json

@@ -21,6 +21,7 @@
   "radio.sendNumber|block": "radio send number %value",
   "radio.sendString|block": "radio send string %msg",
   "radio.sendValue|block": "radio send|value %name|= %value",
+  "radio.setFrequencyBand|block": "radio set frequency band %band",
   "radio.setGroup|block": "radio set group %ID",
   "radio.setTransmitPower|block": "radio set transmit power %power",
   "radio.setTransmitSerialNumber|block": "radio set transmit serial number %transmit",

libs/radio/radio.cpp

@@ -109,4 +109,18 @@ namespace radio {
 
         uBit.radio.setTransmitPower(power);
     }
+
+    /**
+    * Change the transmission and reception band of the radio to the given channel
+    * @param band a frequency band in the range 0 - 83. Each step is 1MHz wide, based at 2400MHz.
+    **/
+    //% help=radio/set-frequency-band
+    //% weight=8 blockGap=8
+    //% blockId=radio_set_frequency_band block="radio set frequency band %band"
+    //% band.min=0 band.max=83
+    //% advanced=true
+    void setFrequencyBand(int band) {
+        if (radioEnable() != MICROBIT_OK) return;
+        uBit.radio.setFrequencyBand(band);
+    }
 }

libs/radio/shims.d.ts

@@ -56,6 +56,17 @@ declare namespace radio {
     //% power.min=0 power.max=7
     //% advanced=true shim=radio::setTransmitPower
     function setTransmitPower(power: int32): void;
+
+    /**
+     * Change the transmission and reception band of the radio to the given channel
+     * @param band a frequency band in the range 0 - 83. Each step is 1MHz wide, based at 2400MHz.
+     **/
+    //% help=radio/set-frequency-band
+    //% weight=8 blockGap=8
+    //% blockId=radio_set_frequency_band block="radio set frequency band %band"
+    //% band.min=0 band.max=83
+    //% advanced=true shim=radio::setFrequencyBand
+    function setFrequencyBand(band: int32): void;
 }
 
 // Auto-generated. Do not edit. Really.

sim/state/radio.ts

@@ -58,11 +58,13 @@ namespace pxsim {
         transmitSerialNumber = false;
         datagram: RadioDatagram;
         groupId: number;
+        band: number;
 
         constructor(runtime: Runtime) {
             this.datagram = new RadioDatagram(runtime);
             this.power = 6; // default value
             this.groupId = 0;
+            this.band = 7; // https://github.com/lancaster-university/microbit-dal/blob/master/inc/core/MicroBitConfig.h#L320
         }
 
         public setGroup(id: number) {
@@ -70,6 +72,7 @@ namespace pxsim {
         }
 
         setTransmitPower(power: number) {
+            power = power | 0;
             this.power = Math.max(0, Math.min(7, power));
         }
 
@@ -77,6 +80,12 @@ namespace pxsim {
             this.transmitSerialNumber = !!sn;
         }
 
+        setFrequencyBand(band: number) {
+            band = band | 0;
+            if (band < 0 || band > 83) return;
+            this.band = band;
+        }
+
         raiseEvent(id: number, eventid: number) {
             Runtime.postMessage(<SimulatorEventBusMessage>{
                 type: "eventbus",
@@ -108,6 +117,10 @@ namespace pxsim.radio {
         board().radioState.setTransmitPower(power);
     }
 
+    export function setFrequencyBand(band: number) { 
+        board().radioState.setFrequencyBand(band);
+    }
+
     export function sendRawPacket(buf: RefBuffer) {
         let cb = getResume();
         board().radioState.datagram.send({