{"id":13780225,"url":"https://github.com/VOLTTRON/volttron","last_synced_at":"2025-05-11T13:32:08.275Z","repository":{"id":11681132,"uuid":"14191740","full_name":"VOLTTRON/volttron","owner":"VOLTTRON","description":"VOLTTRON Distributed Control System Platform","archived":false,"fork":false,"pushed_at":"2024-08-20T20:12:30.000Z","size":156126,"stargazers_count":460,"open_issues_count":410,"forks_count":218,"subscribers_count":51,"default_branch":"main","last_synced_at":"2024-11-02T08:55:41.929Z","etag":null,"topics":["bacnet","buildings","message-bus","modbus","office-hours","python","volttron","volttron-applications","volttron-instance"],"latest_commit_sha":null,"homepage":"https://volttron.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VOLTTRON.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-07T02:07:46.000Z","updated_at":"2024-10-24T14:54:07.000Z","dependencies_parsed_at":"2023-09-21T19:20:37.644Z","dependency_job_id":"c357a4ac-2131-4f4f-9d9b-59731a1690bc","html_url":"https://github.com/VOLTTRON/volttron","commit_stats":{"total_commits":8447,"total_committers":124,"mean_commits":68.12096774193549,"dds":0.693737421569788,"last_synced_commit":"7b5339b9d3cb7c0fea2c2fe7cb8296393b11232d"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VOLTTRON%2Fvolttron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VOLTTRON%2Fvolttron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VOLTTRON%2Fvolttron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VOLTTRON%2Fvolttron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VOLTTRON","download_url":"https://codeload.github.com/VOLTTRON/volttron/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225056781,"owners_count":17414207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bacnet","buildings","message-bus","modbus","office-hours","python","volttron","volttron-applications","volttron-instance"],"created_at":"2024-08-03T18:01:13.510Z","updated_at":"2024-11-17T15:31:03.503Z","avatar_url":"https://github.com/VOLTTRON.png","language":"Python","funding_links":[],"categories":["Python","Energy","Energy Consumption"],"sub_categories":["Buildings and Cities"],"readme":"![image](docs/source/files/VOLLTRON_Logo_Black_Horizontal_with_Tagline.png)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/fcf58045b4804edf8f4d3ecde3016f76)](https://app.codacy.com/gh/VOLTTRON/volttron?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=VOLTTRON/volttron\u0026utm_campaign=Badge_Grade_Settings)\n\n# VOLTTRON\n\nThis repository is for the current production VOLTTRON. We are working on VOLTTRON 10 (modular) which is available under \ngithub at https://github.com/eclipse-volttron/.  The modular version of VOLTTRON will help ease deployment and support \nflexible deployment where in only required agents/applications can be installed, thereby simplifying setup and upgrade \nsteps for the end user. The VOLTTRON team are currently working on porting agents from monolithic VOLTTRON to the \nmodular version of VOLTTRON. To know more about modular VOLTTRON, please visit our new documentation site available \nat https://eclipse-volttron.readthedocs.io/en/latest/. We would love for you to try it out and give us early \nfeedback. Also, until our work on modular VOLTTRON is completed, please continue cloning and using this \nrepository for your production systems.\n\nVOLTTRON™ is an open source platform for distributed sensing and control. The\nplatform provides services for collecting and storing data from buildings and\ndevices and provides an environment for developing applications which interact\nwith that data.\n\n## Upgrading Pre-8 to VOLTTRON 9.x\n\nVOLTTRON 8 introduces four changes that require an explict upgrade step when upgrading from an earlier VOLTTRON version\n\n    1. Dynamic RPC authorization feature - This requires a modification to the auth file. If you have a pre-existing\n       instance of VOLTTRON running on an older version, the auth file will need to be updated.\n    2. Historian agents now store the cache database (backup.sqlite file) in\n       \u003cvolttron home\u003e/agents/\u003cagent uuid\u003e/\u003cagentname-version\u003e/\u003cagentname-version\u003e.agent-data directory instead of\n       \u003cvolttron home\u003e/agents/\u003cagent uuid\u003e/\u003cagentname-version\u003e directory. In future all core agents will write data only\n       to the \u003cagentname-version\u003e.agent-data subdirectory. This is because vctl install --force backs up and restores\n       only the contents of this directory.\n    3. SQLHistorians (historian version 4.0.0 and above) now use a new database schema where metadata is stored in\n       topics table instead of separate metadata table. SQLHistorians with version \u003e= 4.0.0 can work with existing\n       database with older schema however the historian agent code should be upgraded to newer version (\u003e=4.0.0) to run\n       with VOLTTRON 8 core.\n    4. VOLTTRON feature to run individual agents as unique Unix users is now named \"agent-isolation-mode\" and is \n       consistently referred to using this name in code, configuration, and documentation. Before VOLTTRON 8.2 this \n       configuration parameter was called \"secure-agent-users\" and related documentation referred to this mode as \n       \"secure mode\".  \n\nTo upgrade:\n\n    1. If upgrading historian, make sure historians are not in auto start mode. To remove any historian from auto start\n       mode use the command 'vctl disable \u003cuuid of historian that is currently enabled\u003e. This is necessary so that the old\n       sqlhistorian does not automatically start after step 5. \n    2. Update volttron source code version to VOLTTRON 8\n    3. activate the volttron environment, and run ```python bootstrap.py --force```. If you have \n       any additional bootstrap options that you need (rabbitmq, web, drivers, etc.) include these in the above command.\n    4. Run ```volttron-upgrade``` to update the auth file, move historian cache files into agent-data directory, and \n       rename the config parameter \"secure-agent-users\" in VOLTTRON_HOME/config to \"agent-isolation-mode\"\n       **Note** that the upgrade script will only move the backup.sqlite file and will not move sqlite historian's db  \n       file if they are within the install directory. If using a SQLite historian, please backup the database file of \n       sqlite historian before upgrading to the latest historian version.\n    5. Start VOLTTRON\n    6. Run ```vctl install --force --vip-identity \u003cvip id of existing historian\u003e --agent-config \u003cconfig\u003e``` to upgrade \n       to the  latest historian version. vctl install --force will backup the cache in \u003cagent-version\u003e.agent-data \n       folder, installs the latest version of the historian and restore the contents of \n       \u003cagent-version\u003e.agent-data folder.\n\n### Upgrading aggregate historians\n\nVOLTTRON 8 also comes with updated SQL aggregate historian schema. However, there is no automated upgrade path for\naggregate historian. To upgrade an existing aggregate historian please refer to the CHANGELOG.md within \nSQLAggregateHistorian source directory\n\n## Features\n\n-   [Message Bus](https://volttron.readthedocs.io/en/latest/platform-features/message-bus/index.html) allows agents to subscribe to data sources and publish results and messages.\n-   [Driver framework](https://volttron.readthedocs.io/en/latest/driver-framework/drivers-overview.html) for collecting data from and sending control actions to buildings and devices.\n-   [Historian framework](https://volttron.readthedocs.io/en/latest/agent-framework/historian-agents/historian-framework.html) for storing data.\n-   [Agent lifecycle managment](https://volttron.readthedocs.io/en/latest/platform-features/control/agent-management-control.html) in the platform\n-   [Web UI](https://volttron.readthedocs.io/en/latest/agent-framework/core-service-agents/volttron-central/volttron-central-overview.html) for managing deployed instances from a single central instance.\n\n## Installation\n\nVOLTTRON is written in Python 3.6+ and runs on Linux Operating Systems. For\nusers unfamiliar with those technologies, the following resources are recommended:\n\n-   \u003chttps://docs.python.org/3.6/tutorial/\u003e\n-   \u003chttp://ryanstutorials.net/linuxtutorial\u003e\n\n### 1. Install prerequisites\n\n[Requirements Reference](https://volttron.readthedocs.io/en/latest/introduction/platform-install.html#step-1-install-prerequisites)\n\nFrom version 7.0, VOLTTRON requires python 3 with a minimum version of 3.6; it is tested only systems supporting that as a native package.\nOn Debian-based systems (Ubuntu bionic, debian buster, raspbian buster), these can all be installed with the following commands:\n\n```sh\nsudo apt-get update\nsudo apt-get install build-essential libffi-dev python3-dev python3-venv openssl libssl-dev libevent-dev git\n ```\n(Note: `libffi-dev` seems to only be required on arm-based systems.)\n\n On Redhat or CENTOS systems, these can all be installed with the following command:\n```sh\nsudo yum update\nsudo yum install make automake gcc gcc-c++ kernel-devel python3.6-devel pythone3.6-venv openssl openssl-devel libevent-devel git\n ```\n\n### 2. Clone VOLTTRON code\n\nFrom version 6.0, VOLTTRON supports two message buses - ZMQ and RabbitMQ. \n\n```sh\ngit clone https://github.com/VOLTTRON/volttron --branch \u003cbranch name\u003e\n```\n\n### 3. Setup virtual environment\n\n#### Steps for ZMQ\n\nRun the following command to install all required packages\n\n```sh\ncd \u003cvolttron clone directory\u003e\npython3 bootstrap.py\nsource env/bin/activate\n```\n\nProceed to step 4.\n\nYou can deactivate the environment at any time by running `deactivate`.\n\n#### Steps for RabbitMQ\n\n##### 1. Install Erlang version 25 packages\n\n###### Install Erlang pre-requisites\n```shell\nsudo apt-get update\nsudo apt-get install -y gnupg apt-transport-https libsctp1 libncurses5\n```\nPlease note there could be other pre-requisites that erlang requires based on the version of Erlang and OS. If there are other pre-requisites required, \ninstall of erlang should fail with appropriate error message. \n\n###### Purge previous versions of Erlang\n```shell\nsudo apt-get purge -yf erlang-base\n```\n\n###### Install Erlang\n\nDownload and install ErlangOTP from [Erlang Solutions](https://www.erlang-solutions.com/downloads/).\nRMQ uses components - ssl, public_key, asn1, and crypto. These are by default included in the OTP\nRabbitMQ 3.9.29 is compatible with Erlang versions 24.3.4.2 to 25.2. VOLTTRON was tested with Erlang version 25.2-1\n\nExample:\n\nOn Ubuntu 22.04:\n\n```shell\nwget https://binaries2.erlang-solutions.com/ubuntu/pool/contrib/e/esl-erlang/esl-erlang_25.2-1~ubuntu~jammy_amd64.deb\nsudo dpkg -i esl-erlang_25.2-1~ubuntu~jammy_amd64.deb\n```\n\nOn Ubuntu 20.04:\n```shell\nwget https://binaries2.erlang-solutions.com/ubuntu/pool/contrib/e/esl-erlang/esl-erlang_25.2-1~ubuntu~focal_amd64.deb\nsudo dpkg -i esl-erlang_25.2-1~ubuntu~focal_amd64.deb\n```\n\n\n##### 2. Configure hostname\n\nMake sure that your hostname is correctly configured in /etc/hosts (See [this StackOverflow Post](https://stackoverflow.com/questions/24797947/os-x-and-rabbitmq-error-epmd-error-for-host-xxx-address-cannot-connect-to-ho)).\nIf you are testing with VMs make please make sure to provide unique host names for each of the VM you are using. \n\nThe hostname should be resolvable to a valid IP when running on bridged mode. RabbitMQ checks for this during initial \nboot. Without this (for example, when running on a VM in NAT mode) RabbitMQ  start would fail with the error \"unable to \nconnect to empd (port 4369) on \u003chostname\u003e.\" Note: RabbitMQ startup error would show up in syslog (/var/log/messages) file\nand not in RabbitMQ logs (/var/log/rabbitmq/rabbitmq@hostname.log)\n\n##### 3. Bootstrap\nRemove older version of rabbitmq_server directory if you are upgrading from a older version. \nDefaults to \u003cuser_home\u003e/rabbitmq_server/rabbitmq_server-3.9.7\n\nRun the rabbitmq boostrap command within an activated VOLTTRON environment\n\n```sh\ncd volttron\nsource env/bin/activate\npython3 bootstrap.py --rabbitmq [optional install directory. defaults to\n\u003cuser_home\u003e/rabbitmq_server]\n```\n\nThis will build the platform and create a virtual Python environment and\ndependencies for RabbitMQ. It also installs RabbitMQ server as the current user.\nIf an install path is provided, that path should exist and the user should have \nwrite permissions. RabbitMQ will be installed under `\u003cinstall dir\u003e/rabbitmq_server-\u003crmq-version\u003e`.\nThe rest of the documentation refers to the directory `\u003cinstall dir\u003e/rabbitmq_server-\u003crmq-version\u003e` as\n`$RABBITMQ_HOME`\n\nYou can check if the RabbitMQ server is installed by checking its status. Please\nnote, the `RABBITMQ_HOME` environment variable can be set in ~/.bashrc. If doing so,\nit needs to be set to the RabbitMQ installation directory (default path is\n`\u003cuser_home\u003e/rabbitmq_server/rabbitmq_server-\u003crmq-version\u003e`)\n\n```sh\necho 'export RABBITMQ_HOME=$HOME/rabbitmq_server/rabbitmq_server-3.9.29'|sudo tee --append ~/.bashrc\nsource ~/.bashrc\n\n$RABBITMQ_HOME/sbin/rabbitmqctl status\n```\n\n##### 4. Activate the environment\n\n```sh\nsource env/bin/activate\n```\n\nYou can deactivate the environment at any time by running `deactivate`.\n\n##### 5. Create RabbitMQ setup for VOLTTRON:\n\n```sh\nvcfg rabbitmq single [--config optional path to rabbitmq_config.yml]\n```\n\nRefer to [examples/configurations/rabbitmq/rabbitmq_config.yml](examples/configurations/rabbitmq/rabbitmq_config.yml)\nfor a sample configuration file.\nAt a minimum you will need to provide the hostname and a unique common-name\n(under certificate-data) in the configuration file. Note: common-name must be\nunique.  The general convention is to use `\u003cvoltttron instance name\u003e-root-ca`.\n\nRunning the above command without the optional configuration file parameter will\ncause the user to be prompted for all the required data in the command prompt. \n`vcfg` will use that data to generate a rabbitmq_config.yml file in the `VOLTTRON_HOME` \ndirectory.\n\nIf the above configuration file is being used as a basis, be sure to update it with \nthe hostname of the deployment (this should be the fully qualified domain name\nof the system).\n\nThis script creates a new virtual host and creates SSL certificates needed\nfor this VOLTTRON instance. These certificates get created under the subdirectory \n\"certificates\" in your VOLTTRON home (typically in ~/.volttron). It\nthen creates the main VIP exchange named \"volttron\" to route message between\nthe platform and agents and alternate exchange to capture unrouteable messages.\n\nNOTE: We configure the RabbitMQ instance for a single volttron_home and\nvolttron_instance. This script will confirm with the user the volttron_home to\nbe configured. The VOLTTRON instance name will be read from volttron_home/config\nif available, if not the user will be prompted for VOLTTRON instance name. To\nrun the scripts without any prompts, save the VOLTTRON instance name in\nvolttron_home/config file and pass the VOLTTRON home directory as a command line\nargument. For example: `vcfg --vhome /home/vdev/.new_vhome rabbitmq single`\n\nThe Following are the example inputs for `vcfg rabbitmq single` command. Since no\nconfig file is passed the script prompts for necessary details.\n\n```sh\nYour VOLTTRON_HOME currently set to: /home/vdev/new_vhome2\n\nIs this the volttron you are attempting to setup?  [Y]:\nCreating rmq config yml\nRabbitMQ server home: [/home/vdev/rabbitmq_server/rabbitmq_server-3.9.29]:\nFully qualified domain name of the system: [cs_cbox.pnl.gov]:\n\nEnable SSL Authentication: [Y]:\n\nPlease enter the following details for root CA certificates\nCountry: [US]:\nState: Washington\nLocation: Richland\nOrganization: PNNL\nOrganization Unit: Volttron-Team\nCommon Name: [volttron1-root-ca]:\nDo you want to use default values for RabbitMQ home, ports, and virtual host: [Y]: N\nName of the virtual host under which RabbitMQ VOLTTRON will be running: [volttron]:\nAMQP port for RabbitMQ: [5672]:\nhttp port for the RabbitMQ management plugin: [15672]:\nAMQPS (SSL) port RabbitMQ address: [5671]:\nhttps port for the RabbitMQ management plugin: [15671]:\nINFO:rmq_setup.pyc:Starting rabbitmq server\nWarning: PID file not written; -detached was passed.\nINFO:rmq_setup.pyc:**Started rmq server at /home/vdev/rabbitmq_server/rabbitmq_server-3.9.29\nINFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost\nINFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost\nINFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost\nINFO:rmq_setup.pyc:\nChecking for CA certificate\n\nINFO:rmq_setup.pyc:\nRoot CA (/home/vdev/new_vhome2/certificates/certs/volttron1-root-ca.crt) NOT Found. Creating root ca for volttron instance\nCreated CA cert\nINFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost\nINFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost\nINFO:rmq_setup.pyc:**Stopped rmq server\nWarning: PID file not written; -detached was passed.\nINFO:rmq_setup.pyc:**Started rmq server at /home/vdev/rabbitmq_server/rabbitmq_server-3.9.29\nINFO:rmq_setup.pyc:\n\n#######################\n\nSetup complete for volttron home /home/vdev/new_vhome2 with instance name=volttron1\nNotes:\n\n-   Please set environment variable `VOLTTRON_HOME` to `/home/vdev/new_vhome2` before starting volttron\n\n-   On production environments, restrict write access to\n    /home/vdev/new_vhome2/certificates/certs/volttron1-root-ca.crt to only admin user. For example: sudo chown root /home/vdev/new_vhome2/certificates/certs/volttron1-root-ca.crt\n\n-   A new admin user was created with user name: volttron1-admin and password=default_passwd.\n    You could change this user's password by logging into \u003chttps://cs_cbox.pnl.gov:15671/\u003e Please update /home/vdev/new_vhome2/rabbitmq_config.yml if you change password\n\n#######################\n```\n\n### 4. Test\n\nWe are now ready to start the VOLTTRON instance. If configured with a RabbitMQ message bus a config file would have been\n generated in `$VOLTTRON\\_HOME/config` with the entry `message-bus=rmq`. If you need to revert to ZeroMQ based \n VOLTTRON, you will have to either remove \"message-bus\" parameter or set it to default \"zmq\" in `$VOLTTRON\\_HOME/config`\n  and restart the volttron process. The following command starts the VOLTTRON process in the background:\n\n```sh\nvolttron -vv -l volttron.log \u0026\n```\n\nThis command causes the shell to enter the virtual Python environment and then starts the platform in debug (vv) mode \nwith a log file named volttron.log.\n\nNext, start an example listener to see it publish and subscribe to the message bus:\n\n```sh\nvctl install examples/ListenerAgent\n```\n\nThis script handles several commands for installing and starting an agent after removing an old copy. This \nsimple agent publishes a heartbeat message and listens to everything on the message bus. Look at the VOLTTRON log to see \nthe activity:\n\n```sh\ntail volttron.log\n```\n\nListener agent heartbeat publishes appear in the logs as:\n\n```sh\n2020-04-20 18:49:31,395 (listeneragent-3.3 13458) __main__ INFO: Peer: pubsub, Sender: listeneragent-3.2_1:, Bus: , Topic: heartbeat/listeneragent-3.2_1, Headers: {'TimeStamp': '2020-04-20T18:49:31.393651+00:00', 'min_compatible_version': '3.0', 'max_compatible_version': ''}, Message:\n'GOOD'\n2020-04-20 18:49:36,394 (listeneragent-3.3 13458) __main__ INFO: Peer: pubsub, Sender: listeneragent-3.2_1:, Bus: , Topic: heartbeat/listeneragent-3.2_1, Headers: {'TimeStamp': '2020-04-20T18:49:36.392294+00:00', 'min_compatible_version': '3.0', 'max_compatible_version': ''}, Message:\n'GOOD'\n```\n\nTo top the platform run the following command:\n\n```sh\n./stop-volttron\n```\n\n## Next Steps\n\nThere are several walkthroughs to explore additional aspects of the platform:\n\n-   [Agent Development Walkthrough](https://volttron.readthedocs.io/en/latest/developing-volttron/developing-agents/agent-development.html)\n-   Demonstration of the [management UI](https://volttron.readthedocs.io/en/latest/deploying-volttron/multi-platform/volttron-central-deployment.html)\n-   [RabbitMQ setup with Federation and Shovel plugins](https://volttron.readthedocs.io/en/latest/deploying-volttron/multi-platform/multi-platform-rabbitmq-deployment.html)\n-   [Backward compatibility with the RabbitMQ message bus](https://volttron.readthedocs.io/en/latest/deploying-volttron/multi-platform/multi-platform-multi-bus.html)\n\n\n## Acquiring Third Party Agent Code\n\nThird party agents are available under the volttron-applications repository. In\norder to use those agents, clone the volttron-applications repository into the same\ndirectory as the VOLTTRON source code:\n\n```sh\ncd \u003cparent directory of volttron\u003e\ngit clone https://github.com/VOLTTRON/volttron-applications.git develop\n```\n\n## Contribute\n\nHow to [contribute](https://volttron.readthedocs.io/en/latest/developing-volttron/contributing-code.html) back:\n\n-   [Issue Tracker](https://github.com/VOLTTRON/volttron/issues)\n-   [Source Code](https://github.com/VOLTTRON/volttron) \n\n## Support\n\nThere are several options for VOLTTRONTM [support](https://volttron.readthedocs.io/en/latest/developing-volttron/community.html).\n\n-   A VOLTTRONTM office hours telecon takes place every other Friday at 11am Pacific over Zoom.\n-   A mailing list for announcements and reminders\n-   The VOLTTRONTM contact email for being added to office hours, the mailing list, and for inquiries is: volttron@pnnl.gov\n-   The preferred method for questions is through [StackOverflow](https://stackoverflow.com/questions/tagged/volttron) since this is easily discoverable by others who may have the same issue.\n-   [GitHub issue tracker](https://github.com/VOLTTRON/volttron/issues) for feature requests, bug reports, and following development activities\n-   VOLTTRON now has a [Slack channel](https://volttron-community.slack.com/signup)\n\n## License\n\nThe project is [licensed](LICENSE.md) under Apache 2.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVOLTTRON%2Fvolttron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVOLTTRON%2Fvolttron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVOLTTRON%2Fvolttron/lists"}