VDA Reference - Amazon Vega Docs

The Vega Device Adapter (VDA) command line utility lets you install, test, and debug your Vega app. VDA is a binary located in the Vega SDK at $HOME/vega/sdk/vega-sdk/main/{SDK version}/bin/tools/vda. To set up your Fire TV Stick with VDA, see Set Up Your Fire TV Stick. VDA works with the Vega Virtual Device (simulator) without additional setup.

VDA global options

To install, test, and debug your Vega app, use these VDA global options, local commands, and shell commands.

Serial override

To direct commands to your device or emulator with a specific serial number or qualifier, use -s. This option overrides the VEGA_SERIAL environment variable.

Device (USB)

vega exec vda -s <serial-or-qualifier>

Example:

vega exec vda -s G0XXXXXXXXXXXXXX shell

Example output:

* daemon not running. starting it now on port 5037 *
* daemon started successfully *

Device (TCP/IP)

When a device is connected through TCP/IP, use the identifier shown in the vega exec vda devices output:

vega exec vda -s <ip>:<port> shell

Example:

vega exec vda -s 192.168.1.100:5555 shell

Example output:

* daemon not running. starting it now on port 5037 *
* daemon started successfully *

Vega Virtual Device

vega exec vda -s emulator-<vvd-port> shell

Example:

vega exec vda -s emulator-5554 shell

Example output:

* daemon not running. starting it now on port 5037 *
* daemon started successfully *

VDA local commands

To manage device connections, transfer files, and control the VDA server, run these commands from your development machine.

Devices

To list all connected devices, use devices. Add -l to list the device qualifiers.

vega exec vda devices [ -l ]

Example:

vega exec vda devices -l

Example output for a device connected through USB:

List of devices attached
G0XXXXXXXXXXXXXX       device usb:14131000

Example output for a device connected through TCP/IP:

List of devices attached
192.168.1.100:5555     device

Example output for the Vega Virtual Device:

List of devices attached
emulator-5554          device

Get serial number

To print the DSN, use get-serialno. For network-connected devices, this command returns the actual DSN rather than the identifier.

vega exec vda get-serialno

Example output for a USB-connected device:

G0XXXXXXXXXXXXXX

Example output for the same device connected through TCP/IP:

G0XXXXXXXXXXXXXX

TCP/IP mode

To switch a USB-connected device to TCP/IP mode, use tcpip with a port number. The device restarts its VDA daemon to listen on the specified port. Use port 5555 or any port greater than 1024.

vega exec vda tcpip <port>

Example:

vega exec vda tcpip 5555

Example output:

restarting in TCP mode port: 5555

After switching to TCP/IP mode, disconnect the USB cable and use connect to establish a wireless connection. For the full setup workflow, see Configure VDA Over TCP/IP.

USB mode

Before you run this command, reconnect the USB cable.

vega exec vda usb

Connect

To connect to a device through TCP/IP, use connect. Configure the device for TCP/IP mode first (see Configure VDA Over TCP/IP).

vega exec vda connect <host>[:<port>]

If you don’t specify a port number, VDA uses port 5555. Example:

vega exec vda connect 192.168.1.100:5555

Example output:

connected to 192.168.1.100:5555

Example output when the connection fails:

failed to connect to '192.168.1.100:5555': Operation timed out

A timeout usually means Developer Mode isn’t enabled or the host and device aren’t on the same network. For the full list of causes, see Fix VDA Connection and Power Issues.

Disconnect

To disconnect from a TCP/IP-connected device, use disconnect. If you run this command without arguments, VDA disconnects from all TCP/IP devices.

vega exec vda disconnect [<host>[:<port>]]

Example:

vega exec vda disconnect 192.168.1.100:5555

Example output:

disconnected 192.168.1.100:5555

To disconnect all TCP/IP devices at once, run the command without arguments:

vega exec vda disconnect

Example output:

disconnected everything

Help

