update_device_data ================== **Source code:** `update_device_data.py `_ Updates Device Data (manually or from predefined values in test list). Description ----------- The Device Data (``cros.factory.test.device_data``) is a special data structure for manipulating DUT information. This test can determine Device Data information (usually for VPD) without using shopfloor backend, usually including: - ``serials.serial_number``: The device serial number. - ``vpd.ro.region``: Region data (RO region). - ``vpd.rw.ubind_attribute`` and ``vpd.rw.gbind_attribute``: User and group registration codes. - Or other values specified in argument ``fields`` or ``config_name``. When argument `manual_input` is True, every values specified in ``fields`` will be displayed on screen with an edit box before written into device data. Note all the values will be written as string in manual mode. The ``fields`` argument is a sequence in format ``(data_key, value, display_name, value_check)``: ================ ============================================================== Name Description ================ ============================================================== ``data_key`` The Device Data key name to write. ``value`` The value to be written, can be modified if ``manual_input`` is True. ``display_name`` The label or name to be displayed on UI. ``value_check`` To validate the input value. Can be a regular expression, list of strings, list of integers, boolean values, or None. When ``value_check`` is a list of strings / integers / bool, an "option label" can be added to each option. So ``value_check`` becomes a list of tuples: ``[ (string, string) ]`` or ``[ (int, string) ]`` or ``[ (bool, string) ]``. The first element of tuple is the value, and the second element is a string to be displayed. ================ ============================================================== If you want to manually configure without default values, the sequence can be replaced by a simple string of key name. The ``config_name`` refers to a JSON config file loaded by ``cros.factory.py.utils.config_utils`` with single dictionary that the keys and values will be directly sent to Device Data. This is helpful if you need to define board-specific data. ``config_name`` and ``fields`` are both optional, but you must specify at least one. If you want to set device data (especially VPD values) using shopfloor or pre-defined values: 1. Use ``shopfloor_service`` test with method=GetDeviceInfo to retrieve ``vpd.{ro,rw}.*``. 2. Use ``update_device_data`` test to write pre-defined or update values to ``vpd.{ro,rw}.*``. 3. Use ``write_device_data_to_vpd`` to flush data into firmware VPD sections. Test Procedure -------------- If argument ``manual_input`` is not True, this will be an automated test without user interaction. If argument ``manual_input`` is True, the test will go through all the fields: 1. Display the name and key of the value. 2. Display an input edit box for simple values, or a list of selection if the ``value_check`` is a sequence of strings or boolean values. 3. Wait for operator to select or input right value. 4. If operator presses ESC, abandon changes and keep original value. 5. If operator clicks Enter, validate the input by ``value_check`` argument. If failed, prompt and go back to 3. Otherwise, write into device data and move to next field. 6. Pass when all fields were processed. Dependency ---------- None. This test only deals with the ``device_data`` module inside factory software framework. Examples -------- To silently load device-specific data defined in board overlay ``py/config/default_device_data.json``, add this in test list:: { "pytest_name": "update_device_data", "args": { "config_name": "default", "manual_input": false } } To silently set a device data 'component.has_touchscreen' to True:: { "pytest_name": "update_device_data", "args": { "fields": [ [ "component.has_touchscreen", true, "Device has touch screen", null ] ], "manual_input": false } } For RMA process to set serial number, region, registration codes, and specify if the device has peripherals like touchscreen:: { "pytest_name": "update_device_data", "args": { "fields": [ [ "serials.serial_number", null, "Device Serial Number", "[A-Z0-9]+" ], ["vpd.ro.region", "us", "Region", null], ["vpd.rw.ubind_attribute", null, "User ECHO", null], ["vpd.rw.gbind_attribute", null, "Group ECHO", null], [ "component.has_touchscreen", null, "Has touchscreen", [true, false] ] ] } } If you don't need default values, there's an alternative to list only key names:: { "pytest_name": "update_device_data", "args": { "fields": [ "serials.serial_number", "vpd.ro.region", "vpd.rw.ubind_attribute", "vpd.rw.gbind_attribute" ] } } Test Arguments -------------- .. list-table:: :widths: 20 10 60 :header-rows: 1 :align: left * - Name - Type - Description * - manual_input - bool - (optional; default: ``True``) Set to False to silently updating all values. Otherwise each value will be prompted before set into Device Data. * - config_name - str, None - (optional; default: ``None``) A JSON config name to load representing the device data to update. * - fields - list, None - (optional; default: ``None``) A list of [data_key, value, display_name, value_check] indicating the Device Data field by data_key must be updated to specified value.