Merge pull request #408 from simonsobs/develop

v0.4.1

.flake8

@@ -15,6 +15,7 @@ exclude =
     socs/mibs/SNMPv2-MIB.py,
     socs/mibs/MBG-SNMP-ROOT-MIB.py,
     socs/mibs/IBOOTPDU-MIB.py,
+    socs/mibs/UPS-MIB.py,
     versioneer.py,
     docs/conf.py,
 per-file-ignores =

.github/workflows/deploy.yml

@@ -3,6 +3,12 @@ name: Deploy Builds
 on:
   release:
     types: [ released ]
+  push:
+    tags:
+      # v0.X.Y pre-release tags
+      - 'v0.*.*a*'
+      - 'v0.*.*b*'
+      - 'v0.*.*rc*'
 
 jobs:
   test:

.github/workflows/pytest.yml

@@ -65,7 +65,7 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
         mv ./tests/.coverage.* ./
-        pip install coveralls
+        pip install -U coveralls
         coverage combine
         coverage report
         coveralls --service=github

.pre-commit-config.yaml

@@ -1,21 +1,21 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
     -   id: check-ast
     -   id: check-yaml
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
     - id: isort
       name: isort (python)
 -   repo: https://github.com/pre-commit/mirrors-autopep8
-    rev: v2.0.0
+    rev: v2.0.1
     hooks:
     -   id: autopep8
 -   repo: https://github.com/pycqa/flake8
-    rev: 5.0.4
+    rev: 6.0.0
     hooks:
     -   id: flake8

CONTRIBUTING.rst

@@ -29,7 +29,12 @@ Releases
 
     **Note:** Releases will be issued by core maintainers of SOCS.
 
-If you are trying to issue a release of SOCS you should follow these steps:
+Before making an official release, test the release properly builds and
+publishes with a pre-release. You can do so by pushing a tag matching
+``v0.*.*a*``, ``v0.*.*b*``, or ``v0.*.*rc*``.
+
+Once the release looks good, publish the official release by following these
+steps:
 
 1. Open a Pull Request, comparing ``develop`` to the ``master`` base branch.
    Describe the features added for this release.

Dockerfile

@@ -2,7 +2,7 @@
 # A container setup with an installation of socs.
 
 # Use the ocs image as a base
-FROM simonsobs/ocs:v0.10.0
+FROM simonsobs/ocs:v0.10.1
 
 # Set up the cryo/smurf user and group so this can run on smurf-servers
 # See link for how all other smurf-containers are set up:

README.rst

@@ -2,7 +2,7 @@
 SOCS - Simons Observatory Control System
 ========================================
 
-.. image:: https://img.shields.io/github/workflow/status/simonsobs/socs/Build%20Develop%20Images
+.. image:: https://img.shields.io/github/actions/workflow/status/simonsobs/socs/develop.yml?branch=develop
     :target: https://github.com/simonsobs/socs/actions?query=workflow%3A%22Build+Develop+Images%22
     :alt: GitHub Workflow Status
 
@@ -44,7 +44,7 @@ Install and update with pip::
 You may install optional dependencies by including one or more agent group
 names on installation, for example::
 
-    $ pip3 install -U socs[labjack,pysmurf]
+    $ pip3 install -U socs[labjack,synacc]
 
 For a complete list of agent groups see the `Installation Documentation`_.
 
@@ -53,6 +53,9 @@ If you would like to install all optional dependencies use the special varient
 
     $ pip3 install -U socs[all]
 
+**Note:** Not all optional dependencies can be installed this way. See the
+`Installation Documentation`_ for more info on specific agent dependencies.
+
 .. _`Installation Documentation`: https://socs.readthedocs.io/en/develop/user/installation.html
 
 Installing from Source

docker/pysmurf_controller/Dockerfile

@@ -1,11 +1,11 @@
-FROM simonsobs/sodetlib:v0.4.1
-
-WORKDIR /app
+FROM simonsobs/sodetlib:v0.5.0-2-g0f91202
 
 ENV OCS_CONFIG_DIR /config
 
+ENV PYTHONUNBUFFERED=1
+
 # SOCS installation
-RUN python3 -m pip install --src=/app/ -e git+https://github.com/simonsobs/socs.git@py36#egg=socs
+RUN python3 -m pip install git+https://github.com/simonsobs/socs.git@develop
 
 RUN pip3 install dumb-init
 

docs/agents/acu_agent.rst

@@ -15,10 +15,16 @@ platforms.
     :func: add_agent_args
     :prog: python3 agent.py
 
+.. _acu_deps:
+
 Dependencies
 ------------
 The `soaculib <https://github.com/simonsobs/soaculib>`_ package must be
