Skip to main content

LabScale Agent User Guide

Introduction​

LabScale provides remote job execution and test runner called simply the Agent. The agent receives commands from the LabScale MQTTS broker and performs actions based on those commands. It also monitors the host and target devices under test and reports various metrics back to the LabScale service. The Agent is controlled by the agentctl executable, this guide describes that tool in more detail.

Download & Install​

To download and install the LabScale Agent, please refer to the Quick Start Guide.

Command Reference​

The Agent is controlled and managed by a tool called agentctl that comes packaged within the agent distribution bundle. The agentctl performs several different kinds of operations based on the commands it is provided. General usage is as follows:

./agentctl [options] command

Options​

The agentctl allows for the following options:

  -help

The help option will display a list of options available to the provided command.

  -debug

The debug option enables extended logging to help debug problems with the agent at run time.

available Commands​

  help|config|devices|dial|dips|adb-discover|monitor|reset|restart|run|start|status|stop|validate|version

help​

The help subcommand displays some helpful information about usage of the agentctl.

tip

agentctl help -help Will display the help for all available commands.

  • Examples:

    • To show top level help for the agentctl:
    ./agentctl help
    Usage of agentctl [command] help|config|devices|dial|dips|adb-discover|monitor|reset|restart|run|start|status|stop|validate|version
    -debug
      	Debug logging
    -help
      	Show help
    • To show help for a single command within the agentctl:
    ./agentctl adb-discover -help
    Usage of adb-discover:
      -debug
      	Debug logging
      -force
      	Force update to backend
    • To show help for all commands within in the agentctl:
    ./agentctl help -help
    Usage of agentctl [command] help|config|devices|dial|dips|adb-discover|monitor|reset|restart|run|start|status|stop|validate|version
    Usage of config:
    -agentId string
     	The Agent ID
    -brokerPort string
     	Update broker port
    -brokerUrl string
     	The broker URL
    -code string
     	Code string provided by LabScale
    -debug
     	Debug logging
    -force
     	Force overwrite of existing config
    -otp string
     	The one-time password
    -outputPath string
     	Config output filepath (default "./config.yaml")
    -portMenu
     	Select alternative broker port
    -show
     	Display this config
    -showPort
     	Display current broker port
    -teamId string
     	The Team ID
    Usage of devices:
    -debug
     	Debug logging
    Usage of dial:
    -debug
     	Debug logging
    -dial-timeout int
     	Dial timeout (default 5)
    -go-resolver
     	Use Go resolver
    -local-ip string
     	Local IP
    -network string
     	Network transport type (default "tcp")
    -resolv-timeout int
     	Resolver timeout (default 5)
    Usage of dips:
    -debug
     	Debug logging
    Usage of adb-discover:
    -debug
     	Debug logging
    -force
     	Force update to backend
    Usage of monitor:
    -debug
     	Debug logging
    -log string
     	Path for output file
    Usage of reset:
    -debug
     	Debug logging
    Usage of restart:
    -debug
     	Debug logging
    Usage of run:
    -debug
     	Debug logging
    -debug-mqtt
     	Debug MQTT logging
    Usage of start:
    -debug
     	Debug logging
    Usage of status:
    -debug
     	Debug logging
    Usage of stop:
    -debug
     	Debug logging
    Usage of validate:
    -debug
     	Debug logging
    Usage of version:
    -debug
     	Debug logging

config​

The config subcommand can be used to set some config parameters.

  • Examples:

    • To configure the agent to use port 443 for communication with the broker:
    ./agentctl config -brokerPort 443
    • To manually select the broker port using an interactive menu:
    ./agentctl config -portMenu
    0) *8883
    1) 443
    Select alternative network port?

devices​

The devices subcommand displays devices that are currently managed by the agent.

  • Example: 
    ./agentctl devices
    Installed devices:
    Device ID     Device Name
    ---------     -----------
    ufbkfo0p3rnr  virt-1
    f1k6tejoo2ue  virt-2

dial​

The dial subcommand opens a plain network connection to an address and reports the local bind address and the remote address it reached. It is a network troubleshooting aid, useful when the agent cannot reach the broker and you need to determine whether name resolution or the outbound connection itself is at fault.

