README

= CDBA control tool
The CDBA control tool is used for remotely booting images on development boards
attached using a CDB Assist [https://github.com/sonyxperiadev/CDB-Assist] or Conmux.

= Dependencies
sudo apt-get install libudev-dev libyaml-dev libftdi1-dev pkg-config meson for debian systems
dnf install systemd-devel libyaml-devel libftdi1-devel pkg-config meson for fedora systems
pacman -S libftdi libgpiod libyaml pkgconf meson for Arch systems

= Device side
On the host with the CDB Assist or Conmux attached the "cdba-server" executable is run
from sandbox/cdba/cdba-server. Available devices are read from $HOME/.cdba

= Build instructions

# meson . build
# ninja -C build

= Client side
The client is invoked as:

  cdba -b <board> -h <host> [-c <power-cylce-count>] [-s <status-fifo>] boot.img

<host> will be connected to using ssh and <board> will be selected for
operation. As the board's fastboot interface shows up the given boot.img will
be transfered and booted on the device.

The board will execute until the key sequence ^A q is invoked or the board
outputs a sequence of 20 ~ (tilde) chards in a row.

If the optional -c is given, the board will upon receiving the tilde sequence
restart the board the given number of times. Each time booting the given
boot.img.

The optional -s argument can be used to specify that a fifo should be created
and opened. cdba will request the server to start sending status/measurement
updates, which will be written to this fifo.

How to quit the console and close session: ctrl+a then q

= Server side

== Device configuration
The list of attached devices is read from $HOME/.cdba and is YAML formatted.

== Status command

The "status-cmd" property for a board specifies a command line that should be
executed to perform measurements and report status updates to the client. The
command is expected to run for the duration of the board session and should
produce a continuous stream of json-formatted lines of status updates according
to the format defined in this document.

=== Example
devices:
  - board: db2k
    cdba: 00000001
    name: "DragonBoard2k"
    fastboot: abcdef1
    voltage: 8000

  - board: mtp2k
    conmux: mtp2k
    fastboot: abcdef2
    fastboot_set_active: true

  - board: evb2k
    users:
      - username
    console: /dev/ttyUSB0
    fastboot: abcdef3
    fastboot_set_active: true

  - board: qrd8550
    alpaca: /dev/serial/by-id/usb-QUALCOMM_Inc._Embedded_Power_Measurement__EPM__device_6E02020620151F14-if01
    console: /dev/serial/by-id/usb-QUALCOMM_MTP_Debug_Board_MT77TGG2-if00-port0
    name: QRD8550
    fastboot: 91671140
    fastboot_set_active: true
    fastboot_key_timeout: 2

  - board: testboard
    console: /dev/serial/by-id/usb-1234-if00-port0
    name: GPIO controller board
    local_gpio:
      power:
        chip: gpiochip0
        line: 7
        active_low: true
      fastboot_key:
        chip: gpiochip0
        line: 8
        active_low: true
      power_key:
        chip: gpiochip0
        line: 14
        active_low: true
      usb_disconnect:
        chip: gpiochip1
        line: 4
    fastboot: cacafada
    fastboot_set_active: true
    fastboot_key_timeout: 2

  - board: testboard2
    console: /dev/serial/by-id/usb-1234-if00-port0
    name: FTDI controller board
    ftdi_gpio:
      vendor: "0x0403"
      product: "0x6011"
      index: 0
      power:
        interface: D
        line: 7
        active_low: true
      fastboot_key:
        interface: D
        line: 8
        active_low: true
      power_key:
        interface: D
        line: 3
        active_low: true
      usb_disconnect:
        interface: D
        line: 2
    fastboot: cacafada
    fastboot_set_active: true
    fastboot_key_timeout: 2

= Status messages

The status messages that are used by the client fifo and the server's status
command should be json-formatted, with one status update per line.

Each message should contain one timestamp member "ts", and one or more
measurement members. Like so:

  {"ts":%d.%03d, "name": {["mv"|"ma"]: %u}(, "name2": {["mv"|"ma"]: %u})*}

The timestamp member ("ts"), should provide the time since first measurement in
decimal form with millisecond accuracy.

The key for the measurement members should be an identifier of the measured
resources, and the value should be an object with members for each unit
measured for the given resource and the measured value.

Valid units to report are "mv", "ma", and "mw".

Note that the cadence of measurement might differ between different items to be
measured, so not all status messages contains data for all items that can be
measured.

== Examples

Single resource "dc" measured at 20.271s, with voltage and current reported:

  {"ts":20.271, "dc":{ "mv": 12165, "ma": 114}}

Multiple resources measured in a single status message, followed by single
resource measurement, all with voltage and current reported:

  {"ts":38.341, "battery":{"mv":8023, "ma":725}, "vdd_cx":{"mv":750, "ma":466}}
  {"ts":44.339, "battery":{"mv":8023, "ma":733}}