chumicro-websockets

Non-blocking WebSocket (RFC 6455) client and server, plain and TLS.

RFC 6455 framing and masking, opening + closing handshakes, text + binary + ping/pong, and oversized-message guards. Plays alongside chumicro-http-server for combined HTTP + WS / HTTPS + WSS deployments. Built on chumicro-sockets and chumicro-timing.

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-Experimental`)
circup install chumicro_websockets

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle-Experimental/chumicro_websockets

# CPython
pip install chumicro-websockets-experimental

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

Quick example

Client:

from chumicro_websockets import WebSocketClient, WebSocketState
from chumicro_sockets.sockets_factory import connector_factory
from chumicro_timing import ticks_ms

client = WebSocketClient(transport_factory=connector_factory())
client.on_text = lambda text: print(f"got: {text}")
client.connect("ws://api.example.com/stream")

while client.state != WebSocketState.CLOSED:
    if client.check(ticks_ms()):
        client.handle(ticks_ms())

Server:

from chumicro_websockets import WebSocketServer
from chumicro_sockets import listener
from chumicro_timing import ticks_ms

def on_connection(connection):
    connection.on_text = lambda text: connection.send_text(f"echo: {text}")

server = WebSocketServer(
    listener=listener("0.0.0.0", 8765),
    on_connection=on_connection,
)

while True:
    now = ticks_ms()          # one timestamp per pass, shared by check and handle
    if server.check(now):
        server.handle(now)

What's included

Wire-format primitives (FrameParser, encode_frame, the handshake parsers and encoders, the close-payload codec, validate_text_payload, the DEFAULT_* knob constants) live in chumicro_websockets._wire for advanced users and tests; the public top-level surface stays small to keep flash + RAM lean on the device.

Where this fits

Depends on chumicro-sockets and chumicro-timing. Pairs with chumicro-http-server for combined HTTP + WS / HTTPS + WSS deployments.

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-websockets
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/websockets

License

MIT