UPS Agent
The UPS Agent is an OCS Agent which monitors various UPS models via SNMP.
usage: python3 agent.py [-h] [--address ADDRESS] [--port PORT]
[--snmp-version {1,2,3}] [--restart-time RESTART_TIME]
[--mode {acq,test}]
Agent Options
- --address
Address to listen to.
- --port
Port to listen on.
Default: 161
- --snmp-version
Possible choices: 1, 2, 3
SNMP version for communication. Must match configuration on the UPS.
Default: “1”
- --restart-time
Number of minutes before restarting agent.
Default: 0
- --mode
Possible choices: acq, test
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],
['--restart-time', 60]]},
Note
The --address
argument should be the address of the UPS on the network.
The --restart-time
argument should be set to number of minutes before
exiting the agent. Setting to 0 (default) will not exit the agent.
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”.
If not using HostManager, we must set restart: unless-stopped
to automatically restart the docker container.
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
- class socs.agents.ups.agent.UPSAgent(agent, address, port=161, version=1, restart_time=0)[source]
Monitor the UPS system via SNMP.
- Parameters:
agent (OCSAgent) – OCSAgent object which forms this Agent
address (str) – Address of the UPS.
port (int) – SNMP port to issue GETs to, default to 161.
version (int) – SNMP version for communication (1, 2, or 3), defaults to 3.
- agent
OCSAgent object which forms this Agent
- Type:
OCSAgent
- is_streaming
Tracks whether or not the agent is actively issuing SNMP GET commands to the UPS. Setting to false stops sending commands.
- Type:
bool
- log
txaio logger object, created by the OCSAgent
- Type:
txaio.tx.Logger
- acq()[source]
Process - Fetch values from the UPS via SNMP.
- Parameters:
test_mode (bool, optional) – Run the Process loop only once. Meant only for testing. Default is False.
Notes
The most recent data collected is stored in session.data in the structure:
>>> response.session['data'] {'upsIdentManufacturer': {'description': 'Falcon'}, 'upsIdentModel': {'description': 'SSG3KRM-2'}, 'upsBatteryStatus': {'status': 2, 'description': 'batteryNormal'}, 'upsSecondsOnBattery': {'status': 0, 'description': 0}, 'upsEstimatedMinutesRemaining': {'status': 60, 'description': 60}, 'upsEstimatedChargeRemaining': {'status': 100, 'description': 100}, 'upsBatteryVoltage': {'status': 120, 'description': 120}, 'upsBatteryCurrent': {'status': 10, 'description': 10}, 'upsBatteryTemperature': {'status': 30, 'description': 30}, 'upsOutputSource': {'status': 3, 'description': normal}, 'upsOutputVoltage': {'status': 120, 'description': 120}, 'upsOutputCurrent': {'status': 10, 'description': 10}, 'upsOutputPower': {'status': 120, 'description': 120}, 'upsOutputPercentLoad': {'status': 25, 'description': 25} 'upsInputVoltage': {'status': 120, 'description': 120}, 'upsInputCurrent': {'status': 10, 'description': 10}, 'upsInputTruePower': {'status': 120, 'description': 120}, 'ups_connection': {'last_attempt': 1656085022.680916, 'connected': True}, 'timestamp': 1656085022.680916}
Some relevant options and units for the above OIDs:
upsBatteryStatus:: Options:: unknown(1), batteryNormal(2), batteryLow(3), batteryDepleted(4) upsSecondsOnBattery:: Note:: Zero shall be returned if the unit is not on battery power. upsEstimatedChargeRemaining:: Units:: percentage upsBatteryVoltage:: Units:: 0.1 Volt DC upsBatteryCurrent:: Units:: 0.1 Amp DC upsBatteryTemperature:: Units:: degrees Centigrade upsOutputSource:: Options:: other(1), none(2), normal(3), bypass(4), battery(5), booster(6), reducer(7) upsOutputVoltage:: Units:: RMS Volts upsOutputCurrent:: Units:: 0.1 RMS Amp upsOutputPower:: Units:: Watts upsInputVoltage:: Units:: RMS Volts upsInputCurrent:: Units:: 0.1 RMS Amp upsInputTruePower:: Units:: Watts
Supporting APIs
- class socs.agents.ups.agent.update_cache(get_result, timestamp)[source]
Update the OID Value Cache.
The OID Value Cache is used to store each unique OID and will be passed to session.data
The cache consists of a dictionary, with the unique OIDs as keys, and another dictionary as the value. Each of these nested dictionaries contains the OID values, name, and description (decoded string). An example for a single OID:
{"upsBatteryStatus": {"status": 2, "description": "batteryNormal"}}
Additionally there is connection status and timestamp information under:
{"ups_connection": {"last_attempt": 1598543359.6326838, "connected": True} {"timestamp": 1656085022.680916}
- Parameters:
get_result (pysnmp.smi.rfc1902.ObjectType) – Result from a pysnmp GET command.
timestamp (float) – Timestamp for when the SNMP GET was issued.