To view the help text, use vega exec vda --help.

vega exec vda --help

Example output:

Vega Device Adapter
Usage: vda [OPTIONS] [SUBCOMMAND]

Options:
  -V,--version                Display program version information and exit
  -h,--help                   Show this help message
  --one-device TEXT           only allowed with 'start-server'
  -a Excludes: -d             listen on all network interfaces, not just localhost
  -d Excludes: -a -e          use USB device (error if multiple devices connected)
  -e Excludes: -d             use TCP/IP device (error if multiple TCP/IP devices available)
  -s SERIAL (Env:VEGA_SERIAL) use device with given serial (overrides $VEGA_SERIAL)
  -t ID:POSITIVE              use device with given transport id
  -H TEXT (Env:VEGA_VDA_SERVER_ADDRESS) Excludes: -L
                              name of vda server host [default=localhost]
  -P INT:INT in [1 - 65534] (Env:VEGA_VDA_SERVER_PORT) Excludes: -L
                              port of vda server [default=5037]
  -L SOCKET (Env:VDA_SERVER_SOCKET) Excludes: -H -P
                              listen on given socket for vda server [default=tcp:localhost:5037]
  --exit-on-write-error       exit if stdout is closed

Kill server

To stop the server, use kill-server.

vega exec vda kill-server

Start server

To start the server, use start-server.

vega exec vda start-server

Example output:

* daemon not running. starting it now on port 5037 *
* daemon started successfully *

Push

To copy a file or directory to your device, use push. Add -p to display the transfer progress.

vega exec vda push [-p] <local> <remote>

Example:

vega exec vda push Echo.png /tmp/

Example output:

$ vega exec vda push Echo.png /tmp/
2283 KB/s (6109 bytes in 0.002s)

$ vega exec vda shell ls /tmp/Echo*
/tmp/Echo.png

Pull

To copy a file or directory from your device, use pull. Add -p to display the transfer progress and -a to display timestamp and mode.

vega exec vda pull [-p] [-a] <remote> [<local>]

Example:

vega exec vda pull -p /tmp/Echo.png

Example output:

$ vega exec vda pull -p /tmp/Echo.png
Transferring: 6109/6109 (100%)
370 KB/s (6109 bytes in 0.016s)

$ ls Echo*
Echo.png

Version

To view your VDA version, use version.

vega exec vda version

Example output:

Vega Device Adapter version 2.12+0a5eee73
Server Version 41
Platform Version 34.0.4

Wait for device

To pause a script until the device is ready to accept commands, use wait-for-device.

vega exec vda wait-for-device

Example output:

$ vega exec vda devices
List of devices attached

$ vega exec vda wait-for-device

$ vega exec vda devices
List of devices attached
G0XXXXXXXXXXXXXX    device

Reboot

To reboot your device, use reboot.

vega exec vda reboot

Example output:

$ vega exec vda reboot

$ vega exec vda wait-for-device

$ vega exec vda devices
List of devices attached
G0XXXXXXXXXXXXXX    device

VDA shell commands

These commands run on the device through the VDA shell.

Invoke the shell

The vega exec vda shell command runs a remote shell interactively and supports several options.

vega exec vda shell

Example output:

##################################################
#####     Welcome to Developer Mode Shell    #####
##################################################
sh(com.amazon.dev.shell):/$

Other shell commands

vega exec vda shell <command>

Example:

vega exec vda shell whoami

Example output:

app_user

App management and communication tools

You can access these tools through the VDA shell:

vega exec vda shell vpm <subcommands>
vega exec vda shell vlcm <subcommands>
vega exec vda shell vmsgr <subcommands>

See App Management and Communication Tools for detailed vpm, vlcm, and vmsgr commands.

Launch component shell

Each app launches one or more components. To get a list of components:

vega exec vda shell vlcm list

Example output:

