chumicro-sockets

One TCP / TLS / UDP socket surface across CircuitPython, MicroPython, and CPython.

One entry per socket shape (connector, listener, udp_socket) hides the per-runtime adapter selection; TLS is a tls= flag on each. Custom-CA TLS and server-side certificates work the same way on every runtime.

Part of the ChuMicro family: small, focused Python libraries for microcontrollers and laptops. Browse all libraries.

Install

# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle`)
circup install chumicro_sockets

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle/chumicro_sockets

# CPython
pip install chumicro-sockets

For bundle setup, pre-compiled .mpy bundles, the experimental channel, and details on PyPI naming, see the chumicro INSTALL guide.

Quick example

from chumicro_sockets import connector

# One connect state machine per runtime.  Runner-shaped apps register
# the connector with the runner (it exposes check / handle / io_*);
# one-shot scripts drive it to terminal inline.  On CircuitPython pass
# the board radio (with chumicro-wifi, radio=wifi.adapter.radio); the
# kwarg is ignored on MicroPython / CPython.
dial = connector("broker.example.com", 1883, radio=None)
while dial.state not in ("ready", "failed"):
    dial.tick(0)
if dial.state == "failed":
    raise dial.last_error
sock = dial.socket
sock.send(b"PING\r\n")
buffer = bytearray(128)
nbytes = sock.recv_into(buffer, 128)
print(bytes(buffer[:nbytes]))
sock.close()

# TLS is a flag: `tls=True` verifies the cert chain on every runtime.
# Each runtime gets its trust roots from the right place:
# CircuitPython's firmware bundle, CPython's OS trust store,
# MicroPython's library-shipped bundle (override via
# `set_default_ca_bundle`).  Pass `context=ssl_context_no_verify()`
# for explicit opt-out.
dial = connector("api.example.com", 443, tls=True)

CircuitPython always needs an explicit radio=. The socketpool is built from it (socketpool.SocketPool(radio)). Pass wifi.adapter.radio from a chumicro-wifi WifiService, or whatever radio object your board exposes. MicroPython and CPython ignore the kwarg.

For tests, chumicro_sockets.testing.FakeSocket implements the same protocol against in-memory bytearrays, so downstream libraries (chumicro-mqtt, chumicro-requests) can exercise their protocol handling without hitting the network.

What's included

Where this fits

No runtime dependencies. On CircuitPython the caller passes a radio (wifi.adapter.radio from a chumicro-wifi WifiService, or any radio object the board exposes) from which the socketpool is built. Substrate for every networked library that follows: chumicro-requests, chumicro-http-server, chumicro-mqtt, chumicro-websockets, and chumicro-ntp.

Platform support

Works on CPython, MicroPython, and CircuitPython.

Examples

Contributing

Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get. Development happens in the ChuMicro repository, whose contributing guide covers setup and the test workflow.

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-sockets
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/sockets

License

MIT