schandrika · schandrika · Sep 21, 2023 · Sep 26, 2023 · Sep 26, 2023 · Sep 26, 2023
diff --git a/README.md b/README.md
@@ -118,8 +118,10 @@ You can deactivate the environment at any time by running `deactivate`.
 ###### Install Erlang pre-requisites
 ```shell
 sudo apt-get update
-sudo apt-get install -y gnupg apt-transport-https libsctp1 
+sudo apt-get install -y gnupg apt-transport-https libsctp1 libncurses5
 ```
+Please 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, 
+install of erlang should fail with appropriate error message. 
 
 ###### Purge previous versions of Erlang
 ```shell

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,7 @@
-sphinx_rtd_theme
-sphinx-autobuild
-sphinx==3.3.0
-m2r2
+sphinx==5.1.1
+sphinx-rtd-theme==1.0.0
+m2r2==0.3.2
+sphinxcontrib-mermaid
 bacpypes
 enum34
 funcsigs

diff --git a/docs/source/agent-framework/driver-framework/drivers-overview.rst b/docs/source/agent-framework/driver-framework/drivers-overview.rst
@@ -175,3 +175,4 @@ To view data being published from the fake driver on the message bus, one can
    modbus/modbus-tk-driver
    obix/obix
    ted-driver/the-energy-detective-driver
+   home-assistant/HomeAssistantDriver
diff --git a/.../source/agent-framework/driver-framework/home-assistant/HomeAssistantDriver.rst b/.../source/agent-framework/driver-framework/home-assistant/HomeAssistantDriver.rst
@@ -0,0 +1,177 @@
+.. _HomeAssistant-Driver:
+
+Home Assistant Driver
+=====================
+
+The Home Assistant driver enables VOLTTRON to read any data point from any Home Assistant controlled device.
+Currently control(write access) is supported only for lights(state and brightness) and thermostats(state and temperature).
+
+The following diagram shows interaction between platform driver agent and home assistant driver.
+
+.. mermaid::
+
+   sequenceDiagram
+       HomeAssistant Driver->>HomeAssistant: Retrieve Entity Data (REST API)
+       HomeAssistant-->>HomeAssistant Driver: Entity Data (Status Code: 200)
+       HomeAssistant Driver->>PlatformDriverAgent: Publish Entity Data
+       PlatformDriverAgent->>Controller Agent: Publish Entity Data
+
+       Controller Agent->>HomeAssistant Driver: Instruct to Turn Off Light
+       HomeAssistant Driver->>HomeAssistant: Send Turn Off Light Command (REST API)
+       HomeAssistant-->>HomeAssistant Driver: Command Acknowledgement (Status Code: 200)
+
+Pre-requisites
+--------------
+Before proceeding, find your Home Assistant IP address and long-lived access token from `here <https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token>`_.
+
+Clone the repository, start volttron, install the listener agent, and the platform driver agent.
+
+- `Listener agent <https://volttron.readthedocs.io/en/main/introduction/platform-install.html#installing-and-running-agents>`_
+- `Platform driver agent <https://volttron.readthedocs.io/en/main/agent-framework/core-service-agents/platform-driver/platform-driver-agent.html?highlight=platform%20driver%20isntall#configuring-the-platform-driver>`_
+
+Configuration
+--------------
+
+After cloning, generate configuration files. Each device requires one device configuration file and one registry file.
+Ensure your registry_config parameter in your device configuration file, links to correct registry config name in the
+config store. For more details on how volttron platform driver agent works with volttron configuration store see,
+`Platform driver configuration <https://volttron.readthedocs.io/en/main/agent-framework/driver-framework/platform-driver/platform-driver.html#configuration-and-installation>`_
+Examples for lights and thermostats are provided below.
+
+Device configuration
+++++++++++++++++++++
+
+Device configuration file contains the connection details to you home assistant instance and driver_type as "home_assistant"
+
+.. code-block:: json
+
+   {
+       "driver_config": {
+           "ip_address": "Your Home Assistant IP",
+           "access_token": "Your Home Assistant Access Token",
+           "port": "Your Port"
+       },
+       "driver_type": "home_assistant",
+       "registry_config": "config://light.example.json",
+       "interval": 30,
+       "timezone": "UTC"
+   }
+
+Registry Configuration
++++++++++++++++++++++++
+
+Registry file can contain one single device and its attributes or a logical group of devices and its
+attributes. Each entry should include the full entity id of the device, including but not limited to home assistant provided prefix 
+such as "light.",  "climate." etc. The driver uses these prefixes to convert states into integers.
+Like mentioned before, the driver can only control lights and thermostats but can get data from all devices
+controlled by home assistant
+
+Each entry in a registry file should also have a 'Entity Point' and a unique value for 'Volttron Point Name'. The 'Entity ID' maps to the device instance, the 'Entity Point' extracts the attribute or state, and 'Volttron Point Name' determines the name of that point as it appears in VOLTTRON.
+
+Attributes can be located in the developer tools in the Home Assistant GUI.
+
+.. image:: home-assistant.png
+
+
+Below is an example file named light.example.json which has attributes of a single light instance with entity
+id 'light.example':
+
+
+.. code-block:: json
+
+   [
+       {
+           "Entity ID": "light.example",
+           "Entity Point": "state",
+           "Volttron Point Name": "light_state",
+           "Units": "On / Off",
+           "Units Details": "on/off",
+           "Writable": true,
+           "Starting Value": true,
+           "Type": "boolean",
+           "Notes": "lights hallway"
+       },
+       {
+           "Entity ID": "light.example",
+           "Entity Point": "brightness",
+           "Volttron Point Name": "light_brightness",
+           "Units": "int",
+           "Units Details": "light level",
+           "Writable": true,
+           "Starting Value": 0,
+           "Type": "int",
+           "Notes": "brightness control, 0 - 255"
+       }
+   ]
+
+
+.. note::
+
+When using a single registry file to represent a logical group of multiple physical entities, make sure the
+"Volttron Point Name" is unique within a single registry file. 
+
+For example, if a registry file contains entities with
+id  'light.instance1' and 'light.instance2' the entry for the attribute brightness for these two light instances could
+have "Volttron Point Name" as 'light1/brightness' and 'light2/brightness' respectively. This would ensure that data
+is posted to unique topic names and brightness data from light1 is not overwritten by light2 or vice-versa.
+
+Example Thermostat Registry
+***************************
+
+For thermostats, the state is converted into numbers as follows: "0: Off, 2: heat, 3: Cool, 4: Auto",
+
+.. code-block:: json
+
+   [
+       {
+           "Entity ID": "climate.my_thermostat",
+           "Entity Point": "state",
+           "Volttron Point Name": "thermostat_state",
+           "Units": "Enumeration",
+           "Units Details": "0: Off, 2: heat, 3: Cool, 4: Auto",
+           "Writable": true,
+           "Starting Value": 1,
+           "Type": "int",
+           "Notes": "Mode of the thermostat"
+       },
+       {
+           "Entity ID": "climate.my_thermostat",
+           "Entity Point": "current_temperature",
+           "Volttron Point Name": "volttron_current_temperature",
+           "Units": "F",
+           "Units Details": "Current Ambient Temperature",
+           "Writable": true,
+           "Starting Value": 72,
+           "Type": "float",
+           "Notes": "Current temperature reading"
+       },
+       {
+           "Entity ID": "climate.my_thermostat",
+           "Entity Point": "temperature",
+           "Volttron Point Name": "set_temperature",
+           "Units": "F",
+           "Units Details": "Desired Temperature",
+           "Writable": true,
+           "Starting Value": 75,
+           "Type": "float",
+           "Notes": "Target Temp"
+       }
+   ]
+
+
+
+Transfer the registers files and the config files into the VOLTTRON config store using the commands below:
+
+.. code-block:: bash
+
+   vctl config store platform.driver light.example.json HomeAssistant_Driver/light.example.json
+   vctl config store platform.driver devices/BUILDING/ROOM/light.example HomeAssistant_Driver/light.example.config
+
+Upon completion, initiate the platform driver. Utilize the listener agent to verify the driver output:
+
+.. code-block:: bash
+
+   2023-09-12 11:37:00,226 (listeneragent-3.3 211531) __main__ INFO: Peer: pubsub, Sender: platform.driver:, Bus: , Topic: devices/BUILDING/ROOM/light.example/all, Headers: {'Date': '2023-09-12T18:37:00.224648+00:00', 'TimeStamp': '2023-09-12T18:37:00.224648+00:00', 'SynchronizedTimeStamp': '2023-09-12T18:37:00.000000+00:00', 'min_compatible_version': '3.0', 'max_compatible_version': ''}, Message:
+   [{'light_brightness': 254, 'state': 'on'},
+    {'light_brightness': {'type': 'integer', 'tz': 'UTC', 'units': 'int'},
+     'state': {'type': 'integer', 'tz': 'UTC', 'units': 'On / Off'}}]
diff --git a/docs/source/agent-framework/driver-framework/home-assistant/home-assistant.png b/docs/source/agent-framework/driver-framework/home-assistant/home-assistant.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -71,7 +71,8 @@ def __getattr__(cls, name):
     # http://www.sphinx-doc.org/en/master/usage/extensions/todo.html
     'sphinx.ext.todo',
     'sphinx.ext.intersphinx',