-installed to use this Agent.
+installed to use this Agent. This can be installed via:
+
+.. code-block:: bash
+
+    $ pip install 'soaculib @ git+https://github.com/simonsobs/soaculib.git@master'
 
 Configuration File Examples
 ---------------------------

docs/agents/bluefors_agent.rst

@@ -45,11 +45,11 @@ Example docker-compose configuration::
     hostname: ocs-docker
     network_mode: "host"
     environment:
-      INSTANCE_ID: bluefors
-      LOGLEVEL: info
-      FRAME_LENGTH: 600
-      STALE_TIME: 2
-      MODE: follow
+      - INSTANCE_ID=bluefors
+      - LOGLEVEL=info
+      - FRAME_LENGTH=600
+      - STALE_TIME=2
+      - MODE=follow
     volumes:
       - ${OCS_CONFIG_DIR}:/config:ro
       - /home/simonsobs/bluefors/logs/:/logs:ro

docs/agents/holo_fpga.rst

@@ -15,6 +15,8 @@ ROACH via an ethernet port, take data, and pass it to the OCS feed.
    :func: make_parser
    :prog: python3 agent.py
 
+.. _holo_fpga_deps:
+
 Dependencies
 ------------
 
@@ -31,9 +33,10 @@ You can install these by first checking you are running Python 3.8::
     $ python --version
     Python 3.8.13
 
-Then by either installing via the optional dependency "holography"::
+Then by either installing via pip::
 
-    $ python -m pip install socs[holography]
+    $ python -m pip install 'casperfpga @ git+https://github.com/casper-astro/casperfpga.git@py38'
+    $ python -m pip install 'holog_daq @ git+https://github.com/McMahonCosmologyGroup/holog_daq.git@main'
 
 Or by cloning the socs repository and using the provided requirements file::
 

docs/agents/holo_synth.rst

@@ -18,6 +18,8 @@ OCS feed.
    :func: make_parser
    :prog: python3 agent.py
 
+.. _holo_synth_deps:
+
 Dependencies
 ------------
 
@@ -36,9 +38,9 @@ You can install these by first checking you are running Python 3.8::
     $ python --version
     Python 3.8.13
 
-Then by either installing via the optional dependency "holography"::
+Then by either installing via pip::
 
-    $ python -m pip install socs[holography]
+    $ python -m pip install 'holog_daq @ git+https://github.com/McMahonCosmologyGroup/holog_daq.git@main'
 
 Or by cloning the socs repository and using the provided requirements file::
 

docs/agents/latrt_xy_stage.rst

@@ -19,6 +19,18 @@ their drivers are shared `here
     :func: make_parser
     :prog: python3 agent.py
 
+.. _latrt_xy_stage_deps:
+
+Dependencies
+------------
+
+The LATRt XY Stage agent requires the `xy_stage_control
+<https://github.com/kmharrington/xy_stage_control>`_ module. This can be
+installed via pip:
+
+.. code-block:: bash
+
+    $ python -m pip install 'xy_stage_control @ git+https://github.com/kmharrington/xy_stage_control.git@main'
 
 Configuration File Examples
 ---------------------------

docs/agents/magpie.rst

@@ -46,6 +46,7 @@ a detmap csv file, with a target sample rate of 20 Hz::
          # Detmap CSV file
          '--det-map', '/home/jlashner/lyrebird_demo/detmap.csv',
          '--offset', 0, 0,
+         '--rotation', 0,
          '--demod-freq', 8,
          '--demod-bandwidth', 0.5
        ]},

docs/agents/pysmurf-controller.rst

@@ -14,6 +14,25 @@ sodetlib control scripts on the smurf-server through an OCS client.
     :func: make_parser
     :prog: python3 agent.py
 
+.. _pysmurf_controller_deps:
+
+Dependencies
+------------
+
+The pysmurf controller requires the following packages:
+
+    - `pysmurf <https://github.com/slaclab/pysmurf>`_
+    - `sodetlib <https://github.com/simonsobs/sodetlib>`_
+    - `sotodlib <https://github.com/simonsobs/sotodlib>`_
+
+These can be installed via pip:
+
+.. code-block:: bash
+
+    $ python -m pip install 'pysmurf @ git+https://github.com/slaclab/pysmurf.git@main'
+    $ python -m pip install 'sodetlib @ git+https://github.com/simonsobs/sodetlib.git@master'
+    $ python -m pip install 'sotodlib @ git+https://github.com/simonsobs/sotodlib.git@master'
+
 Configuration File Examples
 -----------------------------------
 
@@ -50,17 +69,17 @@ named ``ocs-pysmurf-monitor`` might look something like::
         security_opt:
             - "aparmor=docker-smurf"
         environment:
