Hardware Setup

Connect a potentiometer to the ESP32 as follows: one outer pin goes to 3.3V, the other outer pin goes to GND, and the middle wiper pin connects to GPIO 5. Then connect the ESP32 to your computer via USB.

If you are using a Chinese ESP32 Super Mini (the small board with the castellated edges), you need to enable USB CDC on Boot in the Arduino IDE under Tools before flashing. Without this setting, the board will not send any data over the serial connection and the notebook will receive nothing.

To find the correct port, open Device Manager on Windows and look under "Ports (COM & LPT)" — you will see something like COM5. On macOS or Linux, run ls /dev/tty.* in the terminal. Update the port string in the notebook cells to match your system. The default in the notebook is "COM5".

Reading Serial Data

This is the most fundamental step: opening a connection to the ESP32 and reading ten lines of raw data. The serial.Serial() call opens the port at 115200 baud, which must match the baud rate set in the firmware. The timeout=1 parameter tells readline to wait at most one second for a line before returning, which prevents the script from hanging indefinitely if no data arrives.

The time.sleep(2) pause after opening the port is important — the ESP32 reboots when a serial connection is established, and it takes a moment to finish booting and start sending data. Without this pause, the first few reads would likely return empty strings.

Once a line arrives, it is a raw bytes object. The .decode() call converts it to a Python string, and .strip() removes the trailing newline character. Wrapping it in repr() when printing shows the quotes around the value, making it easy to confirm the data looks exactly as expected — for example '2640' rather than just 2640. After reading ten values, ser.close() releases the port so it is available for the next cell.

Copy

# Serial Read from your MCU
import serial, time

# When running on Chinese ESP Super Minis, don't forget to enable "USB CDC On Boot" within Tool Settings, as it will not send data via Serial otherwise

ser = serial.Serial("COM5", 115200, timeout=1) # Port differs - COM for Win tty Path for Linux / Unix
time.sleep(2) # ESP Boot

for _ in range(10):
    line = ser.readline().decode(errors="ignore").strip()
    print(repr(line))

ser.close()

Live Potentiometer Monitor

This cell combines the serial reader from Cell 1 with the Tkinter window from Cell 2. The companion script poti-monitor.py opens a desktop window that displays the current potentiometer value, updating every 50 milliseconds as you turn the dial.

The most important design decision in this script is setting timeout=0 when opening the serial port. A blocking timeout would cause readline() to pause for up to a second waiting for data, which would make the Tkinter window freeze and feel unresponsive. With timeout=0, readline() returns immediately with whatever data is available, and the window stays fluid.

The update loop is implemented using root.after(50, update), which tells Tkinter's event loop to call the update function again after 50 ms. This cooperates with the GUI framework rather than fighting it — a plain while loop would block the event loop entirely and crash the window. The line.isdigit() check filters out any malformed or empty lines before updating the label, ensuring only valid integers are displayed.

The close-handling pattern safely releases any previously open serial connection. This is important throughout the notebook because cells are often re-run, and attempting to open a port that is already open raises an error.

Copy

import tkinter as tk
import serial

ser = serial.Serial("COM5", 115200, timeout=0)  # timeout=0 = non-blocking!

def update():
    line = ser.readline().decode(errors="ignore").strip()
    if line.isdigit():
        label.config(text=f"Poti Value: {line}")
    root.after(50, update)

def on_close():
    ser.close()
    root.destroy()

root = tk.Tk()
root.title("Poti Monitor")

label = tk.Label(root, text="Poti Value: –", font=("Arial", 24))
label.pack(padx=40, pady=40)

root.protocol("WM_DELETE_WINDOW", on_close)

update()
root.mainloop()

Tkinter Window with Embedded Real-Time Plot

This cell is where everything from the previous steps comes together for the first time. Rather than showing the potentiometer value as a number in a label or as a chart in a separate Matplotlib window, this script embeds a live-updating plot directly inside a Tkinter window, creating a single self-contained desktop application.

