tools/README.md

## First Time Setup

For first time setup we need to create a virtual environment, enter it, and
install dependencies. These steps have consolidated into a start script.

```console
source start_venv.sh
```

#### Install venv if missing:

If venv is missing, install the package with:

```console
sudo apt-get install python3-venv
```

### Exit Virtual Environment

Exit the virtual environment using the `deactivate` command.

```console
(.venv) ~/chromiumos/src/third_party/dolos/battery $ deactivate
~/chromiumos/src/third_party/dolos/batterydata $
```


## Programming The Cable

Example arguments using Dolos to fetch the latest meep config and use a generic or specific hwid

When you know the model but not the hwid the lowest index is used.

```console
(.venv) $ doloscmd program-cable --serial DOLOSV1-C-1520240019 --hwid "meep"
```

If you provide the full HWID we can fetch the model from the name.

```console
(.venv) $ doloscmd program-cable --serial DOLOSV1-C-1520240019 --hwid "MEEP C4B-A2H-F4K-G9G-Z2J"
```

Testing a local file does not require a hwid information.

```console
(.venv) $ doloscmd program-cable --serial DOLOSV1-C-1520240019 --file meep.yaml
```


### Optional: Setup crosfleet and SSH access:

https://goto.google.com/crosfleet-cli
https://goto.google.com/chromeos-lab-duts-ssh

## Importing Battery Information

```console
(.venv) $ dolos_load_battery  --help
usage: dolos_load_battery [-h] (-s SSH | -i) [-p I2C_PORT] -f FILE [-c COMMENT] [-v]

options:
  -h, --help   show this help message and exit
  -s SSH       Use SSH and ECTool to extract registers from a remote DUT
  -i           Use a FTDI board to extract registers from an unplugged battery
  -p I2C_PORT  Configure ECTool's I2C port if I2C_PORT_BATTERY is known
  -f FILE      File path to export yaml data
  -c COMMENT   Comment data
  -v           Enable verbose logging
```

### Steps to extract battery data from the Fleet

Find checkout `MODEL` with crosfleet and identify the `DUT_HOSTNAME` field.
```console
crosfleet dut lease -model $MODEL
```

Example:
```console
crosfleet dut lease -model pico
Verifying the provided DUT dimensions...
Found 45 DUT(s) (39 busy) matching the provided DUT dimensions
...
DUT_HOSTNAME=chromeos8-row10-rack8-host46
MODEL=pico
BOARD=jacuzzi
SERVO_HOSTNAME=chromeos8-row10-rack8-labstation6
SERVO_PORT=9996
SERVO_SERIAL=SERVOV4P1-S-2103240648
```

Pass the `DUT_HOSTNAME` Parameter to the dolos_load_battery.py script and specify
an `OUTPUT` path for the yaml data.


```console
dolos_load_battery -s $DUT_HOSTNAME -f $OUTPUT
```

Example:
```console
(.venv) $ dolos_load_battery -s chromeos8-row10-rack8-host46 -f pico.yaml
INFO - dolos_load_battery.py:252:configure_connections : Connected
INFO - dolos_load_battery.py:176:_configure_port : Detecting port
INFO - dolos_load_battery.py:180:_configure_port : Using port 4
INFO - dolos_load_battery.py:197:load_registers : Loading registers
INFO - dolos_load_battery.py:201:load_registers : Progress 1/40 - Loading 'SB_MANUFACTURER_ACCESS'
...
INFO - dolos_load_battery.py:201:load_registers : Progress 40/40 - Loading 'SB_PACK_STATUS'
INFO - dolos_load_battery.py:209:export_table : Exporting yaml to:PosixPath('test.yaml')
```

Final steps:

PolarityHigh can not be extracted automatically. We need to test it with full
DUT-Cable-Dolos setup to confirm it is correct. It needs to be set to be set to
`low` or `high`.

```yaml
Polarity: high
```

When the DUT is powered on, we can see the correct state using the `status` command
in the Dolos console:

```console
System present     : Absent (signal HIGH, polarity LOW)
```

If the DUT is active and `signal HIGH` is reported, we need to adjust the Polarity.

```yaml
Polarity: high
```

```console
System present     : Present (signal HIGH, polarity HIGH)
```


## Update the Configs from the HWID database

The HWID database provides a mapping between an individual DUT's HWID
and which specific battery registers are used. The tool is designed to do
batch updating of configs generated by the load_battery tool.

To set it up, you need to clone the internal chromeos-hwid repo.

```console
git clone "https://chrome-internal.googlesource.com/chromeos/chromeos-hwid"
```

If you have a set of files you want to update you can pass an input and output
directory to process.

```console
dolos_process_configs -id {PATH/chromeos-hwid} -i input_dir -o output_dir
```

The tool can also download the latest copies and upgrade them with the download
option.

```console
dolos_process_configs -id {PATH/chromeos-hwid} -i input_dir -o output_dir -d
```

## Important note about naming

EEPROM Configs for a given model have a naming convention of
{MODEL}_v{VERSION}.yaml. The highest version number is used to find the latest
copy.