From bce93fe4c3b27a3001fc37fa9a58a7cca3472ebe Mon Sep 17 00:00:00 2001 From: Chandrika Sivaramakrishnan Date: Mon, 23 Oct 2023 12:49:10 -0700 Subject: [PATCH] Updated help text and vcfg documentation --- .../platform-configuration.rst | 60 ++++++++++++++++--- volttron/platform/instance_setup.py | 8 +-- .../platform/test_vcfg_config_update.py | 4 +- 3 files changed, 58 insertions(+), 14 deletions(-) diff --git a/docs/source/deploying-volttron/platform-configuration.rst b/docs/source/deploying-volttron/platform-configuration.rst index 569d86485c..b3b9f5f390 100644 --- 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 + + +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/volttron/platform/instance_setup.py b/volttron/platform/instance_setup.py index ce559d5756..487d35ea3f 100644 --- a/volttron/platform/instance_setup.py +++ b/volttron/platform/instance_setup.py @@ -1118,8 +1118,8 @@ def _exit_with_metadata_error(): { "vip-id": [ { "config-name": "optional. name. defaults to config - "config": "json config or config file name", - "config-type": "optional. type of config. defaults to json" + "config": "json config or string config or config file name", + "config-type": "optional. type of config - csv or json or raw. defaults to json" }, ... ],... }""") @@ -1229,8 +1229,8 @@ def main(): { "vip-id": [ { "config-name": "optional. name. defaults to config - "config": "json config or config file name", - "config-type": "optional. type of config. defaults to json" + "config": "json config or string config or config file name", + "config-type": "optional. type of config - csv or json or raw. defaults to json" }, ... ],... }""") diff --git a/volttrontesting/platform/test_vcfg_config_update.py b/volttrontesting/platform/test_vcfg_config_update.py index 62fa7f11bd..c34fdfa652 100644 --- a/volttrontesting/platform/test_vcfg_config_update.py +++ b/volttrontesting/platform/test_vcfg_config_update.py @@ -16,8 +16,8 @@ { "vip-id": [ { "config-name": "optional. name. defaults to config - "config": "json config or config file name", - "config-type": "optional. type of config. defaults to json" + "config": "json config or string config or config file name", + "config-type": "optional. type of config - csv or json or raw. defaults to json" }, ... ],... }"""