Changes to allow for reading more than one continuous block of resgis… (

#473)

* Changes to allow for reading more than one continuous block of resgisters at a time
Support reading of bit or bit range within individual registers needed for reading i.e. alarm conditions from the generator controller
Configuration file loading switched to read an entire directory of .yaml files at a time

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Replaced lambda function definitions in favor of real function definitions
in order to satisify flake8 pre-commit.ci tests.
Manual merge executed.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Better documentation

Added a configuration section to generator.rst
Added sample configuration files in sample_configs directory.
Sample interval is now an argument to the agent.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Small changes to docs formatting and args

---------

Co-authored-by: David Boettger <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: jlashner <[email protected]>

docs/agents/generator.rst

@@ -29,13 +29,18 @@ using all of the available arguments::
       {'agent-class': 'GeneratorAgent',
        'instance-id': 'generator',
        'arguments': [['--host', '192.168.2.88'],
-                     ['--port', 502],
+                     ['--port', 5021],
                      ['--mode', 'acq'],
-                     ['--read-config', '/home/ocs/CONFIG/ocs/generator-config.yaml']]}
+                     ['--configdir', 'G1_config'],
+                     ['--sample-interval', 10]
+                     ]}
 
 .. note::
     The ``--host`` argument should be the IP address of the generator on the network.
 
+    The '--configdir' argument specifies a directory name for configuration files
+    relative to the $OCS_CONFIG_DIR environment variable.
+
 Docker Compose
 ``````````````
 
@@ -59,24 +64,80 @@ The ``LOGLEVEL`` environment variable can be used to set the log level for
 debugging. The default level is "info".
 
 Description
------------
+```````````
 
 On-site generators will be used to provide power to the SO site.
-Each generator have the same controller/interface, the Deep Sea Electronics (DSE)
+Each generator has the same controller/interface, the Deep Sea Electronics (DSE)
 8610 mark II. The Generator Agent allows the monitoring of each generator controller
 via Modbus. It queries registers and publishes data in an acquisition process. The
 agent has been tested with on-site generators.
 
-The Generator Agent requires a config file which contains information on all
-possible registers that it may query from the generator controller. The config file
-also sets the amount of registers we want to query in the acquisition process.
+The Generator Agent requires a configuration directory which contains information on all
+registers that it queries from the generator controller.
 
 Agent Fields
 ````````````
-
 The fields consist of the register name and the last value, which are necessarily
 formatted depending on the register.
 
+Configuration
+`````````````
+A direcotry of .yaml configuration files is one of the arguments to the agent.
+A single .yaml file specifies meta-data about a continuous block of registers to
+read. The agent will interpret all .yaml files in the specified directory as
+specifications of register blocks.
+
+A single .yaml file must contain keys that specify which registers to read and
+how to interpret the data contained in those registers. The key 'read_start' or
+'page' must be specified, where 'read_start' is the register offset to begin reading
+at, and 'page' is a shorthand for read_start = 256 * page because the DSE GenComm
+documentation lists all registers as an offset from their page number. If both keys
+are specified, 'read_start' is given preference.
+
+The configuration file must also specify 'read_len', which is how many registers to read
+beyond the 'read_start' value.
+
+The 'registers' key contains a dictionary with information about how to interpret the data
+contained in the registers that are read. There is no requirement to read all registers
+returned in the block, and the same registers can be interpreted by multiple entries in
+the 'registers' key.
+
+An example 'registers' entry is contained below::
+
+  Engine_fuel_level:
+    max_val: 130.0
+    min_val: 0.0
+    offset: 3
+    read_as: 16U
+    scale: 1.0
+    units: '%'
+
+They key for each register entry is a description of what information the register contains.
+The sub-keys 'offset', 'read_as', 'scale', and 'units' are required entries, but 'max_val' and
+'min_val' are optional.
+
+read_as must be one of 16U, 16S, 32U, 32S, or bin. These specify how the data in the register
+contained at the specified offset should be interpereted: 16 bit unsigned (16U), 16 bit signed (16S),
+32 bit unsigned (32U), 32 bit signed (32S) or binary (bin). When the 32 bit data types are used, it is
+implied that the register one byond the specified offset is also being read because each register is
+only 16 bits long. In this case binary corresponds to reading a value from an individual bit or range of
+bits within a single 16 bit register. A single bit can be read by specifying i.e. 'bin 2' which would
+correspond to reading the second most significant bit out of the register, and a range can be specified
+by i.e. 'bin 5-8'. The values specified by 'bin' are one-indexed, following the GenComm documentation
+specifications. An example of reading different binary values out of the same register follows::
+
+  Alarm_emergency_stop:
+    offset: 1
+    read_as: bin 13-16
+    units: None
+  Alarm_low_oil_pressure:
+    offset: 1
+    read_as: bin 9-12
+    units: None
+
+Finally, the file must specify the 'block_name' key which is a description of what the continuous
+block of registers contains.
+
 Agent API
 ---------