> For the complete documentation index, see [llms.txt](https://docs.smart-stuff.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smart-stuff.nl/p1-modbus-dongle/firmware-v3-all-modbus-rtu-adapters/custom-mapping.md). # Custom Modbus mapping Create, validate, save and use a custom Modbus register mapping on Smart Meter Modbus RTU adapters with firmware v3. The custom mapper lets an experienced installer define the Modbus registers that a connected system expects. It is useful when no supplied standard mapping matches an inverter, charger, PLC or energy-management system. {% hint style="warning" %} This is an expert feature for **Smart Meter Modbus RTU adapters with firmware v3**. A custom mapping can make the target system display incorrect energy data when register addresses, data types, scaling or word order are wrong. Use a standard mapping whenever one fits. {% endhint %}
Firmware v3 Custom mapping Expert screen with verified mappings, mapping settings and editable register rows

The Custom mapping · Expert screen: start from a verified mapping or build and validate a profile register by register.

## The mapper screen The top of the screen has three parts: * **Verified mappings** lets you choose a Smartstuff starting point and load it into the editor. * **Mapping** contains the mapping name, 32-bit word order and the behaviour for registers that are not mapped. It also has buttons to start a new mapping and import or export JSON. * **Register entries** is the editable table. Each row has the register address, source or derived value, factor, type, sign, missing-value rule and an optional constant. Use the delete icon to remove an entry. At the bottom of the table, use **Validate** before uploading. **Validate & upload** checks the mapping and only then writes it to the adapter. **← Device** returns to the normal Device Manager screen without changing the mapping. ## What it does One named custom mapping can be stored persistently on each adapter. It contains up to 80 register entries. For every entry you choose: * The Modbus register address. * The smart-meter value or derived value to expose, or a constant value. * The scale factor. * The data type: 16- or 32-bit signed/unsigned integer, or 32-bit float. * The missing-value behaviour: use the source default, return zero, or report it as unavailable. For 32-bit entries you can select MSW-first or LSW-first word order for the entire mapping. You can also choose whether registers not included in the mapping return zero (the default) or a Modbus error. Returning zero can be needed when a controller reads a broad register block containing unused addresses. V3 also supports **By direction** for applicable phase-current and total-current values, so a current can follow the import/export direction reported by the smart meter. ## Create and activate a mapping 1. Install the **V3 Alpha** with the [web installer](/p1-modbus-dongle/firmware-v2-existing-installations/update.md), then connect the adapter with a USB data cable and open the [Device Manager](https://config.smart-stuff.nl/). 2. Select **Connect** and choose the adapter. The **Custom mapping · Expert** action appears only when compatible v3 firmware is connected. 3. Open **Custom mapping · Expert**. 4. Choose a verified starter mapping and select **Use mapping**, or select **New mapping**. 5. Enter a recognizable name, set the word order and add the required register entries. 6. Select **Validate**. Correct every reported address, overlap, type, source or size issue. 7. Select **Validate & upload**. The adapter verifies and stores the mapping before activating it. 8. Return to the device overview, choose **Custom mapping — *****your mapping name*** as the Modbus mapping and select **Save**. 9. Test the required registers with the target system before commissioning the installation. The mapper stores the editable definition in the browser while you work. The adapter receives a validated compiled version, not arbitrary JSON. ## Verified starter mappings The mapper includes a Smartstuff library of verified starting points: * **SDM630 compatible** * **SDM630 compatible (inverted)** for installations that need inverted signed power values * **P1M floats**, including signed phase currents by direction Load a starter mapping when it is close to the desired result, then make only the required changes. A starter mapping is a useful basis, but the final responsibility for compatibility with the target device remains with the installer. ## Save and share safely Use **Export JSON** to make a backup before changing a working mapping. Use **Import JSON** to restore it or transfer it to another v3 Smart Meter Modbus RTU adapter. Importing does not change the adapter until you validate and upload the mapping. Only one custom mapping is stored on an adapter. Uploading another one replaces the stored custom mapping after validation succeeds. Keep the exported JSON for each installation, together with the target device model and its required register documentation. ## Limits and troubleshooting * A name may contain up to 48 printable characters. * A mapping may contain up to 80 entries and use at most 1024 bytes of adapter storage. * Register entries may not overlap; a 32-bit value occupies two consecutive Modbus registers. * Custom mappings are specific to firmware v3. Export the JSON before changing major firmware generations. * If **Custom mapping** is not available in the mapping list, upload a valid mapping first and then select it in the Device Manager. * Use the [Modbus monitor](/p1-modbus-dongle/firmware-v2-existing-installations/configuration.md#modbus-monitor-and-diagnostics) while testing to see the addresses and results requested by the target system.