Package: volttron-boptest
boptest-agentThe volttron-boptest-agent utilizes the volttron-lib-boptest-integration library to perform simulation control and
benchmark tasks.BOPTEST is designed to facilitate
the performance evaluation and benchmarking of building control strategies, which
contains these key components:Run-Time Environment (RTE): Deployed with Docker and accessed with a RESTful HTTP API, use the RTE to set up tests,
control building emulators, access data, and report KPIs.Test Case Repository: A collection of ready-to-use building emulators representing a range of building types and HVAC
systems.Key Performance Indicator (KPI) Reporting: A set of KPIs is calculated by the the RTE using data from the building
emulator being controlled.For more information, please visitIBPSA Project 1 - BOPTEST.PrerequisitesPython 3 (tested with Python3.10)Linux OS (tested with Ubuntu 22.04)PythonTo install specific Python version (e.g., Python 3.10), we recommend usingpyenv.# install pyenvgitclonehttps://github.com/pyenv/pyenv~/.pyenv# setup pyenv (you should also put these three lines in .bashrc or similar)exportPATH="${HOME}/.pyenv/bin:${PATH}"exportPYENV_ROOT="${HOME}/.pyenv"eval"$(pyenvinit-)"# install Python 3.10pyenvinstall3.10# make it available globallypyenvglobalsystem3.10Quick-startSetup environment and VOLTTRON platformThe following recipe walks through the steps to install and demonstrate basic usage of "volttron-boptest" agent.The following recipe walks through the steps to install and run use case example.Note: For the ease of reproducibility, in this demo, we
will git clone thevolttron-boptestrepo to the~/sandbox/path. Feel free to modify the workflow as desired.kefei@ubuntu-22:~/sandbox$gitclonehttps://github.com/eclipse-volttron/volttron-boptest.git
Cloninginto'volttron-boptest'...
remote:Enumeratingobjects:450,done.
remote:Countingobjects:100%(450/450),done.
remote:Compressingobjects:100%(242/242),done.
remote:Total450(delta192),reused424(delta170),pack-reused0Receivingobjects:100%(450/450),3.66MiB|7.06MiB/s,done.
Resolvingdeltas:100%(192/192),done.
kefei@ubuntu-22:~/sandbox$cdvolttron-boptest/
kefei@ubuntu-22:~/sandbox/volttron-boptest$Create and activate a virtual environment.It is recommended to use a virtual environment for installing volttron.python-mvenvenvsourceenv/bin/activate

