volttron-dnp3-outstation 2.0.0rc0

A Volttron agent that acts as a dnp3 outstation.

volttron-dnp3-outstation

Distributed Network Protocol (DNP or DNP3) has achieved a large-scale acceptance since its introduction in 1993. This protocol is an immediately deployable solution for monitoring remote sites because it was developed for communication of critical infrastructure status, allowing for reliable remote control.

DNP3 is typically used between centrally located masters and distributed remotes. Application layer fragments from Master DNP3 stations are typically requests for operations on data objects, and application layer fragments from Slave DNP3 stations (i.e., Outstation) are typically responses to those requests. A DNP3 Outstation may also transmit a message without a request (an unsolicited response). The volttron-dnp3-outstation is an implementation of the DNP3 master following the VOLTTRON Agent Specifications.

Note: to fully desmonstate the volttron-dnp3-outstation features, including polling data, setting point values, etc., it is suggested to establish connection between an outstation and a DNP3 master instance. The dnp3-python can provide the essential master functionality, and as part of the volttron-dnp3-outstation dependency, it is immediately available after the volttron-dnp3-outstation is installed.

Prerequisites

• Python 3 (tested with Python3.8, Python3.9, Python3.10)

Python

To install specific Python version (e.g., Python 3.8), we recommend using pyenv.

# 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.10
pyenv install 3.10

# make it available globally
pyenv global system 3.10

Installation

The following recipe walks through the steps to install and configure a DNP3 agent. Note that it uses default setup to work out-of-the-box. Please feel free to refer to related documentations for details.

1. Create and activate a virtual environment.

   It is recommended to use a virtual environment for installing volttron.

   python -m venv env
   source env/bin/activate
   
   pip install volttron
   

2. Install volttron and start the platform.

   Note: According to the volttron-core#README, setup VOLTTRON_HOME environment variable is mandatory: ... if you have/had in the past, a monolithic VOLTTRON version that used the default VOLTTRON_HOME $HOME/.volttron. This modular version of VOLTTRON cannot work with volttron_home used by monolithic version of VOLTTRON(version 8.3 or earlier)

   # Setup environment variable `VOLTTRON_HOME`
   export VOLTTRON_HOME=<path-to-volttron_home-dir>
   
   # Start platform with output going to volttron.log
   volttron -vv -l volttron.log &
   

3. Install the "volttron-dnp3-outstation" dependency.

   There are two options to install the DNP3 Driver. You can install this library using the version on PyPi or install it from the source code (git clone might be required.) Note: the vctl install command in the following step can handle dependency installation using pypi. However, in this demo we demonstrate what is happening under the neath the hood by separating the dependency installation and agent registry steps.

   # option 1: install from pypi
   pip install volttron-dnp3-outstation
   
   # option 2: install from the source code (Note: `-e` option to use editable mode, useful for development.)
   pip install [-e] <path-to-the-source-code-root>/volttron-dnp3-outstation/
   

4. Install and start the "volttron-dnp3-outstation" agent.

   Prepare the default config files:

   # Create config file place holders
   mkdir config
   touch config/dnp3-outstation-config.json
   

   Edit the dnp3-outstation-config.json as follows:

   {
    "outstation_ip": "0.0.0.0",
    "master_id": 2,
    "outstation_id": 1,
    "port":  21000
   }
   

   Use vctl install command to register to the volttron home path. Note: for demo purposes and reproducibility, we assign vip-identity as "dnp3_outstation", but you can choose any other valid agent identity as desired.

   vctl install volttron-dnp3-outstation --agent-config <path-to-agent-config> \
   --vip-identity dnp3_outstation \
   --start
   

   (Optional) Use vctl stauts to verify the installation

   (env) kefei@ubuntu-22:~/sandbox/dnp3-outstation-sandbox$ vctl status
   UUID   AGENT                             IDENTITY        TAG PRIORITY STATUS          HEALTH
   e      volttron-dnp3-outstation-0.0.1rc0 dnp3_outstation              running [3408]  GOOD
   

