chumicro-msgpack

Compact binary serialization for settings and config, 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-Experimental`)
circup install chumicro_msgpack

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

# CPython
pip install chumicro-msgpack-experimental

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, since 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 does when it writes 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

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

License

MIT