VOLTTRON Control

The base platform functionality focuses on the agent lifecycle, management of the platform itself, and security. This section describes how to use the commands included with VOLTTRON to configure and control the platform, agents and drivers.

Platform Commands

Eclipse VOLTTRONtm (VOLTTRON/volttron) files for a platform instance are stored under a single directory known as the VOLTTRON home. This home directory is set via the VOLTTRON_HOME environment variable and defaults to $HOME/.volttron. Multiple instances of the platform may exist under the same account on a system by setting the VOLTTRON_HOME environment variable appropriately before executing VOLTTRON commands. The volttron and volttron-ctrl commands can be passed arguments or be specified in a configuration file. By default a configuration file will be created the first time an instance is executed at VOLTTRON_HOME/config.

VOLTTRON’s configuration file uses a modified INI format where section names are command names for which the settings in the section apply. Settings before the first section are considered global and will be used by all commands for which the settings are valid. Settings keys are long options (with or without the opening “–”) and are followed by a colon (:) or equal (=) and then the value. Boolean options need not include the separator or value, but may specify a value of 1, yes, or true for true or 0, no, or false for false.

[volttron]
instance-name = volttron1
vip-address = tcp://127.0.0.1:22916

where:

  • instance-name - Name of the VOLTTRON instance. This has to be unique if multiple instances need to be connected together

  • vip-address - VIP address of the VOLTTRON instance. It contains the IP address and port number (default port number is 22916)

Start volttron with default config file
volttron -l volttron.log &
Start with alternate configuration file
volttron -c <config> -l volttron.log &

Below is a compendium of commands which can be used to operate the VOLTTRON Platform from the command line interface.

VOLTTRON Platform Command

The main VOLTTRON platform command is volttron, however this command is seldom run as-is. In most cases the user will want to run the platform in the background. In a limited number of cases, the user will wish to enable verbose logging. A typical command to start the platform is:

Note

  • All commands and sub-commands have help available with -h or --help

  • Additional configuration files may be specified with -c or -config

  • To specify a log file, use -l or --log

  • The ampersand (&) can be added to then end of the command to run the platform in the background, freeing the open shell to be used for additional commands.

volttron -vv -l volttron.log &

volttron Optional Arguments

  • -c FILE, –config FILE - Start the platform using the configuration from the provided FILE

  • -l FILE, –log FILE - send log output to FILE instead of standard output/error

  • -L FILE, –log-config FILE - Use the configuration from FILE for VOLTTRON platform logging

  • –log-level LOGGER:LEVEL - override default logger logging level (INFO, DEBUG, WARNING, ERROR, CRITICAL, NOTSET)

  • -q, –quiet - decrease logger verboseness; may be used multiple times to further reduce logging (i.e. -qq)

  • -v, –verbose - increase logger verboseness; may be used multiple times (i.e. -vv)

  • –verboseness LEVEL - set logger verboseness level

  • -h, –help - show this help message and exit

  • –version - show program’s version number and exit

Note

Visit the Python 3 logging documentation for more information about logging and verboseness levels.

Agent Options

  • –autostart - automatically start enabled agents and services after platform startup

  • –vip-address ADDR - Address to bind for VIP connections

  • –instance-name INSTANCE_NAME - The name of the instance that will be reported to VOLTTRON Central.

Warning

Certain options alter some basic behaviors of the platform, such as –agent-isolation-mode which causes the platform to run each agent using its own Unix user to spawn the process. Please view the documentation for each feature to understand its implications before choosing to run the platform in that fashion.

volttron-ctl Commands

volttron-ctl (vctl) is used to issue commands to the platform from the command line. Through volttron-ctl it is possible to install and removed agents, start and stop agents, manage the configuration store, get the platform status, and shutdown the platform.

Warning

vctl creates a special temporary agent to communicate with the platform with a specific VIP Identity, thus multiple instances of vctl cannot run at the same time. Attempting to do so will result in a conflicting identity error.

Use vctl with one or more of the following arguments, or below sub-commands:

vctl Optional Arguments

  • -c FILE, –config FILE - Start the platform using the configuration from the provided FILE

  • –debug - show tracebacks for errors rather than a brief message

  • -t SECS, –timeout SECS - timeout in seconds for remote calls (default: 60)

  • –vip-address ADDR - URL to bind for VIP connections

  • -l FILE, –log FILE - send log output to FILE instead of standard output/error

  • -L FILE, –log-config FILE - Use the configuration from FILE for VOLTTRON platform logging

  • -q, –quiet - decrease logger verboseness; may be used multiple times to further reduce logging (i.e. -qq)

  • -v, –verbose - increase logger verboseness; may be used multiple times (i.e. -vv)

  • –verboseness LEVEL - set logger verboseness level (this level is a numeric level co

  • –json - format output to json

  • -h, –help - show this help message and exit

Commands

  • install - install an agent from wheel or from an agent package directory

    Note

    If –agent-config is not specified then a default config, config.json or config.yml file in the agent directory will be used as configuration. If none present then no configuration file will be loaded.

  • tag AGENT TAG - set, show, or remove agent tag for a particular agent

  • remove AGENT - disconnect specified agent from the platform and remove its installed agent package from VOLTTRON_HOME

  • peerlist - list the peers connected to the platform

  • status - show status of installed agents

  • health AGENT - show agent health as JSON

  • clear - clear status of defunct agents

  • enable AGENT - enable agent to start automatically

  • disable AGENT - prevent agent from start automatically

  • start AGENT - start installed agent

  • stop AGENT - stop agent

  • restart AGENT - restart agent

  • run PATH - start any agent by path

    Note

    Does NOT upgrade agents from the agent’s code directory, requires agent wheel file.

  • rpc - rpc controls

  • certs OPTIONS - manage certificate creation

  • auth OPTIONS - manage authorization entries and encryption keys

  • config OPTIONS - manage the platform configuration store

  • shutdown - stop all agents (providing the –platform optional argument causes the platform to be shutdown)

  • send WHEEL - send agent and start on a remote platform

  • stats - manage router message statistics tracking

  • rabbitmq OPTIONS - manage rabbitmq

Note

For each command with OPTIONS in the description, additional options are required to make use of the command. For each, please visit the corresponding section of documentation.

Note

Visit the Python 3 logging documentation for more information about logging and verboseness levels.

vctl auth Subcommands

  • add - add new authentication record

  • add-known-host - add server public key to known-hosts file

  • keypair - generate CurveMQ keys for encrypting VIP connections

  • list - list authentication records

  • list-known-hosts - list entries from known-hosts file

  • publickey - show public key for each agent

  • remove - removes one or more authentication records by indices

  • remove-known-host - remove entry from known-hosts file

  • serverkey - show the serverkey for the instance

  • update - updates one authentication record by index

vctl certs Subcommands

  • create-ssl-keypair - create a SSL keypair

  • export-pkcs12 - create a PKCS12 encoded file containing private and public key from an agent. This function is may also be used to create a Java key store using a p12 file.

vctl config Subcommands

  • store AGENT CONFIG_NAME CONFIG PATH - store a configuration file in agent’s config store (parses JSON by default, use –csv for CSV files)

  • edit AGENT CONFIG_NAME - edit a configuration. (opens nano by default, respects EDITOR env variable)

  • delete AGENT CONFIG_NAME - delete a configuration from agent’s config store (–all removes all configs for the agent)

  • list AGENT - list stores or configurations in a store

  • get AGENT CONFIG_NAME - get the contents of a configuration

vctl rpc Subcommands

  • code - shows how to use RPC call in other agents

  • list - lists all agents and their RPC methods