Basic Usage Example

Like other VOLTTRON agent, the volttron-dnp3-outstation agent provides public interface and can be evoked by VOLTTRON RPC calls. The volttron-dnp3-outstation provided a commandline interface vdnp3_outstation as an RPC method wrapper. Please see run_volttron_dnp3_outstation_cli.py for implementation details of the RPC examples.

1. (Optional) Inspect the dnp3 outstation cli help menu.

   (env) kefei@ubuntu-22:~/sandbox/dnp3-driver-sandbox$ python -m vdnp3_outstation.run_volttron_dnp3_outstation_cli -h
   usage: dnp3-outstation [-h] [-aid <peer-name>]
   
   Run a dnp3 outstation agent. Specify agent identity, by default `dnp3_outstation`
   
   options:
     -h, --help            show this help message and exit
     -aid <peer-name>, --agent-identity <peer-name>
                           specify agent identity (parsed as peer-name for rpc call), default 'dnp3_outstation'.
   

2. Start the dnp3 outstation cli

   Start the volttron-dnp3-outstation cli. If you follow along this demo, the agent vip-identity should be "dnp3_outstation".

   (env) kefei@ubuntu-22:~/sandbox/dnp3-agent-sandbox$ python -m vdnp3_outstation.run_volttron_dnp3_outstation_cli --agent-identity dnp3_outstation
   2023-03-23 11:51:25,975 root DEBUG: Creating ZMQ Core None
   2023-03-23 11:51:25,975 volttron.client.vip.agent.core DEBUG: address: ipc://@/home/kefei/.volttron/run/vip.socket
   2023-03-23 11:51:25,975 volttron.client.vip.agent.core DEBUG: identity: 08953498-18e6-4070-9576-521bad3e82be
   2023-03-23 11:51:25,975 volttron.client.vip.agent.core DEBUG: agent_uuid: None
   2023-03-23 11:51:25,975 volttron.client.vip.agent.core DEBUG: serverkey: None
   2023-03-23 11:51:25,976 volttron.client.vip.agent.core DEBUG:  environ keys: dict_keys(['SHELL', 'SESSION_MANAGER', 'QT_ACCESSIBILITY', 'COLORTERM', 'XDG_CONFIG_DIRS', 'SSH_AGENT_LAUNCHER', 'XDG_MENU_PREFIX', 'GNOME_DESKTOP_SESSION_ID', 'CONDA_EXE', '_CE_M', 'GNOME_SHELL_SESSION_MODE', 'SSH_AUTH_SOCK', 'HOMEBREW_PREFIX', 'XMODIFIERS', 'DESKTOP_SESSION', 'GTK_MODULES', 'PWD', 'LOGNAME', 'XDG_SESSION_DESKTOP', 'XDG_SESSION_TYPE', 'MANPATH', 'SYSTEMD_EXEC_PID', 'XAUTHORITY', 'VOLTTRON_HOME', 'HOME', 'USERNAME', 'IM_CONFIG_PHASE', 'LANG', 'LS_COLORS', 'XDG_CURRENT_DESKTOP', 'VIRTUAL_ENV', 'VTE_VERSION', 'WAYLAND_DISPLAY', 'GNOME_TERMINAL_SCREEN', 'INFOPATH', 'GNOME_SETUP_DISPLAY', 'LESSCLOSE', 'XDG_SESSION_CLASS', 'TERM', '_CE_CONDA', 'LESSOPEN', 'USER', 'HOMEBREW_CELLAR', 'GNOME_TERMINAL_SERVICE', 'CONDA_SHLVL', 'DISPLAY', 'SHLVL', 'QT_IM_MODULE', 'HOMEBREW_REPOSITORY', 'VIRTUAL_ENV_PROMPT', 'CONDA_PYTHON_EXE', 'XDG_RUNTIME_DIR', 'PS1', 'XDG_DATA_DIRS', 'PATH', 'GDMSESSION', 'DBUS_SESSION_BUS_ADDRESS', '_', 'RABBITMQ_NOT_AVAILABLE'])
   2023-03-23 11:51:25,976 volttron.client.vip.agent.core DEBUG: server key from env None
   2023-03-23 11:51:25,976 volttron.client.vip.agent.core DEBUG: AGENT RUNNING on ZMQ Core 08953498-18e6-4070-9576-521bad3e82be
   2023-03-23 11:51:25,976 volttron.client.vip.agent.core DEBUG: keys: server: _M0Ds3SfjECMrmXulHQZtPIlsYW7JwzXMXJH1Koy2T4 public: _M0Ds3SfjECMrmXulHQZtPIlsYW7JwzXMXJH1Koy2T4, secret: yfjc9g5znWMEjTSX3kfINGwhCvaDI80fK8vN76-C7SQ
   2023-03-23 11:51:25,977 volttron.client.vip.zmq_connection DEBUG: ZMQ connection 08953498-18e6-4070-9576-521bad3e82be
   2023-03-23 11:51:25,977 volttron.client.vip.zmq_connection DEBUG: connecting to url ipc://@/home/kefei/.volttron/run/vip.socket?publickey=_M0Ds3SfjECMrmXulHQZtPIlsYW7JwzXMXJH1Koy2T4&secretkey=yfjc9g5znWMEjTSX3kfINGwhCvaDI80fK8vN76-C7SQ&serverkey=_M0Ds3SfjECMrmXulHQZtPIlsYW7JwzXMXJH1Koy2T4
   2023-03-23 11:51:25,977 volttron.client.vip.zmq_connection DEBUG: url type is <class 'str'>
   2023-03-23 11:51:25,981 volttron.client.vip.agent.core INFO: Connected to platform: identity: 08953498-18e6-4070-9576-521bad3e82be version: 1.0
   2023-03-23 11:51:25,981 volttron.client.vip.agent.core DEBUG: Running onstart methods.
    
   ========================= MENU ==================================
   <ai> - set analog-input point value
   <ao> - set analog-output point value
   <bi> - set binary-input point value
   <bo> - set binary-output point value
    
   <dd> - display database
   <di> - display (outstation) info
   <cr> - config then restart outstation
   =================================================================
    
   !!!!!!!!! WARNING: The outstation is NOT connected !!!!!!!!!
   {'outstation_ip_str': '0.0.0.0', 'port': 20000, 'masterstation_id_int': 2, 'outstation_id_int': 1, 'peer': 'dnp3_outstation'}
    
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   

