UC2-REST 0.2.0.37__tar.gz → 0.2.0.39__tar.gz

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UC2-REST
-Version: 0.2.0.37
+Version: 0.2.0.39
 Summary: This pacage will help you to drive the ESP32-driven microscopy control modules from UC2
 Home-page: https://github.com/openUC2/UC2-REST
 Author: Benedict Diederich

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/UC2_REST.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UC2-REST
-Version: 0.2.0.37
+Version: 0.2.0.39
 Summary: This pacage will help you to drive the ESP32-driven microscopy control modules from UC2
 Home-page: https://github.com/openUC2/UC2-REST
 Author: Benedict Diederich

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/UC2_REST.egg-info/SOURCES.txt

@@ -21,8 +21,10 @@ uc2rest/digitalin.py
 uc2rest/digitalout.py
 uc2rest/fan.py
 uc2rest/galvo.py
+uc2rest/gpio.py
 uc2rest/gripper.py
 uc2rest/home.py
+uc2rest/i2c.py
 uc2rest/laser.py
 uc2rest/lcddisplay.py
 uc2rest/ledmatrix.py
@@ -34,6 +36,7 @@ uc2rest/motor_config.py
 uc2rest/mserial.py
 uc2rest/objective.py
 uc2rest/pid.py
+uc2rest/ptz.py
 uc2rest/rotator.py
 uc2rest/slm.py
 uc2rest/state.py

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/uc2rest/UC2Client.py

@@ -22,6 +22,9 @@ from .analog import Analog
 from .modules import Modules
 from .digitalout import DigitalOut
 from .digitalin import DigitalIn
+from .gpio import GPIO
+from .ptz import PTZ
+from .i2c import I2C
 from .rotator import Rotator
 from .logger import Logger
 from .cmdrecorder import cmdRecorder
@@ -155,7 +158,16 @@ class UC2Client(object):
         
         # initialize digital in
         self.digitalin = DigitalIn(self)
-        
+
+        # initialize GPIO / collision-detector slave interface
+        self.gpio = GPIO(self)
+
+        # initialize PTZ keyboard bridge interface (CAN node-id 61)
+        self.ptz = PTZ(self)
+
+        # initialize generic I2C passthrough (sensors on the GPIO slave bus)
+        self.i2c = I2C(self)
+
         # initialize messaging
         self.message = Message(self)
         

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/uc2rest/__version__.py

@@ -6,7 +6,7 @@ __version__.py
 
 __title__ = 'UC2-REST'
 __description__ = 'This pacage will help you to drive the ESP32-driven microscopy control modules from UC2'
-__version__ = "v0.2.0.37"
+__version__ = "v0.2.0.39"
 __author__ = 'Benedict Diederich'
 __author_email__ = 'benedictdied@gmail.com'
 __license__ = 'GPL v3'

uc2_rest-0.2.0.39/uc2rest/gpio.py

