MBMap - Specification v2.2.0

MBMap Specification v2.2.0

One addition to the version 2 format. It is an optional key that older readers can ignore, so the format version stays 2 and every existing map stays valid.

What's new

• Parts of a block (parts, §4.10): a new optional register key for devices that keep several values in one block and only accept the block written whole, such as an SMS gateway whose block holds the recipient's number followed by the text. The map still describes the block as one string register; parts names the values inside it (name, offset in registers, type, length, description). A tool that knows parts shows each part as a field of its own, decodes them on read, and on write builds the whole block from the parts and sends it in one request (FC16). An empty part is sent as zero bytes, and a write that covers only some parts is never sent.
• New diagnostic (§7): bad-parts, for an empty parts, parts on a register that is not a string with a valid length, or a part that is missing its name or offset, has an unknown type, goes beyond the block or overlaps another part. The JSON Schema and the validator cover the new key, with new test files in tests/.

Compatibility

• The format version is still 2. A reader that does not know parts reads and writes the whole block as one string, in one request, exactly as before (§8).
• parts cannot make a block more writable than the register: access stays the register's.

Contents

• Specification: SPEC.md
• JSON Schema: schema/mbmap-2.schema.json
• Validator: tools/validate/validate.py
• Validation tests: tests/

MBMap - Specification v2.1.0

MBMap Specification v2.1.0

Two additions to the version 2 format. Both are optional keys that older readers can ignore, so the format version stays 2 and every existing map stays valid.

What's new

• Identity from the device (identify, §4.8): a new top-level block that describes the answer to Report Slave ID (FC17) or Read Device Identification (FC43). Each field says where the value sits, its type, and a role (model, firmware or serial), with an optional enum to turn a type code into a model name. This lets a tool check the map against devices that do not expose their model in a register. An answer that cannot be read counts as unknown, never as a mismatch (§9).
• Reading in separate requests (read_alone and read_group, §4.9): two optional register keys for devices that refuse a read running across the border between two internal tables, even though every register in it exists. read_alone: true reads a register in a request of its own; read_group reads a register only together with registers of the same group.
• New diagnostics (§7): bad-identify and bad-read. The JSON Schema and the validator cover both additions, with new test files in tests/.

Compatibility

• The format version is still 2. Readers that do not know the new keys ignore them (§8) and read the same registers as before.
• On a device that refuses a joined request, an older reader fails exactly as it did without read_alone and read_group. Readers that support them avoid the failure.

Contents

• Specification: SPEC.md
• JSON Schema: schema/mbmap-2.schema.json
• Validator: tools/validate/validate.py
• Validation tests: tests/

MBMap - Specification v2.0.0

MBMap Specification v2.0.0

This release introduces version 2 of the MBMap specification, a JSON-based format for describing Modbus device register maps.

Highlights

• JSON format: Replaces the legacy CSV-based format with structured .mbmap.json files.
• JSON Schema: Defines the structure and constraints of MBMap v2 files.
• Addressing: Explicit support for 0-based and 1-based register addressing.
• Data types and byte order: Defines signed and unsigned integers, floating-point values, strings, byte order, and word order.
• Register decoding: Adds scaling, offsets, dynamic scale factors, enumerations, sentinels, and bit fields.
• Access control: Describes read/write permissions and write limits for registers.
• Firmware compatibility: Supports model identification, firmware ranges, and firmware-dependent registers.
• Map validation: Defines validation rules, diagnostic codes, severity levels, and JSON Pointer locations.
• Versioning: Separates specification versioning from individual map revisions.
• Interoperability: Defines compatibility rules for readers and support for vendor-specific extensions.
• Device verification: Supports reference values and device identity checks to help detect incorrect maps or connection settings.

Migration from v1

Version 1, based on CSV, is deprecated. The repository includes a migration tool to convert legacy maps to the new format.

New implementations do not need to support v1 files.

Contents

• Specification: SPEC.md
• JSON Schema: schema/mbmap-2.schema.json
• Examples: examples/
• Validation tests: tests/
• Migration tool: tools/migrate/migrate.py

Compatibility

This release defines MBMap format version 2. The format version is independent of the library's release version.

See SPEC.md for the complete specification, validation rules, and compatibility requirements.