pipinstallvolttronInstall volttron and start the platform.Note:
According to thevolttron-core#README, setup
VOLTTRON_HOME
environment variable is mandatory:
... if you have/had in the past, a monolithic VOLTTRON version that used the default VOLTTRON_HOME
$HOME/.volttron. This modular version of VOLTTRON cannot work with volttron_home used by monolithic version of
VOLTTRON(version 8.3 or earlier)# Setup environment variable `VOLTTRON_HOME`exportVOLTTRON_HOME=<path-to-volttron_home-dir># Start platform with output going to volttron.logvolttron-vv-lvolttron.log&Setup the boptest simulation server locally.In order to demonstrate the basic usage of volttron-boptest-agent, we need to setup the boptest simulation server.(Please see more details about boptest quick-start
atQuick-Start to Deploy a Test Case)DownloadIBPSA Project 1 - BOPTESTrepository to <boptest_repo>. For
demo purpose, let boptest_repo be~/project1-boptest.gitclonehttps://github.com/ibpsa/project1-boptest~/project1-boptestInstallDockerandDocker Compose.Note: this demo run docker as a non-root user, you can
followLinux post-installation steps for Docker Engineto achieve similar setup.(Optional) Verify withdocker-compose versionto verify the installation(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$docker-composeversion
docker-composeversion1.29.2,buildunknown
docker-pyversion:5.0.3
CPythonversion:3.10.6
OpenSSLversion:OpenSSL3.0.215Mar2022Build and deploy a test case.The basic command to start a test case is by usingTESTCASE=<testcase_name> docker-compose up.For demo purpose, we will build and deploy testcase1, for avialbe testcases please
seetestcases/(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$TESTCASE=testcase1docker-compose--file~/project1-boptest/docker-compose.ymlup
Creatingnetwork"boptest-net"withthedefaultdriver
Creatingproject1-boptest_boptest_1...doneAttachingtoproject1-boptest_boptest_1
boptest_1|07/13/202309:59:42PMUTCrootINFOControlstepsetsuccessfully.
boptest_1|07/13/202309:59:42PMUTCrootINFOTestsimulationinitializedsuccessfullyto0.0swithwarmupperiodof0.0s.
boptest_1|07/13/202309:59:42PMUTCrootINFOTestcasescenariowassetsuccessfully.
...
boptest_1|*Debugmode:off
boptest_1|07/13/202309:59:42PMUTCwerkzeugINFO*Runningonhttp://0.0.0.0:5000/(PressCTRL+Ctoquit)Or use detach mode(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$TESTCASE=testcase1docker-compose--file~/project1-boptest/docker-compose.ymlup--detachStartingproject1-boptest_boptest_1...done(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$dockercontainerls
CONTAINERIDIMAGECOMMANDCREATEDSTATUSPORTSNAMES
ddd0f2cc1f99boptest_base"/bin/sh -c 'python …"23hoursagoUp12seconds127.0.0.1:5000->5000/tcpproject1-boptest_boptest_1Note: Usedocker-compose downto shut down the service.Verify boptest simulation server is running properly:(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$curlhttp://127.0.0.1:5000/name{"message":"Queried the name of the test case successfully.","payload":{"name":"testcase1"},"status":200}Install volttron boptest agentInstall the "volttron-boptest" dependency.There are two options to install volttron-boptest. You can install this library using the version on PyPi or install
it from the source code (git clonemight be required.)
Note: thevctl installcommand in the following step can handle dependency installation using pypi. However, in
this demo we demonstrate what is happening under the neath the hood by separating the dependency installation and
agent registry
steps.# option 1: install from pypipipinstallvolttron-boptest# option 2: install from the source code (Note: `-e` option to use editable mode, useful for development.)pipinstall[-e]<path-to-the-source-code-root>/volttron-boptest/Install and start the "volttron-boptest" agent.We will use thetestcase1.configas the agent config for this demo. Please
seeexamples/for other example config files.Usevctl installcommand to register to the volttron home path.
Note: for demo purposes and reproducibility, we assign vip-identity as "volttron_boptest_agent", but you can choose
any other valid agent identity as desired.(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$vctlinstallvolttron-boptest\--agent-configvolttron-boptest-agent/examples/testcase1.config\--vip-identityvolttron_boptest_agent\--start
Agenta0fd6f5c-3751-4312-9f59-ca541b8aac4einstalledandstarted[4980]Observe DataThe volttron-boptest agent publishes events on the message bus. To see these events in the Volttron log file, install
aListener Agent:vctl install volttron-listener --start(Optional) Usevctl stautsto verify the installation(env)kefei@ubuntu-22:~/sandbox/volttron-boptest$vctlstatus
UUIDAGENTIDENTITYTAGPRIORITYSTATUSHEALTHavolttron-boptest-agent-0.0.1volttron_boptest_agentrunning[59108]GOOD2volttron-listener-0.2.0rc0volttron-listener-0.2.0rc0_1running[59096]GOOD(optional) Inspect the volttron.log fileWithin the volttron.log, we should see similar logs as follows# Create config file place holdersKPIRESULTS-----------2023-07-1318:27:51,124(volttron-boptest-agent-0.0.159108)root(186)INFO:emis_tot:0.2147137757521314KgCO2/m$^2$2023-07-1318:27:51,174(volttron-boptest-agent-0.0.159108)root(186)INFO:ener_tot:1.073568878760657kWh/m$^2$2023-07-1318:27:51,223(volttron-boptest-agent-0.0.159108)root(186)INFO:idis_tot:508.47225004790033ppmh/zone2023-07-1318:27:51,280(volttron-boptest-agent-0.0.159108)root(186)INFO:pdih_tot:NonekW/m$^2$2023-07-1318:27:51,330(volttron-boptest-agent-0.0.159108)root(186)INFO:pele_tot:NonekW/m$^2$2023-07-1318:27:51,381(volttron-boptest-agent-0.0.159108)root(186)INFO:pgas_tot:0.09615811655434148kW/m$^2$2023-07-1318:27:51,436(volttron-boptest-agent-0.0.159108)root(186)INFO:tdis_tot:5.316029375566828Kh/zone2023-07-1318:27:51,494(volttron-boptest-agent-0.0.159108)root(186)INFO:time_rat:0.001856946445725582s/s2023-07-1318:27:51,550(volttron-boptest-agent-0.0.159108)root(202)INFO:========runworkflowcompleted.======2023-07-1318:27:51,553(volttron-boptest-agent-0.0.159108)<stdout>(0)INFO:["======= kpi {'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': 1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, 'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': 5.316029375566828, 'time_rat': 0.001856946445725582}"]2023-07-1318:27:51,558(volttron-boptest-agent-0.0.159108)root(129)INFO:===========refactoringonstart2023-07-1318:27:52,067(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,071(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,073(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,074(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,075(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,076(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,078(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,079(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,081(volttron-listener-0.2.0rc059096)listener.agent(104)INFO:Peer:pubsub,Sender:volttron_boptest_agent:,Bus:,Topic:PNNL/BUILDING/UNIT/kpi,Headers:{'min_compatible_version':'3.0','max_compatible_version':''},Message:("{'cost_tot': 0.075149821513246, 'emis_tot': 0.2147137757521314, 'ener_tot': ""1.073568878760657, 'idis_tot': 508.47225004790033, 'pdih_tot': None, ""'pele_tot': None, 'pgas_tot': 0.09615811655434148, 'tdis_tot': ""5.316029375566828, 'time_rat': 0.001856946445725582}")2023-07-1318:27:52,084(volttron-boptest-agent-0.0.159108)root(305)INFO:========onstartcompleted.======DevelopmentPlease see the following for contributing
guidelinescontributing.Please see the following helpful guide
aboutdeveloping modular VOLTTRON agentsDisclaimer NoticeThis 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.