# Design requirements The firmware needs to be: 1. Hackable 1. Code-base easy to edit 1. Easy to compile 1. Easy to debug 1. Easy to deploy: No need for custom clients/complex protocols 1. Easy to use: No need for custom clients/complex protocols, everything should be human readable / interactable # HOST's USB descriptor The device harness' HOST USB port should expose the following device: * Vendor/device ID: TBD * Product name: \$name v\$version * Serial number: a unique serial number * Interfaces: * TTY device: control channel * TTY device: DUT console # Control channel protocol ## Framing The protocol should be ASCII- and line-based, for ease of use. Commands should be sent to the board in this format: CMD ARG1 ARG2 ARG3... The response should look like this: ERRORCODE\rHuman readable error code\n VALUE1\n VALUE2\rHuman readable value2\n <empty line> $ The use of `\r` enables the creation of machine and human readable outputs. Drivers would read everything up to the first `\r` or `\n` while humans using normal consoles should only see the human readable part... or the machine readable part if the firmware did not have anything better to write to humans. Available error codes: * `0`: Everything went well * Any other value depends on the `CMD` used The format of `VALUE` is dependent on the `CMD` used. See the commands section for a detailed list. The communication is synchronous, so the driver should wait for `\n\n$ ` before sending the next command. If no empty line is found, the command can be considered done executing 1 second after the last byte has been received. ## Commands ### USB: (Dis)connect the USB port from the HOST to the DUT Command format: `USB [STATUS] Statuses: * ON: Turn ON the port, providing power to the DUT and connecting it to the host * OFF: Turn OFF the port, cutting power to the DUT and disconnecting from the host Error codes: TBD Return values: * When `STATUS` is missing: `UP` or `DOWN` * With `STATUS` argument: `$CURRENT_STATUS $NEW_STATUS` ### VBAT: Read or set the current voltage of the battery emulator Command format: `VBAT [VOLTAGE [I_MAX]]` Formats: * `VOLTAGE`: `[int|float]V`, default value: `0V` * `I_MAX`: `[int|float]A`, default value: `0A` Error codes: * `1` / `INVALID_VOLTAGE_FORMAT`: Invalid voltage format. Supported format is `[int|float]V` * `2` / `INVALID_I_MAX_FORMAT`: Invalid current format. Supported format is `[int|float]A` * `3` / `VOLTAGE_EXCEEDS_VBAT_MAX`: The voltage exceeds the limit set by `VBAT_MAX` * `4` / `VOLTAGE_TOO_LOW`: The voltage is lower than the minimum voltage that can be set * `5` / `VOLTAGE_TOO_HIGH`: The voltage is higher than the maximum voltage than can be set * `6` / `I_MAX_TOO_HIGH`: The maximum current wanted exceeds the limits of the power supply at the wanted voltage. Current limit is PS_I_MAX A at VOLTAGE Return values: * Without the `VOLTAGE` argument: `$CURRENT_VOLTAGE` * With the `VOLTAGE` argument: `$CURRENT_VOLTAGE $CURRENT_I_MAX $NEW_VOLTAGE $NEW_I_MAX` ### VBAT_MAX: Maximum voltage allowed to be set using the VBAT command (software protection) Command format: `VBAT_MAX [VOLTAGE]` `VOLTAGE` format: `[int|float]V`, default value: `4.5V` Error codes: * `1` / `INVALID_VOLTAGE_FORMAT`: Invalid voltage format. Supported format is `[int|float]V` Return values: * Without the `VOLTAGE` argument: `$VOLTAGE` * With the `VOLTAGE` argument: `$CURRENT_VOLTAGE $NEW_VOLTAGE` ### PWR_MON: Print statistics about the power consumption Command format: `PWR_MON` Error codes: * `1` / `PWR_MON_UNSUPPORTED`: Power monitoring is unsupported by the board Return values: * A list of power rails, presented following this format: `$RAIL_NAME $PARENT_RAIL $VOLTAGE $CURRENT $POWER $ENERGY\r* $RAIL_NAME: ${VOLTAGE}V x ${CURRENT}A = ${POWER}W ($ENERGY Joules since startup)` With: * `$RAIL_NAME`: The relatively short name of the power rail * `$PARENT_RAIL`: The name of the parent rail if this rail represents a subset of the power of another rail, or `-` if this is a top-level rail. * `$VOLTAGE`: The voltage of the rail in Volts, or - if not applicable * `$CURRENT`: The current of the rail in Amperes, or - if not applicable * `$POWER`: The power consumption of the rail, in Watts * `$ENERGY`: The total energy consumption since the the startup of the board Note 1: All the children rails should be listed after their parent rail, with an extra 2 spaces of indentation before the `*` in the human readable description to make it appear like a tree. Note 2: The first rail listed should always be `TOTAL`, so that tests that do not care about the power rail can just care about this rail and ignore the rest. It would also be a guarantee that any future harness would have at least this rail in common with the current harness. ### BTN_DOWN: Depress one or more buttons Command format: `BTN_DOWN [$BTN [$BTN [...]]]` Error codes: * `1` / `UNKNOWN_BUTTON`: The following buttons are unknown: BTN1, BTN2, ... Return values: * The list of buttons and their state:`$BTN $STATE\r* $BTN: $STATE` With: * `$BTN`: One of `PWR`, `VOL_UP`, or `VOL_DOWN` * `$STATE`: Either `UP` if the button is not pressed, or `DOWN` if the button is pressed ### BTN_UP: Release one or more buttons Command format: `BTN_UP [$BTN [$BTN [...]]]` Same error codes and return values as `BTN_DOWN`. ### DELAY: Delay execution of the next command by the specified amount of milliseconds This command does nothing, unless executed by the sequencer (SEQ_QUEUE) in which case it will delay execution of the next command in the batch buffer by the specified amount of milliseconds. Command format: `DELAY $MILLIS` Error codes: None Return values: None ### SEQ_QUEUE: Add a command to the batch buffer for asynchronous execution Rationale: Because some tests may require interacting with the device when it is suspended or otherwise inactive, it is important to be able to schedule commands for later execution. A command can be added to the list of commands to execute by prepending it with `SEQ_QUEUE`. The command will not be executed until the `SEQ_START` command is sent and all the previous `SEQ_QUEUE` commands have executed. Invalid commands are ignored at execution time, along with any `SEQ_*` command. Format: `SEQ_QUEUE $CMD ...` Error codes: * `1` / `BATCH_BUFFER_FULL`: The batch buffer is full and cannot accept any more command Return values: None ### SEQ_START: Start executing the commands queued in the batch buffer Format: `SEQ_START` Error codes: * `1` / `EMPTY_BATCH_BUFFER`: The batch buffer is empty and thus has nothing to execute Return values: None ### SEQ_RESET: Empty the batch buffer Format: `SEQ_RESET` Error codes: None Return values: None ### SEQ_LIST: Print the list of commands found in the batch buffer Error codes: None Return values: The list of commands currently found in the batch buffer ### Example ``` $ USB UP 0\rOK DOWN UP\rThe phone's USB port has been turned on and connected to the HOST $ VBAT 0\rOK 0.0V\rThe current battery voltage is set to 0V. Available modes: PD 5V 5A\r* PD: 5V @ 5A PD 12V 3A\rPD 12V @ 3A PPS 3.3V-18V 5A\rPPS 3.3V - 18V @ 5A $ VBAT 3.85V 5A 0\rOK 0.0V 0A 3.85V 5A\rThe battery voltage was changed from 0.0V@0A to 3.85V@5A $ VBAT 5V 3\rVOLTAGE_EXCEEDS_VBAT_MAX 4.5V\rThe voltage exceeds the maximum value set by VBAT_MAX (4.5V) $ VBAT_MAX 6V 0\rOK 4.5V 6V'rMaximum allowed voltage went from 4.5V to 6V $ PWR_MON 0\rOK TOTAL - - - 21.74 3579\r* TOTAL: 21.74W (3579 Joules since startup) BATTERY TOTAL 4.35 3.1 13.485 2345\r* USB: 4.35V x 3.1A = 13.49W (2345 Joules since startup) BATTERY_1 BATTERY 4.35 1.55 13.485 2345\r * USB: 4.35V x 1.55A = 6.74W (1172.5 Joules since startup) BATTERY_2 BATTERY 4.35 1.55 13.485 2345\r * USB: 4.35V x 1.55A = 6.74W (1172.5 Joules since startup) USB TOTAL 5.1 1.65 8.25 1234\r* USB: 5.1V x 1.65A = 8.25W (1234 Joules since startup) $ SEQ_RESET 0\rOK $ SEQ_QUEUE USB DOWN 0\rOK $ SEQ_QUEUE BTN_DOWN PWR 0\rOK $ SEQ_QUEUE DELAY 5000 0\rOK $ SEQ_QUEUE BTN_UP PWR 0\rOK $ SEQ_QUEUE DELAY 1000 0\rOK $ SEQ_QUEUE BTN_DOWN VOL_DOWN 0\rOK $ SEQ_QUEUE USB UP 0\rOK $ SEQ_QUEUE DELAY 10000 0\rOK $ SEQ_QUEUE BTN_UP VOL_DOWN 0\rOK $ SEQ_LIST 0\rOK USB DOWN DELAY 5000 BTN_UP PWR DELAY 1000 BTN_DOWN VOL_DOWN USB UP DELAY 10000 BTN_UP VOL_DOWN $ SEQ_START 0\rOK ## DUT-side access It would be ideal if the pmOS test suite could be running the following tests on every device: * Battery/PMIC testing: charging, discharging, BMS-exported metrics such as current and voltage, ... * System-level power testing: Making sure power usage is reasonable in some key scenarios like screen off, idle launcher, video playback, ... * USB hotplugging: Ensure reliability of connection/disconnection of the USB port All of these tests would have to be done by executing tests on the DUT side (using ktest, or from the initramfs), and would benefit with being able to control the harness through the serial connection. I propose to also expose a variation of the protocol we use for the control channel, with an additional set of AT command to enter/exit talking to the harness. These AT commands could be stripped from the HOST -> DUT side so that tty echos don't end up triggering the talking to the harness mode, and thus allow the host to control the harness by using the serial connection, not the control channel. Finally, I suggest that when a command is being executed by the DUT, we would buffer the `HOST` -> `DUT` data so as not to mix harness and host data. TODO: Figure out the set of AT commands, or another solution.