Implement Nova API jogging support and enhance UI controls

- Added support for bidirectional jogging control via the Nova API, allowing users to send jogging commands for joint and cartesian movements.
- Enhanced mujoco_server.py to handle new jogging commands and integrate with the Nova API for real-time control.
- Updated the UR5 environment to initialize and manage the NovaJogger for handling jogging operations.
- Improved the UI to include jogging controls for translation and rotation, providing users with intuitive interaction options.
- Enhanced README.md to document the new jogging features and usage modes, including Digital Twin, Nova IK, and Hybrid modes.
- Introduced test scripts for validating Nova API connections and jogging functionality, improving overall reliability and user experience.

README.md

@@ -573,10 +573,20 @@ Nova API integration provides two key features:
    python3 scripts/test_nova_connection.py
    ```
 
+### Usage Modes
+
+Nova API integration supports three distinct modes:
+
+1. **Digital Twin Mode** (State Streaming Only - Recommended): The simulation mirrors a real robot's state. Robot movements come from the physical robot via WebSocket. Local target controls are ignored. This is the default when `.env.local` is detected.
+
+2. **Nova IK Mode** (IK Only): Use Nova's cloud-based IK solver while controlling the simulation robot locally. Useful for validating IK solutions or when you want to use Nova's kinematic model.
+
+3. **Hybrid Mode** (Both): Uses Nova state streaming and Nova IK. Generally not recommended since the real robot is controlled externally.
+
 ### Usage Examples
 
-#### Enable State Streaming Only
-Sync robot state from Nova API (joint positions from real robot):
+#### Digital Twin Mode (State Streaming Only - Default)
+Mirror a real robot's state in the simulation:
 
 ```python
 import os
@@ -598,8 +608,8 @@ env = UR5Env(
     render_mode="human",
     scene_name="scene",
     nova_api_config={
-        "use_state_stream": True,  # Enable state streaming
-        "use_ik": False  # Use local IK
+        "use_state_stream": True,  # Mirror real robot state
+        "use_ik": False  # Real robot controlled externally
     }
 )
 
