Meinberg Syncbox Agent

The Meinberg Syncbox Agent is an OCS Agent which monitors the Meinberg syncbox, the Monitoring is performed via SNMP.

usage: python3 agent.py [-h] [--address ADDRESS] [--port PORT]
                        [--snmp-version {1,2,3}] [--mode {acq,test}]
                        [--outputs OUTPUTS [OUTPUTS ...]]
                        [--sample-period SAMPLE_PERIOD]

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

Default: “1”

--mode

Possible choices: acq, test

Default: “acq”

--outputs

Syncbox outputs to monitor. Defaults to [1,2,3].

Default: [1, 2, 3]

--sample-period

Acq sample period in seconds. Defaults to 10.

Default: 10

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

{'agent-class': 'MeinbergSyncboxAgent',
 'instance-id': 'timing-syncbox',
 'arguments': [['--address', '192.168.2.166'],
               ['--port', 161],
               ['--mode', 'acq'],
               ['--snmp-version', 1],
               ['--outputs', [1, 2, 3]],
               ['--sample-period', 10]]},

Note

The --address argument should be the address of the syncbox on the network. This is not the main Meinberg M1000 device. The --outputs argument can be any of the available 3 outputs. The --sample-period argument is the number of seconds between sampling data.

Docker Compose

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

ocs-timing-syncbox:
  image: simonsobs/socs:latest
  hostname: ocs-docker
  network_mode: "host"
  volumes:
    - ${OCS_CONFIG_DIR}:/config:ro
  environment:
    - INSTANCE_ID=timing-syncbox
    - 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

The Meinberg syncbox synchronizes to the M1000 from PTP and distributes signal to attached devices in various formats (IRIG, PPS, etc).

The Meinberg Syncbox Agent actively issues SNMP GET commands to request the status from several Object Identifiers (OIDs) specified by the syncbox provided Management Information Base (MIB). 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 syncbox. 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 outputs on the OID “mbgSyncboxN2XOutputMode”. This results in field names such as “mbgSyncboxN2XOutputMode_1” and “mbgSyncboxN2XOutputMode_2”.

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.meinberg_syncbox.agent.MeinbergSyncboxAgent(agent, address, port=161, version=1, outputs=[1, 2, 3], sample_period=10)[source]

Monitor the syncbox system via SNMP.

Parameters:

agent (OCSAgent) – OCSAgent object which forms this Agent
address (str) – Address of the syncbox.
port (int) – SNMP port to issue GETs to, default to 161.
version (int) – SNMP version for communication (1, 2, or 3), defaults to 1.
outputs (list of ints) – List of outputs to monitor.

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 syncbox. 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 syncbox 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']
{'mbgSyncboxN2XSerialNumber_0':
    {'status': '009811006890',
     'description': '009811006890'},
'mbgSyncboxN2XFirmwareRevision_0':
    {'status': '1.20 ',
     'description': '1.20 '},
'mbgSyncboxN2XSystemTime_0':
    {'status': '2023-10-28 14:25:54 UTC',
     'description': '2023-10-28 14:25:54 UTC'},
'mbgSyncboxN2XCurrentRefSource_0':
    {'status': 'PTP',
     'description': 'PTP'},
'mbgSyncboxN2XPtpProfile_0':
    {'status': 0,
     'description': 'none'},
'mbgSyncboxN2XPtpNwProt_0':
    {'status': 1,
     'description': 'ipv4'},
'mbgSyncboxN2XPtpPortState_0':
    {'status': 9,
     'description': 'slave'},
'mbgSyncboxN2XPtpDelayMechanism_0':
    {'status': 0,
     'description': 'e2e'},
'mbgSyncboxN2XPtpDelayRequestInterval_0':
    {'status': 1,
     'description': '1'},
'mbgSyncboxN2XPtpTimescale_0':
    {'status': 0,
     'description': 'tai'},
'mbgSyncboxN2XPtpUTCOffset_0':
    {'status': '37 sec',
     'description': '37 sec'},
'mbgSyncboxN2XPtpUTCOffset_0_value':
    {'status': 37000000,
     'description': '37 sec'},
'mbgSyncboxN2XPtpLeapSecondAnnounced_0':
    {'status': 'no',
     'description': 'no'},
'mbgSyncboxN2XPtpGrandmasterClockID_0':
    {'status': 'EC:46:70:FF:FE:0A:AB:FE',
     'description': 'EC:46:70:FF:FE:0A:AB:FE'},
'mbgSyncboxN2XPtpGrandmasterTimesource_0':
    {'status': 32,
     'description': 'gps'},
'mbgSyncboxN2XPtpGrandmasterPriority1_0':
    {'status': 64,
     'description': '64'},
'mbgSyncboxN2XPtpGrandmasterClockClass_0':
    {'status': 6,
     'description': '6'},
'mbgSyncboxN2XPtpGrandmasterClockAccuracy_0':
    {'status': 33, 'description':
     'accurateToWithin100ns'},
'mbgSyncboxN2XPtpGrandmasterClockVariance_0':
    {'status': 13563,
     'description': '13563'},
'mbgSyncboxN2XPtpOffsetToGrandmaster_0':
    {'status': '10 ns',
     'description': '10 ns'},
'mbgSyncboxN2XPtpOffsetToGrandmaster_0_value':
    {'status': 0.01,
     'description': '10 ns'},
'mbgSyncboxN2XPtpMeanPathDelay_0':
    {'status': '875 ns',
     'description': '875 ns'},
'mbgSyncboxN2XPtpMeanPathDelay_0_value':
    {'status': 0.875,
     'description': '875 ns'},
'mbgSyncboxN2XOutputMode_1':
    {'status': 4,
     'description': 'pulsePerSecond'},
 'syncbox_connection':
    {'last_attempt': 1656085022.680916,
     'connected': True},
 'timestamp': 1656085022.680916,
 'address': '10.10.10.50'}

