Running QDSpy as MQTT client

• How it works
• Testing QDSpy via MQTT

How it works

The QDSpy client (QDSpy_MQTT_main.py) receives commands via the MQTT broker. These commands are published by the server as messages under the topic qds/<UUID>/srv. The messages have the format <command>,<message index>,<value1>[,<value2], ...], with:

• UUID is the unique ID of the client-server connection (see below)
• command tells the client to load a stimulus, run it, etc.
• message index is steadily increasing, allowing to match commands with replies (not yet used).
• value1, ... are parameters (e.g., a stimulus file name).

Any programs that can publish and subscribe MQTT messages can serve as QDSpy server. For the examples below, we will use a small test program (test_mqtt.py).

The client replies to every command in a similar format: The topic is qds/<UUID>/cli, the message <reply>,<message index>,<value1>[,<value2], ...].

• reply can be ok, error (followed by an error code and an error message), or state (followed by a state ID and the state name).

Testing QDSpy via MQTT

The following was tested with the QDSpy client running on a Raspberry Pi 5. It is assumed that QDSpy was installed following these instructions.

1. In the configuration file (QDSpy.ini), the MQTT broker and a unique ID are defined:

   [MQTT]
   str_mqtt_broker_address = test.mosquitto.org
   str_mqtt_uuid = d6d09beb68a3448a

   Both parameters must be the same for client and server.

2. Start the client on the Raspberry Pi. Open a terminal and run:

   cd ~
   source qdspy/bin/activate
   cd QDSpy
   python QDSpy_MQTT_main.py 

   QDSpy starts and outputs a lot of text, which should at the end look something like:

   20250330_175919   DEBUG   Initiating MQTT ...
   20250330_175919   DEBUG   MQTT|Connecting to `test.mosquitto.org` ...
   20250330_175920   DEBUG   ... done
   20250330_175920   DEBUG   MQTT|Start listening ...
   20250330_175920      ok   MQTT|Connected to `test.mosquitto.org`
   

   Now the client is ready.

3. Prepare the environment for the test program (the MQTT server) in a second shell on the same Raspberry Pi or on a different machine (e.g., a PC). Note that you need to change the commands depending on the OS you are using.

   cd ~
   source qdspy/bin/activate
   cd QDSpy

4. Check the state of the QDSpy client:

   python test_mqtt.py state

   ... will result in something like:

   20250330_185053   DEBUG   MQTT|Connecting to `test.mosquitto.org` ...
   20250330_185053   DEBUG   MQTT|Start listening ...
   20250330_185053      ok   MQTT|Connected to `test.mosquitto.org`
   20250330_185053    INFO   MQTT|<- `qds/d6d09beb68a3448a/srv state,0`
   20250330_185053    INFO   MQTT|-> `qds/d6d09beb68a3448a/cli state,0,2,ready`
   20250330_185054   DEBUG   MQTT|Stop listening
   

   ... indicating that the client is ready. In the terminal of the client, is should look like this:

   20250330_185053    INFO   MQTT|-> `qds/d6d09beb68a3448a/srv state,0`
   20250330_185053    INFO   MQTT|<- `qds/d6d09beb68a3448a/cli state,0,2,ready`
   

5. Compile, load, and run a stimulus.

   python test_mqtt.py compile,Test6_rp5

   ... compiles the stimulus file, if it exists. For stimuli that take longer to compile, check state before issuing the next command.

   python test_mqtt.py load,Test6_rp5

   ... loads the compiled stimulus, ready to play with:

   python test_mqtt.py play

   Use stop to end the stimulus presentation, and exit to terminate the client.