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