VOLTTRON Documentation Release 5.0-Rc2
Total Page:16
File Type:pdf, Size:1020Kb
VOLTTRON Documentation Release 5.0-rc2 The VOLTTRON Developer Team Jan 03, 2018 Contents 1 Features 3 2 Background 5 3 Installation 7 4 Next Steps 9 5 Acquiring Third Party Agent Code 11 6 Contribute 13 7 Support 15 7.1 License.................................................. 15 Python Module Index 423 i ii VOLTTRON Documentation, Release 5.0-rc2 VOLTTRONTM is an open-source platform for distributed sensing and control. The platform provides services for collecting and storing data from buildings and devices and provides an environment for developing applications that interact with that data. Contents 1 VOLTTRON Documentation, Release 5.0-rc2 2 Contents CHAPTER 1 Features Out of the box VOLTTRON provides: • a secure message bus allowing agents to subcribe to data sources and publish results and messages. • secure connectivity between multiple instances. • BACnet, ModBus and other device/system protocol connectivity through our driver framework for collecting data from and sending control actions to buildings and devices. • automatic data capture and retrieval through our historian framework. • platform based agent lifecycle managment. •a web based management tool for managing several instances from a central instance. • the ability to easily extend the functionality of existing agents or create new ones for your specific purposes. 3 VOLTTRON Documentation, Release 5.0-rc2 4 Chapter 1. Features CHAPTER 2 Background VOLTTRONTM is written in Python 2.7 and runs on Linux Operating Systems. For users unfamiliar with those technologies, the following resources are recommended: • https://docs.python.org/2.7/tutorial/ • http://ryanstutorials.net/linuxtutorial/ 5 VOLTTRON Documentation, Release 5.0-rc2 6 Chapter 2. Background CHAPTER 3 Installation Install VOLTTRON by running the following commands that installs needed prerequisites, clones the source code, then builds the virtual environment for using the platform. sudo apt-get update sudo apt-get install build-essential python-dev openssl libssl-dev libevent-dev git git clone https://github.com/VOLTTRON/volttron cd volttron python bootstrap.py This will build the platform and create a virtual Python environment. Activate this and then start the platform with: . env/bin/activate volttron -vv -l volttron.log& This enters the virtual Python environment and then starts the platform in debug (vv) mode with a log file named volttron.log. Next, start an example listener to see it publish and subscribe to the message bus: scripts/core/make-listener This script handles several different commands for installing and starting an agent after removing an old copy. This simple agent publishes a heartbeat message and listens to everything on the message bus. Look at the VOLTTRON log to see the activity: tail volttron.log Results in: 2016-10-17 18:17:52,245 (listeneragent-3.2 11367) listener.agent INFO: Peer: 'pubsub', ,! Sender: 'listeneragent-3.2_1' :, Bus: u'', Topic: 'heartbeat/ListenerAgent/f230df97-658e-45d3-8165-18a2ec834d3f', ,!Headers: {'Date': '2016-10-18T01:17:52.239724+00:00', 'max_compatible_version': u'', 'min_ ,!compatible_version': '3.0'}, 7 VOLTTRON Documentation, Release 5.0-rc2 Message: {'status': 'GOOD', 'last_updated': '2016-10-18T01:17:47.232972+00:00', ,!'context': 'hello'} Stop the platform: volttron-ctl shutdown --platform 8 Chapter 3. Installation CHAPTER 4 Next Steps There are several walkthroughs to explore additional aspects of the platform: • Agent Development Walkthrough • Demonstration of the management UI 9 VOLTTRON Documentation, Release 5.0-rc2 10 Chapter 4. Next Steps CHAPTER 5 Acquiring Third Party Agent Code Third party agents are available under volttron-applications repository. In order to use those agents, add volttron- applications repository under the volttron/applications directory by using following command: git subtree add –prefix applications https://github.com/VOLTTRON/volttron-applications.git develop –squash 11 VOLTTRON Documentation, Release 5.0-rc2 12 Chapter 5. Acquiring Third Party Agent Code CHAPTER 6 Contribute How to contribute back: • Issue Tracker: http://github.com/VOLTTRON/volttron/issues • Source Code: http://github.com/VOLTTRON/volttron 13 VOLTTRON Documentation, Release 5.0-rc2 14 Chapter 6. Contribute CHAPTER 7 Support There are several options for VOLTTRONTM support. • A VOLTTRONTM office hours telecon takes place every other Friday at 11am Pacific over Skype. • volttron-community.slack.com is where the VOLTTRONTM community at large can ask questions and meet with others using VOLTTRONTM. Signup via https://volttron-community.signup.team/ • A mailing list for announcements and reminders • The VOLTTRONTM contact email for being added to office hours, the mailing list, and for inquiries is: volt- [email protected] • The preferred method for questions is through stackoverflow since this is easily discoverable by others who may have the same issue. http://stackoverflow.com/questions/tagged/volttron • GitHub issue tracker for feature requests, bug reports, and following development activities http://github.com/ VOLTTRON/volttron/issues 7.1 License The project is licensed under a modified BSD license. Contents: 7.1.1 Overview VOLTTRON™ is an open-source distributed control and sensing platform for integrating buildings and the power grid. VOLTTRON connects devices, agents in the platform, agents in the Cloud, and signals from the power grid. The platform also supports use cases such as demand response and integration of distributed renewable energy sources. VOLTTRON provides an environment for agent execution and serves as a single point of contact for interfacing with devices (rooftop units, building systems, meters, etc.), external resources, and platform services such as data archival and retrieval. VOLTTRON applications are referred to as agents since VOLTTRON provides an agent-based programming paradigm to ease application development and minimize the lines of code that need to be written by 15 VOLTTRON Documentation, Release 5.0-rc2 domain experts such as buildings engineers. VOLTTRON provides a collection of utility and helper classes that simplifies agent development. The VOLTTRON white paper provides an overview of the capabilities of the platform: https://volttron.org/sites/ default/files/publications/PNNL-25499_VOLTTRON_2016.pdf Components An overview of the VOLTTRON platform components is illustrated in the figure below. The platform comprises several components and agents that provide services to other agents. Of these components, the Information Exchange Bus (IEB), or Message Bus is central to the platform. All other VOLTTRON components communicate through it using the publish/subscribe paradigm over a variety of topics. Drivers communicate with devices allowing their data to be published on the IEB. Agents can control devices by interacting with the Actuator Agent to schedule and send commands. The Historian framework takes data published on the messages bus and stores it to a database, file, or sends it to another location. The agent lifecycle is controlled by the Agent Instantiation and Packaging (AIP) component which launches agents in an Agent Execution Environment. This isolates agents from the platform while allowing them to interact with the IEB. Agents in the Platform Agents deployed on VOLTTRON can perform one or more roles which can be broadly classified into the following groups: 16 Chapter 7. Support VOLTTRON Documentation, Release 5.0-rc2 • Platform Agents: Agents which are part of the platform and provide a service to other agents. Examples are agents which interface with devices to publish readings and handle control signals from other agents. • Cloud Agents: These agents represent a remote application which needs access to the messages and data on the platform. This agent would subscribe to topics of interest to the remote application and would also allow it publish data to the platform. • Control Agents: These agents control the devices of interest and interact with other resources to achieve some goal. Platform Services: • Message Bus: All agents and services publish and subscribe to topics on the message bus. This provides a single interface that abstracts the details of devices and agents from each other. Components in the platform basically produce and consume events. • Weather Information: This agent periodically retrieves data from the Weather Underground site. It then refor- mats it and publishes it out to the platform on a weather topic. • Modbus-based device interface: The Modbus driver publishes device data onto the message bus. It also handles the locking of devices to prevent multiple conflicting directives. • Application Scheduling: This service allows the scheduling of agents’ access to devices in order to prevent conflicts. • Logging service: Agents can publish arbitrary strings to a logging topic and this service will push them to a historian for later analysis. Definition of Terms This page lays out a common terminology for discussing the components and underlying technologies used by the platform. The first section discusses capabilities and industry standards that volttron conforms to while the latter is specific to the VOLTTRON domain. Industry Terms • BACNet: Building Automation and Control network, that leverages ASHRAE, ANSI, and IOS 16484-5 stan- dard protocols. • JSON-RPC: JSON-encoded remote procedure call • JSON: JavaScript object notation is a text-based, human-readable, open data interchange format, similar to XML, but less verbose • Publish/subscribe: A message delivery pattern where senders (publishers)