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----Ddatadata'
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)[source]¶ Generates a header-formatted bytestring of message type
msg_type
and withmsg_words
specified words
-
larpix.format.pacman_msg_format.
format_word
(msg_type, word_type, *data)[source]¶ Generates a word-formatted bytestring of word type specified by the
msg_type
andword_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)[source]¶ 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)[source]¶ 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)[source]¶ msg_words
should be a list of tuples that can be unpacked and passed intoformat_word
-
larpix.format.pacman_msg_format.
parse_msg
(msg)[source]¶ returns a tuple of:
(<header data>, [<word 0 data>, ...])
-
larpix.format.pacman_msg_format.
format
(packets, msg_type='REQ', ts_pacman=0)[source]¶ 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 formatsPacket_v2
,SyncPacket
, andTriggerPacket
objects.
-
larpix.format.pacman_msg_format.
parse
(msg, io_group=None)[source]¶ Converts a PACMAN message into larpix packets
The header is parsed into a
TimestampPacket
, data words are parsed intoPacket_v2
objects, trigger words are parsed intoTriggerPacket
objects, and sync words are parsed intoSyncPacket
objects.