Add Docker backend support for MicroPython execution without hardware

readme.md

@@ -61,6 +61,48 @@ For the source please refer to the samples folder
 Recommended : install stubs for your MCU of choice
 - [ ] Install stubs for MicroPython syntax checking `pip install micropython-rp2-stubs` (or your port of choise)
 
+### Docker Backend Support (New!)
+
+**For users without physical hardware**, micropython-magic now supports running MicroPython code in Docker containers:
+
+```bash
+# Install Docker support
+pip install -U "micropython-magic[widgets]" docker
+
+# Ensure Docker is running
+docker --version
+```
+
+Use the Docker backend in your notebooks:
+```python
+# Load the extension
+%load_ext micropython_magic
+
+# Run MicroPython in Docker instead of physical hardware
+%%micropython --backend docker
+print("Hello from MicroPython in Docker!")
+import sys
+print(f"Running: {sys.version}")
+```
+
+**Benefits of Docker Backend:**
+- ✅ **No hardware required** - Perfect for learning and development
+- ✅ **Consistent environment** - Same MicroPython version across machines  
+- ✅ **Easy setup** - Just requires Docker installation
+- ✅ **CI/CD friendly** - Can be used in automated testing
+- ✅ **Safe experimentation** - No risk of damaging hardware
+
+**Limitations:**
+- ❌ No GPIO/hardware access (no `machine` module functionality)
+- ❌ No hardware-specific features (WiFi, sensors, etc.)
+- ℹ️ Variables don't persist between cells (each execution is independent)
+
+The Docker backend uses the official `micropython/unix:latest` image and is ideal for:
+- Learning MicroPython syntax and concepts
+- Algorithm development and testing  
+- Code validation before deployment to hardware
+- Educational environments and workshops
+
 ## Usage
 
 **1) Create a notebook**
@@ -113,6 +155,7 @@ Please refer to the [samples folder](samples/) for more examples
 1. [board_control](samples/board_control.ipynb) - basic board control
 1. [board_selection.](samples/board_selection.ipynb) - list connected boards and loop through them
 1. [device_info](samples/device_info.ipynb) - Get simple access to port, board and hardware and firmware information
+1. [**Docker Backend Demo**](samples/docker_backend_demo.ipynb) - 🆕 Run MicroPython in Docker containers (no hardware required)
 1. [WOKWI](samples/wokwi.ipynb) - Use MicroPython magic with WOKWI as a simulator (no device needed)
 1. [Plot rp2 CPU temp](samples/plot_cpu_temp_rp2.ipynb) - create a plot of the CPU temperature of a rp2040 MCU(bqplot)
 1. [Display Memory Map](samples/mem_info.ipynb) - Micropython memory map visualizer

samples/docker_backend_demo.ipynb