@@ -0,0 +1,171 @@
+"""GPIO / collision-detector interface for the UC2 CAN GPIO slave.
+
+The CAN master exposes the GPIO slave (XIAO node, default CAN node-id 60)
+through two serial endpoints:
+
+    {"task":"/gpio_get"}
+        -> {"gpio":{"node":60,"mean":585,"filtered":584,"raw":581,
+                    "reference":585,"threshold":150,"sensitivity":4,
+                    "trip":0,"estop":0},"ok":true,"qid":N}
+
+    {"task":"/gpio_act","threshold":150,"sensitivity":4,
+     "reference":585,"calibrate":1}          (all value fields optional)
+
+Collision detection runs ON THE SLAVE: the sensor has an idle value (the
+"reference"); a collision = `sensitivity` consecutive samples deviating more
+than `threshold` ADC counts from the reference (rising OR falling). Sensor
+values are never streamed on the CAN bus — polling /gpio_get triggers SDO
+reads on demand. Only the collision/E-stop EVENT is pushed asynchronously;
+the master then prints:
+
+    {"gpio":{"event":1,"node":60,"trip":1,"estop":0,"flags":3,
+             "filtered":2365,"raw":2937,...}}
+
+The "event":1 marker distinguishes pushed edges from /gpio_get responses
+(both share the top-level "gpio" key and therefore both arrive at the same
+serial callback).
+"""
+
+
+class GPIO(object):
+    def __init__(self, parent):
+        self._parent = parent
+
+        # last known state (merged from get_status responses and async events)
+        self.status = {}
+
+        # register a callback for any {"gpio":{...}} frame on the serial loop
+        if hasattr(self._parent, "serial"):
+            self._parent.serial.register_callback(self._callback_gpio, pattern="gpio")
+
+        # user-registered callbacks
+        self._collision_callbacks = []   # fired on async trip/clear events
+        self._status_callbacks = []      # fired on every gpio frame
+
+    # ─────────────────────────────────────────────────────────────────
+    # Async event plumbing
+    # ─────────────────────────────────────────────────────────────────
+    def _callback_gpio(self, data):
+        """Handle any serial frame with a top-level "gpio" key.
+
+        Pushed events carry "event":1 and fire the collision callbacks;
+        /gpio_get responses only refresh the cached status."""
+        try:
+            gpio = data.get("gpio", None)
+            if not isinstance(gpio, dict):
+                return
+            self.status.update(gpio)
+
+            for cb in self._status_callbacks:
+                try:
+                    cb(dict(self.status))
+                except Exception as e:
+                    print(f"Error in gpio status callback: {e}")
+
+            if gpio.get("event", 0):
+                for cb in self._collision_callbacks:
+                    try:
+                        cb(dict(gpio))
+                    except Exception as e:
+                        print(f"Error in gpio collision callback: {e}")
+        except Exception as e:
+            print("Error in _callback_gpio: ", e)
+
+    def register_collision_callback(self, callbackfct):
+        """Register a function called on every asynchronously pushed GPIO
+        event (collision trip/clear, E-stop press/release). The callback
+        receives the event dict, e.g. {"event":1,"trip":1,"estop":0,...}.
+        Check ["trip"] to distinguish collision-began from collision-cleared."""
+        if callbackfct not in self._collision_callbacks:
+            self._collision_callbacks.append(callbackfct)
+
+    def register_status_callback(self, callbackfct):
+        """Register a function called on EVERY gpio frame (async events and
+        /gpio_get responses alike) with the merged status dict."""
+        if callbackfct not in self._status_callbacks:
+            self._status_callbacks.append(callbackfct)
+
+    # ─────────────────────────────────────────────────────────────────
+    # Query / configuration
+    # ─────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _extract_gpio(response):
+        """Unwrap a post_json return into the "gpio" dict.
+
+        mserial.sendMessage returns a LIST of response dicts on success
+        (self.responses[qid] is a per-frame list), a plain string on
+        timeout/interrupt, or an int qid when getReturn=False — so handle
+        all shapes defensively."""
+        candidates = response if isinstance(response, list) else [response]
+        for item in candidates:
+            if isinstance(item, dict):
+                gpio = item.get("gpio")
+                if isinstance(gpio, dict):
+                    return gpio
+        return {}
+
+    def get_status(self, node=None, timeout=1):
+        """Poll the collision detector (SDO reads on the CAN bus).
+
+        Returns the "gpio" dict: mean (rolling average), filtered, raw,
+        baseline, sigma, mode (0=auto/1=manual), reference, threshold,
+        sensitivity, trip, estop."""
+        path = "/gpio_get"
+        payload = {"task": path}
+        if node is not None:
+            payload["node"] = node
+        r = self._parent.post_json(path, payload, getReturn=True, timeout=timeout)
+        gpio = self._extract_gpio(r)
+        if gpio:
+            self.status.update(gpio)
+            return gpio
+        # Response didn't parse (timeout/odd shape) — fall back to the cache
+        # maintained by the async serial callback, which sees every frame.
+        return dict(self.status)
+
+    def _act(self, node=None, timeout=1, **fields):
+        path = "/gpio_act"
+        payload = {"task": path}
+        if node is not None:
+            payload["node"] = node
+        payload.update(fields)
+        return self._parent.post_json(path, payload, getReturn=True, timeout=timeout)
+
+    def set_threshold(self, threshold, node=None, timeout=1):
+        """Deviation band (ADC counts) around the reference outside which a
+        sample votes for "collision". Persisted in the slave's NVS."""
+        return self._act(node=node, timeout=timeout, threshold=int(threshold))
+
+    def set_sensitivity(self, sensitivity, node=None, timeout=1):
+        """Number of CONSECUTIVE out-of-band samples (at 50 Hz) required to
+        trip — and in-band samples to clear. 3-4 rejects single-sample spikes
+        while confirming a real collision within ~60-80 ms."""
+        return self._act(node=node, timeout=timeout, sensitivity=int(sensitivity))
+
+    def set_reference(self, reference, node=None, timeout=1):
+        """Explicitly set the idle baseline (ADC counts). Typically you poll
+        get_status()["mean"] while the system is idle and write that value
+        here — or simply use calibrate()."""
+        return self._act(node=node, timeout=timeout, reference=int(reference))
+
+    def calibrate(self, node=None, timeout=1):
+        """Tell the slave to take its CURRENT rolling mean as the new
+        reference (persisted in NVS). MANUAL mode only — in AUTO the baseline
+        tracks itself. Do this while the system is idle and collision-free."""
+        return self._act(node=node, timeout=timeout, calibrate=1)
+
+    def set_mode(self, mode, node=None, timeout=1):
+        """Select the detection mode (persisted on the slave in NVS).
+
+        mode: "auto"  (default, recommended) — adaptive baseline + robust
+              sigma z-score. Parameter-free: tracks a slowly drifting
+              background and trips on a fast deflection. No calibration.
+        mode: "manual" — fixed reference +/- threshold. Deterministic;
+              requires the reference to be calibrated to the idle level.
+
+        Accepts "auto"/"manual" or 0/1."""
+        if isinstance(mode, str):
+            mval = 1 if mode.lower() == "manual" else 0
+        else:
+            mval = 1 if int(mode) else 0
+        return self._act(node=node, timeout=timeout, mode=mval)