-    'm2r2'
+    'm2r2',
+    'sphinxcontrib.mermaid'
 ]
 
 # prefix sections with the document so that we can cross link

diff --git a/docs/source/deploying-volttron/platform-configuration.rst b/docs/source/deploying-volttron/platform-configuration.rst
@@ -6,11 +6,11 @@ Platform Configuration
 
 Each instance of the VOLTTRON platform includes a `config` file which is used to configure the platform instance on
 startup.  This file is kept in :term:`VOLTTRON_HOME` and is created using the `volttron-cfg` (`vcfg`) command, or will
-be created with default values on start up of the platform otherwise.
+be created with default values on start up of the platform otherwise. `vcfg` also provides commands to configure and
+install few frequently used agents and update configuration-store entries
 
 Following is helpful information about the `config` file and the `vcfg` command.
 
-
 VOLTTRON_HOME
 =============
 
@@ -75,9 +75,13 @@ The example consists of the following entries:
 VOLTTRON Config
 ===============
 
-The `volttron-cfg` or `vcfg` command allows for an easy configuration of the VOLTTRON environment.  The command includes
-the ability to set up the platform configuration, an instance of the platform historian, VOLTTRON Central UI, and
-VOLTTRON Central Platform agent.
+The `volttron-cfg` or `vcfg` command allows for an easy configuration of the VOLTTRON environment.
+The `vcfg` command can be run without any arguments to go through all available configuration steps sequentially and
+pick what is appropriate for a given instance of VOLTTRON. This is useful when starting with a new VOLTTRON instance.
+
+`vcfg` command can also be used with specific subcommands to configure and install specific agents such as
+listener agent, platform historian, VOLTTRON Central UI, and VOLTTRON Central Platform agent
+or add one or more agent configurations to VOLTTRON's configuration store.
 
 Running `vcfg` will create a `config` file in `VOLTTRON_HOME` which will be populated according to the answers to
 prompts.  This process should be repeated for each platform instance, and can be re-run to reconfigure a platform
