Stimulator Encoder Agent

The optical encoder signals of the stimulator are captured by Kria KR260 boards with the PTP timing reference. This agent runs inside the KR260 to publish captured data to the crossbar.

usage: python3 agent.py [-h] [--path-dev PATH_DEV] [--path-lock PATH_LOCK]

Agent Options

--path-dev

Path to the device file.

--path-lock

Path to the lock file.

Default: /tmp/.stim-lock

Configuration File Examples

Below are useful configurations examples for the relevant OCS files and for running the agent in a docker container.

OCS Site Config

To configure the stimulator encoder agent we need to add a StimEncAgent block to our ocs configuration file. Here is an example configuration block using all of the available arguments:

{'agent-class': 'StimEncAgent',
 'instance-id': 'stim-enc',
 'arguments':[]}

Description

The stimulator is equipped with two optical encoders to monitor the position of the rotating chopper. The Kria KR260 board is used to capture these encoder signals. The signal is routed to the programmable logic (PL) in the Zynq Ultrascale+ chip on the Kria. Changes in the encoder states are captured with the PTP-based timestamp provided by the timestamp unit (TSU) in the Gigabit Ethernet MAC in Zynq. The packet containing the encoder states and the timestamp is sent to the FIFO inside the PL and is then read from the processor via the AXI interface. The interface is memory-mapped with the uio (User Space I/O) driver.

The hardware timestamp of the PTP origin is provided in TAI format, which is offset by 37 seconds from UTC at least until December 31, 2025.

Agent API

class socs.agents.stimulator_encoder.agent.StimEncAgent(agent, path_dev=None, path_lock=PosixPath('/tmp/.stim-lock'))[source]

OCS agent class for stimulator encoder

Parameters:

path_dev (str or pathlib.Path) – Path to the generic-uio device file for str_rd IP.
path_lock (str or pathlib.Path) – Path to the lockfile.

acq()[source]

Process - Start acquiring data.

Notes

An example of the session data:

>>> response.session['data']

{'timestamp_tai': 1736541833.679634,
 'state': 1,
 'freq': 10.1,
 'timestamp': 1736541796.779634
}

Supporting APIs

class socs.agents.stimulator_encoder.drivers.StimEncError[source]: Exception rased by stimulator encoder reader.

class socs.agents.stimulator_encoder.drivers.StimEncTime(time_raw: int)[source]

Stimulator encoder time.

Parameter

time_rawint: Raw time format from TSU. [sec 48 bits][nsec 30 bits][sub-nsec 16 bits]

property sec: int

Seconds part of timestamp.

Returns:: sec – Seconds part of timestamp.
Return type:: int

property nsec: int

Nano second part of timestamp.

Returns:: nsec – Nano-sec part of timestamp.
Return type:: int

property tai: float

Time in seconds from TAI epoch.

Returns:: tai – Seconds from TAI epoch.
Return type:: float

class socs.agents.stimulator_encoder.drivers.StimEncData(data_bytes)[source]

Stimulator encoder data.

Parameter

data_rawndarray: Raw data from PL FIFO.

property time_raw: int

94 bit TSU timestamp.

Returns:: time_raw – 94 bit TSU timestamp.
Return type:: int

property time: StimEncTime

TSU timestamp.

Returns:: time – TSU timestamp abstraction.
Return type:: StimTime

property utime: float

Unix timestamp at class creation.

Returns:: utime
Return type:: Unix timestamp when this object is created.

class socs.agents.stimulator_encoder.drivers.StimEncReader(path_dev, path_lock=PosixPath('/tmp/.stim-lock'), verbose=True)[source]

Class to read encoder data.

Parameters:

path_dev (str or pathlib.Path) – Path to the generic-uio device file for str_rd IP.
path_lock (str or pathlib.Path) – Path to the lockfile.

fill()[source]: Get data from PL fifo and put into software fifo.

run()[source]: Run infinite loop of data filling.