If no address argument is supplied, the broker URL from the agent's config.yaml is used. An address given without a port defaults to port 80.

The dial subcommand accepts the following options:

  • -network <type> — the network transport type to dial (default tcp).
  • -dial-timeout <seconds> — how long to wait on the connection attempt (default 5).
  • -resolv-timeout <seconds> — how long to wait on name resolution (default 5).
  • -go-resolver — use the Go DNS resolver instead of the host system resolver.
  • -local-ip <address> — bind the outgoing connection to a specific local IP address.
  • -debug — additionally list the local IP addresses found on the host.

An example of dialing the broker directly:

./agentctl dial broker.labscale.com:8883
connecting to tcp: broker.labscale.com:8883
bind address tcp: 192.168.1.24:54782
connected to: 52.10.24.117:8883

dips​

The dips subcommand displays the Device Integration Packages (DIPs) that are currently managed by the agent.

  • Example: 
    ./agentctl dips
    Installed DIPs:
    DIP Name             DIP Version
    --------             ------------
    android_adb_dip      v2.1.2
    macos_host_dip       v2.22.0.495
    raspberry_pi_ssh_dip v2.0.3
    virtual_dip          v2.0.4

adb-discover​

The adb-discover command will discover and register ADB devices that are connected to the local host. This allows for automatic addition of ADB device to the agent. Devices will only be discovered once but can be re-discovered with the -force option.

  • Example: 
    ./agentctl adb-discover
    ADB found the following devices:
    * emulator-5554
    Publishing new devices: emulator-5554
    Done!

monitor​

The monitor subcommand will start the agent in a foreground task that monitors its execution and will automatically restart the agent if it prematurely exits. Output from the agent can be redirected to a file with the -log <logfile> option. To exit, press CTRL-C.

  • Example: 
    ./agentctl monitor -log foo.txt
    Entering monitoring mode...

run​

The run subcommand will start the agent in an unsupervised, foreground task. To exit, press CTRL-C.

The -debug-mqtt option additionally enables the low-level MQTT client logging. This is separate from the general -debug option because the MQTT trace output is verbose, and is normally only needed when diagnosing broker connection or subscription problems.

  • Example: 
    ./agentctl run -debug -debug-mqtt

start​

The start subcommand will start the agent in a supervised, demonized background task if it has not been already started and will display the version and process ID of the running agent. Output from the agent is redirected to the labscale-agent.log file in the same location. If the agent is already running, it will notify the user, but not launch another instance. To stop the agent, type ./agentctl stop.

  • Example: 
    ./agentctl start
    Starting Agent: 2.22.0.495+ae0a2e9
    Agent started: 14424

stop​

The stop subcommand will stop a running agent, or notify the user that the agent is not running.

  • Example: 
    ./agentctl stop
    Agent stopped

restart​

The restart subcommand will stop and then start the agent and is essentially the same as issuing the stop and then start commands.

reset​

The reset subcommand forces the agent to rebuild its device and DIP dependencies. Use it when a DIP or device installation on the host has become inconsistent and you want the agent to reinstall everything from scratch.

The behavior depends on whether the agent is currently running:

  • If the agent is running, it is signaled to reset in place. The agent reports itself online again and reinstalls its DIPs and devices without needing a restart.

  • If the agent is not running, the installed DIPs and the local device list are removed from the host. The agent will rebuild them the next time it starts.

  • Examples:

    • Resetting a running agent:
    ./agentctl reset
    Resetting agent pid: 14424
    • Resetting a stopped agent:
    ./agentctl reset
    Resetting agent

status​

The status subcommand will display the current running state of the agent.

  • Examples:

    • If the agent is not running
    ./agentctl status
    Agent is not running
    • If the agent is running, it will show the current process ID
    ./agentctl status
    Agent is running: 11507

validate​

The validate subcommand will test the connection between the agent and the LabScale broker service. If the is a problem with the connection, it will return a reason for its inability to connect, otherwise it will simply say that it is ready to run.

  • Example: 
    ./agentctl validate
    Ready to run.

version​

The version subcommand will print the version of the agentctl.

  • Example:
    • To display the current version of the CLI tool:
    ./agentctl version
    version: 2.0.0.0+wxyz