UC2-REST 0.2.0.35__tar.gz → 0.2.0.38__tar.gz

{uc2_rest-0.2.0.35 → uc2_rest-0.2.0.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UC2-REST
-Version: 0.2.0.35
+Version: 0.2.0.38
 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.35 → uc2_rest-0.2.0.38}/UC2_REST.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UC2-REST
-Version: 0.2.0.35
+Version: 0.2.0.38
 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.35 → uc2_rest-0.2.0.38}/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

{uc2_rest-0.2.0.35 → uc2_rest-0.2.0.38}/uc2rest/UC2Client.py

@@ -22,6 +22,8 @@ from .analog import Analog
 from .modules import Modules
 from .digitalout import DigitalOut
 from .digitalin import DigitalIn
+from .gpio import GPIO
+from .i2c import I2C
 from .rotator import Rotator
 from .logger import Logger
 from .cmdrecorder import cmdRecorder
@@ -47,9 +49,9 @@ class UC2Client(object):
     is_serial = False
     BAUDRATE = 115200
 
-    def __init__(self, host=None, port=31950, serialport=None, identity="UC2_Feather", baudrate=BAUDRATE, 
+    def __init__(self, host=None, port=31950, serialport=None, identity="UC2_Feather", baudrate=BAUDRATE,
                  NLeds=64, SerialManager=None, DEBUG=False, logger=None, skipFirmwareCheck=False,
-                 isPyScript=False):
+                 isPyScript=False, device_id=None, requireMaster=False):
         '''
         This client connects to the UC2-REST microcontroller that can be found here
         https://github.com/openUC2/UC2-REST
@@ -80,7 +82,7 @@ class UC2Client(object):
         # initialize communication channel (serial only)
         if serialport is not None:
             # use USB connection
-            self.serial = Serial(serialport, baudrate, parent=self, identity=identity, DEBUG=DEBUG, skipFirmwareCheck=skipFirmwareCheck)
+            self.serial = Serial(serialport, baudrate, parent=self, identity=identity, DEBUG=DEBUG, skipFirmwareCheck=skipFirmwareCheck, device_id=device_id, requireMaster=requireMaster)
             self.is_serial = True
             self.is_connected = self.serial.is_connected
             self.serial.DEBUG = DEBUG
@@ -155,7 +157,13 @@ class UC2Client(object):
         
         # initialize digital in
         self.digitalin = DigitalIn(self)
-        
+
+        # initialize GPIO / collision-detector slave interface
+        self.gpio = GPIO(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.35 → uc2_rest-0.2.0.38}/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.35"
+__version__ = "v0.2.0.38"
 __author__ = 'Benedict Diederich'
 __author_email__ = 'benedictdied@gmail.com'
 __license__ = 'GPL v3'

uc2_rest-0.2.0.38/uc2rest/can.py

@@ -0,0 +1,282 @@
+class CAN(object):
+    def __init__(self, parent):
+        """
+        CANController handles sending commands to a remote CAN device via the parent post_json interface.
+
+        :param parent: Parent object with post_json(path, payload, getReturn, timeout, nResponses)
+        """
+        self._parent = parent
+        
+        # Store latest scan results
+        self.scanResults = []
+        self.deviceCount = 0
+        
+        # Register a callback function for the CAN status on the serial loop
+        if hasattr(self._parent, "serial"):
+            self._parent.serial.register_callback(self._callback_can_status, pattern="scan")
+        
+        # Announce a function that is called when we receive a CAN scan update through the callback
+        self._callbackPerKey = {}
+        self.nCallbacks = 10
+        self._callbackPerKey = self.init_callback_functions(nCallbacks=self.nCallbacks)
+        print(self._callbackPerKey)
+    
+    def init_callback_functions(self, nCallbacks=10):
+        """Initialize the callback functions."""
+        _callbackPerKey = {}
+        self.nCallbacks = nCallbacks
+        for i in range(nCallbacks):
+            _callbackPerKey[i] = []
+        return _callbackPerKey
+    
+    def _callback_can_status(self, data):
+        """
+        Cast the json in the form:
+        {
+            "scan": [
+                {"canId": 20, "deviceType": 1, "status": 0, "deviceTypeStr": "laser", "statusStr": "idle"},
+                {"canId": 10, "deviceType": 0, "status": 0, "deviceTypeStr": "motor", "statusStr": "idle"}
+            ],
+            "qid": 2,
+            "count": 1
+        }
+        into the scan results array.
+        """
+        try:
+            if "scan" in data:
+                self.scanResults = data["scan"]
+                self.deviceCount = data.get("count", len(self.scanResults))
+                
+                # Call registered callback function with scan results
+                if callable(self._callbackPerKey[0]):
+                    self._callbackPerKey[0](self.scanResults)
+        except Exception as e:
+            print("Error in _callback_can_status: ", e)
+    
+    def register_callback(self, key, callbackfct):
+        """Register a callback function for a specific key."""
+        self._callbackPerKey[key] = callbackfct
+
+    def get_can_ids(self):
+        """Return CAN node IDs from the latest scan (e.g. for OTA flashing)."""
+        return [entry.get("canId") for entry in self.scanResults
+                if entry.get("canId") is not None]
+
+    def reboot_remote(self, qid=1, can_address=0, isBlocking=False, timeout=2):
+        """
+        Reboot a CAN device.
+
+        - ``can_address == 0`` reboots the master (this ESP32) itself.
+        - ``can_address in 1..127`` reboots a remote slave by SDO-writing 1
+          to OD index 0x2507 sub 0 on the target node. The slave's
+          CO_tmr_task observes the write and calls ESP.restart() ~200 ms
+          later.
+
+        :param qid: Query ID for the CAN command (unused by firmware, kept
+            for API compatibility)
+        :param can_address: 0 = master, 1..127 = remote slave nodeId
+        :param isBlocking: If True, wait for response
+        :param timeout: Timeout for the command in seconds
+        :return: Response from the device, e.g.
+            ``{"status":"ok","nodeId":11}`` or
+            ``{"status":"error","error":"SDO write failed","nodeId":11}``.
+        """
+        path = "/can_act"
+        payload = {
+            "task": path,
+            "restart": int(can_address)
+        }
+        nResponses = 1 if isBlocking else 0
+        # Send the payload to the parent, which handles the actual communication
+        return self._parent.post_json(
+            path,
+            payload,
+            getReturn=isBlocking,
+            timeout=timeout if isBlocking else 0,
+            nResponses=nResponses
+        )
+
+    def scan(self, qid=1, timeout=5, probe_range=False, id_from=1, id_to=127):
+        """
+        Scan the CAN bus for connected devices.
+
+        :param qid: Query ID for the CAN command (default: 1)
+        :param timeout: Timeout for the scan in seconds (default: 5)
+        :param probe_range: if True, additionally SDO-probe node-ids
+            ``id_from..id_to`` for their MAC so brand-new / unrouted nodes are
+            discovered (reported with deviceTypeStr "unrouted"). Absent ids
+            fast-fail on the firmware side. Use this for MAC-keyed provisioning.
+        :param id_from: first node-id to probe when ``probe_range`` is set
+        :param id_to: last node-id to probe when ``probe_range`` is set
+        :return: Response containing scan results with device information.
+                 Reachable nodes are SDO-probed for their firmware build
+                 timestamp (OD 0x2508), version (0x2500) and MAC (0x2509);
+                 the master reports its own identity under the "master" key.
+                 Example: {
+                     "master": {"canId": 1, "build": "Jun 22 2026 14:30:11",
+                                "fwVersion": "UC2-ESP v2.0", "mac": "AA:BB:CC:DD:EE:01"},
+                     "scan": [
+                         {"canId": 10, "deviceType": 0, "deviceTypeStr": "motor",
+                          "status": 0, "statusStr": "idle",
+                          "build": "Jun 22 2026 14:31:02", "fwVersion": "UC2-ESP v2.0",
+                          "mac": "AA:BB:CC:DD:EE:10"},
+                         {"canId": 20, "deviceType": 1, "deviceTypeStr": "laser",
+                          "status": 1, "statusStr": "unreachable"}
+                     ],
+                     "qid": 1,
+                     "count": 2
+                 }
+                 Note: "build"/"fwVersion"/"mac" are only present for nodes that
+                 answered the SDO probe (i.e. statusStr == "idle").
+        """
+        path = "/can_act" #         {"task":"/can_act", "scan": true}
+        payload = {
+            "task": path,
+            "scan": True,
+            "qid": qid
+        }
+        if probe_range:
+            payload["probeRange"] = True
+            payload["from"] = int(id_from)
+            payload["to"] = int(id_to)
+        return self._parent.post_json(
+            path,
+            payload,
+            getReturn=True,
+            timeout=timeout,
+            nResponses=1
+        )
+
+    def discover(self, qid=1, timeout=8, id_from=1, id_to=127):
+        """
+        Discover all nodes on the bus by SDO-probing a node-id range.
+
+        Convenience wrapper around ``scan(probe_range=True, ...)`` — finds nodes
+        that aren't in the master's routing table yet (e.g. freshly flashed
+        boards), reporting their MAC + build info so they can be provisioned by
+        MAC via :meth:`assign_node_id_by_mac`.
+
+        :return: same shape as :meth:`scan`; probed-but-unrouted nodes carry
+            deviceTypeStr "unrouted".
+        """
+        return self.scan(qid=qid, timeout=timeout,
+                         probe_range=True, id_from=id_from, id_to=id_to)
+
+    def get_available_devices(self, timeout=2):
+        """
+        Get list of available CAN devices.
+
+        :param timeout: Timeout for the command in seconds (default: 2)
+        :return: Response containing available CAN IDs and other bus information
+                 Example: {
+                     "input": {"task": "/can_get"},
+                     "address": 1,
+                     "addresspref": 1,
+                     "addressgetcan": 1,
+                     "nonworking": [0,0,0,...],
+                     "available": [20,0,0,...],
+                     "rx": 18,
+                     "tx": 17
+                 }
+        """
+        path = "/can_act"
+        payload = {
+            "task": path,
+            "scan": True
+        }
+        return self._parent.post_json(
+            path,
+            payload,
+            getReturn=True,
+            timeout=timeout,
+            nResponses=2
+        )
+
+    def get_device_build_info(self):
+        """
+        Return per-node firmware build info from the latest scan results.
+
+        :return: dict keyed by CAN id, e.g.
+                 {10: {"build": "Jun 22 2026 14:31:02",
+                       "fwVersion": "UC2-ESP v2.0",
+                       "mac": "AA:BB:CC:DD:EE:10"}}
+                 Only nodes that answered the SDO probe during the last scan()
+                 appear here. Call scan() first to refresh.
+        """
+        info = {}
+        for entry in self.scanResults:
+            cid = entry.get("canId")
+            if cid is None:
+                continue
+            fields = {k: entry[k] for k in ("build", "fwVersion", "mac")
+                      if k in entry}
+            if fields:
+                info[cid] = fields
+        return info
+
+    def set_remote_node_id(self, new_id, target=None, by_mac=None,
+                           expect_mac=None, qid=1, isBlocking=True, timeout=4):
+        """
+        Reassign a remote node's CAN id over the bus (SDO write to OD 0x250A).
+
+        Identify the node EITHER by its current id (``target``, optionally with
+        ``expect_mac`` for a safety check) OR purely by its MAC (``by_mac``), in
+        which case the firmware probes the bus to find which id currently has
+        that MAC — use this when you don't know the current id. ``new_id`` is
+        always the desired new id.
+
+        The slave persists the new id to NVS and performs a CANopen
+        communication reset, so it reappears at ``new_id`` after ~0.3 s.
+
+        :param new_id: desired CAN id (1..127)
+        :param target: current CAN id (1..127) of the node to reconfigure
+        :param by_mac: target MAC "AA:BB:CC:DD:EE:FF" — firmware finds the node
+            (use instead of ``target`` when the current id is unknown)
+        :param expect_mac: when using ``target``, verify the node's MAC matches
+            before committing (id only ever binds to the intended device)
+        :param qid: Query ID (kept for API symmetry)
+        :param isBlocking: wait for the firmware acknowledgement
+        :param timeout: command timeout in seconds
+        :return: firmware response, e.g. ``{"status":"ok","target":60,"newId":70}``
+            or ``{"status":"error","error":"MAC not found on bus","mac":"..."}``
+        """
+        if by_mac is None and target is None:
+            raise ValueError("set_remote_node_id requires either target or by_mac")
+        path = "/can_act"
+        payload = {
+            "task": path,
+            "setRemoteNodeId": int(new_id),
+            "qid": qid,
+        }
+        if by_mac is not None:
+            payload["byMac"] = str(by_mac)
+        else:
+            payload["target"] = int(target)
+            if expect_mac is not None:
+                payload["expectMac"] = str(expect_mac)
+        nResponses = 1 if isBlocking else 0
+        return self._parent.post_json(
+            path,
+            payload,
+            getReturn=isBlocking,
+            timeout=timeout if isBlocking else 0,
+            nResponses=nResponses,
+        )
+
+    def assign_node_id_by_mac(self, mac, new_id, qid=1, timeout=5):
+        """
+        Assign a CAN id to the node with the given MAC address.
+
+        The firmware probes the bus to locate whichever node currently
+        advertises ``mac`` and reassigns it to ``new_id`` in a single round-trip
+        (no need to know the node's current id). This is the canonical
+        MAC-keyed provisioning call.
+
+        :param mac: target MAC as "AA:BB:CC:DD:EE:FF" (case-insensitive)
+        :param new_id: desired CAN id (1..127)
+        :param qid: Query ID
+        :param timeout: request timeout in seconds
+        :return: firmware response, e.g. ``{"status":"ok","target":60,"newId":70,
+            "mac":"..."}`` or ``{"status":"error","error":"MAC not found on bus"}``
+        """
+        return self.set_remote_node_id(new_id, by_mac=mac, qid=qid, timeout=timeout)

uc2_rest-0.2.0.38/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)