Calibrate compass (#392)

* adding 'calibrate-compass' function

* fixing simulator.

* updated docs

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

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)