Site Configuration Endpoint

Version V1

---

The Site Configurtion Endpoint allows administrators to register and configure downstream devices on a Molecule site. Partners can pair devices — such as inverters, relays, or other DER components — using the following endpoint:

PUT https://api-dev.moleculesystems.com/gateway/admin/device/configure?organizationId=<Organization ID>&moleculeId=<Molecule ID>

Replace <Organization ID> with your organization's UUID and <Molecule ID> with the unique identifier for the Molecule site or gateway.

This end point validates the request and responds synchronously with a receipt.

tip

For production use https://api.moleculesystems.com/

---

Device Configuration Payload Structure

A device configuration request consists of:

• A list of device configuration objects (devices)
• Each object includes Modbus communication parameters and optional register write checks (mb_check_write)

note

If device_id exists within the site / gateway, it will be replaced with this one.

Top-Level Fields

Field	Type	Description
devices	array	List of device configuration objects to pair.

Device Fields (devices[])

Field	Type	Description
device_id	string	Unique identifier for the downstream device (e.g., inverter ID, relay ID).
device_type	string	Protocol type for the device. Allowed value: modbus.
device_name	string	Friendly name given to the device: Inverter.
device_integration	string	Deive integration identifier: <organization id>/<integration internal name>.
mb_type	integer	Modbus type identifier. Specifies the Modbus communication mode. 1-RTU, 2-TCP/IP.
mb_device_type	integer	Modbus device type code identifying the category of device. 1-Meter, 2-Solar Inverter, 3-Storage Inverter, 99-Others
mb_slave_id	integer	Modbus slave ID for the device on the RS-485 bus.
mb_baud	integer	Baud rate for Modbus RTU serial communication (e.g., 9600).
mb_rtu_no	integer	RTU port number the device is physically connected to.
mb_ip	string	IP address for Modbus TCP/IP communication - Only applicable to mb_type 2 (e.g., 192.168.1.80).
mb_port	integer	IP port for Modbus TCP/IP communication - Only applicable to mb_type 2 (e.g., 502).
mb_check_write	array (optional)	List of register write commands used to verify device configuration after pairing.

Register Write Fields (mb_check_write[])

Field	Type	Description
reg_cmd_id	integer	Unique identifier for this register write command.
reg_fun	integer	Modbus function code (e.g., 6 = Write Single Register).
reg_reg	integer	Modbus register address.
reg_value	integer	Value to write to the target register.

note

mb_check_write is used to verify and write Modbus registers to the device once a successful pairing is established.

---

Sample Pair Device Request

{
    "devices": [
        {
            "device_id": "20000",
            "device_type": "modbus",
            "device_name": "Inverter",
            "device_integration": "00000000-0000-0000-0000-000000000001/Cesar_5b5ce76d",
            "mb_type": 2,
            "mb_device_type": 3,
            "mb_slave_id": 1,
            "mb_baud": 9600,
            "mb_rtu_no": 1,
            "mb_check_write": [
                {
                    "reg_cmd_id": 1,
                    "reg_fun": 6,
                    "reg_reg": 10,
                    "reg_value": 40
                },
                {
                    "reg_cmd_id": 2,
                    "reg_fun": 6,
                    "reg_reg": 12,
                    "reg_value": 90
                }
            ]
        }
    ]
}

This example configures:

• Device 20000 → paired as a Modbus TCP/IP device at 192.168.1.80:502
• Two register writes are applied: command 1 writes value 40 to register 10, command 2 writes value 90 to register 12

---

API Response

The API responds synchronously with a receipt confirming the device configuration result for each device.

Sample Response

{
  "devices": [
    {
      "device_id": "20000",
      "status": "accepted",
      "message": "Device paired and configured successfully."
    },
    {
      "device_id": "20001",
      "status": "accepted",
      "message": "Device paired and configured successfully."
    }
  ]
}

Response Fields

Field	Type	Description
devices	array	List of individual device results.
devices[].device_id	string	The device ID associated with the result.
devices[].status	string	Per-device status. "accepted" or "error".
devices[].code	string	Error code if the device failed. Omitted on success.
devices[].message	string	Human-readable description of the result.

Error Responses

Device Pairing Failed

Returned when the API fails to establish a connection with one or more devices.

{
  "devices": [
    {
      "device_id": "20000",
      "status": "error",
      "code": "PAIRING_FAILED",
      "message": "Failed to pair device. The device did not respond."
    },
    {
      "device_id": "20001",
      "status": "error",
      "code": "PAIRING_FAILED",
      "message": "Failed to pair device. The device did not respond."
    }
  ]
}

Registry Write Failed

Returned when the API passes for pairing but fails to complete one or more mb_check_write register writes.

{
  "devices": [
    {
      "device_id": "20000",
      "status": "error",
      "code": "REGISTRY_WRITE_FAILED",
      "message": "Device paired but register write failed."
    },
    {
      "device_id": "20001",
      "status": "error",
      "code": "REGISTRY_WRITE_FAILED",
      "message": "Device paired but register write failed."
    }
  ]
}

Partial Success

Returned when the API passes for some devices and fails for others.

{
  "devices": [
    {
      "device_id": "20000",
      "status": "accepted",
      "message": "Device paired and configured successfully."
    },
    {
      "device_id": "21000",
      "status": "error",
      "code": "PAIRING_FAILED",
      "message": "Failed to pair device. The device did not respond."
    }
  ]
}

warning

When the API fails for some devices, retry only those with "status": "error" — do not resubmit devices that already returned "status": "accepted".

note

A REGISTRY_WRITE_FAILED response means the API passed for pairing but the device is not fully configured. Verify the register addresses and values in mb_check_write for each failed device before retrying.

---

Best Practices for Device Pairing

Idempotency

• Reuse the same device_id when retrying a failed configuration request.
• This API endpoint treats repeated calls with the same device ID as the same configuration.

tip

Using a consistent device_id across retries ensures idempotent behavior — the API will not create duplicate device entries for repeated requests with the same ID.

Device Capability Validation

Partners should ensure:

• The device supports the specified mb_type and mb_deviceType
• The mb_slave_id, mb_baud, and mb_rtu_no values match the physical device
• For mb_type 2 (TCP/IP), mb_ip and mb_port are provided and reachable

Register Write Validation

• mb_check_write entries should use register addresses and values valid for the target device.
• If verification is not needed, mb_check_write can be omitted.

Retry Logic

• Retry only on network or server errors.
• Do not change the device_id between retries for the same device.

warning

Generating a new device_id on every retry attempt may result in duplicate device registrations. Always reuse the original device_id when retrying a failed request.

Time Synchronization

• Ensure partner systems and devices use synchronized clocks (NTP recommended).