Merge pull request #190 from AccelerationConsortium/copilot/fix-189

Add aside section showing Python alternative to MicroPython for device communication and update non-MicroPython notebook

Author: sgbaird

.gitignore

@@ -60,3 +60,4 @@ docs/courses/hello-world/micropython/mqtt_as.py
 docs/courses/hello-world/images/43577_2023_498_Fig1_HTML.webp
 docs/courses/hello-world/scratch.py
 docs/courses/hello-world/results.csv
+docs/courses/hello-world/deployment.zip

docs/courses/hello-world/1.4.1-onboard-led-temp.ipynb

@@ -179,6 +179,17 @@
     "    plt.show()  # Show the plot"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Aside: Using Python instead of MicroPython for device communication\n",
+    "\n",
+    "This notebook demonstrates communication with a microcontroller running MicroPython (such as a Raspberry Pi Pico W). However, if you were using a device that supports full Python (e.g., a Raspberry Pi Zero 2W running a complete operating system instead of being restricted to MicroPython), you could use the `paho-mqtt` Python library directly on the device itself. \n",
+    "\n",
+    "For an example of how to implement the device-side MQTT communication using Python instead of MicroPython, see the [non-MicroPython device version notebook](./1.4.2-non-micropython-device-version.ipynb). This approach can be useful when working with more powerful hardware that can run a full operating system and Python environment."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/courses/hello-world/1.4.2-non-micropython-device-version.ipynb

