MBMap Registry

About MBMap

MBMap is an open format and a shared, community-maintained registry of Modbus device maps: 635 devices from 158 manufacturers today, all in the public domain.

The problem

Reading a Modbus device starts with its register map, and that map usually lives in a PDF manual: a table of addresses, data types, scale factors and byte orders that every engineer types into their own tool by hand. Each tool stores it in its own format, so the same work is repeated for every device, in every tool, by everyone who uses it. Mistakes in the copy (an address off by one, a swapped word order) show up as wrong values on site.

What MBMap does

A .mbmap.json file describes one device model: who makes it, how to connect to it and what every register means. Write the map once, check it, and any compatible tool can load it with the variables already named, scaled and typed. The registry collects these maps in one place, on GitHub, where anyone can add a device or correct one.

How the format works

A map is a plain JSON document with a JSON Schema. Top-level keys give the manufacturer, the model and the connection defaults (protocol, unit id, serial settings, byte and word order, address base). Each register has a name, a Modbus area (coil, discrete, input, holding), an address and a type, and may add a unit, a scale, access rights, write limits, translation tables for states and bit fields. One register per line keeps every change a one-line diff. 

{
  "mbmap": 2,
  "vendor": "Example Corp",
  "model": "EM-100",
  "protocol": "rtu",
  "baudrate": 9600,
  "parity": "E",
  "word_order": "big",
  "registers": [
    {"name": "Voltage", "group": "Measurements", "area": "input", "address": 0, "type": "float32", "unit": "V"},
    {"name": "Active energy", "group": "Energy", "area": "holding", "address": 256, "type": "uint32", "scale": 0.01, "unit": "kWh", "word_order": "little"},
    {"name": "Reset energy", "group": "Commands", "area": "coil", "address": 0, "type": "bool", "access": "W"}
  ]
}

The full rules, including validation codes every reader reports the same way, are in the specification (SPEC.md).

How far a map can be trusted

Every map in the library says where it comes from in x_status. It is a library convention, not part of the format, and Modbench shows it next to each map.

  • Verified Tested on a real device. (18 maps)
  • Official Written from the manufacturer's documentation, but not tested on a device yet. (456 maps)
  • Unofficial Copied from an unofficial source and not tested. Read it as a draft and check a value on the real device before you rely on the rest. (161 maps)

Many unofficial maps were converted from other open catalogues to get the library started, and nobody has checked them against the manufacturer's documentation yet. Whatever the status, the maps are provided as is: check a map against the manufacturer's documentation before you write to a live device.

MBMap and Modbench

Modbench is a Modbus TCP/RTU client for Windows, Linux and macOS, and the main tool that reads MBMap maps. It browses and downloads this library directly, reads and writes a device by register name, checks the device against the map's models and firmware, and can run a simulated device shaped after a map. This website is its companion on the web: the same maps and the same look, for finding a device before you connect to it.

Using the maps in your own tool

The format is open and any tool can read it. Everything is served from the repository:

  • index.json lists every map with its path, size, SHA-256, status and register count.
  • Each map is at https://raw.githubusercontent.com/nobrega8/mbmap-library/main/maps/<vendor>/<model>.mbmap.json.
  • A signed copy of the index is published on the signed branch, so an app can check that the maps it downloads are the library's (see Signed index).
  • The tests/ folder has sample files and the diagnostics a reader must report, to check an implementation against the spec.

Support part of the format or all of it, then open a pull request to list your tool on the compatibility page.

An open community project

The maps, the specification and the tools are dedicated to the public domain under CC0 1.0: use them for anything, including commercial products, without asking. The registry grows with contributions from engineers, technicians, integrators and manufacturers: new maps, corrections and tests on real hardware. Here is how to help.

Esc