Meinberg M1000 Agent

The Meinberg M1000 Agent is an OCS Agent which monitors the Meinberg M1000, the main source of timing for the SO site. Monitoring is performed via SNMP.

usage: python3 agent.py [-h] [--auto-start AUTO_START] [--address ADDRESS]
                        [--port PORT] [--snmp-version {1,2,3}]

Agent Options

--auto-start

Automatically start polling for data at Agent startup.

Default: True

--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 M1000.

Default: “3”

Description

The Meinberg M1000 is a critical piece of hardware, it provides the precise timing information distributed among the SO site. The M1000 synchronizes to GPS and distributes timing mostly over the network using PTP. The M1000 has an Simple Network Management Protocol (SNMP) interface, allowing one to monitor the state of the device.

The Meinberg M1000 Agent actively issues SNMP GET commands to request the status from several Object Identifiers (OIDs) specified by the Meinberg provided Management Information Base (MIB). We sample only a subset of the OIDs defined by the MIB, following recommendations from the M1000 manual. This 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 M1000. 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. redundant power supplies on the OID “mbgLtNgSysPsStatus”. This results in field names such as “mbgLtNgSysPsStatus_0” and “mbgLtNgSysPsStatus_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 we refer to the M1000 manual.

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 Meinberg M1000 Agent we need to add a MeinbergM1000Agent block to our ocs configuration file. Here is an example configuration block using all of the available arguments:

{'agent-class': 'MeinbergM1000Agent',
 'instance-id': 'meinberg-m1000',
 'arguments': [['--address', '10.10.10.101'],
               ['--port', 161],
               ['--auto-start', True],
               ['--snmp-version', 3]]},

Note

The --address argument should be the address of the M1000 on the network. This is the main network interface for the device, not the PTP interface, which is different.

Docker Compose

The Meinberg M1000 Agent should be configured to run in a Docker container. An example docker-compose service configuration is shown here:

ocs-m1000:
  image: simonsobs/socs:latest
  hostname: ocs-docker
  network_mode: "host"
  volumes:
    - ${OCS_CONFIG_DIR}:/config:ro
  environment:
    - INSTANCE_ID=meinberg-m1000
    - SITE_HUB=ws://10.10.10.2:8001/ws
    - SITE_HTTP=http://10.10.10.2:8001/call
    - LOGLEVEL=info

The LOGLEVEL environment variable can be used to set the log level for debugging. The default level is “info”.

Agent API

class socs.agents.meinberg_m1000.agent.MeinbergM1000Agent(agent, address, port=161, version=3)[source]

Monitor the Meinberg LANTIME M1000 timing system via SNMP.

Parameters:

agent (OCSAgent) – OCSAgent object which forms this Agent
address (str) – Address of the M1000.
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 M1000. 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 M1000 via SNMP.

Notes

The session.data object stores each unique OID with its latest status, decoded value, and the last time the value was retrived. This will look like the example here:

>>> response.session['data']
{"mbgLtNgRefclockLeapSecondDate_1":
    {"status": "not announced",
     "lastGet":1598626144.5365012},
 "mbgLtNgPtpPortState_1":
    {"status": 3,
     "description": "disabled",
     "lastGet": 1598543397.689727},
 "mbgLtNgNtpCurrentState_0":
    {"status": 1,
     "description": "not synchronized",
     "lastGet": 1598543363.289597},
 "mbgLtNgRefclockState_1":
    {"status": 2,
     "description": "not synchronized",
     "lastGet": 1598543359.6326838},
 "mbgLtNgSysPsStatus_1":
    {"status": 2,
     "description": "up",
     "lastGet": 1598543359.6326838},
 "mbgLtNgSysPsStatus_2":
    {"status": 2,
     "description": "up",
     "lastGet": 1598543359.6326838},
 "mbgLtNgEthPortLinkState_1":
    {"status": 1,
     "description": "up",
     "lastGet": 1598543359.6326838}
 "m1000_connection":
    {"last_attempt": 1598543359.6326838,
     "connected": True}}

Note that session.data is populated within the MeinbergSNMP.run_snmp_get() call.

Supporting APIs

class socs.agents.meinberg_m1000.agent.MeinbergSNMP(address, port=161, version=3)[source]

Meinberg SNMP communicator. Handles communication with and decoding of values from the Meinberg M1000.

Parameters:

address (str) – Address of the M1000.
port (int) – SNMP port to issue GETs to, default to 161.
version (int) – SNMP version for communication (1, 2, or 3), defaults to 3.

address

Address of the M1000.

Type:: str

port

SNMP port to issue GETs to.

Type:: int

snmp

snmp handler from SOCS

Type:: socs.snmp.SNMPTwister

mib_timings

list of dicts describing the SNMP OIDs to check, and at which intervals. Each dict contains the keys “oid”, “interval”, and “lastGet”. The corresponding values are of types tuple, integer, and float, respectively. “lastGet” is initialized as None, since no SNMP GET commands have been issued.

Type:: list

oid_cache

Cache of OID values and corresponding decoded values. Meant to be passed directly to session.data.

Type:: dict

update_cache(get_result, timestamp)[source]

Update the OID Value Cache.

The OID Value Cache is used to store each unique OID, the latest value, the associated decoded string, and the last time the OID was queried from the M1000.

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, description (decoded string), and last query time. An example for a single OID:

{"mbgLtNgPtpPortState_1":
    {"status": 3,
     "description": "disabled",
     "lastGet": 1598543397.689727}}

Additionally there is connection status information under:

{"m1000_connection":
    {"last_attempt": 1598543359.6326838,
    "connected": True}

This method modifies self.oid_cache.

Parameters:

get_result (pysnmp.smi.rfc1902.ObjectType) – Result from a pysnmp GET command.
timestamp (float) – Timestamp for when the SNMP GET was issued.

run_snmp_get(session)[source]

Peform the main data acquisition steps, issuing SNMP GET commands for each OID, depending on when we last queried them.

These steps are performed for each group of OIDs in the same timing interval. We first build a list of OIDs to query. We then query them, update the local cache which is passed to the session.data object, build an OCS formatted message, and publish that message on the OCS Feed.

If no OID should be queried yet we continue, expecting the Agent to handle any waiting that should be done between queries.