python-ecosys/debugpy: Add VS Code debugging support for MicroPython.

This adds a minimal port of debugpy that enables VS Code debugging of
MicroPython applications using the Debug Adapter Protocol (DAP).

Features implemented:
- DAP protocol support for VS Code integration
- Line breakpoints with verification
- Step over/into/out debugging operations
- Stack trace inspection with frame navigation
- Variable inspection (locals and globals scopes)
- Expression evaluation in debugging context
- Network communication via TCP socket listener

The implementation integrates with MicroPython's sys.settrace functionality
and provides a familiar debugging experience similar to CPython debugpy.

Usage:
  import debugpy
  debugpy.listen()  # Start debug server
  debugpy.debug_this_thread()  # Enable debugging
  # Connect VS Code debugger to 127.0.0.1:5678

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: pi-anl

python-ecosys/debugpy/README.md

@@ -0,0 +1,171 @@
+# MicroPython debugpy
+
+A minimal implementation of debugpy for MicroPython, enabling VS Code debugging support.
+
+## Features
+
+- Debug Adapter Protocol (DAP) support for VS Code integration
+- Basic debugging operations:
+  - Breakpoints
+  - Step over/into/out
+  - Stack trace inspection
+  - Variable inspection (locals and globals)
+  - Expression evaluation
+  - Pause/continue execution
+
+## Requirements
+
+- MicroPython with `sys.settrace` support (enabled in Unix coverage build)
+- Socket support for network communication
+- JSON support for DAP message parsing
+
+## Usage
+
+### Basic Usage
+
+```python
+import debugpy
+
+# Start listening for debugger connections
+host, port = debugpy.listen()  # Default: 127.0.0.1:5678
+print(f"Debugger listening on {host}:{port}")
+
+# Enable debugging for current thread
+debugpy.debug_this_thread()
+
+# Your code here...
+def my_function():
+    x = 10
+    y = 20
+    result = x + y  # Set breakpoint here in VS Code
+    return result
+
+result = my_function()
+print(f"Result: {result}")
+
+# Manual breakpoint
+debugpy.breakpoint()
+```
+
+### VS Code Configuration
+
+Create a `.vscode/launch.json` file in your project:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Attach to MicroPython",
+            "type": "python",
+            "request": "attach",
+            "connect": {
+                "host": "127.0.0.1",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ],
+            "justMyCode": false
+        }
+    ]
+}
+```
+
+### Testing
+
+1. Build the MicroPython Unix coverage port:
+   ```bash
+   cd ports/unix
+   make VARIANT=coverage
+   ```
+
+2. Run the test script:
+   ```bash
+   cd lib/micropython-lib/python-ecosys/debugpy
+   ../../../../ports/unix/build-coverage/micropython test_debugpy.py
+   ```
+
+3. In VS Code, open the debugpy folder and press F5 to attach the debugger
+
+4. Set breakpoints in the test script and observe debugging functionality
+
+## API Reference
+
+### `debugpy.listen(port=5678, host="127.0.0.1")`
+
+Start listening for debugger connections.
+
+**Parameters:**
+- `port`: Port number to listen on (default: 5678)
+- `host`: Host address to bind to (default: "127.0.0.1")
+
+**Returns:** Tuple of (host, port) actually used
+
+### `debugpy.debug_this_thread()`
+
+Enable debugging for the current thread by installing the trace function.
+
+### `debugpy.breakpoint()`
+
+Trigger a manual breakpoint that will pause execution if a debugger is attached.
+
+### `debugpy.wait_for_client()`
+
+Wait for the debugger client to connect and initialize.
+
+### `debugpy.is_client_connected()`
+
+Check if a debugger client is currently connected.
+
+**Returns:** Boolean indicating connection status
+
+### `debugpy.disconnect()`
+
+Disconnect from the debugger client and clean up resources.
+
+## Architecture
+
+The implementation consists of several key components:
+
+1. **Public API** (`public_api.py`): Main entry points for users
+2. **Debug Session** (`server/debug_session.py`): Handles DAP protocol communication
+3. **PDB Adapter** (`server/pdb_adapter.py`): Bridges DAP and MicroPython's trace system
+4. **Messaging** (`common/messaging.py`): JSON message handling for DAP
+5. **Constants** (`common/constants.py`): DAP protocol constants
+
+## Limitations
+
+This is a minimal implementation with the following limitations:
+
+- Single-threaded debugging only
+- No conditional breakpoints
+- No function breakpoints
+- Limited variable inspection (no nested object expansion)
+- No step back functionality
+- No hot code reloading
+- Simplified stepping implementation
+
+## Compatibility
+
+Tested with:
+- MicroPython Unix port (coverage variant)
+- VS Code with Python extension
+- CPython 3.x (for comparison)
+
+## Contributing
+
+This implementation provides a foundation for MicroPython debugging. Contributions are welcome to add:
+
+- Conditional breakpoint support
+- Better variable inspection
+- Multi-threading support
+- Performance optimizations
+- Additional DAP features
+
+## License
+
+MIT License - see the MicroPython project license for details.

python-ecosys/debugpy/debugpy/__init__.py

@@ -0,0 +1,20 @@
+"""MicroPython debugpy implementation.
+
+A minimal port of debugpy for MicroPython to enable VS Code debugging support.
+This implementation focuses on the core DAP (Debug Adapter Protocol) functionality
+needed for basic debugging operations like breakpoints, stepping, and variable inspection.
+"""
+
+__version__ = "0.1.0"
+
+from .public_api import listen, wait_for_client, breakpoint, debug_this_thread
+from .common.constants import DEFAULT_HOST, DEFAULT_PORT
+
+__all__ = [
+    "listen",
+    "wait_for_client", 
+    "breakpoint",
+    "debug_this_thread",
+    "DEFAULT_HOST",
+    "DEFAULT_PORT",
+]

python-ecosys/debugpy/debugpy/common/__init__.py

@@ -0,0 +1 @@
+# Common utilities and constants for debugpy

python-ecosys/debugpy/debugpy/common/constants.py

@@ -0,0 +1,57 @@
+"""Constants used throughout debugpy."""
+
+# Default networking settings
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 5678
+
+# DAP message types
+MSG_TYPE_REQUEST = "request"
+MSG_TYPE_RESPONSE = "response"
+MSG_TYPE_EVENT = "event"
+
+# DAP events
+EVENT_INITIALIZED = "initialized"
+EVENT_STOPPED = "stopped"
+EVENT_CONTINUED = "continued"
+EVENT_THREAD = "thread"
+EVENT_BREAKPOINT = "breakpoint"
+EVENT_OUTPUT = "output"
+EVENT_TERMINATED = "terminated"
+EVENT_EXITED = "exited"
+
+# DAP commands
+CMD_INITIALIZE = "initialize"
+CMD_LAUNCH = "launch"
+CMD_ATTACH = "attach"
+CMD_SET_BREAKPOINTS = "setBreakpoints"
+CMD_CONTINUE = "continue"
+CMD_NEXT = "next"
+CMD_STEP_IN = "stepIn"
+CMD_STEP_OUT = "stepOut"
+CMD_PAUSE = "pause"
+CMD_STACK_TRACE = "stackTrace"
+CMD_SCOPES = "scopes"
+CMD_VARIABLES = "variables"
+CMD_EVALUATE = "evaluate"
+CMD_DISCONNECT = "disconnect"
+
+# Stop reasons
+STOP_REASON_STEP = "step"
+STOP_REASON_BREAKPOINT = "breakpoint"
+STOP_REASON_EXCEPTION = "exception"
+STOP_REASON_PAUSE = "pause"
+STOP_REASON_ENTRY = "entry"
+
+# Thread reasons
+THREAD_REASON_STARTED = "started"
+THREAD_REASON_EXITED = "exited"
+
+# Trace events
+TRACE_CALL = "call"
+TRACE_LINE = "line"
+TRACE_RETURN = "return"
+TRACE_EXCEPTION = "exception"
+
+# Scope types
+SCOPE_LOCALS = "locals"
+SCOPE_GLOBALS = "globals"

python-ecosys/debugpy/debugpy/common/messaging.py

@@ -0,0 +1,127 @@
+"""JSON message handling for DAP protocol."""
+
+import json
+import socket
+from .constants import MSG_TYPE_REQUEST, MSG_TYPE_RESPONSE, MSG_TYPE_EVENT
+
+
+class JsonMessageChannel:
+    """Handles JSON message communication over a socket using DAP format."""
+    
+    def __init__(self, sock):
+        self.sock = sock
+        self.seq = 0
+        self.closed = False
+        self._recv_buffer = b""
+        
+    def send_message(self, msg_type, command=None, **kwargs):
+        """Send a DAP message."""
+        if self.closed:
+            return
+            
+        self.seq += 1
+        message = {
+            "seq": self.seq,
+            "type": msg_type,
+        }
+        
+        if command:
+            if msg_type == MSG_TYPE_REQUEST:
+                message["command"] = command
+                if kwargs:
+                    message["arguments"] = kwargs
+            elif msg_type == MSG_TYPE_RESPONSE:
+                message["command"] = command
+                message["request_seq"] = kwargs.get("request_seq", 0)
+                message["success"] = kwargs.get("success", True)
+                if "body" in kwargs:
+                    message["body"] = kwargs["body"]
+                if "message" in kwargs:
+                    message["message"] = kwargs["message"]
+            elif msg_type == MSG_TYPE_EVENT:
+                message["event"] = command
+                if kwargs:
+                    message["body"] = kwargs
+        
+        json_str = json.dumps(message)
+        content = json_str.encode("utf-8")
+        header = f"Content-Length: {len(content)}\r\n\r\n".encode("utf-8")
+        
+        try:
+            self.sock.send(header + content)
+        except OSError:
+            self.closed = True
+            
+    def send_request(self, command, **kwargs):
+        """Send a request message."""
+        self.send_message(MSG_TYPE_REQUEST, command, **kwargs)
+        
+    def send_response(self, command, request_seq, success=True, body=None, message=None):
+        """Send a response message."""
+        kwargs = {"request_seq": request_seq, "success": success}
+        if body is not None:
+            kwargs["body"] = body
+        if message is not None:
+            kwargs["message"] = message
+        self.send_message(MSG_TYPE_RESPONSE, command, **kwargs)
+        
+    def send_event(self, event, **kwargs):
+        """Send an event message."""
+        self.send_message(MSG_TYPE_EVENT, event, **kwargs)
+        
+    def recv_message(self):
+        """Receive a DAP message."""
+        if self.closed:
+            return None
+            
+        try:
+            # Read headers
+            while b"\r\n\r\n" not in self._recv_buffer:
+                data = self.sock.recv(1024)
+                if not data:
+                    self.closed = True
+                    return None
+                self._recv_buffer += data
+                
+            header_end = self._recv_buffer.find(b"\r\n\r\n")
+            header_str = self._recv_buffer[:header_end].decode("utf-8")
+            self._recv_buffer = self._recv_buffer[header_end + 4:]
+            
+            # Parse Content-Length
+            content_length = 0
+            for line in header_str.split("\r\n"):
+                if line.startswith("Content-Length:"):
+                    content_length = int(line.split(":", 1)[1].strip())
+                    break
+                    
+            if content_length == 0:
+                return None
+                
+            # Read body
+            while len(self._recv_buffer) < content_length:
+                data = self.sock.recv(content_length - len(self._recv_buffer))
+                if not data:
+                    self.closed = True
+                    return None
+                self._recv_buffer += data
+                
+            body = self._recv_buffer[:content_length]
+            self._recv_buffer = self._recv_buffer[content_length:]
+            
+            # Parse JSON
+            try:
+                return json.loads(body.decode("utf-8"))
+            except (ValueError, UnicodeDecodeError):
+                return None
+                
+        except OSError:
+            self.closed = True
+            return None
+            
+    def close(self):
+        """Close the channel."""
+        self.closed = True
+        try:
+            self.sock.close()
+        except OSError:
+            pass