The key to making this work is FigureCanvasTkAgg, a Matplotlib backend that renders a Matplotlib figure as a Tkinter widget. Instead of calling plt.show() — which would open a separate window and block execution — the figure is attached to the Tkinter root window using canvas.get_tk_widget().pack(). From that point on, Tkinter manages the window and Matplotlib manages the chart inside it.

The update logic uses FuncAnimation, which calls an update function every 50 ms. On each call, a new value is read from the serial port and appended to a list. The Y-axis is fixed between 0 and 3168, corresponding to the observed ADC range of the ESP32. The X-axis uses a scrolling window showing the most recent 100 samples — ax.set_xlim(max(0, len(values) - 100), len(values)) — so the chart always follows the latest data rather than compressing everything into a shrinking view as more samples accumulate.

Window closing is handled cleanly via root.protocol("WM_DELETE_WINDOW", on_close), which ensures the serial port is closed before the window is destroyed. Without this, the port would remain locked after closing the window and the next cell would fail to open it.

Copy

import tkinter as tk
import serial
import matplotlib.pyplot as plt
import matplotlib.animation as animation
from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg

ser = serial.Serial("COM5", 115200, timeout=0)
values = []

root = tk.Tk()
root.title("Poti Realtime Plot")

fig, ax = plt.subplots()
line, = ax.plot([], [])

canvas = FigureCanvasTkAgg(fig, master=root)
canvas.get_tk_widget().pack()

def update(frame):
    raw = ser.readline().decode(errors="ignore").strip()
    if raw.isdigit():
        values.append(int(raw))
    line.set_data(range(len(values)), values)
    ax.set_ylim(0, 3168)
    ax.set_xlim(max(0, len(values) - 100), len(values))  # scrollend
    return line,

def on_close():
    ser.close()
    root.destroy()

root.protocol("WM_DELETE_WINDOW", on_close)

ani = animation.FuncAnimation(fig, update, interval=50, cache_frame_data=False)
root.mainloop()

3D Visualization with three.js

This step opens poti-threejs.html in the default browser. Instead of showing only the small Python launcher, the page below shows the actual HTML and JavaScript that create the three.js scene — a 3D cube that rotates in real time as you turn the potentiometer.

The scene setup follows the standard three.js structure: a Scene object holds all the 3D elements, a PerspectiveCamera defines the viewpoint, and lights are added so the cube's material is visible. The cube itself is a simple BoxGeometry with a teal-colored standard material. The WebGL renderer is attached to the page body and sized to fill the window.

The potentiometer value arrives via the same WebSocket server started in Cell 7. A JavaScript WebSocket client listens for incoming messages and maps each raw ADC value to a rotation angle: dividing by the maximum observed value (3168) gives a 0–1 range, which is then multiplied by 2π to cover a full 360-degree rotation. This means the physical position of the potentiometer dial maps directly to the visual orientation of the cube. The current numeric value is also displayed as text on the page.

The render loop runs continuously using requestAnimationFrame, which is the browser's standard mechanism for smooth animation — it calls the render function before each screen refresh, typically at 60 frames per second.

One practical note: the current version of three.js requires an HTTP server to load as a JavaScript module, which does not work when opening a file directly from disk. For this project, an older version of three.js was used instead, which loads as a classic script tag and works with local files.

Copy

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Poti 3D</title>
  <script src="three.min.js"></script>
  <style>
    body { margin: 0; background: #000; }
    #val { position: fixed; top: 20px; left: 20px; color: #fff; font: 32px monospace; }
  </style>
</head>
<body>

<div id="val">–</div>

<script>

const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

const scene  = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.1, 100);
camera.position.z = 4;

scene.add(new THREE.AmbientLight(0xffffff, 1));
scene.add(new THREE.DirectionalLight(0xffffff, 2));

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(2, 2, 2),
  new THREE.MeshStandardMaterial({ color: 0x4f98a3 })
);
scene.add(cube);

// WebSocket
const ws = new WebSocket('ws://localhost:8000/ws');
ws.onmessage = e => {
  const v = parseInt(e.data);
  cube.rotation.y = (v / 3168) * Math.PI * 2;
  document.getElementById('val').textContent = v;
};

// Render loop
function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();
</script>
</body>
</html>