Calibrate compass (#392)

* adding 'calibrate-compass' function

* fixing simulator.

* updated docs

* fixing compat test suite with 'calibrate()' function

docs/reference/input.md

@@ -22,7 +22,6 @@ input.rotation(Rotation.Pitch);
 input.magneticForce(Dimension.X);
 input.runningTime();
 input.setAccelerometerRange(AcceleratorRange.OneG);
-input.calibrate();
 input.onLogoDown(() => {
     
 });
@@ -42,4 +41,4 @@ input.onShake(() => {
 
 ### See Also
 
-[onButtonPressed](/reference/input/on-button-pressed), [onGesture](/reference/input/on-gesture), [onPinPressed](/reference/input/on-pin-pressed), [buttonIsPressed](/reference/input/button-is-pressed), [compassHeading](/reference/input/compass-heading), [pinIsPressed](/reference/input/pin-is-pressed), [temperature](/reference/input/temperature), [acceleration](/reference/input/acceleration), [lightLevel](/reference/input/light-level), [rotation](/reference/input/rotation), [magneticForce](/reference/input/magnetic-force), [runningTime](/reference/input/running-time), [setAccelerometerRange](/reference/input/set-accelerometer-range)
+[onButtonPressed](/reference/input/on-button-pressed), [onGesture](/reference/input/on-gesture), [onPinPressed](/reference/input/on-pin-pressed), [buttonIsPressed](/reference/input/button-is-pressed), [compassHeading](/reference/input/compass-heading), [pinIsPressed](/reference/input/pin-is-pressed), [temperature](/reference/input/temperature), [acceleration](/reference/input/acceleration), [lightLevel](/reference/input/light-level), [rotation](/reference/input/rotation), [magneticForce](/reference/input/magnetic-force), [runningTime](/reference/input/running-time), [setAccelerometerRange](/reference/input/set-accelerometer-range), [calibrate-compass](/reference/input/calibrate-compass)

docs/reference/input/calibrate-compass.md

@@ -0,0 +1,29 @@
+# Calibrate Compass
+
+Runs the compass calibration sequence.
+
+```sig
+input.calibrateCompass();
+```
+
+### Calibration
+
+The calibration will ask you to draw a circle by tilting the
+@boardname@.
+
+If you are calibrating or using the compass near metal, it might
+confuse the @boardname@.
+
+### Example
+
+This example runs the calibration when the user presses **A+B** buttons.
+
+```blocks
+input.onButtonPressed(Button.AB, () => {
+    input.calibrateCompass();
+})
+```
+
+### See also
+
+[compassHeading](/reference/input/compass-heading)

docs/reference/input/compass-heading.md

@@ -52,13 +52,25 @@ basic.forever(() => {
 ### Calibration
 
 Every time you start to use the compass (for example, if you have just
-turned the @boardname@ on), the @boardname@ will start to **calibrate**
+turned the @boardname@ on), the @boardname@ will start to [calibrateCompass](/reference/input/calibrate-compass)
 (adjust itself).  It will ask you to draw a circle by tilting the
 @boardname@.
 
 If you are calibrating or using the compass near metal, it might
 confuse the @boardname@.
 
+### ~ hint
+
+Keep the calibration handy by running it when the user pressed **A+B**.
+
+```block
+input.onButtonPressed(Button.AB, () => {
+    input.calibrateCompass();
+})
+```
+
+### ~
+
 ### See also
 
-[acceleration](/reference/input/acceleration)
+[acceleration](/reference/input/acceleration), [calibrateCompass](/reference/input/calibrate-compass)

docs/reference/music.md

@@ -10,8 +10,6 @@ music.beat(BeatFraction.Whole);
 music.tempo();
 music.changeTempoBy(20);
 music.setTempo(120);
-music.onEvent(MusicEvent.MelodyNotePlayed, () => {});
-music.setPlayTone((freq, ms) => {});
 ```
 
 ### See Also

docs/reference/music/set-play-tone.md

@@ -4,7 +4,7 @@ Replaces the implementation of the [music play tone](/reference/music/play-tone)
 
 
 ```sig
-music.setPlayTone((freq, ms) => {})
+music.setPlayTone((frequency: number, duration: number) => {})
 ```
 
 ### Parameters

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

@@ -99,7 +99,8 @@
   "input.acceleration|param|dimension": "TODO",
   "input.buttonIsPressed": "Get the button state (pressed or not) for ``A`` and ``B``.",
   "input.buttonIsPressed|param|button": "the button to query the request, eg: Button.A",
-  "input.calibrate": "Obsolete, compass calibration is automatic.",
+  "input.calibrate": "Obsolete, use input.calibrateCompass instead.",
+  "input.calibrateCompass": "Obsolete, compass calibration is automatic.",
   "input.compassHeading": "Get the current compass heading in degrees.",
   "input.lightLevel": "Reads the light level applied to the LED screen in a range from ``0`` (dark) to ``255`` bright.",
   "input.magneticForce": "Get the magnetic force value in ``micro-Teslas`` (``µT``). This function is not supported in the simulator.",

libs/core/_locales/core-strings.json

@@ -220,6 +220,7 @@
   "images|block": "images",
   "input.acceleration|block": "acceleration (mg)|%NAME",
   "input.buttonIsPressed|block": "button|%NAME|is pressed",
+  "input.calibrateCompass|block": "calibrate compass",
   "input.compassHeading|block": "compass heading (°)",
   "input.lightLevel|block": "light level",
   "input.magneticForce|block": "magnetic force (µT)|%NAME",

libs/core/input.cpp

@@ -313,8 +313,11 @@ namespace input {
     /**
      * Obsolete, compass calibration is automatic.
      */
-    //% help=input/calibrate weight=0
-    void calibrate() { }
+    //% help=input/calibrate-compass advanced=true
+    //% blockId="input_compass_calibrate" block="calibrate compass"
+    void calibrateCompass() { 
+        uBit.compass.calibrate();        
+    }
 
     /**
      * Sets the accelerometer sample range in gravities.

libs/core/input.ts

@@ -47,4 +47,12 @@ namespace input {
     export function onLogoDown(body: Action): void {
         onGesture(Gesture.LogoDown, body);
     }
+
+    /**
+     * Obsolete, use input.calibrateCompass instead.
+     */
+    //% weight=0 help=input/calibrate-compass
+    export function calibrate() {
+        input.calibrateCompass();
+    }
 }

libs/core/shims.d.ts

@@ -339,8 +339,9 @@ declare namespace input {
     /**
      * Obsolete, compass calibration is automatic.
      */
-    //% help=input/calibrate weight=0 shim=input::calibrate
-    function calibrate(): void;
+    //% help=input/calibrate-compass advanced=true
+    //% blockId="input_compass_calibrate" block="calibrate compass" shim=input::calibrateCompass
+    function calibrateCompass(): void;
 
     /**
      * Sets the accelerometer sample range in gravities.

pxtarget.json

@@ -55,7 +55,8 @@
                 "type": "api",
                 "map": {
                     "bluetooth\\s*\\.uartRead\\s*\\((.*?)\\)": "bluetooth.uartReadUntil($1)",
-                    "bluetooth\\s*\\.uartWrite\\s*\\((.*?)\\)": "bluetooth.uartWriteUntil($1)"
+                    "bluetooth\\s*\\.uartWrite\\s*\\((.*?)\\)": "bluetooth.uartWriteUntil($1)",
+                    "input\\s*\\.calibrate\\s*\\(": "input.calibrateCompass("
                 }
             },
             {

sim/state/misc.ts

@@ -78,7 +78,8 @@ namespace pxsim.input {
         return runtime.runningTime();
     }
 
-    export function calibrate() {
+    export function calibrateCompass() {
+        // device calibrates...
     }
 }