Adafruit CircuitPython ConnectionManager

Common errors

• AttributeError: 'module' object has no attribute 'SocketPool'

  cause This usually occurs when trying to use `socketpool.SocketPool()` in a CircuitPython environment where the `socketpool` module is not correctly set up by a network driver, or on CPython if the `socketpool` PyPI package is not installed.
  fix For CircuitPython, ensure your network driver (e.g., `adafruit_esp32spi`) is initialized and its socket interface is set (e.g., `esp32spi_socket.set_interface(esp)`). For CPython, run `pip install socketpool`.

• RuntimeError: Please install the 'requests' CircuitPython library (or similar missing dependency error)

  cause You are likely trying to use `adafruit-circuitpython-requests` without it being installed on your CircuitPython board or in your CPython environment.
  fix Install `adafruit-circuitpython-requests`. For CircuitPython, use `circup install adafruit_requests`. For CPython, use `pip install adafruit-circuitpython-requests`.

• socket.gaierror: [Errno -2] Name or service not known

  cause This error indicates a DNS resolution failure, meaning the device cannot convert a domain name (like `example.com`) into an IP address. This is typically due to incorrect network configuration (e.g., Wi-Fi credentials, gateway, DNS servers).
  fix Verify your network connection (Wi-Fi, Ethernet), ensure `secrets.py` (if on CircuitPython) has correct credentials, and check that your network allows DNS lookups.

• TypeError: ConnectionManager() missing 1 required positional argument: 'socket_pool'

  cause You attempted to create a `ConnectionManager` instance without providing the mandatory `socket_pool` object.
  fix Pass an initialized `SocketPool` instance as the first argument to `ConnectionManager`, e.g., `manager = ConnectionManager(pool)`.

Warnings

• breaking Version 3.0.0 introduced significant changes related to SSL socket recycling and exception handling. Code relying on specific exception types for network failures or particular SSL behavior might break.
  Fix: Update to 3.0.0+ and review network error handling code. New exceptions are more consistent with `urllib3`.
• breaking Version 2.0.0 updated its internal handling to match changes in `ESP32SPI` and `WIZNET5K` APIs. If you're using older versions of these underlying network drivers, `ConnectionManager` might not function correctly.
  Fix: Ensure that your `adafruit-circuitpython-esp32spi` or `adafruit-circuitpython-wiznet5k` libraries (and associated firmware) are updated to compatible versions, typically the latest available.
• gotcha ConnectionManager requires an initialized `SocketPool` instance, which it does not provide itself. This pool must come from a network driver (e.g., `adafruit_esp32spi_socket`, `adafruit_wiznet5k_socket`) on CircuitPython or the `socketpool` PyPI package on CPython.
  Fix: Always pass a properly configured `SocketPool` object to the `ConnectionManager` constructor, e.g., `manager = ConnectionManager(pool)`.
• gotcha For HTTPS connections, a `ssl.create_default_context()` object must be passed to the `ConnectionManager` constructor. Without it, attempts to connect to HTTPS endpoints will fail.
  Fix: When dealing with HTTPS, initialize `ConnectionManager` like this: `manager = ConnectionManager(pool, ssl_context=ssl.create_default_context())`.

Install

• pip install adafruit-circuitpython-connectionmanager Install library
• pip install socketpool adafruit-circuitpython-requests Install common companion libraries for CPython

Imports

• ConnectionManager

  from adafruit_connection_manager import ConnectionManager

• PoolManager

  from adafruit_connection_manager import PoolManager

  PoolManager is an alias for ConnectionManager, often used for CPython compatibility.

Quickstart

This quickstart demonstrates how to initialize `ConnectionManager` with a `SocketPool` and `ssl` context, then integrate it with `adafruit-circuitpython-requests` to perform an HTTP(S) GET request. This example is runnable on CPython after installing `socketpool`, `adafruit-circuitpython-connectionmanager`, and `adafruit-circuitpython-requests`.

import os
import socketpool
import adafruit_connection_manager
import adafruit_requests as requests
import ssl # Required for HTTPS

# 1. Initialize a SocketPool.
# For CPython, use `pip install socketpool`.
# For CircuitPython, this would be provided by your board's firmware or a driver
# like `adafruit_esp32spi.adafruit_esp32spi_socket` or `adafruit_wiznet5k.adafruit_wiznet5k_socket`.
pool = socketpool.SocketPool()

# 2. Create an SSL context for HTTPS requests.
# This is crucial for secure connections.
ssl_context = ssl.create_default_context()

# 3. Instantiate ConnectionManager, passing the socket pool and SSL context.
manager = adafruit_connection_manager.ConnectionManager(pool, ssl_context)

# 4. Set ConnectionManager as the socket interface for adafruit_requests.
# For CPython, use `pip install adafruit-circuitpython-requests`.
requests.set_socket(manager)

# 5. Make an HTTP(S) request.
# Using os.environ.get for a safe default URL.
test_url = os.environ.get("TEST_URL", "https://httpbin.org/get")
print(f"Attempting to fetch data from: {test_url}")

try:
    response = requests.get(test_url)
    print(f"Status Code: {response.status_code}")
    print(f"Response (first 100 chars): {response.text[:100]}...")
    response.close() # Important to close responses in CircuitPython
except Exception as e:
    print(f"Error fetching URL: {e}")