From fffdaa67d6f8842fb78bb1a33d58150831963361 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Mon, 13 Mar 2023 18:18:17 -0700 Subject: [PATCH 01/11] Added (monolithic) documentation for Fake Driver. --- docs/Makefile | 20 ++++++ docs/source/conf.py | 59 ++++++++++++++++ docs/source/index.rst | 157 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 236 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..b7e6a4f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,59 @@ +# -*- coding: utf-8 -*- {{{ +# ===----------------------------------------------------------------------=== +# +# Installable Component of Eclipse VOLTTRON +# +# ===----------------------------------------------------------------------=== +# +# Copyright 2022 Battelle Memorial Institute +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may not +# use this file except in compliance with the License. You may obtain a copy +# of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# ===----------------------------------------------------------------------=== +# }}} + +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'VOLTTRON Fake Driver' +copyright = '2022, Pacific Northwest National Lab' +author = 'Pacific Northwest National Lab' + +release = '0.1' +version = '0.1.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +# epub_show_urls = 'footnote' diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..8d10d16 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,157 @@ +.. _Fake-Driver: + +=========== +Fake Driver +=========== + +The FakeDriver is included as a way to quickly see data published to the message bus in a format +that mimics what a true Driver would produce. This is an extremely simple implementation of the +:ref:`VOLTTRON driver framework `. + + +Fake Device Driver Configuration +================================ + +This driver does not connect to any actual device and instead produces random and or pre-configured values. + + +Driver Config +------------- + +There are no arguments for the `driver_config` section of the device configuration file. The `driver_config` entry must +still be present and should be left blank. + +Here is an example device configuration file: + +.. code-block:: json + + { + "driver_config": {}, + "driver_type": "bacnet", + "registry_config":"config://registry_configs/vav.csv", + "interval": 5, + "timezone": "UTC", + "heart_beat_point": "heartbeat" + } + +A sample fake device configuration file can be found in the VOLTTRON repository in +`examples/configurations/drivers/fake.config` + +Fake Device Registry Configuration File +--------------------------------------- + +The registry configuration file is a `CSV `_ file. Each row +configures a point on the device. + +The following columns are required for each row: + + - **Volttron Point Name** - The name by which the platform and agents running on the platform will refer to this + point. For instance, if the `Volttron Point Name` is `HeatCall1` (and using the example device configuration + above) then an agent would use `pnnl/isb2/hvac1/HeatCall1` to refer to the point when using the RPC interface of + the actuator agent. + - **Units** - Used for meta data when creating point information on the historian. + - **Writable** - Either `TRUE` or `FALSE`. Determines if the point can be written to. Only points labeled `TRUE` + can be written to through the ActuatorAgent. Points labeled `TRUE` incorrectly will cause an error to be returned + when an agent attempts to write to the point. + + +The following columns are optional: + + - **Starting Value** - Initial value for the point. If the point is reverted it will change back to this value. By + default, points will start with a random value (1-100). + - **Type** - Value type for the point. Defaults to "string". Valid types are: + + * string + * integer + * float + * boolean + +Any additional columns will be ignored. It is common practice to include a `Point Name` or `Reference Point Name` to +include the device documentation's name for the point and `Notes` and `Unit Details` for additional information +about a point. Please note that there is nothing in the driver that will enforce anything specified in the +`Unit Details` column. + +.. csv-table:: BACnet + :header: Volttron Point Name,Units,Units Details,Writable,Starting Value,Type,Notes + + Heartbeat,On/Off,On/Off,TRUE,0,boolean,Point for heartbeat toggle + OutsideAirTemperature1,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm + SampleWritableFloat1,PPM,10.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation + SampleLong1,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch + SampleWritableShort1,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode + SampleBool1,On / Off,on/off,FALSE,TRUE,boolean,Status indicator of cooling stage 1 + SampleWritableBool1,On / Off,on/off,TRUE,TRUE,boolean,Status indicator + +A sample fake registry configuration file can be found +`here `_ +or in the VOLTTRON repository in ``examples/configurations/drivers/fake.csv`` + + +.. _Fake-Driver-Install: + +Installation +============ + +Installing a Fake driver in the :ref:`Platform Driver Agent ` requires adding copies of the device +configuration and registry configuration files to the Platform Driver's :ref:`configuration store ` + +- Create a config directory (if one doesn't already exist) inside your Volttron repository: + +.. code-block:: bash + + mkdir config + +All local config files will be worked on here. + +- Copy over the example config file and registry config file from the VOLTTRON repository: + +.. code-block:: bash + + cp examples/configurations/drivers/fake.config config/ + cp examples/configurations/drivers/fake.csv config/ + +- Edit the driver config `fake.config` for the paths on your system: + +.. code-block:: json + + { + "driver_config": {}, + "registry_config": "config://fake.csv", + "interval": 5, + "timezone": "US/Pacific", + "heart_beat_point": "Heartbeat", + "driver_type": "fakedriver", + "publish_breadth_first_all": false, + "publish_depth_first": false, + "publish_breadth_first": false + } + +- Create a copy of the Platform Driver config from the VOLTTRON repository: + +.. code-block:: bash + + cp examples/configurations/drivers/platform-driver.agent config/fake-platform-driver.config + +- Add fake.csv and fake.config to the :ref:`configuration store `: + +.. code-block:: bash + + vctl config store platform.driver devices/campus/building/fake config/fake.config + vctl config store platform.driver fake.csv config/fake.csv --csv + +- Edit `fake-platform-driver.config` to reflect paths on your system + +.. code-block:: json + + { + "driver_scrape_interval": 0.05 + } + +- Use the scripts/install-agent.py script to install the Platform Driver agent: + +.. code-block:: bash + + python scripts/install-agent.py -s services/core/PlatformDriverAgent -c config/fake-platform-driver.config + +- If you have a :ref:`Listener Agent` already installed, you should start seeing data being published to + the bus. From c3d828f73cef2338fc06c4c1ae2dd6426c906740 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Fri, 17 Mar 2023 11:10:34 -0700 Subject: [PATCH 02/11] Modular updates to documentation. --- docs/source/index.rst | 81 ++++++++++++++----------------------------- fake.config | 9 ++--- 2 files changed, 29 insertions(+), 61 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8d10d16..e74b70f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,16 +26,19 @@ Here is an example device configuration file: .. code-block:: json { + "driver_type": "fake", "driver_config": {}, - "driver_type": "bacnet", - "registry_config":"config://registry_configs/vav.csv", + "registry_config":"config://fake.csv", "interval": 5, - "timezone": "UTC", - "heart_beat_point": "heartbeat" + "timezone": "US/Pacific", + "heart_beat_point": "Heartbeat", + "publish_breadth_first_all": false, + "publish_depth_first": false, + "publish_breadth_first": false } -A sample fake device configuration file can be found in the VOLTTRON repository in -`examples/configurations/drivers/fake.config` +A sample fake device configuration file can be found in the volttron-lib-fake-driver repository as +:ref:`fake.config ` Fake Device Registry Configuration File --------------------------------------- @@ -46,13 +49,13 @@ configures a point on the device. The following columns are required for each row: - **Volttron Point Name** - The name by which the platform and agents running on the platform will refer to this - point. For instance, if the `Volttron Point Name` is `HeatCall1` (and using the example device configuration - above) then an agent would use `pnnl/isb2/hvac1/HeatCall1` to refer to the point when using the RPC interface of - the actuator agent. + point. For instance, if the `Volttron Point Name` is `HeatCall1` and the device configuration is stored as + `devices/pnnl/isb2/hvac1`, then an agent would use `pnnl/isb2/hvac1/HeatCall1` to refer to the point when using + the RPC interface of the driver or actuator agents. - **Units** - Used for meta data when creating point information on the historian. - **Writable** - Either `TRUE` or `FALSE`. Determines if the point can be written to. Only points labeled `TRUE` - can be written to through the ActuatorAgent. Points labeled `TRUE` incorrectly will cause an error to be returned - when an agent attempts to write to the point. + can be written. Writing to points labeled `FALSE` will cause an error to be returned when an agent attempts to + write to the point. The following columns are optional: @@ -83,8 +86,8 @@ about a point. Please note that there is nothing in the driver that will enforc SampleWritableBool1,On / Off,on/off,TRUE,TRUE,boolean,Status indicator A sample fake registry configuration file can be found -`here `_ -or in the VOLTTRON repository in ``examples/configurations/drivers/fake.csv`` +`here `_ +or in the volttron-lib-fake-driver repository as `fake.csv`. .. _Fake-Driver-Install: @@ -95,63 +98,31 @@ Installation Installing a Fake driver in the :ref:`Platform Driver Agent ` requires adding copies of the device configuration and registry configuration files to the Platform Driver's :ref:`configuration store ` -- Create a config directory (if one doesn't already exist) inside your Volttron repository: +- Create a local directory for editing config files (if one doesn't already exist): .. code-block:: bash - mkdir config - -All local config files will be worked on here. - -- Copy over the example config file and registry config file from the VOLTTRON repository: - -.. code-block:: bash - - cp examples/configurations/drivers/fake.config config/ - cp examples/configurations/drivers/fake.csv config/ - -- Edit the driver config `fake.config` for the paths on your system: - -.. code-block:: json - - { - "driver_config": {}, - "registry_config": "config://fake.csv", - "interval": 5, - "timezone": "US/Pacific", - "heart_beat_point": "Heartbeat", - "driver_type": "fakedriver", - "publish_breadth_first_all": false, - "publish_depth_first": false, - "publish_breadth_first": false - } - -- Create a copy of the Platform Driver config from the VOLTTRON repository: + mkdir myconfig -.. code-block:: bash +- Save copies, in myconfig, of the example + :ref:`device config file ` + and :ref:`registry file ` + from the volttron-lib-fake-driver repository. - cp examples/configurations/drivers/platform-driver.agent config/fake-platform-driver.config +- Edit the fake.config and fake.csv files, if desired. - Add fake.csv and fake.config to the :ref:`configuration store `: .. code-block:: bash - vctl config store platform.driver devices/campus/building/fake config/fake.config - vctl config store platform.driver fake.csv config/fake.csv --csv - -- Edit `fake-platform-driver.config` to reflect paths on your system - -.. code-block:: json - - { - "driver_scrape_interval": 0.05 - } + vctl config store platform.driver devices/campus/building/fake myconfig/fake.config + vctl config store platform.driver fake.csv myconfig/fake.csv --csv - Use the scripts/install-agent.py script to install the Platform Driver agent: .. code-block:: bash - python scripts/install-agent.py -s services/core/PlatformDriverAgent -c config/fake-platform-driver.config + python scripts/install-agent.py -s services/core/PlatformDriverAgent -i platform.driver -t driver - If you have a :ref:`Listener Agent` already installed, you should start seeing data being published to the bus. diff --git a/fake.config b/fake.config index 4009a7a..06b1ca5 100644 --- a/fake.config +++ b/fake.config @@ -1,4 +1,5 @@ { + "driver_type": "fake", "driver_config": {}, "registry_config":"config://fake.csv", "interval": 5, @@ -6,9 +7,5 @@ "heart_beat_point": "Heartbeat", "publish_breadth_first_all": false, "publish_depth_first": false, - "publish_breadth_first": false, - "campus": "campus", - "building": "building", - "unit": "fake_device", - "driver_type": "fake" - } + "publish_breadth_first": false +} From 0733909980d9c2a8d56a3ef7a17824c2f8ecafb6 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Fri, 17 Mar 2023 11:10:34 -0700 Subject: [PATCH 03/11] Modular updates to documentation. --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index e74b70f..1b1de94 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -106,7 +106,7 @@ configuration and registry configuration files to the Platform Driver's :ref:`co - Save copies, in myconfig, of the example :ref:`device config file ` - and :ref:`registry file ` + and `registry file ` from the volttron-lib-fake-driver repository. - Edit the fake.config and fake.csv files, if desired. From 66343e84b903228fba009b6e2b3fb1b985a731fc Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Fri, 17 Mar 2023 11:20:45 -0700 Subject: [PATCH 04/11] Corrections to links in documentation. --- docs/source/index.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 1b1de94..850b3db 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -38,7 +38,7 @@ Here is an example device configuration file: } A sample fake device configuration file can be found in the volttron-lib-fake-driver repository as -:ref:`fake.config ` +`fake.config `_ Fake Device Registry Configuration File --------------------------------------- @@ -85,9 +85,8 @@ about a point. Please note that there is nothing in the driver that will enforc SampleBool1,On / Off,on/off,FALSE,TRUE,boolean,Status indicator of cooling stage 1 SampleWritableBool1,On / Off,on/off,TRUE,TRUE,boolean,Status indicator -A sample fake registry configuration file can be found -`here `_ -or in the volttron-lib-fake-driver repository as `fake.csv`. +A sample fake registry configuration file can be found in the volttron-lib-fake-driver repository as +`fake.csv `_. .. _Fake-Driver-Install: @@ -105,8 +104,8 @@ configuration and registry configuration files to the Platform Driver's :ref:`co mkdir myconfig - Save copies, in myconfig, of the example - :ref:`device config file ` - and `registry file ` + `device config file `_ + and `registry file `_ from the volttron-lib-fake-driver repository. - Edit the fake.config and fake.csv files, if desired. From 09853f32d4737cd6f269d937876cf4fda235f1d3 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Fri, 17 Mar 2023 11:25:23 -0700 Subject: [PATCH 05/11] Additional documentation tweaks. --- docs/source/index.rst | 8 ++++---- fake.config | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 850b3db..8900358 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,7 +28,7 @@ Here is an example device configuration file: { "driver_type": "fake", "driver_config": {}, - "registry_config":"config://fake.csv", + "registry_config":"config://registry_configs/fake.csv", "interval": 5, "timezone": "US/Pacific", "heart_beat_point": "Heartbeat", @@ -37,7 +37,7 @@ Here is an example device configuration file: "publish_breadth_first": false } -A sample fake device configuration file can be found in the volttron-lib-fake-driver repository as +This sample fake device configuration file can also be found in the volttron-lib-fake-driver repository as `fake.config `_ Fake Device Registry Configuration File @@ -114,8 +114,8 @@ configuration and registry configuration files to the Platform Driver's :ref:`co .. code-block:: bash - vctl config store platform.driver devices/campus/building/fake myconfig/fake.config - vctl config store platform.driver fake.csv myconfig/fake.csv --csv + vctl config store platform.driver devices/campus/building/fake1 myconfig/fake.config + vctl config store platform.driver registry_configs/fake.csv myconfig/fake.csv --csv - Use the scripts/install-agent.py script to install the Platform Driver agent: diff --git a/fake.config b/fake.config index 06b1ca5..ce7c3fb 100644 --- a/fake.config +++ b/fake.config @@ -1,7 +1,7 @@ { "driver_type": "fake", "driver_config": {}, - "registry_config":"config://fake.csv", + "registry_config":"config://registry_configs/fake.csv", "interval": 5, "timezone": "US/Pacific", "heart_beat_point": "Heartbeat", From a0b4d9e1cb0e86c18365cc7c462e4ad428c3e07a Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Fri, 17 Mar 2023 12:54:06 -0700 Subject: [PATCH 06/11] Corrected missed installation command in modular documentation udpates. --- docs/source/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8900358..a61e666 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -117,11 +117,11 @@ configuration and registry configuration files to the Platform Driver's :ref:`co vctl config store platform.driver devices/campus/building/fake1 myconfig/fake.config vctl config store platform.driver registry_configs/fake.csv myconfig/fake.csv --csv -- Use the scripts/install-agent.py script to install the Platform Driver agent: +- If it is not already installed, install the Platform Driver agent: .. code-block:: bash - python scripts/install-agent.py -s services/core/PlatformDriverAgent -i platform.driver -t driver + vctl install volttron-platform-driver --vip-identity platform.driver --tag driver - If you have a :ref:`Listener Agent` already installed, you should start seeing data being published to - the bus. + the bus as soon as the driver agent is started. From 96b610bc1c1c1223ce0575871fb29d2024e2a1ac Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Mon, 1 May 2023 11:30:10 -0700 Subject: [PATCH 07/11] Updated documentation, README, and dependencies. --- README.md | 79 ++++++++++++++----------------------------- docs/source/index.rst | 10 ++++-- pyproject.toml | 4 +-- 3 files changed, 36 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 0af6824..b6a9c24 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,53 @@ # volttron-lib-fake-driver -![Passing?](https://github.com/VOLTTRON/volttron-lib-fake-driver/actions/workflows/run-tests.yml/badge.svg) +![Passing?](https://github.com/eclipse-volttron/volttron-lib-fake-driver/actions/workflows/run-tests.yml/badge.svg) [![pypi version](https://img.shields.io/pypi/v/volttron-lib-fake-driver.svg)](https://pypi.org/project/volttron-lib-fake-driver/) -The FakeDriver is a way to quickly see data published to the message bus in a format that mimics what a true Driver would produce. This is an extremely simple implementation of the [VOLTTRON driver framework](https://volttron.readthedocs.io/en/develop/agent-framework/driver-framework/drivers-overview.html#driver-framework). This driver does not connect to any actual device and instead produces random and or pre-configured values. +The FakeDriver is a way to quickly see data published to the message bus in a format that mimics +what a true Driver would produce. This is an extremely simple implementation of the +[VOLTTRON Driver Framework](https://volttron.readthedocs.io/en/develop/agent-framework/driver-framework/drivers-overview.html#driver-framework). +This driver does not connect to any actual device and instead produces random and or pre-configured values. -# Prerequisites +# Requires -* Python 3.8 +* python >= 3.10 +* volttron >= 10.0 +* volttron-lib-base-driver -## Python -
-To install Python 3.8, we recommend using pyenv. +# Documentation +More detailed documentation can be found on [ReadTheDocs](https://volttron.readthedocs.io/en/modular/). The RST source +of the documentation for this component is located in the "docs" directory of this repository. -```bash -# install pyenv -git clone https://github.com/pyenv/pyenv ~/.pyenv - -# setup pyenv (you should also put these three lines in .bashrc or similar) -export PATH="${HOME}/.pyenv/bin:${PATH}" -export PYENV_ROOT="${HOME}/.pyenv" -eval "$(pyenv init -)" - -# install Python 3.8 -pyenv install 3.8.10 - -# make it available globally -pyenv global system 3.8.10 -``` -
# Installation -1. Create and activate a virtual environment. - -```shell -python -m venv env -source env/bin/activate -``` - -2. Install volttron and start the platform. +Before installing the VOLTTRON Modbus driver, VOLTTRON should be installed and running. +Its virtual environment should be active. Information on how to install +of the VOLTTRON platform can be found [here](https://github.com/eclipse-volttron/volttron-core). -```shell -pip install volttron - -# Start platform with output going to volttron.log -volttron -vv -l volttron.log & -``` - -3. Install the volttron platform driver: +1. If it is not already, install the VOLTTRON Platform Driver Agent: -```shell -vctl install volttron-platform-driver --vip-identity platform.driver --start -``` + ```shell + vctl install volttron-platform-driver --vip-identity platform.driver --start + ``` -4. Install the volttron fake driver library. - - You have two options. You can install this library using the version on PyPi: +2. Install the volttron fake driver library: ```shell pip install volttron-lib-fake-driver ``` -5. Install a Fake Driver onto the Platform Driver. - -Installing a Fake driver in the Platform Driver Agent requires adding copies of the device configuration and registry configuration files to the Platform Driver’s configuration store +3. Store device and registry files for the Fake device to the Platform Driver configuration store: -Create a config directory and navigate to it: +* Create a config directory and navigate to it: ```shell mkdir config cd config ``` -Navigate to the config directory and create a file called `fake.config` and add the following JSON to it: +* Navigate to the config directory and create a file called `fake.config` and add the following JSON to it: ```json { @@ -90,7 +63,7 @@ Navigate to the config directory and create a file called `fake.config` and add } ``` -Create another file called `fake.csv` and add the following contents to it: +* Create another file called `fake.csv` and add the following contents to it: ```csv Point Name,Volttron Point Name,Units,Units Details,Writable,Starting Value,Type,Notes @@ -120,14 +93,14 @@ EKG_Sin,EKG_Sin,1-0,SIN Wave,TRUE,sin,float,SIN wave EKG_Cos,EKG_Cos,1-0,COS Wave,TRUE,sin,float,COS wave ``` -Add fake.csv and fake.config to the configuration store: +* Add fake.csv and fake.config to the configuration store: ``` vctl config store platform.driver devices/campus/building/fake fake.config vctl config store platform.driver fake.csv fake.csv --csv ``` -6. Observe Data +4. Observe Data To see data being published to the bus, install a [Listener Agent](https://pypi.org/project/volttron-listener/): diff --git a/docs/source/index.rst b/docs/source/index.rst index a61e666..23e9714 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,7 +6,7 @@ Fake Driver The FakeDriver is included as a way to quickly see data published to the message bus in a format that mimics what a true Driver would produce. This is an extremely simple implementation of the -:ref:`VOLTTRON driver framework `. +:ref:`VOLTTRON Driver Framework `. Fake Device Driver Configuration @@ -94,7 +94,7 @@ A sample fake registry configuration file can be found in the volttron-lib-fake- Installation ============ -Installing a Fake driver in the :ref:`Platform Driver Agent ` requires adding copies of the device +Installing a Fake driver in the :ref:`Platform Driver Agent ` requires adding copies of the device configuration and registry configuration files to the Platform Driver's :ref:`configuration store ` - Create a local directory for editing config files (if one doesn't already exist): @@ -123,5 +123,11 @@ configuration and registry configuration files to the Platform Driver's :ref:`co vctl install volttron-platform-driver --vip-identity platform.driver --tag driver +- Install the volttron fake driver library: + +.. code-block:: bash + + pip install volttron-lib-fake-driver + - If you have a :ref:`Listener Agent` already installed, you should start seeing data being published to the bus as soon as the driver agent is started. diff --git a/pyproject.toml b/pyproject.toml index 30093fd..96c2f1e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,8 +26,8 @@ classifiers = [ ] [tool.poetry.dependencies] -python = ">=3.8,<4.0" -volttron-lib-base-driver = "^0.2.0rc0" +python = ">=3.10,<4.0" +volttron-lib-base-driver = "^0.2.1rc2" [tool.poetry.group.dev.dependencies] volttron-testing = "^0.4.0rc0" From d8a0cfbd57f862da5cd841d04533d476d3a1410a Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Mon, 1 May 2023 11:46:31 -0700 Subject: [PATCH 08/11] Updated run-tests workflow to current os and python versions. --- .github/workflows/run-tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index b090938..0b2e58f 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -29,7 +29,7 @@ jobs: strategy: matrix: os: [ubuntu-22.04] - python: ['3.8', '3.9', '3.10'] + python: ['3.10', '3.11'] runs-on: ${{ matrix.os }} From a9a5912696e6358425252350417c43edd0110cc1 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Fri, 5 May 2023 05:43:50 -0700 Subject: [PATCH 09/11] README fixes. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b6a9c24..f0eeda4 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@ of the documentation for this component is located in the "docs" directory of th # Installation -Before installing the VOLTTRON Modbus driver, VOLTTRON should be installed and running. -Its virtual environment should be active. Information on how to install -of the VOLTTRON platform can be found [here](https://github.com/eclipse-volttron/volttron-core). +Before installing, VOLTTRON should be installed and running. Its virtual environment should be active. +Information on how to install of the VOLTTRON platform can be found +[here](https://github.com/eclipse-volttron/volttron-core). 1. If it is not already, install the VOLTTRON Platform Driver Agent: From 13e59796f2dce7e2f780361e09da17c826cf2864 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Thu, 18 May 2023 11:30:12 -0700 Subject: [PATCH 10/11] Updates to README.md. --- README.md | 150 +++++++++++++++++++++++++++--------------------------- 1 file changed, 76 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index f0eeda4..efbc140 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # volttron-lib-fake-driver +![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg) +![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg) ![Passing?](https://github.com/eclipse-volttron/volttron-lib-fake-driver/actions/workflows/run-tests.yml/badge.svg) [![pypi version](https://img.shields.io/pypi/v/volttron-lib-fake-driver.svg)](https://pypi.org/project/volttron-lib-fake-driver/) @@ -34,86 +36,86 @@ Information on how to install of the VOLTTRON platform can be found 2. Install the volttron fake driver library: -```shell -pip install volttron-lib-fake-driver -``` + ```shell + pip install volttron-lib-fake-driver + ``` 3. Store device and registry files for the Fake device to the Platform Driver configuration store: -* Create a config directory and navigate to it: - -```shell -mkdir config -cd config -``` - -* Navigate to the config directory and create a file called `fake.config` and add the following JSON to it: - -```json -{ - "driver_config": {}, - "registry_config": "config://fake.csv", - "interval": 5, - "timezone": "US/Pacific", - "heart_beat_point": "Heartbeat", - "driver_type": "fake", - "publish_breadth_first_all": false, - "publish_depth_first": false, - "publish_breadth_first": false - } -``` - -* Create another file called `fake.csv` and add the following contents to it: - -```csv -Point Name,Volttron Point Name,Units,Units Details,Writable,Starting Value,Type,Notes -EKG,EKG,waveform,waveform,TRUE,sin,float,Sine wave for baseline output -Heartbeat,Heartbeat,On/Off,On/Off,TRUE,0,boolean,Point for heartbeat toggle -OutsideAirTemperature1,OutsideAirTemperature1,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm -SampleWritableFloat1,SampleWritableFloat1,PPM,1000.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation -SampleLong1,SampleLong1,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch -SampleWritableShort1,SampleWritableShort1,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode -SampleBool1,SampleBool1,On / Off,on/off,FALSE,TRUE,boolean,Status indidcator of cooling stage 1 -SampleWritableBool1,SampleWritableBool1,On / Off,on/off,TRUE,TRUE,boolean,Status indicator -OutsideAirTemperature2,OutsideAirTemperature2,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm -SampleWritableFloat2,SampleWritableFloat2,PPM,1000.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation -SampleLong2,SampleLong2,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch -SampleWritableShort2,SampleWritableShort2,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode -SampleBool2,SampleBool2,On / Off,on/off,FALSE,TRUE,boolean,Status indidcator of cooling stage 1 -SampleWritableBool2,SampleWritableBool2,On / Off,on/off,TRUE,TRUE,boolean,Status indicator -OutsideAirTemperature3,OutsideAirTemperature3,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm -SampleWritableFloat3,SampleWritableFloat3,PPM,1000.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation -SampleLong3,SampleLong3,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch -SampleWritableShort3,SampleWritableShort3,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode -SampleBool3,SampleBool3,On / Off,on/off,FALSE,TRUE,boolean,Status indidcator of cooling stage 1 -SampleWritableBool3,SampleWritableBool3,On / Off,on/off,TRUE,TRUE,boolean,Status indicator -HPWH_Phy0_PowerState,PowerState,1/0,1/0,TRUE,0,int,Power on off status -ERWH_Phy0_ValveState,ValveState,1/0,1/0,TRUE,0,int,power on off status -EKG_Sin,EKG_Sin,1-0,SIN Wave,TRUE,sin,float,SIN wave -EKG_Cos,EKG_Cos,1-0,COS Wave,TRUE,sin,float,COS wave -``` - -* Add fake.csv and fake.config to the configuration store: - -``` -vctl config store platform.driver devices/campus/building/fake fake.config -vctl config store platform.driver fake.csv fake.csv --csv -``` + * Create a config directory and navigate to it: + + ```shell + mkdir config + cd config + ``` + + * Navigate to the config directory and create a file called `fake.config` and add the following JSON to it: + + ```json + { + "driver_config": {}, + "registry_config": "config://fake.csv", + "interval": 5, + "timezone": "US/Pacific", + "heart_beat_point": "Heartbeat", + "driver_type": "fake", + "publish_breadth_first_all": false, + "publish_depth_first": false, + "publish_breadth_first": false + } + ``` + + * Create another file called `fake.csv` and add the following contents to it: + + ```csv + Point Name,Volttron Point Name,Units,Units Details,Writable,Starting Value,Type,Notes + EKG,EKG,waveform,waveform,TRUE,sin,float,Sine wave for baseline output + Heartbeat,Heartbeat,On/Off,On/Off,TRUE,0,boolean,Point for heartbeat toggle + OutsideAirTemperature1,OutsideAirTemperature1,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm + SampleWritableFloat1,SampleWritableFloat1,PPM,1000.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation + SampleLong1,SampleLong1,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch + SampleWritableShort1,SampleWritableShort1,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode + SampleBool1,SampleBool1,On / Off,on/off,FALSE,TRUE,boolean,Status indidcator of cooling stage 1 + SampleWritableBool1,SampleWritableBool1,On / Off,on/off,TRUE,TRUE,boolean,Status indicator + OutsideAirTemperature2,OutsideAirTemperature2,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm + SampleWritableFloat2,SampleWritableFloat2,PPM,1000.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation + SampleLong2,SampleLong2,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch + SampleWritableShort2,SampleWritableShort2,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode + SampleBool2,SampleBool2,On / Off,on/off,FALSE,TRUE,boolean,Status indidcator of cooling stage 1 + SampleWritableBool2,SampleWritableBool2,On / Off,on/off,TRUE,TRUE,boolean,Status indicator + OutsideAirTemperature3,OutsideAirTemperature3,F,-100 to 300,FALSE,50,float,CO2 Reading 0.00-2000.0 ppm + SampleWritableFloat3,SampleWritableFloat3,PPM,1000.00 (default),TRUE,10,float,Setpoint to enable demand control ventilation + SampleLong3,SampleLong3,Enumeration,1 through 13,FALSE,50,int,Status indicator of service switch + SampleWritableShort3,SampleWritableShort3,%,0.00 to 100.00 (20 default),TRUE,20,int,Minimum damper position during the standard mode + SampleBool3,SampleBool3,On / Off,on/off,FALSE,TRUE,boolean,Status indidcator of cooling stage 1 + SampleWritableBool3,SampleWritableBool3,On / Off,on/off,TRUE,TRUE,boolean,Status indicator + HPWH_Phy0_PowerState,PowerState,1/0,1/0,TRUE,0,int,Power on off status + ERWH_Phy0_ValveState,ValveState,1/0,1/0,TRUE,0,int,power on off status + EKG_Sin,EKG_Sin,1-0,SIN Wave,TRUE,sin,float,SIN wave + EKG_Cos,EKG_Cos,1-0,COS Wave,TRUE,sin,float,COS wave + ``` + + * Add fake.csv and fake.config to the configuration store: + + ``` + vctl config store platform.driver devices/campus/building/fake fake.config + vctl config store platform.driver fake.csv fake.csv --csv + ``` 4. Observe Data -To see data being published to the bus, install a [Listener Agent](https://pypi.org/project/volttron-listener/): - -``` -vctl install volttron-listener --start -``` - -Once installed, you should see the data being published by viewing the Volttron logs file that was created in step 2. -To watch the logs, open a separate terminal and run the following command: - -``` -tail -f /volttron.log -``` + To see data being published to the bus, install a [Listener Agent](https://pypi.org/project/volttron-listener/): + + ``` + vctl install volttron-listener --start + ``` + + Once installed, you should see the data being published by viewing the Volttron logs file that was created in step 2. + To watch the logs, open a separate terminal and run the following command: + + ``` + tail -f /volttron.log + ``` # Development From bda0623d9e35f007c7abff00f8b3e1aad465f0a3 Mon Sep 17 00:00:00 2001 From: "David M. Raker" Date: Tue, 3 Oct 2023 15:12:38 -0700 Subject: [PATCH 11/11] Updated links in readme.md --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index efbc140..5dc6714 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# volttron-lib-fake-driver +# VOLTTRON Fake Driver Interface ![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg) ![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg) @@ -7,7 +7,7 @@ The FakeDriver is a way to quickly see data published to the message bus in a format that mimics what a true Driver would produce. This is an extremely simple implementation of the -[VOLTTRON Driver Framework](https://volttron.readthedocs.io/en/develop/agent-framework/driver-framework/drivers-overview.html#driver-framework). +[VOLTTRON Driver Framework](https://eclipse-volttron.readthedocs.io/en/latest/external-docs/volttron-platform-driver/docs/source/index.html). This driver does not connect to any actual device and instead produces random and or pre-configured values. # Requires @@ -18,8 +18,8 @@ This driver does not connect to any actual device and instead produces random an # Documentation -More detailed documentation can be found on [ReadTheDocs](https://volttron.readthedocs.io/en/modular/). The RST source -of the documentation for this component is located in the "docs" directory of this repository. +More detailed documentation can be found on [ReadTheDocs](https://eclipse-volttron.readthedocs.io/en/latest/external-docs/volttron-platform-driver/docs/source/index.html). +The RST source of the documentation for this component is located in the "docs" directory of this repository. # Installation @@ -121,7 +121,7 @@ Information on how to install of the VOLTTRON platform can be found Please see the following for contributing guidelines [contributing](https://github.com/eclipse-volttron/volttron-core/blob/develop/CONTRIBUTING.md). -Please see the following helpful guide about [developing modular VOLTTRON agents](https://github.com/eclipse-volttron/volttron-core/blob/develop/DEVELOPING_ON_MODULAR.md) +Please see the following helpful guide about [developing modular VOLTTRON agents](https://eclipse-volttron.readthedocs.io/en/latest/developing-volttron/developing-agents/agent-development.html) # Disclaimer Notice