-            INSTANCE_ID=pysmurf-controller-s2
-            SITE_HUB=ws://${CB_HOST}:8001/ws
-            SITE_HTTP=ws://${CB_HOST}:8001/call
-            SMURFPUB_BACKEND: udp
-            SMURFPUB_ID: crate1slot2
-            SMURFPUB_UDP_HOST: ocs-pysmurf-monitor
-            DISPLAY: $DISPLAY
-            OCS_CONFIG_DIR: /config
-            EPICS_CA_ADDR_LIST: 127.255.255.255
-            EPICS_CA_MAX_ARRAY_BYTES: 80000000
-            SLOT: 2
+            - INSTANCE_ID=pysmurf-controller-s2
+            - SITE_HUB=ws://${CB_HOST}:8001/ws
+            - SITE_HTTP=ws://${CB_HOST}:8001/call
+            - SMURFPUB_BACKEND=udp
+            - SMURFPUB_ID=crate1slot2
+            - SMURFPUB_UDP_HOST=ocs-pysmurf-monitor
+            - DISPLAY
+            - OCS_CONFIG_DIR=/config
+            - EPICS_CA_ADDR_LIST=127.255.255.255
+            - EPICS_CA_MAX_ARRAY_BYTES=80000000
+            - SLOT=2
         volumes:
             - ${OCS_CONFIG_DIR}:/config
             - /data:/data

docs/agents/ups.rst

@@ -0,0 +1,104 @@
+.. highlight:: rst
+
+.. _ups:
+
+====================
+UPS Agent
+====================
+
+The UPS Agent is an OCS Agent which monitors various UPS models via SNMP.
+
+.. argparse::
+    :filename: ../socs/agents/ups/agent.py
+    :func: add_agent_args
+    :prog: python3 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
+```````````````
+
+To configure the UPS Agent we need to add a UPSAgent
+block to our ocs configuration file. Here is an example configuration block
+using all of the available arguments::
+
+      {'agent-class': 'UPSAgent',
+       'instance-id': 'ups',
+       'arguments': [['--address', '10.10.10.50'],
+                     ['--port', 161],
+                     ['--mode', 'acq'],
+                     ['--snmp-version', 1]]},
+
+.. note::
+    The ``--address`` argument should be the address of the UPS on the network.
+
+Docker Compose
+``````````````
+
+The UPS Agent should be configured to run in a Docker container. An
+example docker-compose service configuration is shown here::
+
+  ocs-ups:
+    image: simonsobs/socs:latest
+    hostname: ocs-docker
+    network_mode: "host"
+    volumes:
+      - ${OCS_CONFIG_DIR}:/config:ro
+    environment:
+      - INSTANCE_ID=ups
+      - SITE_HUB=ws://127.0.0.1:8001/ws
+      - SITE_HTTP=http://127.0.0.1:8001/call
+      - LOGLEVEL=info
+
+
+The ``LOGLEVEL`` environment variable can be used to set the log level for
+debugging. The default level is "info".
+
+Description
+-----------
+
+Various UPS models will be used to power various components on the SO site.
+The UPS Agent allows the monitoring of a UPS model. It provides information
+on the manufacturer and model of the UPS. It monitors the state of each
+output, as well as several stats of the battery. The UPS has an Simple Network
+Management Protocol (SNMP) interface. The agent has been tested on the
+following Falcon models: SSG3K-2T, SSG3KRM-2. These models require a SNMP
+interface add-on card to be installed.
+
+The UPS Agent actively issues SNMP GET commands to request the status from
+several Object Identifiers (OIDs) specified by the provided Management
+Information Base (MIB). We sample only a subset of the OIDs defined by the MIB.
+The MIB has been converted from the original .mib format to a .py format that
+is consumable via pysnmp and is provided by socs.
+
+Agent Fields
+````````````
+
+The fields returned by the Agent are built from the SNMP GET responses from the
+UPS. The field names consist of the OID name and the last value of the OID,
+which often serves as an index for duplicate pieces of hardware that share a
+OID string, i.e. outputs on the OID "upsOutputVoltage". This results in field
+names such as "upsOutputVoltage_0" and "upsOutputVoltage_1".
+
+These queries mostly return integers which map to some state. These integers
+get decoded into their corresponding string representations and stored in the
+OCS Agent Process' session.data object. For more details on this structure, see
+the Agent API below. For information about the states corresponding to these
+values, refer to the MIB file.
+
+Agent API
+---------
+
+.. autoclass:: socs.agents.ups.agent.UPSAgent
+    :members:
+
+Supporting APIs
+---------------
+
+.. autoclass:: socs.agents.ups.agent.update_cache
+    :members:
+    :noindex:

docs/index.rst

@@ -66,6 +66,7 @@ API Reference        Full API documentation for core parts of the SOCS library.
     agents/synacc
     agents/tektronix3021c
     agents/thorlabs_mc2000b
+    agents/ups
     agents/vantage_pro2
     agents/wiregrid_actuator
     agents/wiregrid_encoder