3. Start a dnp3 master to establish connection.

   If there is no connection between an outstation and a master, you may see the warning !!!!!!!!! WARNING: The outstation is NOT connected !!!!!!!!!. To establish such a connection, open another terminal, and run dnp3demo master. (More details about the "dnp3demo" module, please see dnp3demo-Module.md)

    ===== Master Operation MENU ==================================
    <ao> - set analog-output point value (for remote control)
    <bo> - set binary-output point value (for remote control)
    <dd> - display/polling (outstation) database
    <dc> - display configuration
    =================================================================
   
    
    ======== Your Input Here: ==(master)======
   

   Note: by default, both the volttron-dnp3-outstation and the dnp3demo master uses configurations to assure valid connection out-of-the-box. e.g., port=20000. Feel free to configure the connection parameters as desired.

4. Basic volttron-dnp3-outstation operations

   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   ai
   You chose <ai> - set analog-input point value
   Type in <float> and <index>. Separate with space, then hit ENTER. e.g., `1.4321, 1`.
   Type 'q', 'quit', 'exit' to main menu.
   
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   0.1212 0
   {'Analog': {0: 0.1212, 1: None, 2: None, 3: None, 4: None, 5: None, 6: None, 7: None, 8: None, 9: None}}
   You chose <ai> - update analog-input point value (for local reading)
   Type in <float> and <index>. Separate with space, then hit ENTER.
   Type 'q', 'quit', 'exit' to main menu.
   
   
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   1.2323 1
   {'Analog': {0: 0.1212, 1: 1.2323, 2: None, 3: None, 4: None, 5: None, 6: None, 7: None, 8: None, 9: None}}
   You chose <ai> - update analog-input point value (for local reading)
   Type in <float> and <index>. Separate with space, then hit ENTER.
   Type 'q', 'quit', 'exit' to main menu.
   

   Example of interaction with the `vdnp3_outstation` module

   (env) kefei@ubuntu-22:~/sandbox/dnp3-agent-sandbox$ python -m vdnp3_outstation.run_volttron_dnp3_outstation_cli --agent-identity dnp3_outstation
   dnp3demo.run_outstation {'command': 'outstation', 'outstation_ip=': '0.0.0.0', 'port=': 20000, 'master_id=': 2, 'outstation_id=': 1}
   ms(1678770551216) INFO    manager - Starting thread (0)
   2023-03-14 00:09:11,216	control_workflow_demo	INFO	Connection Config
   2023-03-14 00:09:11,216	control_workflow_demo	INFO	Connection Config
   2023-03-14 00:09:11,216	control_workflow_demo	INFO	Connection Config
   ms(1678770551216) INFO    server - Listening on: 0.0.0.0:20000
   2023-03-14 00:09:11,216	control_workflow_demo	DEBUG	Initialization complete. Outstation in command loop.
   2023-03-14 00:09:11,216	control_workflow_demo	DEBUG	Initialization complete. Outstation in command loop.
   2023-03-14 00:09:11,216	control_workflow_demo	DEBUG	Initialization complete. Outstation in command loop.
   Connection error.
   Connection Config {'outstation_ip_str': '0.0.0.0', 'port': 20000, 'masterstation_id_int': 2, 'outstation_id_int': 1}
   Start retry...
   Connection error.
   Connection Config {'outstation_ip_str': '0.0.0.0', 'port': 20000, 'masterstation_id_int': 2, 'outstation_id_int': 1}
   ms(1678770565247) INFO    server - Accepted connection from: 127.0.0.1
   ==== Outstation Operation MENU ==================================
   <ai> - update analog-input point value (for local reading)
   <ao> - update analog-output point value (for local control)
   <bi> - update binary-input point value (for local reading)
   <bo> - update binary-output point value (for local control)
   <dd> - display database
   <dc> - display configuration
   =================================================================
    
    
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   ai
   You chose <ai> - update analog-input point value (for local reading)
   Type in <float> and <index>. Separate with space, then hit ENTER.
   Type 'q', 'quit', 'exit' to main menu.
    
    
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   0.1212 0
   {'Analog': {0: 0.1212, 1: None, 2: None, 3: None, 4: None, 5: None, 6: None, 7: None, 8: None, 9: None}}
   You chose <ai> - update analog-input point value (for local reading)
   Type in <float> and <index>. Separate with space, then hit ENTER.
   Type 'q', 'quit', 'exit' to main menu.
    
    
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   1.2323 1
   {'Analog': {0: 0.1212, 1: 1.2323, 2: None, 3: None, 4: None, 5: None, 6: None, 7: None, 8: None, 9: None}}
   You chose <ai> - update analog-input point value (for local reading)
   Type in <float> and <index>. Separate with space, then hit ENTER.
   Type 'q', 'quit', 'exit' to main menu.
    
    
   ======== Your Input Here: ==(DNP3 OutStation Agent)======
   

Development

Please see the following for contributing guidelines contributing.

Please see the following helpful guide about developing modular VOLTTRON agents

Disclaimer Notice

This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.

Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.