Bit-parser | Not Hacker News!

Discussion (1 comments)

Showing 1 comments

developer4ltu

16 days ago

Hi HN,

In many protocols, a single byte (or two) encodes multiple independent signals:

boolean flags

RFU / reserved bits

small counters

mode selectors

multi-bit values with constrained ranges

Typical solutions end up as:

scattered masks and shifts

duplicated logic across CLI tools, tests, and UIs

decode-only helpers with no clean reverse operation

frontend teams re-implementing the bit layout by hand

I wanted something small and declarative, where:

the bit layout is defined once

decoding and encoding are symmetric

the same definition can drive CLIs, validation, and UI calculators

What bit-parser does Basic decoding from BitParser import parse_bits

descriptors = [ "pin7", "pin6", "pin5", "pin4", "pin3", "pin2", "pin1", "pin0", ]

parse_bits("A3", descriptors)

Output:

['pin7', 'pin5', 'pin1', 'pin0']

This returns only the enabled labels.

Full parsing mode (explicit, UI-friendly)

Often you need all bits, not just the enabled ones — for tables, validators, or interactive tools.

from BitParser import parse_bits_full

rows = parse_bits_full("80", descriptors)

rows[0] rows[-1]

Example output:

{ 'kind': 'bit', 'label': 'pin7', 'enabled': True, 'bit_index': 7 }

{ 'kind': 'bit', 'label': 'pin0', 'enabled': False, 'bit_index': 0 }

This mode is intentionally verbose and ordered. It’s meant to be consumed by UIs or other tooling, not just printed.

Custom hex calculator example

One concrete use case this grew out of: custom hex / bit calculators for protocols.

Imagine a small web UI where a user:

toggles flags

sets numeric fields

immediately sees the resulting hex value

With bit-parser, the backend logic is trivial.

Backend logic (Python) from BitParser import ( parse_bits_full, encode_bits, MultiBitValueParser )

descriptors = [ "error", "warning", MultiBitValueParser("mode", bit_count=2), "enabled", "rfu", "rfu", "rfu", ]

# User enters hex hex_value = "29"

rows = parse_bits_full(hex_value, descriptors)

# rows can be sent directly to the UI

Example rows sent to frontend:

[ { "kind": "bit", "label": "error", "enabled": True }, { "kind": "bit", "label": "warning", "enabled": False }, { "kind": "multi", "label": "mode", "value": 2 }, { "kind": "bit", "label": "enabled", "enabled": True }, { "kind": "bit", "label": "rfu", "enabled": False } ]

User toggles fields in the UI, backend encodes it back:

encode_bits( enabled_labels=["error", "enabled"], values={"mode": 3}, descriptors=descriptors )

Result:

"2D"

No masks. No duplicated bit math in JS. Same definition used for decoding, validation, and encoding.

Multi-bit fields and ranges

The helper supports:

grouped bit fields (MultiBitValueParser)

value ranges (SameValueRange)

repeated labels with disambiguation

This is useful for RFU blocks, counters, and mode selectors commonly found in embedded protocols.

Why not use existing libraries?

Most libraries I’ve used either:

focus on parsing only

are heavy frameworks

don’t round-trip cleanly (decode ≠ encode)

are awkward to expose to frontend tooling

This is intentionally small and boring — a helper, not a framework.

Where it fits

Embedded / IoT diagnostics

Protocol analyzers

CLI tools

Test harnesses

Custom hex / bit calculators

UIs that expose device configuration

Feedback welcome

I’m interested in feedback on:

API shape and naming

missing primitives you’d expect

real-world protocol edge cases

Thanks for reading.

Resources