Replace low-level sockets with adafruit_httpserver

Note: as of Oct 26, 2025, this code depends on a PR that hasn't yet been merged:
adafruit/Adafruit_CircuitPython_ESP32SPI#218

I had to pull this branch into the ESP32SPI submodule of the circuitpython source and then build custom firmware to get this to work.

Author: ulfmagnetics

matrixportal/code.py

@@ -13,6 +13,8 @@
 from adafruit_esp32spi import adafruit_esp32spi
 from adafruit_matrixportal.matrix import Matrix
 from digitalio import DigitalInOut
+from adafruit_httpserver import Server, Request, Response
+import adafruit_esp32spi.adafruit_esp32spi_socketpool as socketpool
 
 # Get wifi details and more from a secrets.py file
 try:
@@ -43,8 +45,8 @@
         continue
 print("Connected to", str(radio.ap_info.ssid, "utf-8"), "\tRSSI:", radio.ap_info.rssi)
 
-# Initialize a requests session
-pool = adafruit_connection_manager.get_radio_socketpool(radio)
+# Initialize socket pool and requests session
+pool = socketpool.SocketPool(radio)
 ssl_context = adafruit_connection_manager.get_radio_ssl_context(radio)
 requests = adafruit_requests.Session(pool, ssl_context)
 
@@ -115,137 +117,49 @@ def load_and_display_bitmap(bitmap_url):
 print("Loading default bitmap...")
 load_and_display_bitmap(DEFAULT_BITMAP_URL)
 
-# Print IP address for testing
-print("=" * 50)
-print(f"MatrixPortal HTTP Server Ready!")
-print(f"IP Address: {radio.pretty_ip(radio.ip_address)}")
-print(f"Test with: curl -X POST http://{radio.pretty_ip(radio.ip_address)} -d \"<bitmap-url>\"")
-print("=" * 50)
+# Create HTTP server
+http_server = Server(pool, debug=True)
+
+@http_server.route("/display", methods=["POST"])
+def display_bitmap_handler(request: Request):
+    """Handle POST requests with bitmap URL in body"""
+    print(f"\nReceived POST request to /display")
+
+    try:
+        # Extract URL from raw POST body
+        body_bytes = request.body
+        bitmap_url = body_bytes.decode('utf-8', errors='ignore').strip()
 
-# Create HTTP server using ESP32 SPI API
-print("Creating server socket...")
-socket_num = radio.get_socket()
-print(f"Allocated socket number: {socket_num}")
+        if not bitmap_url:
+            print("Empty URL in POST body")
+            return Response(request, "Empty URL in POST body", status=400)
 
-# Start server on port 80
-radio.start_server(port=80, socket_num=socket_num)
-print(f"Server started on port 80, socket {socket_num}")
+        print(f"Received URL: {bitmap_url}")
 
-# Verify server is listening
-state = radio.server_state(socket_num)
-print(f"Server state: {state}")
-print("Listening for HTTP requests on port 80...")
+        # Load and display the bitmap
+        load_and_display_bitmap(bitmap_url)
 
-# Socket state constants
-SOCKET_CLOSED = 0
-SOCKET_LISTEN = 1
-SOCKET_ESTABLISHED = 4
+        print("Bitmap loaded and displayed successfully")
+        return Response(request, "Bitmap displayed successfully", status=200)
 
-# Buffer for accumulating request data
-request_buffer = b""
+    except Exception as e:
+        print(f"Error loading bitmap: {e}")
+        return Response(request, f"Error loading bitmap: {e}", status=500)
+
+# Start HTTP server
+ip = radio.pretty_ip(radio.ip_address)
+print("\n" + "=" * 50)
+print(f"Starting HTTP server at {ip}:80")
+http_server.start(str(ip), port=80)
+print(f"MatrixPortal HTTP Server Ready!")
+print(f"Test with: curl -X POST http://{ip}/display -d \"<bitmap-url>\"")
+print("=" * 50)
 
-# Main server loop - poll for incoming connections
-print("Waiting for client connections...")
+# Main server loop
+print("Listening for HTTP requests...")
 while True:
     try:
-        # Check the server socket state
-        state = radio.server_state(socket_num)
-
-        # Only process data if a client is connected (SOCKET_ESTABLISHED)
-        if state != SOCKET_ESTABLISHED:
-            # No client connected, continue polling
-            time.sleep(0.1)
-            continue
-
-        # Client is connected! Check if data is available
-        available = radio.socket_available(socket_num)
-
-        if available <= 0:
-            # No data available yet, continue polling
-            time.sleep(0.05)
-            continue
-
-        # Data available - read it
-        print(f"\nClient connected, reading {available} bytes...")
-        chunk = radio.socket_read(socket_num, available)
-        request_buffer += chunk
-
-        # Check if we have complete headers
-        if b"\r\n\r\n" not in request_buffer:
-            # Wait for more data if headers are incomplete
-            continue
-
-        # We have a complete HTTP request (headers + body)
-        print(f"Received request ({len(request_buffer)} bytes)")
-
-        try:
-            # Parse HTTP request
-            request_str = request_buffer.decode('utf-8', errors='ignore')
-            lines = request_str.split('\r\n')
-
-            # Check if it's a POST request
-            if lines[0].startswith('POST'):
-                # Find Content-Length header
-                content_length = 0
-                for line in lines:
-                    if line.lower().startswith('content-length:'):
-                        content_length = int(line.split(':')[1].strip())
-                        break
-
-                # Extract body
-                header_end = request_buffer.find(b"\r\n\r\n")
-                body = request_buffer[header_end + 4:]
-
-                # Check if we have the complete body
-                if len(body) >= content_length:
-                    # Extract URL from body
-                    bitmap_url = body[:content_length].decode('utf-8', errors='ignore').strip()
-
-                    if bitmap_url:
-                        print(f"Received URL: {bitmap_url}")
-
-                        try:
-                            # Load and display the bitmap
-                            load_and_display_bitmap(bitmap_url)
-
-                            # Send success response
-                            response = b"HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nBitmap displayed successfully\r\n"
-                            radio.socket_write(socket_num, response)
-                            print("Bitmap loaded and displayed successfully")
-
-                        except Exception as e:
-                            print(f"Error loading bitmap: {e}")
-                            response = f"HTTP/1.1 500 Internal Server Error\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nError loading bitmap: {e}\r\n".encode()
-                            radio.socket_write(socket_num, response)
-                    else:
-                        print("Empty URL in POST body")
-                        response = b"HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nEmpty URL in POST body\r\n"
-                        radio.socket_write(socket_num, response)
-
-                    # Clear buffer for next request
-                    request_buffer = b""
-            else:
-                # Not a POST request
-                print(f"Not a POST request: {lines[0]}")
-                response = b"HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nOnly POST requests are supported\r\n"
-                radio.socket_write(socket_num, response)
-                request_buffer = b""
-
-        except Exception as e:
-            print(f"Error parsing request: {e}")
-            response = b"HTTP/1.1 500 Internal Server Error\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nError processing request\r\n"
-            try:
-                radio.socket_write(socket_num, response)
-            except:
-                pass
-            request_buffer = b""
-
-            gc.collect()
-
-        # Small delay to prevent busy-waiting
-        time.sleep(0.1)
-
+        http_server.poll()
     except Exception as e:
         print(f"Server error: {e}")
-        request_buffer = b""
         time.sleep(1)