Some relevant options and units for the above OIDs:

mbgSyncboxN2XPtpProfile::
    Options:: none(0),
              power(1),
              telecom(2)
mbgSyncboxN2XPtpNwProt::
    Options:: unknown(0),
              ipv4(1),
              ipv6(2),
              ieee802-3(3),
              deviceNet(4),
              controlNet(5),
              profiNet(6)
mbgSyncboxN2XPtpPortState::
    Options:: uninitialized(0),
              initializing(1),
              faulty(2),
              disabled(3),
              listening(4),
              preMaster(5),
              master(6),
              passive(7),
              uncalibrated(8),
              slave(9)
mbgSyncboxN2XPtpDelayMechanism::
    Options:: e2e(0),
              p2p(1)
mbgSyncboxN2XPtpTimescale::
    Options:: tai(0),
              arb(1)
mbgSyncboxN2XPtpGrandmasterTimesource::
    Options:: atomicClock(16),
              gps(32),
              terrestrialRadio(48),
              ptp(64),
              ntp(80),
              handSet(96),
              other(144),
              internalOscillator(160)
mbgSyncboxN2XPtpGrandmasterClockAccuracy::
    Options:: accurateToWithin25ns(32),
              accurateToWithin100ns(33),
              accurateToWithin250ns(34),
              accurateToWithin1us(35),
              accurateToWithin2Point5us(36),
              accurateToWithin10us(37),
              accurateToWithin25us(38),
              accurateToWithin100us(39),
              accurateToWithin250us(40),
              accurateToWithin1ms(41),
              accurateToWithin2Point5ms(42),
              accurateToWithin10ms(43),
              accurateToWithin25ms(44),
              accurateToWithin100ms(45),
              accurateToWithin250ms(46),
              accurateToWithin1s(47),
              accurateToWithin10s(48),
              accurateToGreaterThan10s(49)
mbgSyncboxN2XPtpUTCOffset_value::
    Units:: microseconds
mbgSyncboxN2XPtpOffsetToGrandmaster_value::
    Units:: microseconds
mbgSyncboxN2XPtpMeanPathDelay_value::
    Units:: microseconds

Supporting APIs

class socs.agents.meinberg_syncbox.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, with connection status and timestamp information:

{"mbgSyncboxN2XCurrentRefSource_0": {"status": 'PTP',
                                     "description": 'PTP'}}

Additionally there is connection status and timestamp information under:

"syncbox_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.