Calibration states (#820)

* color calibration

libs/color-sensor/color.ts

@@ -297,9 +297,22 @@ namespace sensors {
         calibrateLight(mode: LightIntensityMode, deviation: number = 8) {
             this.calibrating = true; // prevent events
 
-            this.light(mode); // trigger a read
+            const statusLight = brick.statusLight(); // save current status light
-            pauseUntil(() => this.isActive()); // ensure sensor is live
+            brick.setStatusLight(StatusLight.Orange);
 
+            this.light(mode); // trigger a read
+            pauseUntil(() => this.isActive(), 5000); // ensure sensor is live
+
+            // check sensor is ready
+            if (!this.isActive()) {
+                brick.setStatusLight(StatusLight.RedFlash); // didn't work
+                pause(2000);
+                brick.setStatusLight(statusLight); // restore previous light
+                return;
+            }
+
+            // calibrating
+            brick.setStatusLight(StatusLight.OrangePulse);
 
             let vold = 0;
             let vcount = 0;
@@ -331,6 +344,10 @@ namespace sensors {
             this.thresholdDetector.setLowThreshold(min);
             this.thresholdDetector.setHighThreshold(max);
 
+            brick.setStatusLight(StatusLight.Green); // success
+            pause(1000);
+            brick.setStatusLight(statusLight); // resture previous light
+
             this.calibrating = false;
         }
 

libs/color-sensor/docs/reference/sensors/color-sensor/calibrate-light.md

@@ -13,6 +13,15 @@ Sometimes when external lighting conditions change, the light sensor measures li
 * **mode**: the type of light threshold to calibrate. This is either ``ambient`` or ``reflected`` light.
 * **deviation**: a [number](/types/number) that is the amount of light level change to adjust in a measurement.
 
+## Calibration states
+
+Calibration happens in the following phases and each phase is tracked by the brick status light.
+
+* **orange**: sensor initialization. This phase ensures that the sensor is in the desired mode and ready to collect data.
+* **orange pulse**: data collection. Light information is being collected, move the sensor over the various light sources to detect.
+* **green**: calibration success. The calibration data has been saved.
+* **red flash**: sensor failure. We were unable to connect to the sensor.
+
 ## Example
 
 Calibrate the ``dark`` and ``light`` thresholds for the ``color 2`` sensor using reflected light.

libs/core/buttons.ts

@@ -247,6 +247,15 @@ namespace brick {
     // the brick starts with the red color
     let currPattern: StatusLight = StatusLight.Off;
 
+    /**
+     * Gets the current light pattern.
+     */
+    //% weight=99 group="Buttons"
+    //% help=brick/status-light
+    export function statusLight() {
+        return currPattern;
+    }
+
     /**
      * Set lights.
      * @param pattern the lights pattern to use. eg: StatusLight.Orange

libs/gyro-sensor/docs/reference/sensors/gyro/reset.md

@@ -22,6 +22,15 @@ To properly reset the gyro, the brick must remain still (undistrurbed) while the
 
 ## ~
 
+## Calibration states
+
+Calibration happens in the following phases and each phase is tracked by the brick status light.
+
+* **orange**: sensor initialization. This phase ensures that the sensor is in the desired mode and ready to collect data.
+* **orange pulse**: data collection. Light information is being collected, move the sensor over the various light sources to detect.
+* **green**: calibration success. The calibration data has been saved.
+* **red flash**: sensor failure. We were unable to connect to the sensor.
+
 ## Example
 Set the brick on a flat surface. Reset `gyro 2` and tilt the brick slighly. Reset it again while it's still tilted. Lay the brick down flat again and display the angle measurement.
 

libs/gyro-sensor/gyro.ts

@@ -92,6 +92,9 @@ namespace sensors {
         reset(): void {
             if (this.calibrating) return; // already in calibration mode
 
+            const statusLight = brick.statusLight(); // save current status light
+            brick.setStatusLight(StatusLight.Orange);
+
             this.calibrating = true;
             // may be triggered by a button click,
             // give time for robot to settle
@@ -101,9 +104,22 @@ namespace sensors {
             // switch back to the desired mode
             this.setMode(this.mode);
             // wait till sensor is live
-            pauseUntil(() => this.isActive());
+            pauseUntil(() => this.isActive(), 5000);
+
+            // check sensor is ready
+            if (!this.isActive()) {
+                brick.setStatusLight(StatusLight.RedFlash); // didn't work
+                pause(2000);
+                brick.setStatusLight(statusLight); // restore previous light
+                return;
+            }
+
             // give it a bit of time to init
             pause(1000)
+
+            // calibrating
+            brick.setStatusLight(StatusLight.OrangePulse);
+
             // compute drift
             this._drift = 0;
             if (this.mode == GyroSensorMode.Rate) {
@@ -113,6 +129,11 @@ namespace sensors {
                 }
                 this._drift /= 200;
             }
+
+            brick.setStatusLight(StatusLight.Green); // success
+            pause(1000);
+            brick.setStatusLight(statusLight); // resture previous light
+
             // and we're done
             this.calibrating = false;
         }