application                                type      pid     id    state       lifespan       timeout container                               launch args
com.amazon.lcm.stem.webview.main           S         2719    1     IDLE        PERMANENT      DEFAULT framework.slice/service                 <none>
com.amazon.lcm.stem.apl.main               S         2725    2     IDLE        PERMANENT      DEFAULT framework.slice/service                 <none>
com.amazon.otad.main                       I         3901    18    NOT_VISIBLE PERMANENT      DEFAULT app.slice/app                           <none>

Use the value from the application column as the <component-id> argument in the following commands. To run a component interactively, use:

vega exec vda shell -c <component-id>

Example output:

vega exec vda shell -c com.amazon.otad.main
##################################################
#####     Welcome to Developer Mode Shell    #####
##################################################
sh(com.amazon.otad):/$

To run a command in the component shell, use:

vega exec vda shell -c <component-id> <command>

Example:

vega exec vda shell -c com.amazon.otad.main df -h /tmp

Example output:

vega exec vda shell -c com.amazon.otad.main df -h /tmp
Filesystem            Size  Used Avail Use% Mounted on
none                   64M     0   64M   0% /tmp

High-level memory

To find the high-level memory footprint of all processes in the system, use ace_memusage.

vega exec vda shell ace_memusage

Example output:

PID   User     Cmdline                                 Swap    Uss     Pss     Rss     Vss
1     root     /sbin/init                              0       1128    2669    8184    28904
401   root     /lib/systemd/systemd-journald           0       2560    3150    7116    19692
423   root     /lib/systemd/systemd-udevd              0       2432    2694    6220    18956

Total System Memory:
Total     Free      Buffers    Cached    Shmem   Slab    Available
1782444   1088312   142808     278528    10880   79024   1479176
Done

Capture a screenshot

To capture and save screenshots in PNG format, use gwsi-tool-screenshooter.

vega exec vda shell gwsi-tool-screenshooter <file.png>

Example:

$ vega exec vda shell gwsi-tool-screenshooter /tmp/test.png

$ vega exec vda pull /tmp/test.png

$ ls test.png
test.png

Device logs

To print device logs to the screen, use loggingctl log:

vega exec vda shell loggingctl log <subcommands>

Example:

vega exec vda shell loggingctl log -o short-precise -f

Example output:

Jun 05 18:10:37.484732 firetvstick-xxxxxxxxxxxxxxxx idle-manager[3268]: I idle-service:[IdleManagerService.cpp:107] transitionTo: 0->2
Jun 05 18:10:37.484831 firetvstick-xxxxxxxxxxxxxxxx idle-manager[3268]: I idle-service:[ScreensaverLauncher.cpp:71] Launching pkg://com.amazon.screensaver
Jun 05 18:10:37.485561 firetvstick-xxxxxxxxxxxxxxxx lcm_service[2151]: I lcm-ipc-server:[LcmServer.cpp:182] Received request: launch app for result (1) from (uid:101, gid:101, pid:3268, security_ctx:System)
<continuous log output>

​VDA global options

​Serial override

​Device (USB)

​Device (TCP/IP)

​Vega Virtual Device

​VDA local commands

​Devices

​Get serial number

​TCP/IP mode

​USB mode

​Connect

​Disconnect

​Help

​Kill server

​Start server

​Push

​Pull

​Version

​Wait for device

​Reboot

​VDA shell commands

​Invoke the shell

​Other shell commands

​App management and communication tools

​Launch component shell

​High-level memory

​Capture a screenshot

​Device logs

​Related topics

VDA global options

Serial override

Device (USB)

Device (TCP/IP)

Vega Virtual Device

VDA local commands

Devices

Get serial number

TCP/IP mode

USB mode

Connect

Disconnect

Help

Kill server

Start server

Push

Pull

Version

Wait for device

Reboot

VDA shell commands

Invoke the shell

Other shell commands

App management and communication tools

Launch component shell

High-level memory

Capture a screenshot

Device logs

Related topics