Welcome to biDAQmqtt’s documentation!

biDAQmqtt implements a daemon that listens to MQTT messages to control the Bicocca DAQ (biDAQ) system.

MQTT (https://mqtt.org) is a lightweight messaging protocol based on a publish-subscribe architecture. MQTT requires a broker to distribute messages and keep track of subscriptions.

In Linux, the most common broker is Mosquitto (https://mosquitto.org) which is usually available in standard repositories (the package is called mosquitto). Useful command-line programs are also included in mosquitto-clients (mosquitto-pub, mosquitto_sub).

The biDAQmqtt daemon can be executed from command line, although this is usually not necessary since the daemon is automatically started at FPGA startup using the script /etc/init.d/S60bidaq.

biDAQmqtt can be configured using the configuration file in /etc/bidaq.conf on the FPGA. The bare minimum configuration consists in specifying the broker IP address and its port.

The FPGA has a broker installed and running, which can be used in small test setups. In the final experiment, it is advisable to offload this task from the FPGA and run the broker on the DAQ PC.

biDAQmqtt messages

MQTT messages consist of a topic and a payload (both strings). A node receives messages only from the topics it has subscribed.

The biDAQmqtt daemon subscribes to the following topics:

  • CUPID/DAQ/Identify

  • CUPID/DAQ/CrateAll_HalfAll

  • CUPID/DAQ/Crate#_HalfAll

  • CUPID/DAQ/CrateAll_Half#

  • CUPID/DAQ/Crate#_Half#

Where # is a number (0-127 for the crate number and 0 or 1 for the half).

To interact with biDAQmqtt, the user sends a message to any of those topics. The biDAQmqtt daemon then appends the _Return string to the topic of the reply message (e.g., the topic of a reply to CUPID/DAQ/Identify is CUPID/DAQ/Identify_Return). This means that the user has to subscribe to the _Return topic before sending the outbound message.

Now we will explain in more detail the meaning of the different topics and the expected payload of both the outbound (from PC to the FPGA) and inbound (from FPGA to PC) messages.

CUPID/DAQ/Identify

Topic CUPID/DAQ/Identify is used to get replies from all daemons currently listening on the network. This is necessary, since the user doesn’t know which daemons are online or offline. Do this at startup or anytime necessary.

The outbound payload can be an empty string.

The inbound payload of the reply is a JSON-encoded dictionary like the following one:

{"IpAddress": "192.168.1.2", "Crate": 0, "Half": 0, "ReturnString": null, "ReturnDataJson": "null"}

The keys of the dictionary are self-explanatory. ReturnString and ReturnDataJson keys are always empty (they are used for other commands, as explained later).

CUPID/DAQ/Crate[…]

Topics CUPID/DAQ/Crate[...] are used to easily send commands to single daemons or groups of daemons.

Commands consist of calls to specific methods or properties of the biDAQpy.biDAQ class. Refer to the biDAQpy.biDAQ documentation pages (https://bidaq.baltig-pages.infn.it/biDAQpy/) for more information.

The payload of the outbound message is a JSON-encoded dictionary that includes the name of the method and its arguments. Refer to the documentation of the payload parse function biDAQmqtt.biDAQmqtt.CmdCallback() for more details on the payload syntax.

Here is an example. If the user wants to call biDAQpy.SubClassOne.FunctionTwo(ArgThree='Four'), then the dictionary to encode in a JSON string is the following:

{‘Method’: ‘SubClassOne.FunctionTwo’, ‘Arguments’: {'ArgThree': 'Four'}}

Replies

The payload of the reply is a dictionary that contains the following keys: IpAddress, Crate, Half, ReturnString, ReturnDataJson.

The ReturnString is a string that returns the status of the command. Possible status strings are the following:

  • OK: method or command executed correctly.

  • ERROR_JSON: error in decoding the JSON string

  • ERROR_BOARD_NOT_AVAILABLE: the selected board is not available.

  • ERROR_EXCEPTION: the method had an exception.

  • ERROR_NOT_FOUND: method or property not found.

  • ERROR_NO_BOARD_NUM: board number was not provided together with board method or property.

  • ERROR_DICT: dictionary keys are not correct.

The ReturnDataJson is a JSON-encoded string of the outputs returned by the method (or the property). Before using the output, the user should decode it from JSON. The decoding from JSON must be done twice: a first time to decode the payload of the MQTT message, a second time to decode ReturnDataJson. This second step is necessary only if ReturnString == 'OK'.

Indices and tables