VOLTTRON Documentation Release 3.5RC1
Total Page:16
File Type:pdf, Size:1020Kb
VOLTTRON Documentation Release 3.5RC1 The VOLTTRON Developer Team June 30, 2016 Contents 1 Installation 3 1.1 Source Code...............................................3 1.2 Bootstrap.................................................3 1.3 Activate..................................................3 1.4 Testing..................................................4 1.5 Execution.................................................4 1.6 Next Steps................................................4 2 License 5 3 Community Resources 7 3.1 Community Resources..........................................7 4 Overview 9 4.1 Definition of Terms............................................9 4.2 Platform Background...........................................9 4.3 Platform Components.......................................... 10 4.4 Agents in the Platform.......................................... 10 4.5 VOLTTRON Version History...................................... 11 5 VOLTTRON Core Services 13 5.1 Base Platform Functionality....................................... 13 5.2 VOLTTRON Historian Framework................................... 19 5.3 VOLTTRON Driver Framework..................................... 25 5.4 VOLTTRON Message Bus........................................ 43 5.5 Service Agents.............................................. 61 5.6 VOLTTRON Security.......................................... 85 5.7 VOLTTRON PNNL Licensed Code................................... 86 6 Developer Resources 91 6.1 Getting Started.............................................. 91 6.2 Agent Development........................................... 103 6.3 Deployment Advice........................................... 156 6.4 Walkthroughs............................................... 161 6.5 Eclipse IDE Setup............................................ 173 7 Example Agents and Uitlities 191 7.1 Example Agents............................................. 191 7.2 Utilities.................................................. 199 i 8 Scalability Experiments 205 8.1 Scalability Setup............................................. 205 8.2 Improvements Based on Results..................................... 207 8.3 Scalability Planning........................................... 207 9 Development History and Roadmap 211 9.1 Migration from 1.2 - 2.0......................................... 211 9.2 Migration from 2.x to 3.x........................................ 211 9.3 3.X drivers................................................ 213 9.4 Migration from 3.0 to 3.5........................................ 214 9.5 Change Logs............................................... 215 9.6 Transitioning from 1.x to 2.x....................................... 217 9.7 VOLTTRON Versions.......................................... 218 10 API Documentation 221 10.1 Services.................................................. 221 10.2 Applications............................................... 260 10.3 Examples................................................. 285 10.4 Volttron.................................................. 294 11 Support 349 12 Indices and tables 351 Python Module Index 353 ii VOLTTRON Documentation, Release 3.5RC1 Contents: Contents 1 VOLTTRON Documentation, Release 3.5RC1 2 Contents CHAPTER 1 Installation VOLTTRON requires the following dependencies in order to bootstrap the development environment. • Essential build tools (gcc, make, autodev-tools, etc.) • Python development files (headers) • Openssl. • Git (Optional) On Debian-based systems, these can all be installed with the following command: sudo apt-get update sudo apt-get install build-essential python-dev openssl libssl-dev libevent-dev git On Arch Linux, the following command will install the dependencies: sudo pacman -S base-devel python2 openssl libssl-dev libsodium 1.1 Source Code To work with the latest devlopment code clone from the develop branch by using the following git command. git clone https://github.com/VOLTTRON/volttron/ -b develop To work with the latest stable code clone the master branch using the following git command. git clone https://github.com/VOLTTRON/volttron/ 1.2 Bootstrap To create a development environment, execute the following in the project root directory. python2.7 bootstrap.py 1.3 Activate Activating the shell sets the correct environment for executing a volttron instance. From the project root directory execute the following. 3 VOLTTRON Documentation, Release 3.5RC1 source env/bin/activate Note that an ‘activated’ command prompt is like the following .. code-block:: bash (volttron)user@machine $ 1.4 Testing VOLTTRON uses py.test as a framework for executing tests. py.test is not installed with the distribution by default. To install py.test and it’s dependencies execute the following: python bootstrap.py --testing To run all of the tests in the volttron repository execute the following in the root directory using an activated command prompt: py.test 1.5 Execution To start a default instance of volttron from an activated command prompt execute the following. volttron -vv Or to start volttron in the background with logging to a file called volttron.log execute the following. volttron -vv -l volttron.log& 1.6 Next Steps • agent-development 4 Chapter 1. Installation CHAPTER 2 License Copyright (c) 2013-2016, Battelle Memorial Institute All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the follow- ing disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, IN- CIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI- NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CON- TRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAM- AGE. The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the FreeBSD Project. This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof. PACIFIC NORTHWEST NATIONAL LABORATORY operated by BATTELLE for the UNITED STATES DEPART- MENT OF ENERGY under Contract DE-AC05-76RL01830 5 VOLTTRON Documentation, Release 3.5RC1 6 Chapter 2. License CHAPTER 3 Community Resources 3.1 Community Resources 3.1.1 Mailing List Join the mailing list by emailing [email protected]. 3.1.2 Office Hours PNNL hosts office hours every other week on Fridays at 10:30 AM (PST). These meetings are designed to be very informal where VOLTTRON developers can answer specific questions about the inner workings of VOLTTRON. These meetings are also available for topical discussions of different aspects of the VOLTTRON platform. Currently the office hours are available through a Lync meeting. Join Lync Meeting Dial in Number: 1-866-528-1882 Conference Number: 886916 7 VOLTTRON Documentation, Release 3.5RC1 8 Chapter 3. Community Resources CHAPTER 4 Overview 4.1 Definition of Terms • JsonRPC: JSON-encoded remote procedure call • JSON: JavaScript object notation is a text-based, human-readable, open data interchange format, similar to XML, but much better • Publish/subscribe: A message delivery pattern where senders (publishers) and receivers (subscribers) do not communicate directly nor necessarily have knowledge of each other, but instead exchange messages through an intermediary based on a mutual class or topic • ZeroMQ or ØMQ: A library used for interprocess and intercomputer communicationc • Modbus: Communications protocol for talking with industrial electronic devices • SSH: Secure shell is a network protocol providing encryption and authentication of data using public-key cryp- tography • SSL: Secure sockets layer is a technology for encryption and authentication of network