chumicro-msgpack

Binary serialization that's typically 30–50 % smaller than JSON.

The subset of MessagePack that fits on a 256 KB board — 32-bit ints, single-precision floats, 16-bit lengths. Wire-compatible with the PyPI msgpack library when it's configured for the same subset (use_single_float=True); on CircuitPython firmware that ships the native msgpack C module, encoding and decoding delegate to the C path automatically.

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_msgpack

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

# CPython
pip install chumicro-msgpack

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

Quick example

from chumicro_msgpack import packb, unpackb

settings = {0: "MyNetwork", 1: "secret", 2: True}

data = packb(settings)       # compact binary bytes
print(len(data))             # much smaller than JSON

restored = unpackb(data)
print(restored)              # {0: 'MyNetwork', 1: 'secret', 2: True}

What's included

Stream-based API (preferred on microcontrollers)

Bytes-based API

Use pack/unpack when writing to files, sockets, or NVM. Use packb/unpackb when you need the encoded bytes in memory (e.g., to measure length before framing).

Supported types

Values outside these limits raise OverflowError on encode. Tags outside the subset (float64 0xcb, int64 0xd3, uint64 0xcf, the *32-length variants) raise a descriptive ValueError on decode that names the offending tag.

tuple decodes back as list — msgpack has no tuple type. dict keys may be any supported type, including int (no strict_map_key enforcement). Ext types (timestamps, custom classes) are not supported in either direction.

Cross-runtime compatibility

Host-side recipe — when a host script needs to produce bytes a chumicro device will read:

import msgpack  # standard PyPI library
data = msgpack.packb(obj, use_single_float=True)
# Caller's job: keep ints in [-2**31, 2**32-1] and lengths under 65 536.

use_single_float=True switches PyPI msgpack from float64 to float32, matching what chumicro reads. This is what chumicro-workspace uses to write runtime_config.msgpack for the device.

Where this fits

Leaf — no upstream ChuMicro deps. Used directly by chumicro-config to decode /runtime_config.msgpack on the device, and by host-side workspace tooling to write it.

Platform support

Examples

Contributing

Working on chumicro-msgpack itself? Clone the mono-repo if you haven't already — the rest of the workflow assumes you're inside that workspace.

pip install -e .[test]
pytest tests/                  # host-side tests
pytest functional_tests/       # on-device tests (needs a board registered in devices.yml)

Register a board before running functional tests: chumicro-workspace add-device <id> --address <port>.

Docs

📖 Stable docs · Experimental docs

Find this library

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

License

MIT