VOLTTRON Quick Start
This tutorial has been written with the intent of helping folks get up-and-running with VOLTTRON. The tutorial is designed to deploy on Linux virtual machines. While not going too much into depth, it covers the following topics:
Install the VOLTTRON platform and verify the installation.
Get familiar with the VOLTTRON components.
Get familiar with the VOLTTRON commands.
Prerequisites
In this tutorial we will demonstrate installing the VOLTTRON platform at an Ubuntu 20.04 LTS (Focal Fossa) Virtual machine. In order to follow the tutorial, the prerequisites are as follows:
Linux OS image (e.g., Ubuntu 20.04)
Virtualization software (e.g., VirtualBox, VMware)
Internet accessibility
sudo capability
Installation Steps
1. Install prerequisites
The first step is to make sure required dependencies are fulfilled. Install the dependencies with the following command:
$ sudo apt-get update
$ sudo apt-get install build-essential python3-dev python3-venv openssl libssl-dev libevent-dev git
Verify python installation with the following command:
$ python3 --version
# expected output similar to this
Python 3.8.10
Similarly, verify git installation.
$ git --version
# expected output similar to this
git version 2.25.1
2. Download VOLTTRON code
Download the VOLTTRON code to the default home directory using git clone
command.
$ cd ~
$ git clone https://github.com/VOLTTRON/volttron
# expected output similar to this
Cloning into 'volttron'...
remote: Enumerating objects: 82987, done.
remote: Counting objects: 100% (4892/4892), done.
remote: Compressing objects: 100% (1971/1971), done.
remote: Total 82987 (delta 3155), reused 4294 (delta 2890), pack-reused 78095
Receiving objects: 100% (82987/82987), 102.73 MiB | 4.19 MiB/s, done.
Resolving deltas: 100% (57997/57997), done.
Checking out files: 100% (1807/1807), done.
...
Note
In this tutorial we download the VOLTTRON code to the default home directory. However, feel free to download the code to a different place as desired.
# $ mkdir <path-to-dir>
# $ cd <path-to-dir>
# $ git clone https://github.com/VOLTTRON/volttron
After successfully downloading the VOLTTRON package, change the current working path to the code path. Then, inspect the source code files.
$ cd volttron
$ ls
# expected output similar to this
bootstrap.py deprecated pylintrc requirements.py stop-volttron
ci-integration docs pytest.ini scripts TERMS.md
CONTRIBUTING.md examples README.md services volttron
COPYRIGHT integrations readthedocs.yml setup.py volttron_data
debugging_utils LICENSE.md RELEASE_NOTES.md start-volttron volttrontesting
3. Bootstrap VOLTTRON environment
VOLTTRON is a Python-based platform. In this step, we will rely on the bootstrap.py
script in the root directory to bootstrap the platform environment. This process will create a virtual environment and install the package’s Python dependencies.
Note
VOLTTRON provides different message bus options. In this tutorial we will demonstrate the default ZeroMQ option. (Read more about message bus.)
Bootstrap the VOLTTRON environment by running the following command. (This may take a while.)
$ python3 bootstrap.py
# expected output similar to this
UPDATE: []
Installing required packages
+ pip install --no-deps wheel==0.30
Collecting wheel==0.30
Using cached
<https://files.pythonhosted.org/packages/0c/80/16a85b47702a1f47a63c104c91abdd0a6704ee8ae3b4ce4afc49bc39f9d9/wheel-0.30.0-py2.py3-none-any.whl>
...
After bootstrap finished, we activate the Python virtual environment with the following command:
$ source env/bin/activate
You may notice the command prompt has changed and there is the virtual environment name as prefix. e.g., (volttron) user@host:~/volttron $
. The prefix environment name indicates the virtual environment is activated.
Alternatively, you can use the following command to verify if the virtual environment is up.
$ env |grep VIRTUAL_ENV |wc -l
# expected output 1(virtual environment is up) or 0 (not up)
Use deactivate command to deactivate the virtual environment, i.e., $ deactivate volttron
. Note: if you run this command, remember to re-activate the virtual environment to follow the rest of the steps.
Note
In this tutorial the VOLTTRON platform is deployed in virtualenv. In case you choose other virtual environment, make adjustment as needed.
4. Start VOLTTRON
In this step, we will start the VOLTTRON platform and demonstrate several VOLTTRON commands.
Start the VOLTTRON platform with the following command:
$ ./start-volttron
# expected output similar to this
...
Starting VOLTTRON verbosely in the background with VOLTTRON_HOME=/home/user/.volttron
Waiting for VOLTTRON to startup..
VOLTTRON startup complete
Check the status of VOLTTRON with the following command:
$ vctl status
For fresh installation, the result might look like the following since there are no agents installed yet.
# expected output similar to this
No installed Agents found
Tip
Use vctl status
to check status.
This is a very useful command to inspect the status of VOLTTRON.
VOLTTRON platform comes with several built in services and example agents out of the box. In this demo, we use the Listener Agent - a simple agent that periodically publishes heartbeat message and listens to everything on the message bus. (Read more about agent.)
Install the Listener agent using the following command:
$ vctl install examples/ListenerAgent --tag listener
# expected output similar to this
Agent b755bae2-a3f5-44a0-b01f-81e30b989138 installed
Start the agent we just installed specified by the listener tag.
$ vctl start --tag listener
# expected output similar to this
Starting b755bae2-a3f5-44a0-b01f-81e30b989138 listeneragent-3.3
Check the status again.
$ vctl status
# expected output similar to this
UUID AGENT IDENTITY TAG STATUS HEALTH
8 listeneragent-3.3 listeneragent-3.3_1 listener running [2192] GOOD
From the above result, we can tell the listener agent is functioning properly!
Tip
While the --tag
sub-command is optional, a tag is helpful for managing agents by adding semantic tags to different topics, so that topic can be queried by tags instead of specific topic name or topic name pattern.
You can choose any tag name that makes sense to you, as long as the tags are already defined in the VOLTTRON tagging schema. (Read more about tag.)
In addition to the vctl status
, another way to check VOLTTRON status is by inspecting the volttron.log
file. The file provides rich information about the platform and becomes handy for debug purposes.
$ tail -f volttron.log
# example output (success)
# listener agent is publishing heartbeat messages successively.
2022-03-04 14:12:46,463 (listeneragent-3.3 2192) __main__ INFO: Peer: pubsub, Sender: listeneragent-3.3_1:, Bus: , Topic: heartbeat/listeneragent-3.3_1, Headers: {'TimeStamp': '2022-03-04T19:12:46.460096+00:00', 'min_compatible_version': '3.0', 'max_compatible_version': ''}, Message: 'GOOD'
...
# example output (error)
2022-03-04 13:16:05,469 (listeneragent-3.3 3233) volttron.platform.vip.agent.core ERROR: No response to hello message after 10 seconds.
2022-03-04 13:16:05,469 (listeneragent-3.3 3233) volttron.platform.vip.agent.core ERROR: Type of message bus used zmq
2022-03-04 13:16:05,469 (listeneragent-3.3 3233) volttron.platform.vip.agent.core ERROR: A common reason for this is a conflicting VIP IDENTITY.
2022-03-04 13:16:05,469 (listeneragent-3.3 3233) volttron.platform.vip.agent.core ERROR: Another common reason is not having an auth entry onthe target instance.
2022-03-04 13:16:05,469 (listeneragent-3.3 3233) volttron.platform.vip.agent.core ERROR: Shutting down agent.
...
5. Stop VOLTTRON (Optional)
To stop VOLTTRON, use the following command:
$ ./stop-volttron
# expected output similar to this
Shutting down VOLTTRON
After stopping the platform, check the status again to verify the VOLTTRON platform is shut down.
$ vctl status
# expected output similar to this
VOLTTRON is not running. This command requires VOLTTRON platform to be running
Clean up (Optional)
If for some reason you would like to clean up VOLTTRON, here is the guide to remove the whole VOLTTRON package
remove the code folder (e.g.,
~/volttron/
)remove the
.volttron/
folder atVOLTTRON_HOME/.volttron
(e.g., by default at~/.volttron
)
Summary
This short tutorial for VOLTTRON first-time users. We covered the following topics.
VOLTTRON platform installation. (e.g., on a Virtual Machine.)
VOLTTRON components. (e.g., agent, message bus, tag.)
VOLTTRON commands. (e.g.,
start-volttron
,vctl status
.)
Next Steps
There are several walk-throughs and detailed explanations of platform features to explore additional aspects of the platform:
Demonstration of the management UI
RabbitMQ setup with Federation and Shovel plugins