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 avaialble 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|dips|adb-discover|monitor|restart|run|start|status|stop|trigger|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|dips|adb-discover|monitor|restart|run|start|status|stop|trigger|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|dips|adb-discover|monitor|restart|run|start|status|stop|trigger|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 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 restart:
    -debug
     	Debug logging
    Usage of run:
    -debug
     	Debug logging
    Usage of start:
    -debug
     	Debug logging
    Usage of status:
    -debug
     	Debug logging
    Usage of stop:
    -debug
     	Debug logging
    Usage of trigger:
    -buildId string
     	Build ID
    -buildNumber string
     	Build number/version
    -buildUri string
     	Location of the build
    -debug
     	Debug logging
    -metadata string
     	Optional build metadata as a JSON string
    -releaseId string
     	Release ID
    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

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.

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.

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 verision
    version: 2.0.0.0+wxyz

trigger​

The trigger subcommand is a command that can be utlized to send trigger events to the LabScale service; however, this command is deprecated and has been replaced by the labscale-cli. Please consult the CLI User Guide for more information on how to trigger jobs and workflows in the LabScale service.