Merge pull request #2807 from VOLTTRON/releases/8.1.1

8.1.1 to main

README.md

@@ -8,6 +8,46 @@ platform provides services for collecting and storing data from buildings and
 devices and provides an environment for developing applications which interact
 with that data.
 
+## Upgrading to VOLTTRON 8.x
+
+VOLTTRON 8 introduces three changes that require an explict upgrade step when upgrading from a earlier VOLTTRON version
+
+    1. Dynamic RPC authorization feature - This requires a modification to the auth file. If you have a pre-existing
+       instance of VOLTTRON running on an older version, the auth file will need to be updated.
+    2. Historian agents now store the cache database (backup.sqlite file) in
+       <volttron home>/agents/<agent uuid>/<agentname-version>/<agentname-version>.agent-data directory instead of
+       <volttron home>/agents/<agent uuid>/<agentname-version> directory. In future all core agents will write data only
+       to the <agentname-version>.agent-data subdirectory. This is because vctl install --force backs up and restores
+       only the contents of this directory.
+    3. SQLHistorians (historian version 4.0.0 and above) now use a new database schema where metadata is stored in
+       topics table instead of separate metadata table. SQLHistorians with version >= 4.0.0 can work with existing
+       database with older schema however the historian agent code should be upgraded to newer version (>=4.0.0) to run
+       with VOLTTRON 8 core.
+
+To upgrade:
+
+    1. If upgrading historian, make sure historians are not in auto start mode. To remove any historian from auto start
+       mode use the command 'vctl disable <uuid of historian that is currently enabled>. This is necessary so that the old
+       sqlhistorian does not automatically start after step 5. 
+    2. Update volttron source code version to VOLTTRON 8
+    3. activate the volttron environment, and run ```python bootstrap.py --force```. If you have 
+       any additional bootstrap options that you need (rabbitmq, web, drivers, etc.) include these in the above command.
+    4. Run ```volttron-upgrade``` to update the auth file and move historian cache files into agent-data directory. 
+       Note that the upgrade script will only move the backup.sqlite file and will not move sqlite historian's db file 
+       if they are within the install directory. If using a SQLite historian, please backup the database file of 
+       sqlite historian before upgrading to the latest historian version.
+    5. Start VOLTTRON
+    6. Run ```vctl install --force --vip-identity <vip id of existing historian> --agent-config <config>``` to upgrade 
+       to the  latest historian version. vctl install --force will backup the cache in <agent-version>.agent-data 
+       folder, installs the latest version of the historian and restore the contents of 
+       <agent-version>.agent-data folder.
+
+### Upgrading aggregate historians
+
+VOLTTRON 8 also comes with updated SQL aggregate historian schema. However, there is no automated upgrade path for
+aggregate historian. To upgrade an existing aggregate historian please refer to the CHANGELOG.md within 
+SQLAggregateHistorian source directory
+
 ## Features
 
 -   [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.
@@ -295,6 +335,7 @@ There are several walkthroughs to explore additional aspects of the platform:
 -   [RabbitMQ setup with Federation and Shovel plugins](https://volttron.readthedocs.io/en/latest/deploying-volttron/multi-platform/multi-platform-rabbitmq-deployment.html)
 -   [Backward compatibility with the RabbitMQ message bus](https://volttron.readthedocs.io/en/latest/deploying-volttron/multi-platform/multi-platform-multi-bus.html)
 
+
 ## Acquiring Third Party Agent Code
 
 Third party agents are available under the volttron-applications repository. In

bootstrap.py

@@ -133,7 +133,7 @@ def update(operation, verbose=None, upgrade=False, offline=False, optional_requi
     # We must install wheel first to eliminate a bunch of scary looking
     # errors at first install.
     # TODO Look towards fixing the packaging so that it works with 0.31
-    pip('install', ['wheel==0.30'], verbose, True, offline=offline)
+    # option_requirements contains wheel as first entry
 
     # Build option_requirements separately to pass install options
     build_option = '--build-option' if wheeling else '--install-option'

docs/source/conf.py

@@ -43,9 +43,9 @@ def __getattr__(cls, name):
 author = 'The VOLTTRON Community'
 
 # The short X.Y version
-version = '8.1'
+version = '8.1.1'
 # The full version, including alpha/beta/rc tags
-release = '8.1'
+release = '8.1.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/index.rst

@@ -137,6 +137,7 @@ at our bi-weekly office-hours and on Slack. To be invited to office-hours or sla
    platform-features/config-store/configuration-store
    platform-features/security/volttron-security
 
+
 .. toctree::
    :caption: VOLTTRON Core Service Agents
    :hidden:
@@ -146,6 +147,7 @@ at our bi-weekly office-hours and on Slack. To be invited to office-hours or sla
 
    volttron-api/services/*/modules
 
+
 .. toctree::
    :caption: VOLTTRON Core Operations Agents
    :hidden:
@@ -155,16 +157,16 @@ at our bi-weekly office-hours and on Slack. To be invited to office-hours or sla
 
    volttron-api/ops/*/modules
 
+
 .. toctree::
    :caption: VOLTTRON Topics
    :hidden:
    :titlesonly:
    :maxdepth: 1
 
+   Releases <volttron-topics/VOLTTRON-releases/index>
    volttron-topics/troubleshooting/index
    volttron-topics/volttron-applications/index
-   volttron-topics/change-log/index
-
 
 
 Indices and tables

docs/source/volttron-topics/VOLTTRON-releases/index.rst

@@ -0,0 +1,13 @@
+.. _VOLTTRON-Releases:
+
+==========
+VOLTTRON Releases
+==========
+
+This section includes individual documents describing important changes to platform components. For information on specific release, please refer to the corresponding document.
+
+
+.. toctree::
+
+   release-history
+   upgrading-versions

docs/source/volttron-topics/VOLTTRON-releases/release-history.rst

@@ -0,0 +1,124 @@
+.. _Release-History:
+
+===============
+Release History
+===============
+
+VOLTTRON Release Documentation for version 5.1.0 and above is found on GitHub.
+`https://github.com/VOLTTRON/volttron/releases <https://github.com/VOLTTRON/volttron/releases>`_
+
+
+VOLTTRON 8.1.1 Maintenance Release
+==================================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/8.1.1 <https://github.com/VOLTTRON/volttron/releases/tag/8.1.1>`_
+
+
+VOLTTRON 8.1 Release
+====================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/8.1 <https://github.com/VOLTTRON/volttron/releases/tag/8.1>`_
+
+
+VOLTTRON 8.0 Full Release
+=========================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/8.0.0 <https://github.com/VOLTTRON/volttron/releases/tag/8.0.0>`_
+
+
+VOLTTRON 7.0.1 Update
+=====================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/7.0.1 <https://github.com/VOLTTRON/volttron/releases/tag/7.0.1>`_
+
+
+VOLTTRON 8.0 Release Candidate
+==============================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/8.0rc1 <https://github.com/VOLTTRON/volttron/releases/tag/8.0rc1>`_
+
+
+VOLTTRON 7.0 Release
+====================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/7.0 <https://github.com/VOLTTRON/volttron/releases/tag/7.0>`_
+
+
+VOLTTRON 7.0 Release Candidate
+==============================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/7.0rc1 <https://github.com/VOLTTRON/volttron/releases/tag/7.0rc1>`_
+
+
+VOLTTRON 6.0 Release
+====================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/6.0 <https://github.com/VOLTTRON/volttron/releases/tag/6.0>`_
+
+
+VOLTTRON 6.0 Release Candidate
+==============================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/6.0rc1 <https://github.com/VOLTTRON/volttron/releases/tag/6.0rc1>`_
+
+
+VOLTTRON 5.1.0 Release
+======================
+
+`https://github.com/VOLTTRON/volttron/releases/tag/5.1.0 <https://github.com/VOLTTRON/volttron/releases/tag/5.1.0>`_
+
+
+VOLTTRON 5.0 Release
+====================
+
+- Tagging service for attaching metadata to topics for simpler retrieval
+- Message bus performance improvement
+- Multi-platform publish/subscribe for simpler coordination across platforms
+- Drivers contributed back for SEP 2.0 and ChargePoint EV
+
+
+VOLTTRON 4.0 Release
+====================
+
+- Documentation moved to ReadTheDocs
+- VOLTTRON Configuration Wizard
+- Configuration store to dynamically configure agents
+- Aggregator agent for aggregating topics
+- More reliable remote install mechanism
+- UI for device configuration
+- Automatic registration of VOLTTRON instances with management agent
+
+
+VOLTTRON 3.0 Release
+====================
+
+-  Modularize Data Historian
+-  Modularize Device Drivers
+-  Secure and accountable communication using the VIP
+-  Web Console for Monitoring and Administering VOLTTRON Deployments
+
+
+VOLTTRON 2.0 Release
+====================
+
+-  Advanced Security Features
+-  Guaranteed resource allocation to agents using execution contracts
+-  Signing and verification of agent packaging
+-  Agent mobility
+-  Admin can send agents to another platform
+-  Agent can request to move
+-  Enhanced command framework
+
+
+VOLTTRON 1.0 – 1.2
+==================
+
+-  Agent execution platform
+-  Message bus
+-  Modbus and BACnet drivers
+-  Historian
+-  Data logger
+-  Device scheduling
+-  Device actuation
+-  Multi-node communication
+-  Weather service

docs/source/volttron-topics/change-log/upgrading-versions.rst → docs/source/volttron-topics/VOLTTRON-releases/upgrading-versions.rst

@@ -8,6 +8,48 @@ It is often recommended that users upgrade to the latest stable release of VOLTT
 releases include helpful new features, bug fixes, and other improvements.  Please see the guides below for upgrading
 your existing deployment to the latest version.
 
+VOLTTRON 8
+==========
+
+VOLTTRON 8 introduces three changes that require an explict upgrade step when upgrading from a earlier VOLTTRON version
+
+    1. Dynamic RPC authorization feature - This requires a modification to the auth file. If you have a pre-existing
+       instance of VOLTTRON running on an older version, the auth file will need to be updated.
+    2. Historian agents now store the cache database (backup.sqlite file) in
+       <volttron home>/agents/<agent uuid>/<agentname-version>/<agentname-version>.agent-data directory instead of
+       <volttron home>/agents/<agent uuid>/<agentname-version> directory. In future all core agents will write data only
+       to the <agentname-version>.agent-data subdirectory. This is because vctl install --force backs up and restores
+       only the contents of this directory.
+    3. SQLHistorians (historian version 4.0.0 and above) now use a new database schema where metadata is stored in
+       topics table instead of separate metadata table. SQLHistorians with version >= 4.0.0 can work with existing
+       database with older schema however the historian agent code should be upgraded to newer version (>=4.0.0) to run
+       with VOLTTRON 8 core.
+
+
+To upgrade:
+
+    1. If upgrading historian, make sure historians are not in auto start mode. To remove any historian from auto start
+       mode use the command 'vctl disable <uuid of historian that is currently enabled>. This is necessary so that the old
+       sqlhistorian does not automatically start after step 5.
+    2. Update volttron source code version to VOLTTRON 8
+    3. activate the volttron environment, and run ```python bootstrap.py --force```. If you have
+       any additional bootstrap options that you need (rabbitmq, web, drivers, etc.) include these in the above command.
+    4. Run ```volttron-upgrade``` to update the auth file and move historian cache files into agent-data directory.
+       Note that the upgrade script will only move the backup.sqlite file and will not move sqlite historian's db file
+       if they are within the install directory. If using a SQLite historian, please backup the database file of
+       sqlite historian before upgrading to the latest historian version.
+    5. Start VOLTTRON
+    6. Run ```vctl install --force --vip-identity <vip id of existing historian> --agent-config <config>``` to upgrade
+       to the  latest historian version. vctl install --force will backup the cache in <agent-version>.agent-data
+       folder, installs the latest version of the historian and restore the contents of
+       <agent-version>.agent-data folder.
+
+Upgrading aggregate historians
+------------------------------
+
+VOLTTRON 8 also comes with updated SQL aggregate historian schema. However, there is no automated upgrade path for
+aggregate historian. To upgrade an existing aggregate historian please refer to the CHANGELOG.md within
+SQLAggregateHistorian source directory
 
 VOLTTRON 7
 ==========