An open library of Modbus register maps in the .mbmap format, a JSON format with a JSON Schema.
Each file describes one device model: the manufacturer, how to connect to it and what every register means. Load a map into a compatible tool and you get the device's variables, already named, scaled and typed, without typing addresses from a PDF manual.
SPEC.md the .mbmap format specification
schema/mbmap-2.schema.json its JSON Schema
COMPATIBILITY.md tools that read the format, and what each supports
maps/<vendor>/<model>.mbmap.json the shared maps
examples/ fictional maps that show the format
index.json list of the maps, for apps that browse the library
tools/ validator, index builder and other scripts (see tools/README.md)
tests/ sample files and the diagnostics each must produce,
for checking any .mbmap reader against the spec
Folder and file names are lowercase slugs, e.g. maps/acme-meters/pm-200.mbmap.json.
The maps in this library say how far they can be trusted in x_status. It is not part of the mbmap format, just an optional key that this library and Modbench read:
verified: tested on a real device.official: written from the manufacturer's documentation (named insource), but not tested on a device yet.unofficial: copied from an unofficial source and not tested. A large part of the library was converted from other open catalogues of Modbus tables to get everyone started. Nobody has checked these against the manufacturer's documentation yet, and some details (byte order, which register area, scaling) may be wrong. Read them as a draft and check a value on the real device before you rely on the rest.
pie showData
title Maps by status
"Verified" : 6
"Official" : 269
"Unofficial" : 222
Tested a map on your device? Tell us in a pull request or a test report, even if you did not write the map.
Corrections are the most useful contribution: see CONTRIBUTING.md. Questions and ideas go to Discussions.
A map is a JSON file with one register per line, so it reads well in any text editor and any language can load it with its JSON parser; editors that support JSON Schema check it as you type.
COMPATIBILITY.md lists the tools that read the format and which parts of it each one supports. The main one is Modbench, a Modbus client for Windows, Linux and macOS that browses and downloads the maps in this repository directly. ScanBus-BR, a Modbus simulator and sniffer for Windows and Linux, can search the library too, and MTUI, a Modbus client for the terminal, imports a pasted map as labelled, decoded registers.
Building a tool that reads .mbmap? Follow SPEC.md, check it against the samples in tests/, and open a pull request to add it to COMPATIBILITY.md. Work in progress is welcome in Show and tell.
A tool that reads .mbmap files can say so with this badge, which links here:
[](https://github.com/nobrega8/mbmap-library)New maps and fixes are welcome. Read CONTRIBUTING.md, then check your file:
python tools/validate/validate.py maps/your-vendor/your-model.mbmap.jsonThanks to everyone who has added or corrected a map.
The maps, the spec and the tools are dedicated to the public domain under CC0 1.0. You can use them for anything, including commercial products, without asking or giving credit.
The maps are provided as is. Always check a map against the manufacturer's documentation before you write to a live device.
The library is free and in the public domain. If it saves you time, you can support its development on Buy Me a Coffee:
