Make the EV3 color sensor calibration applicable to the EV3 color sensor

lib/ev3/color.py

@@ -189,9 +189,39 @@ class ColorSensor(EV3UartSensor):
         else:  # code == 0: COLOR_NONE => return None
             return None
 
-    def calibrate(self):
+    def calibrate_hw(self):
         """
-        Calibrate the sensor's RGB components and save them to sensor memory.
+        Send a hardware recalibration request to the sensor.
+
+        BEWARE. Do not call this unless you know what you are doing.
+
+        The calibration is intended to give the sensor an idea what a
+        "100% white" is. Once the sensor receives the calibration
+        challenge, it will perform one RGB measurement. This measurement
+        will then be encoded into the sensor's EEPROM (any previous
+        factory calibration will be overwritten!).
+
+        The hardware calibration affects only the following sensor modes:
+         - COL-REFLECT (handled by the sensor.reflection() method)
+         - COL-COLOR (handled by the sensor.color() method)
+        These are the sensor modes that perform scaling within the sensor itself.
+
+        After the calibration, the COL-REFLECT mode should return 100 %
+        if you keep the sensor in the same position as during calibration.
+
+        For a repeatable calibration process, it should be possible to
+        build a simple calibration jig. It seems that the factory LEGO
+        calibration makes the sensor return 100 % in COL-REFLECT when
+        the sensor is pointed at a 3x3 surface made of white LEGO 32523
+        parts from a distance of ~one Technic brick.
         """
-        self.read_raw_mode(ColorSensor.MODE_COL_CAL)
-        
+        self.read_raw_mode(ColorSensor.MODE_COL_CAL) # the sensor will send one DATA message with all zeros
+        self.write_command(b'LEGO-FAC-CAL-1') # this will allow the calibration to start
+
+        # loop until the sensor sends a new DATA message; it should contain nonzero data (the calibration is then complete)
+        items = self.read_raw_mode(ColorSensor.MODE_COL_CAL)
+        while items[0] == 0:
+            items = self.read_raw_mode(ColorSensor.MODE_COL_CAL)
+
+        # switch the sensor back to a mode where it will not time out
+        self.reflection()