Contribute
A good map saves the next person an afternoon with a PDF manual. All maps live in the mbmap-library repository on GitHub; every contribution goes through it.
Add a new device
Write a map from the manufacturer's public documentation, check it with the validator and open a pull request.
Request a device
Can't write the map yourself? Ask for it, ideally with a link to the manufacturer's Modbus documentation.
Verify a map on real hardware
Read a device with a map and compare the values with its display. Report the result, good or bad, even if you did not write the map.
Report or fix incorrect data
A wrong address, type, scale or byte order? Every device page has “Suggest a correction”, which edits the file on GitHub and opens a pull request, and “Report a problem”.
Check an unofficial map
Compare a converted map with the manufacturer's manual, fix what is wrong and record the document you used. It then becomes official.
Improve the documentation
Questions about the format, ideas for it, or a tool that reads .mbmap files: start a discussion, or propose a change to the docs.
Submitting a map and verifying a map
Submitting adds or changes a file: you write the registers from a source, and say which in
sources. A map written from the manufacturer's documentation is
Official; one copied from
another catalogue, a forum or a third-party integration is
Unofficial.
Verifying is testing an existing map on a real device: read it, compare the values with the device's display or its own software (at least one value per register group, and the byte and word order of a 32-bit value), and report the device, firmware and connection you used. Only then does a map become Verified. Anyone can verify a map; you do not need to be its author. A test that finds problems is just as useful: report it so the map is not marked as verified.
Before you open a pull request
- Name the file
maps/<vendor>/<model>.mbmap.jsonwith lowercase slugs, e.g.maps/acme-meters/pm-200.mbmap.json. - Run the validator and fix every error:
python tools/validate/validate.py maps/<vendor>/<model>.mbmap.json - Rebuild the index:
python tools/index/build_index.py - Increase
revisionwhen a change affects how a device is read or written.
Rules
- Only public information. Nothing from documents under NDA or marked confidential.
- Do not copy manuals. Addresses, types and units are facts; write descriptions in your own words.
- No private data. No IP addresses, serial numbers or site names from a real installation.
- Prefer accuracy over coverage. If you are unsure about a register, leave it out or say so.
The full guide is CONTRIBUTING.md. By contributing, you agree to release your contribution under CC0 1.0.