PACMAN interface message format

A python interface to the pacman ZMQ message format.

The pacman ZMQ messages are a raw bytestring with two components: a short header and N words. It’s a bit cumbersome to work with bytestrings in data (and keep track of endianness / etc), so this module allows you to translate between native python objects and the pacman message bytestring.

To import this module:

import larpix.format.pacman_msg_format as pacman_msg_fmt

Access to the message content is provided by the parse_msg(msg) method which takes a single pacman message bytestring as an argument, e.g.:

msg = b'!-----
P---------------' # a simple ping response
data = pacman_msg_fmt.parse_msg(msg) # (('REP',123456,1), [('PONG')])
msg = b'D-----
D
------datadata' # a simple data message
data = pacman_msg_fmt.parse_msg(msg) # (('DATA',123456,1), [('DATA',1,1234,b'datadata')])

The creation of messages can be performed with the inverse method, format_msg(msg_type, msg_words). Here, the msg_type is one of 'DATA', 'REQ', or 'REP', and msg_words is a list of tuples indicating the word type (index 0) and the word data (index 1, 2, …). Word types are specified by strings that can be found in the word_type_table. The necessary fields (and primitive types) for the word data is described in the word_fmt_table. E.g.:

data = ('REP', [('PONG')]) # simple ping response
msg = pacman_msg_fmt.format_msg(*data) # b'!----
P'
data = ('DATA', [('DATA',1,1234,b'datadata')])
msg = pacman_msg_fmt.format_msg(*data) # b'D----
D
datadata'

To facilitate translating to/from larpix-control packet objects, you can use the format(pkts, msg_type) and parse(msg, io_group=None) methods. E.g.:

packet = Packet_v2()
packet.io_channel = 1
msg = pacman_msg_fmt.format([packet]) # b'?----
D
'

packets = pacman_msg_fmt.parse(msg, io_group=1) # [Packet_v2(b'')]
packets[0].io_group # 1

Note that no io_group data is contained within a pacman message. This means that when formatting messages, packets’ io_group field is ignored, and when parsing messages, an io_group value needs to be specified at the time of parsing.

larpix.format.pacman_msg_format.latest_version = '0.0'

Most up-to-date message format version.

larpix.format.pacman_msg_format.format_header(msg_type, msg_words)

Generates a header-formatted bytestring of message type msg_type and with msg_words specified words

larpix.format.pacman_msg_format.format_word(msg_type, word_type, *data)

Generates a word-formatted bytestring of word type specified by the msg_type and word_type. The data contained within the word should be passed in as additional positional arguments in the order that they appear in the word (least significant byte first). E.g. for a data word:

data_word = format_word('DATA','DATA',<io_channel>,<receipt_timestamp>,<data_word_content>)

larpix.format.pacman_msg_format.parse_header(msg)

Returns a tuple of the data contained in the header:

(<msg type>, <msg time>, <msg words>)

larpix.format.pacman_msg_format.parse_word(msg_type, word)

Returns a tuple of data contained in word (little endian), first item is always the word type

larpix.format.pacman_msg_format.format_msg(msg_type, msg_words)

msg_words should be a list of tuples that can be unpacked and passed into format_word

larpix.format.pacman_msg_format.parse_msg(msg)

returns a tuple of:

(<header data>, [<word 0 data>, ...])

larpix.format.pacman_msg_format.format(packets, msg_type='REQ', ts_pacman=0)

Converts larpix packets into a single PACMAN message. The message header is automatically generated.

Note:: For request messages, this method only formats Packet_v2 objects. For data messages, this method only formats Packet_v2, SyncPacket, and TriggerPacket objects.

larpix.format.pacman_msg_format.parse(msg, io_group=None)

Converts a PACMAN message into larpix packets

The header is parsed into a TimestampPacket, data words are parsed into Packet_v2 objects, trigger words are parsed into TriggerPacket objects, and sync words are parsed into SyncPacket objects.