@@ -610,8 +620,8 @@ for _ in range(1000):
 env.close()
 ```
 
-#### Enable Nova IK Only
-Use Nova's IK solver while keeping local state:
+#### Nova IK Mode (IK Only)
+Use Nova's cloud-based IK solver while controlling the simulation robot locally:
 
 ```python
 env = UR5Env(
@@ -626,19 +636,23 @@ env = UR5Env(
 env.set_target(x=0.4, y=0.2, z=0.6)
 ```
 
-#### Full Integration (Both Features)
-Enable both state streaming and Nova IK:
+#### Hybrid Mode (Not Recommended)
+Enable both state streaming and Nova IK. Generally not useful since the real robot is controlled externally:
 
 ```python
 env = UR5Env(
     render_mode="human",
     nova_api_config={
-        "use_state_stream": True,  # Sync robot state from Nova
-        "use_ik": True  # Use Nova IK
+        "use_state_stream": True,  # Mirror real robot
+        "use_ik": True  # Also use Nova IK (usually not needed)
     }
 )
 ```
 
+**Note**: When state streaming is enabled, the simulation becomes a read-only digital twin that displays the real robot's movements. Local target controls and IK computations are ignored since the robot is controlled by external hardware/software.
+
+**Sending Commands to Robot**: To send motion commands to the real robot through Nova API, use Nova's motion execution endpoints directly (not currently implemented in the web UI). The simulation is designed to visualize robot state, not to command it.
+
 ### Environment Variables Reference
 
 | Variable | Required | Default | Description |

mujoco_server.py

@@ -170,10 +170,15 @@ def init_ur5(scene_name="scene"):
     # Check if Nova API is configured via environment variables
     nova_config = None
     if os.getenv('NOVA_INSTANCE_URL') and os.getenv('NOVA_ACCESS_TOKEN'):
-        print("Nova API configuration detected, enabling state streaming and IK")
+        # Enable state streaming (digital twin mode) and jogging (bidirectional control)
+        # State streaming: simulation shows the real robot's state
+        # Jogging: UI can send directional jog commands to control the real robot
+        # IK is disabled because real robot is controlled via jogging API
+        print("Nova API configuration detected, enabling state streaming and jogging")
         nova_config = {
             "use_state_stream": True,
-            "use_ik": True
+            "use_ik": False,  # Disabled: using jogging API instead
+            "use_jogging": True  # Enable bidirectional robot control
         }
 
     if scene_name == "scene_t_push":
@@ -272,9 +277,11 @@ def broadcast_state():
             use_orientation = env.get_use_orientation()
 
             # Check Nova API status
+            nova_client = getattr(env, '_nova_client', None)
             nova_state_streaming = getattr(env, '_use_nova_state_stream', False)
             nova_ik = getattr(env, '_use_nova_ik', False)
-            nova_connected = getattr(env, '_nova_client', None) is not None
+            # Show connected if client exists (even if first state not received yet)
+            nova_connected = nova_client is not None
 
             state_msg = json.dumps({
                 'type': 'state',
@@ -535,6 +542,22 @@ def handle_ws_message(data):
             if env is not None and current_robot in ("ur5", "ur5_t_push"):
                 env.set_use_orientation(use)
 
+    # Nova jogging commands
+    elif msg_type == 'start_jog':
+        payload = data.get('data', {})
+        jog_type = payload.get('jog_type')
+        jog_params = payload.get('params', {})
+        with mujoco_lock:
+            if env is not None and current_robot in ("ur5", "ur5_t_push"):
+                success = env.start_jog(jog_type, **jog_params)
+                if not success:
+                    print(f"[Server] Failed to start jog: {jog_type}, {jog_params}")
+
+    elif msg_type == 'stop_jog':
+        with mujoco_lock:
+            if env is not None and current_robot in ("ur5", "ur5_t_push"):
+                env.stop_jog()
+
 
 def _serialize_space(space):
     if hasattr(space, "low") and hasattr(space, "high"):
@@ -927,6 +950,55 @@ def index():
             .ik-controls.active, .joint-controls.active { display: block; }
             .joint-sliders .slider-row { margin-bottom: 6px; }
             .joint-sliders label { width: 40px; display: inline-block; font-size: 0.75em; }
+
+            /* Jogging controls */
+            .jog-controls { margin: 10px 0; }
+            .jog-row {
+                display: flex;
+                align-items: center;
+                gap: 8px;
+                margin-bottom: 8px;
+            }
+            .jog-row label {
+                width: 30px;
+                display: inline-block;
+                font-size: 0.85em;
+                text-align: left;
+            }
+            .jog-btn {
+                width: 40px;
+                height: 40px;
+                padding: 0;
+                font-size: 1.5em;
+                font-weight: bold;
+                background: rgba(188, 190, 236, 0.15);
+                color: var(--wb-secondary);
+                border: 1px solid rgba(188, 190, 236, 0.3);
+                border-radius: 6px;
+                cursor: pointer;
+                transition: all 0.15s;
+                user-select: none;
+                -webkit-user-select: none;
+                flex-shrink: 0;
+            }
+            .jog-btn:hover {
+                background: rgba(139, 127, 239, 0.3);
+                border-color: rgba(139, 127, 239, 0.5);
+                transform: scale(1.05);
+            }
+            .jog-btn:active {
+                background: rgba(139, 127, 239, 0.5);
+                border-color: rgba(139, 127, 239, 0.7);
+                transform: scale(0.95);
+            }
+            .jog-row .val-display {
+                flex-grow: 1;
+                width: auto;
+                text-align: center;
+                font-family: monospace;
+                font-size: 0.9em;
+                color: #fff;
+            }
         </style>
     </head>
     <body>
@@ -953,6 +1025,12 @@ def index():
                 Reward: <span id="arm_reward">-</span><br>
                 Mode: <span id="control_mode_display">IK</span> | Steps: <span id="arm_step_val">0</span><br>
                 <div style="margin-top: 8px; padding-top: 8px; border-top: 1px solid rgba(188, 190, 236, 0.2);">
+                    <div id="nova_connection_badge" style="display: none; margin-bottom: 8px; padding: 6px 10px; background: rgba(76, 175, 80, 0.15); border-radius: 4px; border-left: 3px solid var(--wb-success);">
+                        <strong style="font-size: 0.85em; color: var(--wb-success);">🌐 Nova Connected</strong>
+                        <div style="font-size: 0.75em; color: rgba(255, 255, 255, 0.7); margin-top: 2px;">
+                            <span id="nova_mode_text">Digital Twin Mode</span> - Read Only
+                        </div>
+                    </div>
                     <strong style="font-size: 0.9em;">Controllers:</strong><br>
                     <span style="font-size: 0.85em;">
                         State: <span id="nova_state_controller" style="color: var(--wb-highlight);">Internal</span><br>
@@ -1032,87 +1110,107 @@ def index():
                 <!-- IK Controls -->
                 <div class="ik-controls active" id="ik_controls">
                     <div class="control-group">
-                        <label>Target Position (XYZ)</label>
-                        <div class="target-sliders">
-                            <div class="slider-row">
-                                <label>X</label>
-                                <input type="range" id="target_x" min="-0.4" max="1.0" step="0.01" value="0.4" oninput="updateTarget()">
-                                <span class="val-display" id="target_x_val">0.40</span>
+                        <label>Translation (XYZ)</label>
+                        <div class="jog-controls">
+                            <div class="jog-row">
+                                <label style="color: #ff6b6b; font-weight: bold;">X</label>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_translation', 'x', '-')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_translation', 'x', '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
+                                <span class="val-display" id="pos_x_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_translation', 'x', '+')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_translation', 'x', '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
-                                <label>Y</label>
-                                <input type="range" id="target_y" min="-0.8" max="0.8" step="0.01" value="0.0" oninput="updateTarget()">
-                                <span class="val-display" id="target_y_val">0.00</span>
+                            <div class="jog-row">
+                                <label style="color: #51cf66; font-weight: bold;">Y</label>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_translation', 'y', '-')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_translation', 'y', '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
+                                <span class="val-display" id="pos_y_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_translation', 'y', '+')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_translation', 'y', '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
-                                <label>Z</label>
-                                <input type="range" id="target_z" min="0.0" max="1.2" step="0.01" value="0.4" oninput="updateTarget()">
-                                <span class="val-display" id="target_z_val">0.40</span>
+                            <div class="jog-row">
+                                <label style="color: #339af0; font-weight: bold;">Z</label>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_translation', 'z', '-')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_translation', 'z', '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
+                                <span class="val-display" id="pos_z_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_translation', 'z', '+')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_translation', 'z', '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
                         </div>
+                        <div style="margin-top: 8px;">
+                            <label style="font-size: 0.85em;">Velocity: <span id="trans_vel_val">50</span> mm/s</label>
+                            <input type="range" id="trans_velocity" min="10" max="200" step="10" value="50" oninput="updateTransVelocity()" style="width: 100%;">
+                        </div>
                     </div>
                     <div class="control-group">
-                        <label style="display: flex; align-items: center; gap: 8px;">
-                            Target Orientation (RPY)
-                            <input type="checkbox" id="use_orientation" checked onchange="setUseOrientation()">
-                            <span style="font-size: 0.75em; opacity: 0.7;">Enable</span>
-                        </label>
-                        <div class="target-sliders" id="orientation_sliders">
-                            <div class="slider-row">
-                                <label>R</label>
-                                <input type="range" id="target_roll" min="-3.14" max="3.14" step="0.05" value="0.0" oninput="updateOrientation()">
-                                <span class="val-display" id="target_roll_val">0.00</span>
+                        <label>Rotation (RPY)</label>
+                        <div class="jog-controls">
+                            <div class="jog-row">
+                                <label style="color: #ff6b6b; font-weight: bold;">Rx</label>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_rotation', 'x', '-')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_rotation', 'x', '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
+                                <span class="val-display" id="rot_x_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_rotation', 'x', '+')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_rotation', 'x', '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
-                                <label>P</label>
-                                <input type="range" id="target_pitch" min="-3.14" max="3.14" step="0.05" value="1.57" oninput="updateOrientation()">
-                                <span class="val-display" id="target_pitch_val">1.57</span>
+                            <div class="jog-row">
+                                <label style="color: #51cf66; font-weight: bold;">Ry</label>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_rotation', 'y', '-')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_rotation', 'y', '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
+                                <span class="val-display" id="rot_y_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_rotation', 'y', '+')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_rotation', 'y', '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
-                                <label>Y</label>
-                                <input type="range" id="target_yaw" min="-3.14" max="3.14" step="0.05" value="0.0" oninput="updateOrientation()">
-                                <span class="val-display" id="target_yaw_val">0.00</span>
+                            <div class="jog-row">
+                                <label style="color: #339af0; font-weight: bold;">Rz</label>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_rotation', 'z', '-')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_rotation', 'z', '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
+                                <span class="val-display" id="rot_z_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('cartesian_rotation', 'z', '+')" onmouseup="stopJog()" ontouchstart="startJog('cartesian_rotation', 'z', '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
                         </div>
+                        <div style="margin-top: 8px;">
+                            <label style="font-size: 0.85em;">Velocity: <span id="rot_vel_val">0.3</span> rad/s</label>
+                            <input type="range" id="rot_velocity" min="0.1" max="1.0" step="0.1" value="0.3" oninput="updateRotVelocity()" style="width: 100%;">
+                        </div>
                     </div>
                 </div>
 
                 <!-- Joint Controls -->
                 <div class="joint-controls" id="joint_controls">
                     <div class="control-group">
-                        <label>Joint Positions (radians)</label>
-                        <div class="joint-sliders">
-                            <div class="slider-row">
+                        <label>Joint Positions</label>
+                        <div class="jog-controls">
+                            <div class="jog-row">
                                 <label>J1</label>
-                                <input type="range" id="joint_0" min="-6.28" max="6.28" step="0.01" value="-1.5708" oninput="updateJoints()">
+                                <button class="jog-btn" onmousedown="startJog('joint', 1, '-')" onmouseup="stopJog()" ontouchstart="startJog('joint', 1, '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
                                 <span class="val-display" id="joint_0_val">-1.57</span>
+                                <button class="jog-btn" onmousedown="startJog('joint', 1, '+')" onmouseup="stopJog()" ontouchstart="startJog('joint', 1, '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
+                            <div class="jog-row">
                                 <label>J2</label>
-                                <input type="range" id="joint_1" min="-6.28" max="6.28" step="0.01" value="-1.5708" oninput="updateJoints()">
+                                <button class="jog-btn" onmousedown="startJog('joint', 2, '-')" onmouseup="stopJog()" ontouchstart="startJog('joint', 2, '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
                                 <span class="val-display" id="joint_1_val">-1.57</span>
+                                <button class="jog-btn" onmousedown="startJog('joint', 2, '+')" onmouseup="stopJog()" ontouchstart="startJog('joint', 2, '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
+                            <div class="jog-row">
                                 <label>J3</label>
-                                <input type="range" id="joint_2" min="-3.14" max="3.14" step="0.01" value="1.5708" oninput="updateJoints()">
+                                <button class="jog-btn" onmousedown="startJog('joint', 3, '-')" onmouseup="stopJog()" ontouchstart="startJog('joint', 3, '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
                                 <span class="val-display" id="joint_2_val">1.57</span>
+                                <button class="jog-btn" onmousedown="startJog('joint', 3, '+')" onmouseup="stopJog()" ontouchstart="startJog('joint', 3, '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
+                            <div class="jog-row">
                                 <label>J4</label>
-                                <input type="range" id="joint_3" min="-6.28" max="6.28" step="0.01" value="-1.5708" oninput="updateJoints()">
+                                <button class="jog-btn" onmousedown="startJog('joint', 4, '-')" onmouseup="stopJog()" ontouchstart="startJog('joint', 4, '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
                                 <span class="val-display" id="joint_3_val">-1.57</span>
+                                <button class="jog-btn" onmousedown="startJog('joint', 4, '+')" onmouseup="stopJog()" ontouchstart="startJog('joint', 4, '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
+                            <div class="jog-row">
                                 <label>J5</label>
-                                <input type="range" id="joint_4" min="-6.28" max="6.28" step="0.01" value="-1.5708" oninput="updateJoints()">
+                                <button class="jog-btn" onmousedown="startJog('joint', 5, '-')" onmouseup="stopJog()" ontouchstart="startJog('joint', 5, '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
                                 <span class="val-display" id="joint_4_val">-1.57</span>
+                                <button class="jog-btn" onmousedown="startJog('joint', 5, '+')" onmouseup="stopJog()" ontouchstart="startJog('joint', 5, '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
-                            <div class="slider-row">
+                            <div class="jog-row">
                                 <label>J6</label>
-                                <input type="range" id="joint_5" min="-6.28" max="6.28" step="0.01" value="0.0" oninput="updateJoints()">
+                                <button class="jog-btn" onmousedown="startJog('joint', 6, '-')" onmouseup="stopJog()" ontouchstart="startJog('joint', 6, '-'); event.preventDefault()" ontouchend="stopJog()">−</button>
                                 <span class="val-display" id="joint_5_val">0.00</span>
+                                <button class="jog-btn" onmousedown="startJog('joint', 6, '+')" onmouseup="stopJog()" ontouchstart="startJog('joint', 6, '+'); event.preventDefault()" ontouchend="stopJog()">+</button>
                             </div>
                         </div>
+                        <div style="margin-top: 8px;">
+                            <label style="font-size: 0.85em;">Velocity: <span id="joint_vel_val">0.5</span> rad/s</label>
+                            <input type="range" id="joint_velocity" min="0.1" max="2.0" step="0.1" value="0.5" oninput="updateJointVelocity()" style="width: 100%;">
+                        </div>
                         <button style="margin-top: 8px; width: 100%;" onclick="goToHome()">Go to Home Position</button>
                     </div>
                 </div>
@@ -1151,7 +1249,7 @@ def index():
                 'g1': '29 DOF humanoid with RL walking policy',
                 'spot': '12 DOF quadruped with trot gait controller',
                 'ur5': '6 DOF robot arm with Robotiq gripper',
-                'ur5_t_push': 'UR5e T-push task with stick tool (no gripper)'
+                'ur5_t_push': 'UR5e T-push task with stick tool'
             };
 
             const robotTitles = {
@@ -1247,37 +1345,28 @@ def index():
                                     const jp = data.joint_positions;
                                     document.getElementById('joint_pos_display').innerText =
                                         jp.map(j => j.toFixed(2)).join(', ');
-                                }
 
-                                // Sync joint sliders with joint targets (not actual positions)
-                                if (data.joint_targets) {
-                                    const jt = data.joint_targets;
+                                    // Update jog button displays with actual joint positions
                                     for (let i = 0; i < 6; i++) {
-                                        document.getElementById('joint_' + i).value = jt[i];
-                                        document.getElementById('joint_' + i + '_val').innerText = jt[i].toFixed(2);
+                                        document.getElementById('joint_' + i + '_val').innerText = jp[i].toFixed(2);
                                     }
                                 }
 
-                                // Sync IK target sliders with target position (not actual EE)
-                                if (data.target) {
-                                    const target = data.target;
-                                    document.getElementById('target_x').value = target.x;
-                                    document.getElementById('target_x_val').innerText = target.x.toFixed(2);
-                                    document.getElementById('target_y').value = target.y;
-                                    document.getElementById('target_y_val').innerText = target.y.toFixed(2);
-                                    document.getElementById('target_z').value = target.z;
-                                    document.getElementById('target_z_val').innerText = target.z.toFixed(2);
+                                // Update cartesian position displays with actual EE position
+                                if (data.end_effector) {
+                                    const ee = data.end_effector;
+                                    document.getElementById('pos_x_val').innerText = ee.x.toFixed(3);
+                                    document.getElementById('pos_y_val').innerText = ee.y.toFixed(3);
+                                    document.getElementById('pos_z_val').innerText = ee.z.toFixed(3);
                                 }
 
-                                // Sync orientation sliders with target orientation
-                                if (data.target_orientation) {
-                                    const ori = data.target_orientation;
-                                    document.getElementById('target_roll').value = ori.roll;
-                                    document.getElementById('target_roll_val').innerText = ori.roll.toFixed(2);
-                                    document.getElementById('target_pitch').value = ori.pitch;
-                                    document.getElementById('target_pitch_val').innerText = ori.pitch.toFixed(2);
-                                    document.getElementById('target_yaw').value = ori.yaw;
-                                    document.getElementById('target_yaw_val').innerText = ori.yaw.toFixed(2);
+                                // Update rotation displays with actual EE orientation
+                                if (data.ee_orientation) {
+                                    const q = data.ee_orientation;
+                                    const euler = quatToEuler(q.w, q.x, q.y, q.z);
+                                    document.getElementById('rot_x_val').innerText = euler[0].toFixed(2);
+                                    document.getElementById('rot_y_val').innerText = euler[1].toFixed(2);
+                                    document.getElementById('rot_z_val').innerText = euler[2].toFixed(2);
                                 }
 
                                 // Update control mode display
@@ -1290,22 +1379,26 @@ def index():
                                     }
                                 }
 
-                                // Sync use_orientation checkbox
-                                if (data.use_orientation !== undefined) {
-                                    const checkbox = document.getElementById('use_orientation');
-                                    if (checkbox.checked !== data.use_orientation) {
-                                        checkbox.checked = data.use_orientation;
-                                        document.getElementById('orientation_sliders').style.opacity = data.use_orientation ? '1' : '0.4';
-                                    }
-                                }
-
                                 // Update Nova API controller status
                                 if (data.nova_api) {
                                     const stateController = document.getElementById('nova_state_controller');
                                     const ikController = document.getElementById('nova_ik_controller');
+                                    const badge = document.getElementById('nova_connection_badge');
 
                                     if (data.nova_api.connected) {
-                                        // Nova API is connected
+                                        // Nova API is connected - show badge
+                                        badge.style.display = 'block';
+
+                                        // Update badge mode text
+                                        const modeText = document.getElementById('nova_mode_text');
+                                        if (data.nova_api.state_streaming && data.nova_api.ik) {
+                                            modeText.innerText = 'Hybrid Mode';
+                                        } else if (data.nova_api.state_streaming) {
+                                            modeText.innerText = 'Digital Twin Mode';
+                                        } else if (data.nova_api.ik) {
+                                            modeText.innerText = 'Nova IK Mode';
+                                        }
+
                                         if (data.nova_api.state_streaming) {
                                             stateController.innerText = 'Nova API';
                                             stateController.style.color = 'var(--wb-success)';
@@ -1322,7 +1415,8 @@ def index():
                                             ikController.style.color = 'var(--wb-highlight)';
                                         }
                                     } else {
-                                        // Nova API not connected - using internal
+                                        // Nova API not connected - hide badge
+                                        badge.style.display = 'none';
                                         stateController.innerText = 'Internal';
                                         stateController.style.color = 'var(--wb-highlight)';
                                         ikController.innerText = 'Internal';
@@ -1461,49 +1555,69 @@ def index():
                 document.getElementById('joint_controls').classList.toggle('active', mode === 'joint');
             }
 
-            function updateTarget() {
-                const x = parseFloat(document.getElementById('target_x').value);
-                const y = parseFloat(document.getElementById('target_y').value);
-                const z = parseFloat(document.getElementById('target_z').value);
-                document.getElementById('target_x_val').innerText = x.toFixed(2);
-                document.getElementById('target_y_val').innerText = y.toFixed(2);
-                document.getElementById('target_z_val').innerText = z.toFixed(2);
-                send('arm_target', {x, y, z});
+            // Jogging velocities
+            let transVelocity = 50.0;  // mm/s
+            let rotVelocity = 0.3;  // rad/s
+            let jointVelocity = 0.5;  // rad/s
+
+            function updateTransVelocity() {
+                transVelocity = parseFloat(document.getElementById('trans_velocity').value);
+                document.getElementById('trans_vel_val').innerText = transVelocity.toFixed(0);
             }
 
-            function updateOrientation() {
-                const roll = parseFloat(document.getElementById('target_roll').value);
-                const pitch = parseFloat(document.getElementById('target_pitch').value);
-                const yaw = parseFloat(document.getElementById('target_yaw').value);
-                document.getElementById('target_roll_val').innerText = roll.toFixed(2);
-                document.getElementById('target_pitch_val').innerText = pitch.toFixed(2);
-                document.getElementById('target_yaw_val').innerText = yaw.toFixed(2);
-                send('arm_orientation', {roll, pitch, yaw});
+            function updateRotVelocity() {
+                rotVelocity = parseFloat(document.getElementById('rot_velocity').value);
+                document.getElementById('rot_vel_val').innerText = rotVelocity.toFixed(1);
             }
 
-            function setUseOrientation() {
-                const enabled = document.getElementById('use_orientation').checked;
-                document.getElementById('orientation_sliders').style.opacity = enabled ? '1' : '0.4';
-                send('use_orientation', {enabled});
+            function updateJointVelocity() {
+                jointVelocity = parseFloat(document.getElementById('joint_velocity').value);
+                document.getElementById('joint_vel_val').innerText = jointVelocity.toFixed(1);
             }
 
-            function updateJoints() {
-                const positions = [];
-                for (let i = 0; i < 6; i++) {
-                    const val = parseFloat(document.getElementById('joint_' + i).value);
-                    positions.push(val);
-                    document.getElementById('joint_' + i + '_val').innerText = val.toFixed(2);
+            function startJog(jogType, axisOrJoint, direction) {
+                if (jogType === 'cartesian_translation') {
+                    send('start_jog', {
+                        jog_type: 'cartesian_translation',
+                        params: {
+                            axis: axisOrJoint,
+                            direction: direction,
+                            velocity: transVelocity,
+                            tcp_id: 'Flange',
+                            coord_system_id: 'world'
+                        }
+                    });
+                } else if (jogType === 'cartesian_rotation') {
+                    send('start_jog', {
+                        jog_type: 'cartesian_rotation',
+                        params: {
+                            axis: axisOrJoint,
+                            direction: direction,
+                            velocity: rotVelocity,
+                            tcp_id: 'Flange',
+                            coord_system_id: 'world'
+                        }
+                    });
+                } else if (jogType === 'joint') {
+                    // Nova jogger uses 1-based joint indexing
+                    send('start_jog', {
+                        jog_type: 'joint',
+                        params: {
+                            joint: axisOrJoint,  // 1-6
+                            direction: direction,
+                            velocity: jointVelocity
+                        }
+                    });
                 }
-                send('joint_positions', {positions});
+            }
+
+            function stopJog() {
+                send('stop_jog', {});
             }
 
             function goToHome() {
                 // UR5e home position - official MuJoCo Menagerie elbow-up pose
                 const home = [-1.5708, -1.5708, 1.5708, -1.5708, -1.5708, 0.0];
-                for (let i = 0; i < 6; i++) {
-                    document.getElementById('joint_' + i).value = home[i];
-                    document.getElementById('joint_' + i + '_val').innerText = home[i].toFixed(2);
-                }
                 send('joint_positions', {positions: home});
             }
 

robots/ur5/nova_api.py

@@ -109,6 +109,7 @@ class NovaApiClient:
             raise RuntimeError("websockets is required for Nova state streaming")
         if self._state_thread is not None:
             return
+        print("[Nova] Starting state stream thread...")
         self._state_thread = threading.Thread(target=self._state_stream_loop, daemon=True)
         self._state_thread.start()
 
@@ -129,6 +130,10 @@ class NovaApiClient:
                 return None
             return dict(self._latest_state)
 
+    def is_state_stream_connected(self) -> bool:
+        """Check if state stream is connected and receiving data."""
+        return self._state_ws is not None and self._latest_state is not None
+
     def inverse_kinematics(self, position_m, orientation_quat) -> Optional[list]:
         model = self._ensure_motion_group_model()
         if not model:
@@ -200,11 +205,17 @@ class NovaApiClient:
             f"{self.config.controller_id}/motion-groups/{self.config.motion_group_id}/state-stream"
             f"?response_rate={int(self.config.response_rate_ms)}"
         )
+        print(f"[Nova] Connecting to state stream: {url}")
         headers = [("Authorization", f"Bearer {self.config.access_token}")]
         try:
-            return connect(url, open_timeout=10, additional_headers=headers)
+            ws = connect(url, open_timeout=10, additional_headers=headers)
+            print(f"[Nova] State stream connected successfully")
+            return ws
         except TypeError:
-            return connect(url, open_timeout=10, extra_headers=headers)
+            print(f"[Nova] Retrying connection with extra_headers parameter...")
+            ws = connect(url, open_timeout=10, extra_headers=headers)
+            print(f"[Nova] State stream connected successfully")
+            return ws
 
     def _ensure_motion_group_description(self) -> Optional[Dict[str, Any]]:
         if self._motion_group_description is not None:

robots/ur5/nova_jogger.py

@@ -0,0 +1,291 @@
+"""
+Nova Jogger Client
+Handles bidirectional jogging control for Nova API motion groups.
+"""
+
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Optional, Literal, Dict, Any
+
+try:
+    from websockets.sync.client import connect
+except Exception as e:
+    print(f"[Nova Jogger] WARNING: Failed to import websockets: {type(e).__name__}: {e}")
+    connect = None
+
+
+JoggingMode = Literal["joint", "cartesian"]
+JogDirection = Literal["positive", "negative", "+", "-"]  # Accept both formats, normalize to positive/negative
+CartesianAxis = Literal["x", "y", "z"]
+
+
+def _normalize_direction(direction: JogDirection) -> str:
+    """Normalize direction to 'positive' or 'negative' format."""
+    if direction == "+":
+        return "positive"
+    elif direction == "-":
+        return "negative"
+    return direction  # Already positive/negative
+
+
+class NovaJogger:
+    """Manages jogging operations for a Nova motion group."""
+
+    def __init__(self, instance_url: str, access_token: str, cell_id: str,
+                 controller_id: str, motion_group_id: str):
+        self.instance_url = instance_url
+        self.access_token = access_token
+        self.cell_id = cell_id
+        self.controller_id = controller_id
+        self.motion_group_id = motion_group_id
+
+        self._jogger_ws = None
+        self._current_mode: Optional[JoggingMode] = None
+        self._lock = threading.Lock()
+        self._connected = False
+        self._receive_thread = None
+        self._stop_thread = False
+
+    def _receive_loop(self):
+        """Background thread to receive WebSocket messages."""
+        while not self._stop_thread and self._jogger_ws is not None:
+            try:
+                # Receive messages with timeout to allow checking stop flag
+                message = self._jogger_ws.recv(timeout=0.5)
+                if message:
+                    # Parse and handle jogger responses/events if needed
+                    try:
+                        data = json.loads(message)
+                        msg_type = data.get("type")
+                        # Log any errors or important events
+                        if msg_type == "error":
+                            print(f"[Nova Jogger] Error from server: {data.get('message')}")
+                    except json.JSONDecodeError:
+                        pass  # Ignore non-JSON messages
+            except TimeoutError:
+                continue  # Timeout is expected, just loop again
+            except Exception as e:
+                if not self._stop_thread:
+                    print(f"[Nova Jogger] Receive error: {e}")
+                break
+
+    def connect(self) -> bool:
+        """Connect to the jogger WebSocket endpoint."""
+        if connect is None:
+            raise RuntimeError("websockets package required for jogging")
+
+        # Note: We'll connect to specific endpoints when mode is set
+        # This just marks us as ready to connect
+        self._connected = True
+        print("[Nova Jogger] Ready to connect (will connect on first jog command)")
+        return True
+
+    def _ensure_websocket_for_mode(self, mode: JoggingMode, tcp_id: str = "Flange",
+                                    coord_system_id: str = "world") -> bool:
+        """Ensure WebSocket is connected for the specified mode."""
+        if not self._connected:
+            print("[Nova Jogger] Not connected")
+            return False
+
+        # If mode changed, close old websocket
+        if self._current_mode != mode and self._jogger_ws is not None:
+            try:
+                self.stop()
+                self._jogger_ws.close()
+            except:
+                pass
+            self._jogger_ws = None
+            self._current_mode = None
+
+        # Connect to appropriate endpoint if needed
+        if self._jogger_ws is None:
+            try:
+                ws_url = self.instance_url.replace("https://", "wss://").replace("http://", "ws://")
+
+                if mode == "joint":
+                    url = f"{ws_url}/api/v1/cells/{self.cell_id}/motion-groups/move-joint"
+                else:  # cartesian
+                    url = f"{ws_url}/api/v1/cells/{self.cell_id}/motion-groups/move-tcp"
+                    self._tcp_id = tcp_id
+                    self._coord_system_id = coord_system_id
+
+                print(f"[Nova Jogger] Connecting to {mode} endpoint: {url}")
+                headers = [("Authorization", f"Bearer {self.access_token}")]
+                self._jogger_ws = connect(url, open_timeout=10, additional_headers=headers)
+
+                # Start receive loop
+                self._stop_thread = False
+                self._receive_thread = threading.Thread(target=self._receive_loop, daemon=True)
+                self._receive_thread.start()
+
+                self._current_mode = mode
+                print(f"[Nova Jogger] Connected to {mode} endpoint")
+                return True
+
+            except Exception as e:
+                print(f"[Nova Jogger] Failed to connect to {mode} endpoint: {e}")
+                return False
+
+        return True
+
+    def set_jogging_mode(self, mode: JoggingMode, tcp_id: str = "Flange",
+                        coord_system_id: str = "world") -> bool:
+        """Set the jogging mode (joint or cartesian)."""
+        return self._ensure_websocket_for_mode(mode, tcp_id, coord_system_id)
+
+    def start_joint_jog(self, joint: int, direction: JogDirection,
+                       velocity_rads_per_sec: float = 0.5) -> bool:
+        """Start jogging a specific joint using continuous velocity commands."""
+        if not self._ensure_websocket_for_mode("joint"):
+            return False
+
+        try:
+            # Create velocity array with all joints (assume 6 joints for UR5)
+            joint_velocities = [0.0] * 6
+
+            # Set velocity for specified joint based on direction
+            if direction == "+" or direction == "positive":
+                joint_velocities[joint] = velocity_rads_per_sec
+            else:
+                joint_velocities[joint] = -velocity_rads_per_sec
+
+            # Send velocity command (matching nova-js format)
+            command = {
+                "motion_group": self.motion_group_id,
+                "joint_velocities": joint_velocities
+            }
+            self._jogger_ws.send(json.dumps(command))
+            print(f"[Nova Jogger] Joint {joint} jogging at {joint_velocities[joint]:.2f} rad/s")
+            return True
+
+        except Exception as e:
+            print(f"[Nova Jogger] Failed to start joint jog: {e}")
+            return False
+
+    def start_cartesian_translation(self, axis: CartesianAxis, direction: JogDirection,
+                                   velocity_mm_per_sec: float = 50.0,
+                                   tcp_id: str = "Flange",
+                                   coord_system_id: str = "world") -> bool:
+        """Start jogging in cartesian translation using continuous velocity commands."""
+        if not self._ensure_websocket_for_mode("cartesian", tcp_id, coord_system_id):
+            return False
+
+        try:
+            # Create direction vector
+            position_direction = {"x": 0, "y": 0, "z": 0}
+            if direction == "+" or direction == "positive":
+                position_direction[axis] = 1
+            else:
+                position_direction[axis] = -1
+
+            # Send velocity command (matching nova-js format)
+            command = {
+                "motion_group": self.motion_group_id,
+                "position_direction": position_direction,
+                "rotation_direction": {"x": 0, "y": 0, "z": 0},
+                "position_velocity": velocity_mm_per_sec,
+                "rotation_velocity": 0,
+                "tcp": tcp_id,
+                "coordinate_system": coord_system_id
+            }
+            self._jogger_ws.send(json.dumps(command))
+            print(f"[Nova Jogger] Cartesian {axis.upper()} translation at {velocity_mm_per_sec} mm/s (dir: {position_direction[axis]})")
+            return True
+
+        except Exception as e:
+            print(f"[Nova Jogger] Failed to start cartesian translation: {e}")
+            return False
+
+    def start_cartesian_rotation(self, axis: CartesianAxis, direction: JogDirection,
+                                velocity_rads_per_sec: float = 0.3,
+                                tcp_id: str = "Flange",
+                                coord_system_id: str = "world") -> bool:
+        """Start jogging in cartesian rotation using continuous velocity commands."""
+        if not self._ensure_websocket_for_mode("cartesian", tcp_id, coord_system_id):
+            return False
+
+        try:
+            # Create direction vector
+            rotation_direction = {"x": 0, "y": 0, "z": 0}
+            if direction == "+" or direction == "positive":
+                rotation_direction[axis] = 1
+            else:
+                rotation_direction[axis] = -1
+
+            # Send velocity command (matching nova-js format)
+            command = {
+                "motion_group": self.motion_group_id,
+                "position_direction": {"x": 0, "y": 0, "z": 0},
+                "rotation_direction": rotation_direction,
+                "position_velocity": 0,
+                "rotation_velocity": velocity_rads_per_sec,
+                "tcp": tcp_id,
+                "coordinate_system": coord_system_id
+            }
+            self._jogger_ws.send(json.dumps(command))
+            print(f"[Nova Jogger] Cartesian {axis.upper()} rotation at {velocity_rads_per_sec} rad/s (dir: {rotation_direction[axis]})")
+            return True
+
+        except Exception as e:
+            print(f"[Nova Jogger] Failed to start cartesian rotation: {e}")
+            return False
+
+    def stop(self) -> bool:
+        """Stop any active jogging movement by sending zero velocities."""
+        if not self._connected or self._jogger_ws is None:
+            return False
+
+        try:
+            if self._current_mode == "joint":
+                # Send zero velocities for all joints
+                command = {
+                    "motion_group": self.motion_group_id,
+                    "joint_velocities": [0.0] * 6
+                }
+            elif self._current_mode == "cartesian":
+                # Send zero velocities for cartesian
+                command = {
+                    "motion_group": self.motion_group_id,
+                    "position_direction": {"x": 0, "y": 0, "z": 0},
+                    "rotation_direction": {"x": 0, "y": 0, "z": 0},
+                    "position_velocity": 0,
+                    "rotation_velocity": 0,
+                    "tcp": getattr(self, '_tcp_id', 'Flange'),
+                    "coordinate_system": getattr(self, '_coord_system_id', 'world')
+                }
+            else:
+                return False
+
+            self._jogger_ws.send(json.dumps(command))
+            print("[Nova Jogger] Stopped (zero velocities sent)")
+            return True
+
+        except Exception as e:
+            print(f"[Nova Jogger] Failed to stop: {e}")
+            return False
+
+    def disconnect(self):
+        """Disconnect from the jogger."""
+        # Stop the receive thread first
+        self._stop_thread = True
+        if self._receive_thread is not None:
+            self._receive_thread.join(timeout=2.0)
+            self._receive_thread = None
+
+        if self._jogger_ws:
+            try:
+                self.stop()
+                self._jogger_ws.close()
+            except Exception as e:
+                print(f"[Nova Jogger] Error during disconnect: {e}")
+            finally:
+                self._jogger_ws = None
+                self._connected = False
+                self._current_mode = None
+
+    def is_connected(self) -> bool:
+        """Check if jogger is connected."""
+        return self._connected and self._jogger_ws is not None

robots/ur5/ur5_env.py

@@ -18,8 +18,10 @@ IKController = _ik_module.IKController
 
 try:
     import nova_api
+    import nova_jogger
 except Exception:
     nova_api = None
+    nova_jogger = None
 
 
 class UR5Env(gym.Env):
@@ -132,8 +134,10 @@ class UR5Env(gym.Env):
 
         # Initialize Nova API attributes FIRST (before any methods that might call _sync_nova_state)
         self._nova_client = None
+        self._nova_jogger = None
         self._use_nova_state_stream = False
         self._use_nova_ik = False
+        self._use_nova_jogging = False
         self._last_nova_sequence = None
 
         # IK controller for end-effector control
@@ -181,10 +185,11 @@ class UR5Env(gym.Env):
 
         use_state = bool(nova_api_config.get("use_state_stream"))
         use_ik = bool(nova_api_config.get("use_ik"))
-        print(f"[Nova] use_state_stream={use_state}, use_ik={use_ik}")
+        use_jogging = bool(nova_api_config.get("use_jogging"))
+        print(f"[Nova] use_state_stream={use_state}, use_ik={use_ik}, use_jogging={use_jogging}")
 
-        if not (use_state or use_ik):
-            print("[Nova] Neither state streaming nor IK requested, skipping configuration")
+        if not (use_state or use_ik or use_jogging):
+            print("[Nova] Neither state streaming, IK, nor jogging requested, skipping configuration")
             return
 
         try:
@@ -217,19 +222,46 @@ class UR5Env(gym.Env):
             self._nova_client = nova_api.NovaApiClient(config)
             self._use_nova_state_stream = use_state
             self._use_nova_ik = use_ik
-            print(f"[Nova] Client created successfully. State streaming: {use_state}, IK: {use_ik}")
+            self._use_nova_jogging = use_jogging
+            print(f"[Nova] Client created successfully. State streaming: {use_state}, IK: {use_ik}, Jogging: {use_jogging}")
 
             if self._use_nova_state_stream:
                 print("[Nova] Starting state stream...")
                 self._nova_client.start_state_stream()
                 print("[Nova] State stream started successfully")
+                print("[Nova] WARNING: State streaming enabled - simulation is now a digital twin.")
+                print("[Nova]          Robot state comes from Nova API, local targets/IK are ignored.")
+
+            if self._use_nova_jogging:
+                if nova_jogger is None:
+                    print("[Nova] ERROR: Jogging requested but nova_jogger module unavailable")
+                    self._use_nova_jogging = False
+                else:
+                    print("[Nova] Creating NovaJogger...")
+                    self._nova_jogger = nova_jogger.NovaJogger(
+                        instance_url=config.instance_url,
+                        access_token=config.access_token,
+                        cell_id=config.cell_id,
+                        controller_id=config.controller_id,
+                        motion_group_id=config.motion_group_id
+                    )
+                    if self._nova_jogger.connect():
+                        print("[Nova] Jogger connected successfully")
+                        print("[Nova] Jogging enabled - UI can send directional jog commands")
+                    else:
+                        print("[Nova] ERROR: Failed to connect jogger")
+                        self._nova_jogger = None
+                        self._use_nova_jogging = False
+
         except Exception as exc:
             print(f"[Nova] ERROR: Failed to initialize Nova API integration: {exc}")
             import traceback
             traceback.print_exc()
             self._nova_client = None
+            self._nova_jogger = None
             self._use_nova_state_stream = False
             self._use_nova_ik = False
+            self._use_nova_jogging = False
 
     def _reset_freejoint(self, joint_name: str, pos, quat):
         """Reset a freejoint pose by name if it exists."""
@@ -304,6 +336,61 @@ class UR5Env(gym.Env):
         """Get current control mode."""
         return self._control_mode
 
+    def start_jog(self, jog_type: str, **kwargs) -> bool:
+        """Start Nova jogging command.
+
+        Args:
+            jog_type: 'joint', 'cartesian_translation', or 'cartesian_rotation'
+            **kwargs: Parameters for the jog command (joint, axis, direction, velocity, etc.)
+
+        Returns:
+            True if command sent successfully
+        """
+        if not self._use_nova_jogging or self._nova_jogger is None:
+            print("[Nova] Jogging not enabled or jogger not connected")
+            return False
+
+        try:
+            if jog_type == 'joint':
+                return self._nova_jogger.start_joint_jog(
+                    joint=kwargs.get('joint', 0),
+                    direction=kwargs.get('direction', '+'),
+                    velocity_rads_per_sec=kwargs.get('velocity', 0.5)
+                )
+            elif jog_type == 'cartesian_translation':
+                return self._nova_jogger.start_cartesian_translation(
+                    axis=kwargs.get('axis', 'x'),
+                    direction=kwargs.get('direction', '+'),
+                    velocity_mm_per_sec=kwargs.get('velocity', 50.0),
+                    tcp_id=kwargs.get('tcp_id', 'Flange'),
+                    coord_system_id=kwargs.get('coord_system_id', 'world')
+                )
+            elif jog_type == 'cartesian_rotation':
+                return self._nova_jogger.start_cartesian_rotation(
+                    axis=kwargs.get('axis', 'x'),
+                    direction=kwargs.get('direction', '+'),
+                    velocity_rads_per_sec=kwargs.get('velocity', 0.3),
+                    tcp_id=kwargs.get('tcp_id', 'Flange'),
+                    coord_system_id=kwargs.get('coord_system_id', 'world')
+                )
+            else:
+                print(f"[Nova] Unknown jog type: {jog_type}")
+                return False
+        except Exception as e:
+            print(f"[Nova] Error starting jog: {e}")
+            return False
+
+    def stop_jog(self) -> bool:
+        """Stop any active Nova jogging movement."""
+        if not self._use_nova_jogging or self._nova_jogger is None:
+            return False
+
+        try:
+            return self._nova_jogger.stop()
+        except Exception as e:
+            print(f"[Nova] Error stopping jog: {e}")
+            return False
+
     def set_joint_positions(self, positions, update_ik_target=True):
         """Set target joint positions directly (bypasses IK).
 
@@ -473,7 +560,9 @@ class UR5Env(gym.Env):
 
     def step_with_controller(self, dt: float = 0.002):
         """Step using controller (IK or direct joint control)."""
-        if self._use_nova_state_stream and self._sync_nova_state():
+        if self._use_nova_state_stream:
+            # In digital twin mode, always sync from Nova (don't do local control)
+            self._sync_nova_state()
             return self._get_obs()
 
         if self._control_mode == 'ik':
@@ -504,6 +593,9 @@ class UR5Env(gym.Env):
         return None
 
     def close(self):
+        if self._nova_jogger is not None:
+            self._nova_jogger.disconnect()
+            self._nova_jogger = None
         if self._nova_client is not None:
             self._nova_client.stop()
             self._nova_client = None
@@ -542,11 +634,14 @@ class UR5Env(gym.Env):
         if not state:
             return False
 
-        sequence = state.get("sequence_number")
+        # Nova API wraps state in a "result" field
+        result = state.get("result", state)
+
+        sequence = result.get("sequence_number")
         if sequence is not None and sequence == self._last_nova_sequence:
             return False
 
-        joint_positions = state.get("joint_position")
+        joint_positions = result.get("joint_position")
         if not joint_positions or len(joint_positions) < 6:
             return False
 

scripts/test_jogger.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Test Nova Jogger WebSocket connection and commands."""
+
+import os
+import sys
+import time
+import json
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# Load .env.local
+def load_env_file(filepath):
+    """Simple .env file loader."""
+    if not filepath.exists():
+        return {}
+    env_vars = {}
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith('#') and '=' in line:
+                key, value = line.split('=', 1)
+                env_vars[key.strip()] = value.strip()
+                os.environ[key.strip()] = value.strip()
+    return env_vars
+
+
+def main():
+    # Load .env.local
+    env_path = Path(__file__).parent.parent / ".env.local"
+    if not env_path.exists():
+        print(f"Error: {env_path} not found")
+        return 1
+
+    print(f"Loading environment from {env_path}")
+    env_vars = load_env_file(env_path)
+
+    # Try to import websockets
+    try:
+        from websockets.sync.client import connect
+        print("✓ websockets module imported successfully")
+    except ImportError as e:
+        print(f"✗ Failed to import websockets: {e}")
+        print("Install with: pip install websockets")
+        return 1
+
+    # Get config
+    instance_url = os.getenv("NOVA_INSTANCE_URL")
+    access_token = os.getenv("NOVA_ACCESS_TOKEN")
+    cell_id = os.getenv("NOVA_CELL_ID", "cell")
+    motion_group_id = os.getenv("NOVA_MOTION_GROUP_ID")
+
+    if not all([instance_url, access_token, motion_group_id]):
+        print("✗ Missing required environment variables")
+        return 1
+
+    # Convert HTTP to WebSocket URL
+    ws_url = instance_url.replace("https://", "wss://").replace("http://", "ws://")
+
+    # Try nova-js style endpoints (continuous velocity)
+    url_joint = f"{ws_url}/api/v1/cells/{cell_id}/motion-groups/move-joint"
+    url_tcp = f"{ws_url}/api/v1/cells/{cell_id}/motion-groups/move-tcp"
+
+    print(f"\nTesting Nova Jogger WebSocket connection (nova-js style)...")
+    print(f"Joint endpoint: {url_joint}")
+    print(f"TCP endpoint: {url_tcp}")
+    print()
+
+    # Try to connect to joint endpoint
+    headers = [("Authorization", f"Bearer {access_token}")]
+    ws = None
+    url = None
+
+    try:
+        print("Connecting to joint endpoint...")
+        ws = connect(url_joint, open_timeout=10, additional_headers=headers)
+        url = url_joint
+        print("✓ WebSocket connected to joint endpoint successfully!")
+    except Exception as e:
+        print(f"✗ Joint endpoint failed: {e}")
+        print("\nTrying TCP endpoint...")
+        try:
+            ws = connect(url_tcp, open_timeout=10, additional_headers=headers)
+            url = url_tcp
+            print("✓ WebSocket connected to TCP endpoint successfully!")
+        except Exception as e2:
+            print(f"✗ Both endpoints failed. TCP error: {e2}")
+            return 1
+
+    try:
+
+        # Check if server sends an initial message
+        print("\nWaiting for initial server message...")
+        try:
+            initial_msg = ws.recv(timeout=2.0)
+            print(f"  Initial message: {initial_msg}")
+        except TimeoutError:
+            print("  No initial message (timeout)")
+
+        # Test 1: Start joint jogging (nova-js style)
+        if "move-joint" in url:
+            print("\n[Test 1] Starting joint jog (J0+)...")
+            jog_cmd = {
+                "motion_group": motion_group_id,
+                "joint_velocities": [0.1, 0.0, 0.0, 0.0, 0.0, 0.0]
+            }
+            ws.send(json.dumps(jog_cmd))
+            print(f"  Sent: {json.dumps(jog_cmd)}")
+
+            # Try to receive response with timeout
+            try:
+                response = ws.recv(timeout=2.0)
+                print(f"  Response: {response}")
+            except TimeoutError:
+                print("  No response received (timeout after 2s)")
+
+            # Let it jog briefly
+            print("  Jogging for 1 second...")
+            time.sleep(1.0)
+
+            # Test 2: Stop jogging (send zero velocities)
+            print("\n[Test 2] Stopping jog (zero velocities)...")
+            stop_cmd = {
+                "motion_group": motion_group_id,
+                "joint_velocities": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+            }
+            ws.send(json.dumps(stop_cmd))
+            print(f"  Sent: {json.dumps(stop_cmd)}")
+
+            try:
+                response = ws.recv(timeout=2.0)
+                print(f"  Response: {response}")
+            except TimeoutError:
+                print("  No response received (timeout after 2s)")
+
+        else:  # TCP endpoint
+            print("\n[Test 1] Starting TCP translation (X+)...")
+            jog_cmd = {
+                "motion_group": motion_group_id,
+                "position_direction": {"x": 1, "y": 0, "z": 0},
+                "rotation_direction": {"x": 0, "y": 0, "z": 0},
+                "position_velocity": 10.0,
+                "rotation_velocity": 0.0,
+                "tcp": "Flange",
+                "coordinate_system": "world"
+            }
+            ws.send(json.dumps(jog_cmd))
+            print(f"  Sent: {json.dumps(jog_cmd)}")
+
+            # Try to receive response
+            try:
+                response = ws.recv(timeout=2.0)
+                print(f"  Response: {response}")
+            except TimeoutError:
+                print("  No response received (timeout after 2s)")
+
+            # Let it jog briefly
+            print("  Jogging for 1 second...")
+            time.sleep(1.0)
+
+            # Test 2: Stop jogging
+            print("\n[Test 2] Stopping jog (zero velocities)...")
+            stop_cmd = {
+                "motion_group": motion_group_id,
+                "position_direction": {"x": 0, "y": 0, "z": 0},
+                "rotation_direction": {"x": 0, "y": 0, "z": 0},
+                "position_velocity": 0,
+                "rotation_velocity": 0,
+                "tcp": "Flange",
+                "coordinate_system": "world"
+            }
+            ws.send(json.dumps(stop_cmd))
+            print(f"  Sent: {json.dumps(stop_cmd)}")
+
+            try:
+                response = ws.recv(timeout=2.0)
+                print(f"  Response: {response}")
+            except TimeoutError:
+                print("  No response received (timeout after 2s)")
+
+        # Close connection
+        print("\n[Test 3] Closing connection...")
+        ws.close()
+        print("✓ Connection closed successfully")
+
+        print("\n✓ All jogger tests completed!")
+        return 0
+
+    except Exception as e:
+        print(f"✗ Test failed: {type(e).__name__}: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/test_state_stream.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Test Nova API state stream WebSocket connection."""
+
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# Simple .env loader
+def load_env_file(filepath):
+    """Simple .env file loader."""
+    if not filepath.exists():
+        return {}
+    env_vars = {}
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith('#') and '=' in line:
+                key, value = line.split('=', 1)
+                env_vars[key.strip()] = value.strip()
+                os.environ[key.strip()] = value.strip()
+    return env_vars
+
+
+def main():
+    # Load .env.local
+    env_path = Path(__file__).parent.parent / ".env.local"
+    if not env_path.exists():
+        print(f"Error: {env_path} not found")
+        return 1
+
+    print(f"Loading environment from {env_path}")
+    env_vars = load_env_file(env_path)
+
+    # Try to import websockets
+    try:
+        from websockets.sync.client import connect
+        print("✓ websockets module imported successfully")
+    except ImportError as e:
+        print(f"✗ Failed to import websockets: {e}")
+        print("Install with: pip install websockets")
+        return 1
+
+    # Get config
+    instance_url = os.getenv("NOVA_INSTANCE_URL")
+    access_token = os.getenv("NOVA_ACCESS_TOKEN")
+    cell_id = os.getenv("NOVA_CELL_ID", "cell")
+    controller_id = os.getenv("NOVA_CONTROLLER_ID")
+    motion_group_id = os.getenv("NOVA_MOTION_GROUP_ID")
+    response_rate = os.getenv("NOVA_RESPONSE_RATE_MS", "200")
+
+    if not all([instance_url, access_token, controller_id, motion_group_id]):
+        print("✗ Missing required environment variables")
+        return 1
+
+    # Convert HTTP to WebSocket URL
+    ws_url = instance_url.replace("https://", "wss://").replace("http://", "ws://")
+    url = (
+        f"{ws_url}/api/v2/cells/{cell_id}/controllers/"
+        f"{controller_id}/motion-groups/{motion_group_id}/state-stream"
+        f"?response_rate={response_rate}"
+    )
+
+    print(f"\nTesting WebSocket state stream connection...")
+    print(f"URL: {url}")
+    print()
+
+    # Try to connect
+    headers = [("Authorization", f"Bearer {access_token}")]
+    try:
+        print("Connecting...")
+        ws = connect(url, open_timeout=10, additional_headers=headers)
+        print("✓ WebSocket connected successfully!")
+
+        print("\nReceiving messages (will stop after 5 messages)...")
+        count = 0
+        for message in ws:
+            count += 1
+            print(f"Message {count}: {len(message)} bytes")
+            if count >= 5:
+                break
+
+        ws.close()
+        print("\n✓ State stream test successful!")
+        return 0
+
+    except Exception as e:
+        print(f"✗ Connection failed: {type(e).__name__}: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_nova_api.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Unit tests for Nova API client."""
+
+import os
+import sys
+import time
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch, MagicMock
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# Load .env.local for tests
+def load_env_file(filepath):
+    """Simple .env file loader."""
+    if not filepath.exists():
+        return {}
+    env_vars = {}
+    with open(filepath, 'r') as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith('#') and '=' in line:
+                key, value = line.split('=', 1)
+                env_vars[key.strip()] = value.strip()
+                os.environ[key.strip()] = value.strip()
+    return env_vars
+
+env_path = Path(__file__).parent.parent / ".env.local"
+if env_path.exists():
+    load_env_file(env_path)
+
+from robots.ur5 import nova_api
+
+
+class TestNovaApiConfig(unittest.TestCase):
+    """Test Nova API configuration."""
+
+    def test_config_from_env(self):
+        """Test creating config from environment variables."""
+        # Should succeed if .env.local is properly configured
+        try:
+            config = nova_api.NovaApiConfig.from_env()
+            self.assertIsNotNone(config.instance_url)
+            self.assertIsNotNone(config.access_token)
+            self.assertIsNotNone(config.controller_id)
+            self.assertIsNotNone(config.motion_group_id)
+            print(f"✓ Config created: {config.instance_url}")
+        except ValueError as e:
+            self.skipTest(f"Skipping: {e}")
+
+    def test_config_validation(self):
+        """Test config validation with missing variables."""
+        with patch.dict(os.environ, {}, clear=True):
+            with self.assertRaises(ValueError) as ctx:
+                nova_api.NovaApiConfig.from_env()
+            self.assertIn("Missing required environment variables", str(ctx.exception))
+
+
+class TestNovaApiClient(unittest.TestCase):
+    """Test Nova API client functionality."""
+
+    @classmethod
+    def setUpClass(cls):
+        """Set up test fixtures."""
+        try:
+            cls.config = nova_api.NovaApiConfig.from_env()
+            cls.skip_integration = False
+        except ValueError:
+            cls.skip_integration = True
+
+    def test_client_creation(self):
+        """Test creating Nova API client."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        client = nova_api.NovaApiClient(self.config)
+        self.assertIsNotNone(client)
+        self.assertEqual(client.config, self.config)
+        print("✓ Client created successfully")
+
+    def test_motion_group_description(self):
+        """Test fetching motion group description."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        client = nova_api.NovaApiClient(self.config)
+        description = client._ensure_motion_group_description()
+
+        self.assertIsNotNone(description)
+        self.assertIn("tcps", description)
+        print(f"✓ Motion group description: {description.get('motion_group_model')}")
+        print(f"  Available TCPs: {list(description.get('tcps', {}).keys())}")
+
+    def test_inverse_kinematics(self):
+        """Test inverse kinematics computation."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        client = nova_api.NovaApiClient(self.config)
+
+        # Test IK for a reachable position
+        position = [0.4, 0.0, 0.4]  # meters
+        orientation = [1.0, 0.0, 0.0, 0.0]  # quaternion (w, x, y, z)
+
+        start = time.time()
+        solution = client.inverse_kinematics(position, orientation)
+        duration = time.time() - start
+
+        self.assertIsNotNone(solution)
+        self.assertEqual(len(solution), 6)
+        print(f"✓ IK solution computed in {duration*1000:.1f}ms")
+        print(f"  Joint angles: {[f'{j:.3f}' for j in solution]}")
+
+    def test_state_stream_connection(self):
+        """Test state stream WebSocket connection."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        # Check if websockets is available
+        try:
+            from websockets.sync.client import connect
+        except ImportError:
+            self.skipTest("websockets package not installed")
+
+        client = nova_api.NovaApiClient(self.config)
+
+        # Start state stream
+        print("  Starting state stream...")
+        start = time.time()
+        client.start_state_stream()
+
+        # Wait for first state (with timeout)
+        timeout = 5.0
+        while time.time() - start < timeout:
+            state = client.get_latest_state()
+            if state is not None:
+                duration = time.time() - start
+                print(f"✓ State stream connected in {duration*1000:.1f}ms")
+                print(f"  Received state with {len(state)} fields")
+
+                # Check for expected fields (Nova API wraps in "result")
+                result = state.get("result", state)
+                self.assertIn("joint_position", result)
+                joints = result["joint_position"]
+                print(f"  Joint positions: {[f'{j:.3f}' for j in joints[:6]]}")
+
+                client.stop()
+                return
+            time.sleep(0.1)
+
+        client.stop()
+        self.fail(f"No state received within {timeout}s")
+
+    def test_state_stream_non_blocking(self):
+        """Test that state stream doesn't block main thread."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        try:
+            from websockets.sync.client import connect
+        except ImportError:
+            self.skipTest("websockets package not installed")
+
+        client = nova_api.NovaApiClient(self.config)
+
+        # Measure time to start stream (should be very fast if non-blocking)
+        start = time.time()
+        client.start_state_stream()
+        duration = time.time() - start
+
+        # Should complete in under 1 second (0.5s sleep + overhead)
+        self.assertLess(duration, 1.0,
+                       f"State stream start took {duration}s, should be < 1s")
+        print(f"✓ State stream started in {duration*1000:.1f}ms (non-blocking)")
+
+        # Verify we can do other work immediately
+        start = time.time()
+        for _ in range(10):
+            time.sleep(0.01)
+        work_duration = time.time() - start
+
+        self.assertLess(work_duration, 0.2, "Main thread was blocked")
+        print(f"✓ Main thread remained responsive ({work_duration*1000:.1f}ms for 10x10ms sleeps)")
+
+        client.stop()
+
+
+class TestNovaApiPerformance(unittest.TestCase):
+    """Test performance characteristics."""
+
+    @classmethod
+    def setUpClass(cls):
+        """Set up test fixtures."""
+        try:
+            cls.config = nova_api.NovaApiConfig.from_env()
+            cls.skip_integration = False
+        except ValueError:
+            cls.skip_integration = True
+
+    def test_ik_latency(self):
+        """Measure IK computation latency."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        client = nova_api.NovaApiClient(self.config)
+
+        # Warm up (first request may be slower)
+        client.inverse_kinematics([0.4, 0.0, 0.4], [1.0, 0.0, 0.0, 0.0])
+
+        # Measure multiple IK calls
+        latencies = []
+        for i in range(10):
+            # Vary the position slightly
+            pos = [0.4 + i*0.01, 0.0, 0.4]
+            start = time.time()
+            solution = client.inverse_kinematics(pos, [1.0, 0.0, 0.0, 0.0])
+            latency = time.time() - start
+            latencies.append(latency)
+            self.assertIsNotNone(solution)
+
+        avg_latency = sum(latencies) / len(latencies)
+        max_latency = max(latencies)
+
+        print(f"✓ IK latency: avg={avg_latency*1000:.1f}ms, max={max_latency*1000:.1f}ms")
+
+        # Warn if latency is high
+        if avg_latency > 0.5:
+            print(f"  WARNING: High IK latency may affect real-time performance")
+
+    def test_state_stream_rate(self):
+        """Measure state stream update rate."""
+        if self.skip_integration:
+            self.skipTest("No Nova configuration available")
+
+        try:
+            from websockets.sync.client import connect
+        except ImportError:
+            self.skipTest("websockets package not installed")
+
+        client = nova_api.NovaApiClient(self.config)
+        client.start_state_stream()
+
+        # Wait for stream to stabilize
+        time.sleep(1.0)
+
+        # Collect timestamps of state updates
+        timestamps = []
+        prev_state = None
+
+        for _ in range(20):  # Collect 20 updates
+            state = client.get_latest_state()
+            if state is not None and state != prev_state:
+                timestamps.append(time.time())
+                prev_state = dict(state)  # Make a copy
+            time.sleep(0.05)  # Check every 50ms
+
+        client.stop()
+
+        # Calculate update intervals
+        if len(timestamps) >= 2:
+            intervals = [timestamps[i+1] - timestamps[i]
+                        for i in range(len(timestamps)-1)]
+            avg_interval = sum(intervals) / len(intervals)
+            rate = 1.0 / avg_interval if avg_interval > 0 else 0
+
+            print(f"✓ State stream rate: {rate:.1f} Hz (interval={avg_interval*1000:.1f}ms)")
+            print(f"  Expected: ~{1000/self.config.response_rate_ms:.1f} Hz")
+        else:
+            self.fail(f"Only received {len(timestamps)} state updates")
+
+
+def run_tests():
+    """Run all tests and print summary."""
+    # Create test suite
+    loader = unittest.TestLoader()
+    suite = unittest.TestSuite()
+
+    suite.addTests(loader.loadTestsFromTestCase(TestNovaApiConfig))
+    suite.addTests(loader.loadTestsFromTestCase(TestNovaApiClient))
+    suite.addTests(loader.loadTestsFromTestCase(TestNovaApiPerformance))
+
+    # Run tests with verbose output
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(suite)
+
+    # Print summary
+    print("\n" + "=" * 60)
+    if result.wasSuccessful():
+        print("✓ ALL TESTS PASSED")
+    else:
+        print("✗ SOME TESTS FAILED")
+        if result.failures:
+            print(f"  Failures: {len(result.failures)}")
+        if result.errors:
+            print(f"  Errors: {len(result.errors)}")
+    print("=" * 60)
+
+    return 0 if result.wasSuccessful() else 1
+
+
+if __name__ == "__main__":
+    sys.exit(run_tests())