@@ -158,12 +162,52 @@ Optional Arguments
   - **-v, --verbose** - Enables verbose output in standard-output (PIP output, etc.)
   - **--vhome VHOME** - Provide a path to set `VOLTTRON_HOME` for this instance
   - **--instance-name INSTANCE_NAME** - Provide a name for this instance.  Required for running secure agents mode
-  - **--list-agents** - Display a list of configurable agents (Listener, Platform Driver, Platform Historian, VOLTTRON
-    Central, VOLTTRON Central Platform)
-  - **--agent AGENT [AGENT ...]** - Configure listed agents
   - **--agent-isolation-mode** - Require that agents run as their own Unix users (this requires running
     `scripts/secure_user_permissions.sh` as `sudo`)
 
+Sub commands
+------------
+**--list-agents**
+~~~~~~~~~~~~~~~~~~
+    Display a list of configurable agents (Listener, Platform Driver, Platform Historian, VOLTTRON
+    Central, VOLTTRON Central Platform)
+
+**--agent AGENT [AGENT ...]**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configure and install one of the listed agents for a specific VOLTTRON instance
+
+**update-config-store --metadata-file METADATA_FILE_OR_DIR [METADATA_FILE_OR_DIR ...]**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Command to bulk add/update multiple agent configurations to VOLTTRON's configuration store. This is especially useful
+for automated deployment use cases. For example, a automated deployment setup where devices in a network are
+detected, and configurations for platform driver and control agents such as ILCAgent are auto generated using semantic
+tags. In such as scenario, adding all the generated configurations to the configuration store using the below command
+is more efficient than running the "vctl config store" command once for each configuration
+
+This command can only be used when volttron instance is not running.
+
+Usage:
+
+.. code-block:: bash
+
+    vcfg update-config-store --metadata-file <one or more metadata file or directories containing metadata files separated by space>
+
+
+Format for Metadata file:
+
+.. code-block::
+
+    { "vip-id": [
+     {
+         "config-name": "optional. name. defaults to config
+         "config": "json config or string config or config file name",
+         "config-type": "optional. type of config - csv or json or raw. defaults to json"
+     }, ...
+     ],...
+    }
+
+
 RabbitMQ Arguments
 ------------------
 vcfg command to configure a single RabbitMQ instance of VOLTTRON.