@@ -17,7 +17,9 @@
     {
       "cell_type": "markdown",
       "source": [
-        "# 1.4.2 Non-MicroPython Device Version"
+        "# 1.4.2 Non-MicroPython Device Version\n",
+        "\n",
+        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/AccelerationConsortium/ac-microcourses/blob/main/docs/courses/hello-world/1.4.2-non-micropython-device-version.ipynb)"
       ],
       "metadata": {
         "id": "JSeeBF7SvENI"
@@ -26,7 +28,11 @@
     {
       "cell_type": "markdown",
       "source": [
-        "This notebook serves as a replacement of [hardware/software communication notebook](./1.4-hardware-software-communication) if you were running on a device that supports Python (e.g., Raspberry Pi 5, Linux, Windows, MacOS, etc.) where you can install the `paho-mqtt` Python library (as opposed to using the `mqtt_as` MicroPython library on a Pico W). This notebook can also be used directly with [the companion notebook](./1.4.1-onboard-led-temp.ipynb). Note that these examples do not consider the possibility of having multiple devices or sending simultaneous requests, for simplicity. However, in [`self-driving-lab-demo`](https://self-driving-lab-demo.readthedocs.io/en/latest/), this is distinguished by passing an `experiment_id` back and forth, which is incorporated into the module assignment."
+        "This notebook serves as an alternative to the [hardware/software communication notebook](./1.4-hardware-software-communication.ipynb) for devices that support full Python rather than MicroPython. If you're using hardware that can run a complete operating system (e.g., Raspberry Pi 4/5, Linux, Windows, macOS, etc.), you can install the `paho-mqtt` Python library directly instead of using the `mqtt_as` MicroPython library.\n",
+        "\n",
+        "This approach is particularly useful when you have more powerful hardware that isn't restricted to MicroPython's limitations. This notebook can be used alongside [the companion notebook](./1.4.1-onboard-led-temp.ipynb) for a complete MQTT communication setup.\n",
+        "\n",
+        "**Note:** These examples don't consider multiple devices or simultaneous requests for simplicity. For more advanced scenarios with experiment tracking, see the [`self-driving-lab-demo`](https://self-driving-lab-demo.readthedocs.io/en/latest/) which uses `experiment_id` for distinguishing between different operations."
       ],
       "metadata": {
         "id": "oJIRtUZTuDQZ"
@@ -35,8 +41,8 @@
     {
       "cell_type": "code",
       "source": [
-        "# only install paho-mqtt if we are running in colab\n",
-        "# matplotlib only for visualization\n",
+        "# Install required packages\n",
+        "# Only install paho-mqtt if we are running in Colab\n",
         "import sys\n",
         "IN_COLAB = 'google.colab' in sys.modules\n",
         "if IN_COLAB:\n",
@@ -60,6 +66,23 @@
         }
       ]
     },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "## MQTT Device Simulation\n",
+        "\n",
+        "The code below simulates an MQTT device that can receive LED control commands and send temperature sensor data. Before running this code, make sure to:\n",
+        "\n",
+        "1. **Replace the credentials** (currently showing public test credentials) with your own HiveMQ Cloud credentials if desired\n",
+        "2. **Set your unique device ID** in the `COURSE_ID` variable\n",
+        "3. **Ensure your device ID matches** what you're using in the companion notebook\n",
+        "\n",
+        "> **_CAUTION:_** The credentials shown below are public test credentials for educational purposes only. In production environments, never hardcode credentials directly in your code or expose them in plain text. Instead, use environment variables, secure configuration files, or cloud secret management services."
+      ],
+      "metadata": {
+        "id": "mqttSetupNote"
+      }
+    },
     {
       "cell_type": "code",
       "execution_count": 10,
@@ -113,90 +136,131 @@
         "\n",
         "# Replace with your actual HiveMQ Cloud credentials and device ID\n",
         "# (or import from your own my_secrets.py)\n",
-        "HIVEMQ_HOST = \"248cc294c37642359297f75b7b023374.s2.eu.hivemq.cloud\"\n",
-        "HIVEMQ_USERNAME = \"sgbaird\"\n",
-        "HIVEMQ_PASSWORD = \"D.Pq5gYtejYbU#L\"\n",
-        "COURSE_ID = \"<your_id_here>\"  # Make sure this matches your Colab script!\n",
+        "HIVEMQ_HOST = \"248cc294c37642359297f75b7b023374.s2.eu.hivemq.cloud\"  # Replace with your HiveMQ host\n",
+        "HIVEMQ_USERNAME = \"sgbaird\"  # Replace with your username\n",
+        "HIVEMQ_PASSWORD = \"D.Pq5gYtejYbU#L\"  # Replace with your password\n",
+        "COURSE_ID = \"<your_id_here>\"  # Make sure this matches your companion notebook!\n",
         "\n",
         "command_topic = f\"{COURSE_ID}/onboard_led\"\n",
         "sensor_data_topic = f\"{COURSE_ID}/onboard_temp\"\n",
         "\n",
-        "# Simulate LED on/off\n",
-        "led_state = False # we will set this as a global var later, to emulate a hardware state\n",
+        "# Simulate LED state (in real hardware, this would be the actual LED)\n",
+        "led_state = False\n",
         "\n",
         "\n",
         "def read_temperature():\n",
-        "    # for demonstration\n",
+        "    \"\"\"Simulate temperature reading (replace with actual sensor code).\"\"\"\n",
         "    return round(25 + random.uniform(-2.0, 2.0), 1)\n",
         "\n",
-        "# The callback for when the client receives a CONNACK response from the server.\n",
         "def on_connect(client, userdata, flags, rc, properties=None):\n",
+        "    \"\"\"Callback for when the client receives a CONNACK response from the server.\"\"\"\n",
         "    if rc == 0:\n",
+        "        print(\"Connected to MQTT broker\")\n",
         "        # Subscribing in on_connect() means that if we lose the connection and\n",
         "        # reconnect then subscriptions will be renewed.\n",
         "        client.subscribe(command_topic, qos=1)\n",
+        "        print(f\"Subscribed to command topic: {command_topic}\")\n",
         "    else:\n",
         "        print(f\"Failed to connect. Return code={rc}\")\n",
         "\n",
         "def on_message(client, userdata, msg):\n",
-        "    # we permit a global var for sake of demo'ing pretend hardware\n",
-        "    # normally the \"state\" would be kept by the device itself (hence one would remove the following line)\n",
+        "    \"\"\"Handle incoming MQTT messages.\"\"\"\n",
+        "    # Global variable for LED state simulation\n",
+        "    # In real hardware, the state would be maintained by the device\n",
         "    global led_state\n",
+        "    \n",
         "    try:\n",
         "        payload_str = msg.payload.decode().strip().lower()\n",
         "        print(f\"Received command on {msg.topic}: {payload_str}\")\n",
         "\n",
         "        if msg.topic == command_topic:\n",
-        "            if msg == \"on\":\n",
+        "            # Process LED commands\n",
+        "            if payload_str == \"on\":\n",
         "                led_state = True\n",
-        "            elif msg == \"off\":\n",
+        "            elif payload_str == \"off\":\n",
         "                led_state = False\n",
-        "            elif msg == \"toggle\":\n",
+        "            elif payload_str == \"toggle\":\n",
         "                led_state = not led_state\n",
         "            else:\n",
         "                print(f\"Unknown command: {payload_str}\")\n",
+        "            \n",
         "            print(f\"LED state: {led_state}\")\n",
+        "            \n",
+        "            # Send temperature reading as response\n",
         "            temperature = read_temperature()\n",
-        "            payload = f\"{temperature}\"\n",
-        "            client.publish(sensor_data_topic, payload, qos=1)\n",
+        "            client.publish(sensor_data_topic, str(temperature), qos=1)\n",
+        "            print(f\"Published temperature: {temperature}°C\")\n",
+        "            \n",
         "    except Exception as exc:\n",
-        "        print(\"Exception in on_message:\", exc)\n",
+        "        print(f\"Exception in on_message: {exc}\")\n",
         "\n",
         "print(\"Setting up MQTT Client\")\n",
         "client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, protocol=mqtt.MQTTv5)\n",
         "\n",
-        "# enable TLS for secure connection\n",
+        "# Enable TLS for secure connection\n",
         "client.tls_set(tls_version=mqtt.ssl.PROTOCOL_TLS_CLIENT)\n",
-        "# set username and password\n",
+        "\n",
+        "# Set username and password\n",
         "client.username_pw_set(HIVEMQ_USERNAME, HIVEMQ_PASSWORD)\n",
-        "# connect to HiveMQ Cloud on port 8883\n",
-        "port = 8883\n",
-        "client.connect(HIVEMQ_HOST, port)\n",
-        "print(\"Connected to MQTT Client\")\n",
-        "client.subscribe(sensor_data_topic, qos=2)\n",
         "\n",
         "# Attach callbacks\n",
         "client.on_connect = on_connect\n",
         "client.on_message = on_message\n",
         "\n",
+        "# Connect to HiveMQ Cloud on port 8883\n",
+        "port = 8883\n",
+        "print(f\"Connecting to {HIVEMQ_HOST}:{port}...\")\n",
+        "client.connect(HIVEMQ_HOST, port)\n",
+        "\n",
         "# Start the MQTT network loop in a separate thread\n",
         "client.loop_start()\n",
         "print(\"Waiting for commands...\")\n",
+        "print(f\"Send commands to topic: {command_topic}\")\n",
+        "print(f\"Temperature data will be published to: {sensor_data_topic}\")\n",
         "\n",
         "start_time = time.time()\n",
         "try:\n",
         "    # Keep the script running to handle incoming messages\n",
         "    while True:\n",
         "        elapsed = round(time.time() - start_time)\n",
-        "        print(f\"Running... Elapsed: {elapsed}s\")\n",
-        "        time.sleep(5)\n",
+        "        if elapsed % 10 == 0:  # Print status every 10 seconds\n",
+        "            print(f\"Running... Elapsed: {elapsed}s\")\n",
+        "        time.sleep(1)\n",
         "except KeyboardInterrupt:\n",
-        "    print(\"Interrupted by user.\")\n",
+        "    print(\"\\nInterrupted by user.\")\n",
         "finally:\n",
         "    # Gracefully stop\n",
+        "    print(\"Disconnecting...\")\n",
         "    client.loop_stop()\n",
-        "    client.disconnect()\n"
-      ]
+        "    client.disconnect()\n",
+        "    print(\"Disconnected.\")"
+      ],
+      "metadata": {
+        "id": "mqttDeviceCode"
+      },
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "## Usage Instructions\n",
+        "\n",
+        "1. **Configure credentials**: Replace the placeholder values for `HIVEMQ_HOST`, `HIVEMQ_USERNAME`, `HIVEMQ_PASSWORD`, and `COURSE_ID` with your actual values\n",
+        "2. **Run the device simulation**: Execute the code cell above to start the MQTT device simulation\n",
+        "3. **Send commands**: Use the companion notebook to send LED commands (`\"on\"`, `\"off\"`, or `\"toggle\"`) to the command topic\n",
+        "4. **Monitor responses**: The device will respond with temperature readings on the sensor data topic\n",
+        "\n",
+        "**Valid LED commands:**\n",
+        "- `\"on\"` - Turn LED on\n",
+        "- `\"off\"` - Turn LED off  \n",
+        "- `\"toggle\"` - Switch LED state\n",
+        "\n",
+        "The device simulation will continue running until you interrupt it (Ctrl+C in terminal or stop the cell in Jupyter/Colab)."
+      ],
+      "metadata": {
+        "id": "usageInstructions"
+      }
     }
   ]
 }