@modpackqt/bytes

Universal byte / register decoder + encoder for Node.js. Free, MIT, zero dependencies, no rate limits.

Decode and encode int16, uint16, int32, uint32, float32, float64, strings, and bitmasks from any Buffer or numeric array — Modbus registers, MQTT payloads, raw TCP/UDP, BLE, LoRaWAN, file parsing.

The same byte/endian engine that powers the node-red-contrib-bytes-modpackqt palette, exposed as a clean Node.js library so you can use it in your own backends, CLIs, edge gateways, and bridge services.

Install

npm install @modpackqt/bytes

Requires Node.js 14 or later. Zero dependencies.

Quick start

const bytes = require('@modpackqt/bytes');

// Decode 2 Modbus holding registers as a single float32 (big-endian, ABCD order)
const value = bytes.decode([0x4248, 0x0000], 'registers', 'BE', 'float32');
// → [50]

// Encode a float back to registers, ready for FC16 write
const regs = bytes.encode([50], 'BE', 'float32');
// → [0x4248, 0x0000]

// Decode a 16-bit word as 16 boolean alarms (LSB first)
const alarms = bytes.decodeBitmask([0b0000000000010101], 'registers');
// → [true, false, true, false, true, false, ...]

// Decode a Modbus string (some devices need byte-swap)
const name = bytes.decodeString([0x4142, 0x4344], 'registers', 'BE', 'utf8', true);
// → "ABCD"

// Re-order bytes between two devices that disagree on endianness
const swapped = bytes.endianSwap([0x1234, 0x5678], 'registers', 'BE_SWAP', 4);
// → [0x3412, 0x7856]

API

decode(input, sourceType, endian, type) → number[]

Decode numeric values.

| Param | Type | Values | |---|---|---| | input | Buffer | number[] | A Buffer, an array of 16-bit registers, or an array of bytes | | sourceType | 'registers' | 'bytes' | How to interpret an input array | | endian | 'BE' | 'LE' | 'BE_SWAP' | 'LE_SWAP' | Word + byte order (see endianness table below) | | type | 'int16' | 'uint16' | 'int32' | 'uint32' | 'float32' | 'float64' | Output type |

Returns an array (always — even for one value) of decoded numbers.

encode(values, endian, type) → number[]

Encode one or more numbers as 16-bit registers (Modbus convention).

decodeString(input, sourceType, endian, encoding?, trim?) → string

Decode a string. encoding defaults to 'utf8'. trim strips trailing nulls and whitespace.

encodeString(value, endian, encoding?, padTo?) → number[]

Encode a string as 16-bit registers. padTo zero-pads to a fixed byte length.

decodeBitmask(input, sourceType, bits?) → boolean[]

Expand each 16-bit word into 16 booleans (LSB first). bits truncates the result.

endianSwap(input, sourceType, endian, width) → number[]

Re-order bytes/words. width is 2, 4, or 8. Useful when bridging two devices that disagree on endianness.

toBuffer(input, sourceType) → Buffer

Lower-level helper — convert any accepted input shape into a Buffer.

Endianness — what the four modes mean

For multi-register values (32-bit and 64-bit), Modbus devices vary by vendor. These are the four common conventions:

| Mode | Word order | Byte order within each word | Example: 0x12345678 over 2 regs | |---|---|---|---| | BE (default) | Big | Big | [0x1234, 0x5678] — "ABCD" | | LE | Little | Little | [0x7856, 0x3412] — "DCBA" | | BE_SWAP | Big | Swapped | [0x3412, 0x7856] — "BADC" | | LE_SWAP | Little | Swapped | [0x5678, 0x1234] — "CDAB" |

Tip: if your decoded float looks insane (1.7e-43 or NaN), try the other three modes — endianness mismatch is the #1 cause.

Use cases

• Modbus — pair with modbus-serial or any Modbus library; this decodes the register arrays they return.
• MQTT — decode binary payloads from sensors / industrial brokers.
• BLE / LoRaWAN — decode characteristic / payload buffers.
• Raw TCP/UDP — decode messages from custom protocols, energy meters, inverters.
• File parsing — binary log files, vendor data dumps.

Quiet mode

The library prints a one-line banner on first import (so users know where to find docs and the free tester). Suppress it with:

MODPACKQT_QUIET=1 node your-app.js

Companion tools

• node-red-contrib-bytes-modpackqt — same engine, as a Node-RED palette
• node-red-contrib-modbus-modpackqt — Modbus TCP/RTU master + slave for Node-RED
• modpackqt/node-red Docker image — Node-RED with both palettes preinstalled
• modpackqt.com — free web-based Modbus tester, virtual devices, AI-assisted setup

Attribution

If @modpackqt/bytes saves you time, a README badge helps others find it:

[![Powered by ModPackQT](https://img.shields.io/badge/Powered%20by-ModPackQT-2563eb)](https://modpackqt.com)

License

MIT. See LICENSE. Provided "as is" without warranty of any kind.