diff --git a/docs/source/introduction/platform-install.rst b/docs/source/introduction/platform-install.rst
@@ -198,7 +198,9 @@ Install Erlang pre-requisites
 +++++++++++++++++++++++++++++
 .. code-block:: bash
     sudo apt-get update
-    sudo apt-get install -y gnupg apt-transport-https libsctp1
+    sudo apt-get install -y gnupg apt-transport-https libsctp1 libncurses5
+
+Please 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, install of erlang should fail with appropriate error message.
 
 Purge previous versions of Erlang
 +++++++++++++++++++++++++++++++++

diff --git a/examples/EnergyPlusAgent/energyplus/agent.py b/examples/EnergyPlusAgent/energyplus/agent.py
@@ -362,22 +362,22 @@ def check_advance(self):
         timestep = int(60 / self.EnergyPlus_sim.timestep)
 
         if not self.EnergyPlus_sim.real_time_flag:
-            self.cosim_sync_counter += timestep
-            if self.cosim_sync_counter < self.EnergyPlus_sim.co_sim_timestep:
+            self.EnergyPlus_sim.cosim_sync_counter += timestep
+            if self.EnergyPlus_sim.cosim_sync_counter < self.EnergyPlus_sim.co_sim_timestep:
                 self.advance_simulation(None, None, None, None, None, None)
             else:
-                self.cosim_sync_counter = 0
+                self.EnergyPlus_sim.cosim_sync_counter = 0
                 self.vip.pubsub.publish('pubsub',
                                         self.tns_actuate,
                                         headers={},
                                         message={}).get(timeout=10)
         elif self.EnergyPlus_sim.hour > self.EnergyPlus_sim.currenthour or self.EnergyPlus_sim.passtime:
             self.EnergyPlus_sim.passtime = True
-            self.cosim_sync_counter += timestep
-            if self.cosim_sync_counter < self.EnergyPlus_sim.co_sim_timestep:
+            self.EnergyPlus_sim.cosim_sync_counter += timestep
+            if self.EnergyPlus_sim.cosim_sync_counter < self.EnergyPlus_sim.co_sim_timestep:
                 self.advance_simulation(None, None, None, None, None, None)
             else:
-                self.cosim_sync_counter = 0
+                self.EnergyPlus_sim.cosim_sync_counter = 0
                 self.vip.pubsub.publish('pubsub',
                                         self.tns_actuate,
                                         headers={},