Add agent for the Lightning Detector (#640)

* Adding agent for the Lightning Detector

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

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

* Removed unused yaml library from code

* replaced match function to comply with python3.8

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

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

* Added modifications suggested by Brian Koopman

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

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

* another set of minor corrections after BK's review

* final changes after PR review

* removed unused docstrings

* Function name modifications on agent, added .rst

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

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

* Move rst file into docs directory

* Add docs page to index

* Fix build warnings and format docs

* fixed bug when reading lightning strike sentences

---------

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

docs/agents/ld_monitor.rst

@@ -0,0 +1,84 @@
+.. highlight:: rst
+
+========================
+Lightning Detector Agent
+========================
+
+The lightning detector agent communicates with the Lightning Detector System at
+the site and parses the data to obtain approximate lightning strike distances
+and standardized alarm levels.
+
+.. argparse::
+   :module: socs.agents.ld_monitor.agent
+   :func: make_parser
+   :prog: agent.py
+
+Configuration File Examples
+---------------------------
+
+Below are configuration examples for the ocs config file and for running the
+Agent in a docker container.
+
+OCS Site Config
+````````````````
+
+An example site-config-file block::
+
+    {'agent-class': 'LDMonitorAgent',
+     'instance-id': 'ld_monitor',
+     'arguments': [['--mode', 'acq']},
+
+Docker Compose
+``````````````
+
+An example docker-compose configuration::
+
+    ocs-template:
+        image: simonsobs/socs:latest
+        hostname: ocs-docker
+        environment:
+          - LOGLEVEL=info
+        volumes:
+          - ${OCS_CONFIG_DIR}:/config
+
+Description
+-----------
+
+The Lightning Detector System is connnected through serial communication with a
+dedicated PC at the site, in which a propietary application calculates
+approximate lightning strike distances and adjusts alarm levels accordingly.
+Data is parsed and the most important parameters are updated. The dedicated PC
+is continously running a script that streams the data via UDP to the client.
+
+Transmitted Data
+````````````````
+
+The lightning detector transmits its data in "sentences". There are 5 types of
+expected sentences:
+
+* electric field
+* lightning strike
+* high-field
+* status
+* alarm timers
+
+Electric field sentences report the electric field value measured by the
+Electric Field Mill in kV/m. Strike sentences include lightning strike distance
+and units (meters or miles) and is only transmitted if a strike is detected.
+High field sentences report an alarm status with respect to set thresholds of
+electric field. Status sentences include data such as alarms (red, orange,
+yellow), remaining timers, all clear status, fault codes, among others. Alarm
+timers sentences are disregarded, as its information is redundant. Each of the
+sentences' data are parsed and published to the feed.
+
+Agent API
+---------
+
+.. autoclass:: socs.agents.ld_monitor.agent.LDMonitorAgent
+    :members:
+
+Supporting APIs
+---------------
+
+.. autoclass:: socs.agents.ld_monitor.agent.LDMonitor
+    :members:

docs/index.rst

@@ -62,6 +62,7 @@ API Reference        Full API documentation for core parts of the SOCS library.
     agents/lakeshore372
     agents/lakeshore425
     agents/latrt_xy_stage
+    agents/ld_monitor
     agents/magpie
     agents/meinberg_m1000_agent
     agents/meinberg_syncbox_agent