uc2_rest-0.2.0.39/uc2rest/i2c.py

@@ -0,0 +1,190 @@
+"""Generic raw-I2C passthrough for the UC2 CAN GPIO slave.
+
+Any I2C device wired to the GPIO slave's sensor bus (SDA=GPIO5/D4,
+SCL=GPIO6/D5 on the can-gpio board) can be read/written from Python WITHOUT
+a device driver on the ESP32. The firmware just relays bytes; the register map
+lives here. One JSON request = one raw transaction (optional write, optional
+inter-phase delay, optional read):
+
+    {"task":"/i2c_act","node":60,"addr":68,"write":[253],"read":6,
+     "delay":12,"stop":1}
+        -> {"node":60,"status":2,"data":[.. up to 40 bytes ..],"ok":true}
+
+    addr  : 7-bit I2C address (decimal; 0x44 == 68)
+    write : bytes to send first (register pointer / command / config)
+    read  : number of bytes to read back (0 = write-only)
+    delay : ms to wait between the write and the read (device conversion time)
+    stop  : 1 → send STOP after the write (device wants a full stop before the
+            read, e.g. SHT4x); 0/omitted → repeated-START (typical register read)
+
+Status byte: 2 = ok, 0x81..0x85 = write failed (I2C NACK / bus error),
+0x90 = fewer bytes read than requested, 0xA0 = bad parameters.
+
+See uc2-ESP: main/src/i2c/I2cBridge.cpp and DeviceRouter::handleI2cAct.
+"""
+
+import time
+
+
+class I2C(object):
+    STATUS_OK = 0x02
+
+    def __init__(self, parent):
+        self._parent = parent
+
+    # ─────────────────────────────────────────────────────────────────
+    # Generic transaction
+    # ─────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _extract(response):
+        """Unwrap a post_json return into the response dict carrying "data".
+
+        mserial.sendMessage returns a LIST of frames on success, a plain
+        string on timeout, or an int qid when getReturn=False — handle all."""
+        candidates = response if isinstance(response, list) else [response]
+        for item in candidates:
+            if isinstance(item, dict) and ("data" in item or "status" in item):
+                return item
+        return {}
+
+    def transaction(self, addr, write=None, read=0, delay_ms=0, stop=False,
+                    node=None, timeout=2):
+        """Run one raw I2C transaction on the slave and return the response
+        dict {"status":int, "data":[...], ...}. `write` is an iterable of
+        byte values; `read` is how many bytes to read back."""
+        payload = {"task": "/i2c_act",
+                   "addr": int(addr) & 0x7F,
+                   "read": int(read),
+                   "delay": int(delay_ms)}
+        if write:
+            payload["write"] = [int(b) & 0xFF for b in write]
+        if stop:
+            payload["stop"] = 1
+        if node is not None:
+            payload["node"] = node
+        r = self._parent.post_json("/i2c_act", payload, getReturn=True,
+                                   timeout=timeout)
+        return self._extract(r)
+
+    def ok(self, response):
+        """True if a transaction response reports success."""
+        return isinstance(response, dict) and response.get("status") == self.STATUS_OK
+
+    # ─────────────────────────────────────────────────────────────────
+    # Register-level convenience wrappers
+    # ─────────────────────────────────────────────────────────────────
+    def read_register(self, addr, reg, length, node=None,
+                      repeated_start=True, timeout=2):
+        """Classic register read: write the register pointer, then read
+        `length` bytes (repeated-START by default). Returns a bytes object
+        (empty on failure)."""
+        res = self.transaction(addr, write=[reg], read=length,
+                               stop=not repeated_start, node=node, timeout=timeout)
+        return bytes(res.get("data", []) or [])
+
+    def write_register(self, addr, reg, values, node=None, timeout=2):
+        """Write `values` (int or iterable) to register `reg`. Returns True on
+        an acknowledged write."""
+        if isinstance(values, int):
+            values = [values]
+        res = self.transaction(addr, write=[reg] + [int(v) & 0xFF for v in values],
+                               read=0, stop=True, node=node, timeout=timeout)
+        return self.ok(res)
+
+    def scan(self, node=None, start=0x08, end=0x77, timeout=2):
+        """Probe the bus for responding devices (0-byte write per address).
+        Returns a list of 7-bit addresses that ACKed."""
+        found = []
+        for a in range(start, end + 1):
+            # zero-length write: beginTransmission + endTransmission(true).
+            res = self.transaction(a, write=[], read=0, stop=True,
+                                   node=node, timeout=timeout)
+            if self.ok(res):
+                found.append(a)
+        return found
+
+    # ─────────────────────────────────────────────────────────────────
+    # Adafruit SHT45 — humidity + temperature (addr 0x44)
+    # ─────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _sht_crc(data):
+        """Sensirion CRC-8: poly 0x31, init 0xFF."""
+        crc = 0xFF
+        for b in data:
+            crc ^= b
+            for _ in range(8):
+                crc = ((crc << 1) ^ 0x31) & 0xFF if (crc & 0x80) else (crc << 1) & 0xFF
+        return crc
+
+    def read_sht45(self, addr=0x44, node=None, precision="high", timeout=2):
+        """Read the SHT45. Sends the measure command, waits for the
+        conversion, reads 6 bytes (T, T_crc, RH, RH_crc) and converts.
+
+        precision: "high" (0xFD, ~9 ms), "med" (0xF6), "low" (0xE0).
+        Returns {"temperature_c", "humidity_pct", "crc_ok"} or None on error."""
+        cmd = {"high": 0xFD, "med": 0xF6, "low": 0xE0}.get(precision, 0xFD)
+        res = self.transaction(addr, write=[cmd], read=6, delay_ms=12,
+                               stop=True, node=node, timeout=timeout)
+        data = res.get("data", []) or []
+        if len(data) < 6:
+            return None
+        t_ticks = (data[0] << 8) | data[1]
+        rh_ticks = (data[3] << 8) | data[4]
+        temp_c = -45.0 + 175.0 * t_ticks / 65535.0
+        rh = -6.0 + 125.0 * rh_ticks / 65535.0
+        rh = max(0.0, min(100.0, rh))
+        crc_ok = (self._sht_crc(data[0:2]) == data[2] and
+                  self._sht_crc(data[3:5]) == data[5])
+        return {"temperature_c": temp_c, "humidity_pct": rh, "crc_ok": crc_ok}
+
+    # ─────────────────────────────────────────────────────────────────
+    # Adafruit TSL2591 — high-dynamic-range light sensor (addr 0x29)
+    # ─────────────────────────────────────────────────────────────────
+    # Command byte: 0xA0 = normal register access; low 5 bits = register addr.
+    _TSL_CMD = 0xA0
+    _TSL_ENABLE = 0x00     # PON(0x01) | AEN(0x02) | (AIEN/NPIEN optional)
+    _TSL_CONTROL = 0x01    # AGAIN[5:4] | ATIME[2:0]
+    _TSL_C0DATAL = 0x14    # CH0 low; auto-increments through 0x17 (CH1 high)
+    _TSL_GAIN = {0x00: 1.0, 0x10: 25.0, 0x20: 428.0, 0x30: 9876.0}
+
+    def read_tsl2591(self, addr=0x29, node=None, gain=0x10, integration=0x01,
+                     timeout=2):
+        """Read the TSL2591 broadband (CH0) and IR (CH1) channels and estimate
+        lux. Powers the ALS on, applies gain/integration, waits one integration
+        period, then reads the four data bytes.
+
+        gain:        0x00=1x, 0x10=25x (default), 0x20=428x, 0x30=9876x
+        integration: 0x00=100ms .. 0x05=600ms (default 0x01 = 200ms)
+        Returns {"ch0_full","ch1_ir","visible","gain","integration_ms",
+                 "lux","saturated"} or None on error."""
+        # Enable ALS (PON | AEN).
+        if not self.write_register(addr, self._TSL_CMD | self._TSL_ENABLE, 0x03,
+                                   node=node, timeout=timeout):
+            return None
+        # Set gain + integration time.
+        self.write_register(addr, self._TSL_CMD | self._TSL_CONTROL,
+                            (gain & 0x30) | (integration & 0x07),
+                            node=node, timeout=timeout)
+        atime_ms = 100 * ((integration & 0x07) + 1)
+        # Wait one full integration period (Python-side so we aren't limited to
+        # the firmware's 255 ms per-transaction delay cap). Small margin added.
+        time.sleep(atime_ms / 1000.0 + 0.05)
+        # Burst-read CH0/CH1 (4 bytes, auto-increment) via repeated-START.
+        res = self.transaction(addr, write=[self._TSL_CMD | self._TSL_C0DATAL],
+                               read=4, stop=False, node=node, timeout=timeout)
+        data = res.get("data", []) or []
+        if len(data) < 4:
+            return None
+        ch0 = data[0] | (data[1] << 8)   # full spectrum
+        ch1 = data[2] | (data[3] << 8)   # IR
+        saturated = ch0 >= 0xFFFF or ch1 >= 0xFFFF
+
+        # Approximate lux (standard TSL2591 formula; device lot variation ~±).
+        again = self._TSL_GAIN.get(gain & 0x30, 1.0)
+        lux = None
+        if ch0 > 0 and not saturated:
+            cpl = (atime_ms * again) / 408.0   # counts-per-lux, DF = 408
+            lux = max(0.0, (ch0 - ch1) * (1.0 - float(ch1) / float(ch0)) / cpl)
+        return {"ch0_full": ch0, "ch1_ir": ch1, "visible": ch0 - ch1,
+                "gain": gain, "integration_ms": atime_ms,
+                "lux": lux, "saturated": saturated}

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/uc2rest/motor.py