@@ -0,0 +1,310 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# MicroPython Magic with Docker Backend\n",
+    "\n",
+    "This notebook demonstrates the new Docker backend support for micropython-magic, allowing you to run MicroPython code in Docker containers instead of requiring physical hardware.\n",
+    "\n",
+    "## Setup\n",
+    "\n",
+    "First, load the micropython magic extension:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext micropython_magic"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Basic Docker Backend Usage\n",
+    "\n",
+    "Use the `--backend docker` parameter to run MicroPython code in a Docker container using the `micropython/unix:latest` image:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%micropython --backend docker\n",
+    "print(\"Hello from MicroPython in Docker!\")\n",
+    "print(f\"Running on platform: {__name__}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## System Information\n",
+    "\n",
+    "Get information about the MicroPython environment running in Docker:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%micropython --backend docker --info"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## MicroPython Features\n",
+    "\n",
+    "Test MicroPython-specific functionality:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%micropython --backend docker\n",
+    "import sys\n",
+    "print(f\"MicroPython version: {sys.version}\")\n",
+    "print(f\"Platform: {sys.platform}\")\n",
+    "print(f\"Implementation: {sys.implementation.name}\")\n",
+    "\n",
+    "# Test some basic operations\n",
+    "numbers = [1, 2, 3, 4, 5]\n",
+    "squared = [x**2 for x in numbers]\n",
+    "print(f\"Squares: {squared}\")\n",
+    "\n",
+    "# Test dictionary operations\n",
+    "data = {'name': 'MicroPython', 'type': 'interpreter', 'container': 'docker'}\n",
+    "for key, value in data.items():\n",
+    "    print(f\"{key}: {value}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Mathematical Operations\n",
+    "\n",
+    "Test mathematical operations and imports:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%micropython --backend docker\n",
+    "import math\n",
+    "\n",
+    "# Test mathematical operations\n",
+    "angle = math.pi / 4\n",
+    "print(f\"sin(π/4) = {math.sin(angle):.6f}\")\n",
+    "print(f\"cos(π/4) = {math.cos(angle):.6f}\")\n",
+    "print(f\"sqrt(2) = {math.sqrt(2):.6f}\")\n",
+    "\n",
+    "# Test some calculations\n",
+    "factorial_5 = 1\n",
+    "for i in range(1, 6):\n",
+    "    factorial_5 *= i\n",
+    "print(f\"5! = {factorial_5}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Line Magic Examples\n",
+    "\n",
+    "Use line magic for quick expressions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%micropython --backend docker print(\"Quick hello from line magic!\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%micropython --backend docker --eval \"2**10\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%micropython --backend docker --eval \"[x*2 for x in range(5)]\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## JSON and Data Structures\n",
+    "\n",
+    "Test JSON handling and complex data structures:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%micropython --backend docker\n",
+    "import json\n",
+    "\n",
+    "# Create a complex data structure\n",
+    "data = {\n",
+    "    'project': 'micropython-magic',\n",
+    "    'backend': 'docker',\n",
+    "    'features': ['container execution', 'no hardware required', 'easy setup'],\n",
+    "    'numbers': [1, 2, 3.14, 42],\n",
+    "    'metadata': {\n",
+    "        'version': '1.0',\n",
+    "        'author': 'micropython-magic'\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "# Convert to JSON and back\n",
+    "json_str = json.dumps(data)\n",
+    "print(f\"JSON length: {len(json_str)}\")\n",
+    "\n",
+    "parsed = json.loads(json_str)\n",
+    "print(f\"Project: {parsed['project']}\")\n",
+    "print(f\"Features: {', '.join(parsed['features'])}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Error Handling\n",
+    "\n",
+    "Test how errors are handled in the Docker backend:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%micropython --backend docker\n",
+    "# This should work\n",
+    "try:\n",
+    "    result = 10 / 2\n",
+    "    print(f\"10 / 2 = {result}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"Error: {e}\")\n",
+    "\n",
+    "# This will cause an error but should be handled\n",
+    "try:\n",
+    "    result = 10 / 0\n",
+    "    print(f\"This won't print\")\n",
+    "except ZeroDivisionError as e:\n",
+    "    print(f\"Caught division by zero: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Custom Docker Image\n",
+    "\n",
+    "You can specify a custom Docker image if needed:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%micropython --backend docker --docker-image micropython/unix:latest\n",
+    "print(\"Using explicitly specified micropython/unix:latest image\")\n",
+    "import sys\n",
+    "print(f\"Version: {sys.version}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Comparison with Serial Backend\n",
+    "\n",
+    "Here's how you would use the traditional serial backend (requires physical hardware):\n",
+    "\n",
+    "```python\n",
+    "# Serial backend (default) - requires connected MCU\n",
+    "%%micropython --backend serial\n",
+    "print(\"This would run on physical hardware\")\n",
+    "\n",
+    "# Docker backend - runs in container\n",
+    "%%micropython --backend docker  \n",
+    "print(\"This runs in Docker container\")\n",
+    "```\n",
+    "\n",
+    "## Advantages of Docker Backend\n",
+    "\n",
+    "- **No Hardware Required**: Run MicroPython code without physical MCUs\n",
+    "- **Consistent Environment**: Same MicroPython version across different machines\n",
+    "- **Easy Setup**: Just requires Docker installation\n",
+    "- **Development and Testing**: Perfect for learning and prototyping\n",
+    "- **CI/CD**: Can be used in automated testing pipelines\n",
+    "\n",
+    "## Limitations\n",
+    "\n",
+    "- **No GPIO/Hardware Access**: Cannot control physical pins or sensors\n",
+    "- **No Hardware-Specific Modules**: modules like `machine`, `time` may have limited functionality\n",
+    "- **Session Persistence**: Variables don't persist between cells (each execution is independent)\n",
+    "\n",
+    "The Docker backend is ideal for learning MicroPython syntax, testing algorithms, and developing code before deploying to physical hardware."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}