Usage
=====

Command line
------------

The MTDA client may be used from the command line using the ``mtda-cli``
command. A remote agent may be specified on the command line using the
``-r`` option or in the environment with the ``MTDA_REMOTE`` variable.
The remote may be alternatively specified in the ``[remote]]`` section
of the local configuration file.

Power commands 
~~~~~~~~~~~~~~

When MTDA is configured with a ``[power]`` control block in its configuration,
the ``target`` command may be used to power the attached target device ON or
OFF::

    # Turn the target on
    $ mtda-cli target on

    # Use the target...

    # Turn the target off
    $ mtda-cli target off

Both commands will fail and return a non-zero status when no power controller
is attached.

Use the ``reset`` command to power-cycle the device::

    $ mtda-cli target reset

Uptime may be printed with the ``uptime`` command::

    $ mtda-cli target uptime
    16 minutes 33 seconds

This is the elapsed time since the device was powered and does not account for
soft resets triggered from the Operating System or hardware watchdog.

Console commands
~~~~~~~~~~~~~~~~

Most MTDA setups will have a console setup to communicate with the target
device. In most cases, this console is simply a serial console either via
RS232 or via USB. Commands (such as boot-loader commands or shell commands)
may be sent using ``console send``::

    $ mtda-cli console send "run boot_usb\n"

You may then check how many lines are in the console buffer::

    $ mtda-cli console lines
    14

You may extract the first line from the ring buffer with the ``console head``
command::

    $ mtda-cli console head
    U-Boot 2015.07 (Jan 08 2017 - 16:25:06 +0100)

or get everything queued in the buffer with ``console flush``::

    $ mtda-cli console flush
    U-Boot 2015.07 (Jan 08 2017 - 16:25:06 +0100)
    ...
    U-Boot>

Data in the ring buffer may also be discarded with ``console clear``::

    $ mtda-cli console clear

Wait up to 60 seconds for a given string on the console::

    $ mtda-cli console wait "login:" 60

Monitor commands
~~~~~~~~~~~~~~~~

Some devices may have a secondary console that may be used to control the
system. Data received from the monitor interface is logged into a ring
buffer that may be read with the ``monitor`` commands listed below.

Send a command (string) to the monitor interface::

    $ mtda-cli monitor send "run boot_usb\n"

Wait up to 30 seconds for a given string on the monitor console::

    $ mtda-cli monitor wait "Hit any key" 30

Storage commands
~~~~~~~~~~~~~~~~

A shared storage device may be controlled with the ``storage`` command in
supported setups (e.g. using special hardware such as the SDMux or when
sharing a media attached to the MTDA host using USB Function). In most
configurations, the target device should be OFF when swapping the shared
device between the ``HOST`` (i.e. the system running the MTDA daemon) and
the ``TARGET`` device. To attach the shared storage to the host, use::

    $ mtda-cli storage host

It is then possible to "burn" disk images using the ``storage write``
command::

    $ mtda-cli storage write console-image.wic.bz2

Images may also be downloaded from a S3 bucket::

    $ export AWS_ACCESS_KEY_ID=my-access-key
    $ export AWS_SECRET_ACCESS_KEY=my-secret-access-key
    $ mtda-cli storage write s3://example.org/console-image.wic.zst

It should be noted that MTDA supports ``.gz``, ``.bz2``, ``.zst`` and
raw images.

Partitions may be mounted on the MTDA host using the ``storage mount``
command::

    $ mtda-cli storage mount 1 # mount 1st partition

The client may then send files to be updated on the mounted partition with
the ``storage update`` command::

    # Update the kernel image
    # (here boot/kernel on the mounted partition, vmlinuz on the client)
    $ mtda-cli storage update boot/kernel vmlinuz

The shared device may be swapped to the ``TARGET`` device the ``storage
target`` command::

    $ mtda-cli storage target

Lastly, the shared device may be exposed on the network using the
``storage network`` command:

    $ mtda-cli storage network

It uses `nbd-server` on the MTDA host and `sudo` and `nbd-client` on
the client (the `nbd` kernel module must loaded or built-in into the
kernel for `nbd-client to succeed). The name of the network block
device will be printed to `stdout` and should be used to detach/release
the block device when done:

    $ nbd-client -d /dev/nbd0

Monitor commands
~~~~~~~~~~~~~~~~

When using KVM in lieu of an actual target device, arbitrary commands
may be sent to the QEMU monitor using the ``command`` command::

    $ mtda-cli command hostfwd_add tcp::8080-:8080

Interactive
-----------

The MTDA client may be used as a terminal to interact directly with the
device under test.

Usage
~~~~~

Start ``mtda-cli`` without any commands. You may use a custom remote agent
using the ``-r`` (or `--remote``) option::

    # use default remote (localhost or remote specified in the configuration)
    $ mtda-cli

    # or with a specific remote
    $ mtda-cli -r mtda-for-pi3.local

Key bindings
~~~~~~~~~~~~

The following key bindings may be used to control MTDA from the interactive console:

 * ``Ctrl-a`` + ``a``: acquire the target
 * ``Ctrl-a`` + ``b``: paste console buffer to pastebin.com
 * ``Ctrl-a`` + ``c``: start/stop screen capture to "screen.cast"
 * ``Ctrl-a`` + ``i``: print target information (power status, SD card, USB ports, etc.)
 * ``Ctrl-a`` + ``m``: switch between the monitor and the console
 * ``Ctrl-a`` + ``p``: toggle power on/off
 * ``Ctrl-a`` + ``q``: quit
 * ``Ctrl-a`` + ``r``: release the target
 * ``Ctrl-a`` + ``s``: swap the shared storage device between the host and target
 * ``Ctrl-a`` + ``t``: toggle display of timestamps
 * ``Ctrl-a`` + ``u``: toggle the 1st USB port on/off