bump version to 0.3.11

Author: rodolfo-verde

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.11] — 2026-07-10
+
+### Fixed
+- Always stop running program via Dashboard before RTDE connect (was: only after boot) — handles crashed sessions leaving ExternalControl running
+- RTDE connection retries (2×5s) with clear error message pointing to controller reboot when registers are locked
+- CLI no longer shows misleading "Remote Control not enabled" hint when the real issue is locked RTDE registers
+
 ## [0.3.10] — 2026-07-10
 
 ### Fixed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "urkit"
-version = "0.3.10"
+version = "0.3.11"
 description = "Universal Robots e-Series control toolkit built on ur_rtde"
 readme = "README.md"
 license = {text = "MIT"}

src/urkit/__init__.py

@@ -24,7 +24,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.3.10"
+__version__ = "0.3.11"
 
 from urkit.config import load_config, resolve_config
 from urkit.exceptions import (

src/urkit/cli/teach.py

@@ -1445,7 +1445,7 @@ def teach_command(args) -> None:
             print("  Gripper activated.", flush=True)
     except ConnectionError as e:
         print(f"Connection error: {e}")
-        if "RTDE" in str(e):
+        if "RTDE" in str(e) and "registers are locked" not in str(e):
             print(
                 "\n  The robot is reachable but RTDE could not connect.\n"
                 "  This usually means Remote Control is not enabled.\n"

src/urkit/robot.py

@@ -176,28 +176,45 @@ def __init__(
             time.sleep(5)
 
         # Stop any running program — RTDE cannot upload its control script
-        # while a program is occupying the Secondary Interface. Only needed
-        # after a boot (a program left running by another client is their problem).
-        if boot_needed:
-            try:
-                self._stop_program()
-                time.sleep(2)
-            except ConnectionError:
-                logger.warning(
-                    "[URRobot] Could not stop program via Dashboard. "
-                    "Continuing — RTDE connection may fail if a program is running."
-                )
+        # while a program occupies the Secondary Interface. Always try, since
+        # a previous session may have left ExternalControl running.
+        try:
+            self._stop_program()
+            time.sleep(2)
+        except ConnectionError:
+            logger.warning(
+                "[URRobot] Could not stop program via Dashboard. "
+                "Continuing — RTDE connection may fail if a program is running."
+            )
 
-        # Connect RTDE — retry after boot, the Secondary Interface may need
-        # extra time to accept connections even after the robot is IDLE.
-        rtde_attempts = 2 if boot_needed else 1
+        # Connect RTDE — retry, the Secondary Interface may need time to
+        # release registers after program stop or boot.
+        from urkit.exceptions import RtdeRegisterConflictError
+
+        rtde_attempts = 2
         for attempt in range(1, rtde_attempts + 1):
             try:
                 self._rtde_c, self._rtde_r, self._rtde_io = _connect_rtde(
                     ip,
                     frequency=self._rtde_frequency,
                 )
                 break
+            except RtdeRegisterConflictError as e:
+                if attempt < rtde_attempts:
+                    logger.warning(
+                        "[URRobot] RTDE registers in use (attempt %d/%d). "
+                        "Retrying in 5s...",
+                        attempt,
+                        rtde_attempts,
+                    )
+                    time.sleep(5)
+                else:
+                    raise ConnectionError(
+                        f"RTDE registers are locked on robot at {ip}. "
+                        "A previous session crashed without releasing its connection.\n"
+                        "Fix: fully shut down the robot controller "
+                        "(Settings → System → Shutdown), wait 10s, power on."
+                    ) from e
             except Exception as e:
                 if attempt < rtde_attempts:
                     logger.warning(