light_sensor_calibration
========================
**Source code:** `light_sensor_calibration.py <https://chromium.googlesource.com/chromiumos/platform/factory/+/refs/heads/main/py/test/pytests/light_sensor_calibration.py>`_

Calibration test for light sensor (a chamber is needed).

Description
-----------
This is a station-based test which calibrates light sensors.
The test controls a light chamber to switch light intensity between different
light preset and reads the value from the light sensor of a DUT.

The calibration method is linear regression. The test samples multiple
data points (e.g., LUX1, LUX2) and find out a new linear equation to fit the
validating data point (e.g., LUX3). The calibrated coefficients scale factor and
bias will be saved to the VPD.

The default chamber connection driver is PL2303 over RS232. You can speicify a
new driver to ``chamber_conn_params``. You also need to provide the
``chamber_cmd`` with which a station can command the light chamber.

Besides the arguments, there are still many configurations in the
light_sensor_calibration.json. For examples::

  {
    "version": "v0.01",
    "light_seq": ["LUX1", "LUX2", "LUX3"],
    "n_samples": 5,
    "read_delay": 2.0,
    "light_delay": 6.0,
    "luxs": [40, 217],
    "validating_light": "LUX3",
    "validating_lux": 316,
    "validating_err_limit": 0.2,
    "force_light_init": false

  }

The most important entries are ``luxs`` and ``validating_lux``. They are the
preset illuminance value of a light chamber fixture. You need a lux meter
to evaluate the preset light settings from the light chamber fixture to get
these values. After you have these values, don't forget to update the runtime
configuration by calling
``cros.factory.utils.config_utils.SaveRuntimeConfig('light_sensor_calibration', new_config)``
so that you have the correct preset light information. There are many things
that influence the preset light value of the light chamber. It could be the
unstable elecrtic environment or if the light chamber's bulb is broken.

Test Procedure
--------------
This is an automated test. Before you start the test, prepare the
physical setup and calibrate the light chamber itself by a lux meter:

1. Connects the station and the DUT.
2. Connects the station and the light chamber.
3. Press start test.
4. After finishing the test, disconnects the station and the DUT.

Dependency
----------
- A light chamber with at least three luminance settings.

Examples
--------
To automatically calibrate the light_sensor with the given ``chamber_cmd``, add
this into test list:

.. test_list::

  generic_ec_component_als_examples:AmbientLightSensorTests.LightSensorCalibration

To debug and use a mocked light chamber:

.. test_list::

  generic_ec_component_als_examples:AmbientLightSensorTests.LightSensorCalibrationWithMockedChamber

Trouble Shooting
----------------
If you found error related to load configuration file:

- This is probably your runtime config format is incorrect.

If you found error connecting to light chamber:

1. Make sure the chamber and station are connected.
2. Make sure the dongle is correct one. If you are not using the dongle with
   PL2303 driver, you need to provide one.

If you found the calibrated coefficients are skewd:

1. This is probably you don't calibrate the light chamber recently.


Test Arguments
--------------
.. list-table::
   :widths: 20 10 60
   :header-rows: 1
   :align: left

   * - Name
     - Type
     - Description

   * - control_chamber
     - bool
     - (optional; default: ``False``) Whether or not to control the chart in the light chamber.

   * - assume_chamber_connected
     - bool
     - (optional; default: ``True``) Assume chamber is connected on test startup. This is useful when running fixture-based testing. The OP won't have to reconnect the fixture everytime.

   * - chamber_conn_params
     - dict, str, None
     - (optional; default: ``None``) Chamber connection parameters, either a dict, defaults to None

   * - chamber_cmd
     - dict
     - A dict for name of lightning to a [cmd, cmd_response].

   * - chamber_n_retries
     - int
     - (optional; default: ``10``) Number of retries when connecting.

   * - chamber_retry_delay
     - int
     - (optional; default: ``2``) Delay between connection retries.

   * - mock_mode
     - bool
     - (optional; default: ``False``) Mock mode allows testing without a fixture.

   * - config_dict
     - dict, None
     - (optional; default: ``None``) The config dictionary. If None, then the config is loaded by config_utils.LoadConfig().

   * - keep_raw_logs
     - bool
     - (optional; default: ``True``) Whether to attach the log by Testlog