From eed92670da26b57f64686ec5052bca1d6284eef3 Mon Sep 17 00:00:00 2001
From: watts <benjamin.watts@psi.ch>
Date: Thu, 13 Aug 2026 16:27:35 +0200
Subject: [PATCH] Update ZMQ Message Reference

---
 ZMQ-Message-Reference.md | 53 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/ZMQ-Message-Reference.md b/ZMQ-Message-Reference.md
index a4ed51a..4cf4591 100644
--- a/ZMQ-Message-Reference.md
+++ b/ZMQ-Message-Reference.md
@@ -245,7 +245,16 @@ Successful modification of the positioner definition will result in the publicat
 
 ## 'modified zonePlate definition'
 
-Changing the parameters for OSAs and zone plates, as well as the size of the OSA gap. All OSAs should be listed under the "OSAs" key, and the one selected for use should include the 'active' key (with a value of 1). All zone plates should be listed under the "zonePlates" key, and the one selected for use should include the 'active' key (with a value of 1). The value of the OSA gap should be given as a float under the key "dOsa"
+Changing the parameters for OSAs and zone plates, as well as the size of the OSA gap. While lots of information is included by the Intens GUI, only a few items are actually acted on by Pixelator:
+* "dOsa" key with a float value of the OSA gap.
+* "OSAs" key with a list of dictionaries containing OSA details - only the one containing `"active":1` is acted on.
+* "zonePlates" key with a list of dictionaries containing zone plate details - only the one containing `"active":1` is acted on.
+
+These keys are not required to all be included in the JSON structure (e.g. the OSA gap can be set without the "OSAs" or "zonePlates" keys being present). When the OSA or zone plate set as "active" is one of the set that are described in the config file, the "activeOSA" and/or "activeZonePlate" is updated in the config file with the associated "name" string. All other details for the zone plate or OSA are taken from the zone plate config file. When the OSA gap is given a new value via the "dOsa" key, the "dOsa" key in the zone plate config file is updated. No other changes are made to the config file.
+
+If the OSA or zone plate holding the `"active":1` key/vale does not have a "name" key or its value is an empty string, then it is understood to be a temporary setting and is processed differently. Firstly, no change is made to the config file, so the settings will be forgotten on restart of Pixelator. Secondly, further info is read from the JSON string. For an OSA, the float value of the "diameter" key is read and applied as the OSA diameter in microns. For a zone plate, the array value of the "b" key is read and applied as the coefficients of a polynomial that describe the energy dependent focal length of the zone plate (assuming infinite source distance)
+
+Details can be found in the [ZonePlate::modify()]{https://gitea.psi.ch/MicroSpectro/Pixelator/src/branch/master/PixelatorController/src/ZonePlate.cc#L164} function.
 
 Example message
 ```
@@ -305,6 +314,48 @@ msg = ['modified zonePlate definition',
 ,"dOsa":301.0
 }']
 ```
+Minimal example messages:
+```
+msg1 = ['modified zonePlate definition',
+'{
+"OSAs":[{
+    "name":"OSA 70"
+    ,"active":1
+    }]
+}']
+
+msg2 = ['modified zonePlate definition',
+'{
+"dOsa":301.0
+}']
+
+msg3 = ['modified zonePlate definition',
+'{"zonePlates":[
+    {
+    "name":"ZonePlate B"
+    ,"active":1
+    }]
+}']
+```
+"test" object example messages:
+```
+msg1 = ['modified zonePlate definition',
+'{
+"OSAs":[{
+    "diameter":70
+    ,"active":1
+    }]
+}']
+
+msg2 = ['modified zonePlate definition',
+'{"zonePlates":[
+    {
+    "name":""
+    ,"active":1
+    ,"b":[0.0,4.821]
+    }]
+}']
+```
 
 ## 'zonePlateFocus'