@@ -1098,7 +1098,7 @@ class Motor(object):
         '''
         if type(axis) != int:
             axis = self.xyztTo1230(axis)
-        
+        # {"task":"/motor_act", "joystickdir": {"steppers": [{"stepperid": 1, "inverted": 1}]}}
         path = "/motor_act"
         payload = {
             "task": path,

{uc2_rest-0.2.0.37 → uc2_rest-0.2.0.39}/uc2rest/mserial.py

@@ -364,11 +364,14 @@ class Serial:
         for i in range(500):
             # if we just want to send but not even wait for a response
             mReadline = self._read(ser)
-            if self.DEBUG and mReadline != "" and mReadline != "\n" and mReadline != b'' and mReadline != b'\n': 
-                self._logger.debug("[checkFirmware]: "+str(mReadline))
-            if mReadline.decode('utf-8').strip() == "++" or mReadline.decode('utf-8').strip().find("++")>=0:
-                self._freeSerialBuffer(ser)
-                return True
+            try:
+                if self.DEBUG and mReadline != "" and mReadline != "\n" and mReadline != b'' and mReadline != b'\n': 
+                    self._logger.debug("[checkFirmware]: "+str(mReadline))
+                if mReadline.decode('utf-8').strip() == "++" or mReadline.decode('utf-8').strip().find("++")>=0:
+                    self._freeSerialBuffer(ser)
+                    return True
+            except Exception as e:
+                self._logger.error("Error in checkFirmware: "+str(e))
         return False
 
     def _generate_identifier(self):

uc2_rest-0.2.0.39/uc2rest/ptz.py

@@ -0,0 +1,156 @@
+"""PTZ keyboard interface for the UC2 CAN PTZ-bridge slave.
+
+A low-cost CCTV PTZ joystick keyboard (Pelco-D/P over RS-485) is read by a
+dedicated CAN bridge node (XIAO, default CAN node-id 61). The bridge maps the
+joystick to motor moves directly on the bus, and forwards every DISCRETE key
+(presets, AUX, iris) to the master, which prints an asynchronous frame:
+
+    {"ptz":{"event":1,"node":61,"type":6,"name":"iris_open","arg":0,"seq":21}}
+
+    type/name:  1 preset_call   2 preset_set   3 preset_clear
+                4 aux_on         5 aux_off      6 iris_open
+                7 iris_close     8 camera_onoff 9 autoscan
+    arg:        preset number (1..255) or AUX number (1..6); 0 otherwise
+    seq:        wraps 0..255, one per key event (the master de-dupes on it)
+
+This mirrors the collision "gpio" event plumbing (see gpio.py): a single
+serial callback on the top-level "ptz" key, an "event":1 marker to tell a
+pushed key from a /ptz_get response, and a list of user callbacks. ImSwitch
+registers one such callback and maps each key to a microscope function
+(snap image, switch objective, toggle an LED …) — see UC2ConfigController.
+
+Debug / config endpoints (handled locally on the bridge node):
+    {"task":"/ptz_act","debug":2}        raw RS-485 hex dump (wiring bring-up)
+    {"task":"/ptz_act","debug":1}        decoded frame JSON
+    {"task":"/ptz_act","addr":3}         accept only camera address 3 (0=any)
+    {"task":"/ptz_act","timeout":2000}   motion watchdog ms (0=off)
+    {"task":"/ptz_get"}                  parser stats + last frame + motion
+"""
+
+
+class PTZ(object):
+    def __init__(self, parent):
+        self._parent = parent
+
+        # last known state (merged from /ptz_get responses and async events)
+        self.status = {}
+        # last discrete key event pushed by the bridge
+        self.last_event = {}
+
+        # register a callback for any {"ptz":{...}} frame on the serial loop
+        if hasattr(self._parent, "serial"):
+            self._parent.serial.register_callback(self._callback_ptz, pattern="ptz")
+
+        # user-registered callbacks
+        self._event_callbacks = []    # fired on async key events (event==1)
+        self._status_callbacks = []   # fired on every ptz frame
+
+    # ─────────────────────────────────────────────────────────────────
+    # Async event plumbing
+    # ─────────────────────────────────────────────────────────────────
+    def _callback_ptz(self, data):
+        """Handle any serial frame with a top-level "ptz" key.
+
+        Pushed key events carry "event":1 and fire the event callbacks;
+        /ptz_get responses only refresh the cached status."""
+        try:
+            ptz = data.get("ptz", None)
+            if not isinstance(ptz, dict):
+                return
+            self.status.update(ptz)
+
+            for cb in self._status_callbacks:
+                try:
+                    cb(dict(self.status))
+                except Exception as e:
+                    print(f"Error in ptz status callback: {e}")
+
+            if ptz.get("event", 0):
+                self.last_event = dict(ptz)
+                for cb in self._event_callbacks:
+                    try:
+                        cb(dict(ptz))
+                    except Exception as e:
+                        print(f"Error in ptz event callback: {e}")
+        except Exception as e:
+            print("Error in _callback_ptz: ", e)
+
+    def register_event_callback(self, callbackfct):
+        """Register a function called on every asynchronously pushed PTZ key
+        event (preset call/set/clear, AUX on/off, iris, …). The callback
+        receives the event dict, e.g.
+        {"event":1,"node":61,"type":1,"name":"preset_call","arg":1,"seq":7}.
+        Use ["name"] and ["arg"] to decide which microscope function to run."""
+        if callbackfct not in self._event_callbacks:
+            self._event_callbacks.append(callbackfct)
+
+    def register_status_callback(self, callbackfct):
+        """Register a function called on EVERY ptz frame (async key events and
+        /ptz_get responses alike) with the merged status dict."""
+        if callbackfct not in self._status_callbacks:
+            self._status_callbacks.append(callbackfct)
+
+    # ─────────────────────────────────────────────────────────────────
+    # Query / configuration
+    # ─────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _extract_ptz(response):
+        """Unwrap a post_json return into the "ptz" dict.
+
+        mserial.sendMessage returns a LIST of response dicts on success, a
+        plain string on timeout, or an int qid — handle all shapes (same
+        defensive pattern as GPIO._extract_gpio)."""
+        candidates = response if isinstance(response, list) else [response]
+        for item in candidates:
+            if isinstance(item, dict):
+                ptz = item.get("ptz")
+                if isinstance(ptz, dict):
+                    return ptz
+        return {}
+
+    def get_status(self, node=None, timeout=1):
+        """Poll the bridge: parser stats (bytesIn/framesOk/resyncs), the last
+        decoded frame and the current motion snapshot. Returns the "ptz" dict.
+        Note: discrete key events are PUSHED (see register_event_callback);
+        polling is only for diagnostics."""
+        path = "/ptz_get"
+        payload = {"task": path}
+        if node is not None:
+            payload["node"] = node
+        r = self._parent.post_json(path, payload, getReturn=True, timeout=timeout)
+        ptz = self._extract_ptz(r)
+        if ptz:
+            self.status.update(ptz)
+            return ptz
+        return dict(self.status)
+
+    def _act(self, node=None, timeout=1, **fields):
+        path = "/ptz_act"
+        payload = {"task": path}
+        if node is not None:
+            payload["node"] = node
+        payload.update(fields)
+        return self._parent.post_json(path, payload, getReturn=True, timeout=timeout)
+
+    def set_debug(self, level, node=None, timeout=1):
+        """Bridge serial debug verbosity: 0 quiet, 1 decoded frame JSON,
+        2 + raw RS-485 hex dump (use for wiring / baud / A-B-swap bring-up)."""
+        return self._act(node=node, timeout=timeout, debug=int(level))
+
+    def set_address(self, addr, node=None, timeout=1):
+        """Only accept keyboard frames for this Pelco camera address
+        (0 = accept any). Handy when several bridges share one keyboard."""
+        return self._act(node=node, timeout=timeout, addr=int(addr))
+
+    def set_motion_timeout(self, timeout_ms, node=None, serial_timeout=1):
+        """Watchdog (ms): stop all axes if the keyboard goes silent while an
+        axis is moving (0 = off). Guards against a lost stop frame.
+
+        Built explicitly (not via _act) because the firmware field is itself
+        named "timeout", which would clash with the serial-call timeout kwarg."""
+        path = "/ptz_act"
+        payload = {"task": path, "timeout": int(timeout_ms)}
+        if node is not None:
+            payload["node"] = node
+        return self._parent.post_json(path, payload, getReturn=True,
+                                      timeout=serial_timeout)