Modbus TCP
Read and write coils and registers of PLCs, meters and industrial gateways over Modbus TCP, and convert registers to numbers and back. Writes act on real equipment. Typical uses: collect meter readings, monitor a machine.
modbus read_holdingmodbus read_holdingmodbus read_inputmodbus read_inputmodbus read_coilsmodbus read_coilsmodbus read_discretemodbus read_discretemodbus write_coilmodbus write_coilmodbus write_registermodbus write_registermodbus write_coilsmodbus write_coilsmodbus write_registersmodbus write_registersmodbus batchmodbus batchmodbus decodemodbus decodemodbus encodemodbus encode

modbus read_holding <host> <address> <quantity>


Description

    Read holding registers (function 3), 125 at most. Result: {function, unit_id, address, quantity, values}, values as unsigned 16-bit integers

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
admin
modbus read_holding "127.0.0.1" "0" "4"
mentdb
{"function": "read_holding", "unit_id": 1, "address": 0, "quantity": 4, "values": [1234, 65535, 16812, 0]}

modbus read_holding <host> <address> <quantity> <json_params>


Description

    Read holding registers with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange), type (int16, uint16, int32, uint32, int64, uint64, float32, float64: adds decoded to the result), byte_order and word_order (big or little, big by default)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
    json_params:   The parameters - String - required
admin
modbus read_holding "127.0.0.1" "0" "4" "{\"port\": 24502}"
mentdb
{"function": "read_holding", "unit_id": 1, "address": 0, "quantity": 4, "values": [1234, 65535, 16812, 0]}
Fixed result from a real call on a local test server (127.0.0.1): two registers as a float
admin
modbus read_holding "127.0.0.1" "2" "2" "{\"port\": 24502, \"type\": \"float32\"}"
mentdb
{"function": "read_holding", "unit_id": 1, "address": 2, "quantity": 2, "values": [16812, 0], "decoded": [21.5]}
Fixed result from a real call on a local test server (127.0.0.1): a float whose words are swapped
admin
modbus read_holding "127.0.0.1" "10" "2" "{\"port\": 24502, \"type\": \"float32\", \"word_order\": \"little\"}"
mentdb
{"function": "read_holding", "unit_id": 1, "address": 10, "quantity": 2, "values": [0, 16812], "decoded": [21.5]}
Fixed result from a real call on a local test server (127.0.0.1): another unit id behind a gateway
admin
modbus read_holding "127.0.0.1" "0" "1" "{\"port\": 24502, \"unit_id\": 5, \"timeout_ms\": 2000}"
mentdb
{"function": "read_holding", "unit_id": 5, "address": 0, "quantity": 1, "values": [1234]}
Fixed result from a real call on a local test server (127.0.0.1): an address that the device does not have
admin
modbus read_holding "127.0.0.1" "5000" "1" "{\"port\": 24502}"
mentdb
Sorry, an error appears (the device answered Modbus exception 2 (illegal data address: this address range does not exist on the device)).
Fixed result from a real call on a local test server (127.0.0.1): nobody listens on this port
admin
modbus read_holding "127.0.0.1" "0" "1" "{\"port\": 24999, \"timeout_ms\": 1000}"
mentdb
Sorry, an error appears (cannot connect to 127.0.0.1:24999 (refused)).

modbus read_input <host> <address> <quantity>


Description

    Read input registers (function 4), 125 at most. Same result as modbus read_holding

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
admin
modbus read_input "127.0.0.1" "0" "3"
mentdb
{"function": "read_input", "unit_id": 1, "address": 0, "quantity": 3, "values": [7, 8, 9]}

modbus read_input <host> <address> <quantity> <json_params>


Description

    Read input registers with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange), type (int16, uint16, int32, uint32, int64, uint64, float32, float64: adds decoded to the result), byte_order and word_order (big or little, big by default)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
    json_params:   The parameters - String - required
admin
modbus read_input "127.0.0.1" "0" "3" "{\"port\": 24502}"
mentdb
{"function": "read_input", "unit_id": 1, "address": 0, "quantity": 3, "values": [7, 8, 9]}

modbus read_coils <host> <address> <quantity>


Description

    Read coils (function 1), 2000 at most. values holds 0 or 1

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
admin
modbus read_coils "127.0.0.1" "0" "3"
mentdb
{"function": "read_coils", "unit_id": 1, "address": 0, "quantity": 3, "values": [0, 1, 0]}

modbus read_coils <host> <address> <quantity> <json_params>


Description

    Read coils with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
    json_params:   The parameters - String - required
admin
modbus read_coils "127.0.0.1" "0" "3" "{\"port\": 24502}"
mentdb
{"function": "read_coils", "unit_id": 1, "address": 0, "quantity": 3, "values": [0, 1, 0]}

modbus read_discrete <host> <address> <quantity>


Description

    Read discrete inputs (function 2), 2000 at most. values holds 0 or 1

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
admin
modbus read_discrete "127.0.0.1" "0" "10"
mentdb
{"function": "read_discrete", "unit_id": 1, "address": 0, "quantity": 10, "values": [1, 0, 1, 1, 0, 0, 1, 0, 1, 1]}

modbus read_discrete <host> <address> <quantity> <json_params>


Description

    Read discrete inputs with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    quantity:   The number of values - Number - required
    json_params:   The parameters - String - required
admin
modbus read_discrete "127.0.0.1" "0" "10" "{\"port\": 24502}"
mentdb
{"function": "read_discrete", "unit_id": 1, "address": 0, "quantity": 10, "values": [1, 0, 1, 1, 0, 0, 1, 0, 1, 1]}

modbus write_coil <host> <address> <value>


Description

    DANGER, see the top of the page. Write one coil (function 5). Result: {function, unit_id, address, quantity, written}

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    value:   1, 0, true or false - String - required
admin
modbus write_coil "127.0.0.1" "5" "true"
mentdb
{"function": "write_coil", "unit_id": 1, "address": 5, "quantity": 1, "written": [1]}

modbus write_coil <host> <address> <value> <json_params>


Description

    DANGER, see the top of the page. Write one coil with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    value:   1, 0, true or false - String - required
    json_params:   The parameters - String - required
admin
modbus write_coil "127.0.0.1" "5" "true" "{\"port\": 24502}"
mentdb
{"function": "write_coil", "unit_id": 1, "address": 5, "quantity": 1, "written": [1]}

modbus write_register <host> <address> <value>


Description

    DANGER, see the top of the page. Write one holding register (function 6)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    value:   An integer from -32768 to 65535. A negative value is sent as its two's complement - Number - required
admin
modbus write_register "127.0.0.1" "50" "-2"
mentdb
{"function": "write_register", "unit_id": 1, "address": 50, "quantity": 1, "written": [65534]}

modbus write_register <host> <address> <value> <json_params>


Description

    DANGER, see the top of the page. Write one holding register with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    value:   An integer from -32768 to 65535 - Number - required
    json_params:   The parameters - String - required
admin
modbus write_register "127.0.0.1" "50" "-2" "{\"port\": 24502}"
mentdb
{"function": "write_register", "unit_id": 1, "address": 50, "quantity": 1, "written": [65534]}

modbus write_coils <host> <address> <json_values>


Description

    DANGER, see the top of the page. Write several coils (function 15), 1968 at most

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    json_values:   A JSON array of 1, 0, true or false - String - required
admin
modbus write_coils "127.0.0.1" "10" "[1, 0, 1, 1]"
mentdb
{"function": "write_coils", "unit_id": 1, "address": 10, "quantity": 4, "written": [1, 0, 1, 1]}

modbus write_coils <host> <address> <json_values> <json_params>


Description

    DANGER, see the top of the page. Write several coils with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    json_values:   A JSON array of 1, 0, true or false - String - required
    json_params:   The parameters - String - required
admin
modbus write_coils "127.0.0.1" "10" "[1, 0, 1, 1]" "{\"port\": 24502}"
mentdb
{"function": "write_coils", "unit_id": 1, "address": 10, "quantity": 4, "written": [1, 0, 1, 1]}

modbus write_registers <host> <address> <json_values>


Description

    DANGER, see the top of the page. Write several holding registers (function 16), 123 at most

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    json_values:   A JSON array of integers from -32768 to 65535 - String - required
admin
modbus write_registers "127.0.0.1" "60" "[16812, 0]"
mentdb
{"function": "write_registers", "unit_id": 1, "address": 60, "quantity": 2, "written": [16812, 0]}

modbus write_registers <host> <address> <json_values> <json_params>


Description

    DANGER, see the top of the page. Write several holding registers with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange)

Parameters

    host:   The host name or IP address of the device - String - required
    address:   The first address, from 0 (the protocol address, not the 40001 of the documentation of some devices) - Number - required
    json_values:   A JSON array of integers from -32768 to 65535 - String - required
    json_params:   The parameters - String - required
admin
modbus write_registers "127.0.0.1" "60" "[16812, 0]" "{\"port\": 24502}"
mentdb
{"function": "write_registers", "unit_id": 1, "address": 60, "quantity": 2, "written": [16812, 0]}

modbus batch <host> <json_requests>


Description

    Run up to 1000 requests in order on one connection. Each request is {op, address, quantity or value or values, unit_id, type, byte_order, word_order}, op being read_coils, read_discrete, read_holding, read_input, write_coil, write_register, write_coils or write_registers. All requests are checked before the first byte is sent. Stops at the first error. Result: {ok, failed, not_attempted, results}. DANGER if it holds writes, see the top of the page

Parameters

    host:   The host name or IP address of the device - String - required
    json_requests:   The requests, as a JSON array - String - required
admin
modbus batch "127.0.0.1" "[{\"op\": \"read_input\", \"address\": 0, \"quantity\": 1}]"
mentdb
{"ok": 1, "failed": 0, "not_attempted": 0, "results": [{"ok": true, "function": "read_input", "unit_id": 1, "address": 0, "quantity": 1, "values": [7]}]}

modbus batch <host> <json_requests> <json_params>


Description

    Run requests with parameters: port (502), unit_id (1, 0 to 255), timeout_ms (5000, 100 to 120000: connection, and then each exchange), stop_on_error (true; false goes on after a Modbus exception of the device; a lost connection or a wrong answer always stops the list)

Parameters

    host:   The host name or IP address of the device - String - required
    json_requests:   The requests, as a JSON array - String - required
    json_params:   The parameters - String - required
admin
modbus batch "127.0.0.1" "[{\"op\": \"write_register\", \"address\": 70, \"value\": 9}, {\"op\": \"read_holding\", \"address\": 70, \"quantity\": 1}, {\"op\": \"read_holding\", \"address\": 2, \"quantity\": 2, \"type\": \"float32\"}]" "{\"port\": 24502}"
mentdb
{"ok": 3, "failed": 0, "not_attempted": 0, "results": [{"ok": true, "function": "write_register", "unit_id": 1, "address": 70, "quantity": 1, "written": [9]}, {"ok": true, "function": "read_holding", "unit_id": 1, "address": 70, "quantity": 1, "values": [9]}, {"ok": true, "function": "read_holding", "unit_id": 1, "address": 2, "quantity": 2, "values": [16812, 0], "decoded": [21.5]}]}
Fixed result from a real call on a local test server (127.0.0.1): an exception does not stop the list
admin
modbus batch "127.0.0.1" "[{\"op\": \"read_holding\", \"address\": 5000, \"quantity\": 1}, {\"op\": \"read_input\", \"address\": 0, \"quantity\": 1}]" "{\"port\": 24502, \"stop_on_error\": false}"
mentdb
{"ok": 1, "failed": 1, "not_attempted": 0, "results": [{"ok": false, "function": "read_holding", "unit_id": 1, "address": 5000, "error": "the device answered Modbus exception 2 (illegal data address: this address range does not exist on the device)"}, {"ok": true, "function": "read_input", "unit_id": 1, "address": 0, "quantity": 1, "values": [7]}]}

modbus decode <json_registers> <type>


Description

    Turn registers into numbers, big endian. Returns a JSON array of values; the number of registers must be a multiple of the width of the type. NaN and the infinities are the texts NaN, Infinity, -Infinity

Parameters

    json_registers:   A JSON array of registers - String - required
    type:   int16, uint16, int32, uint32, int64, uint64, float32 or float64 - String - required
admin
modbus decode "[16812, 0]" "float32"
mentdb
[21.5]
Two int32
admin
modbus decode "[0, 7, 65535, 65535]" "int32"
mentdb
[7, -1]
A uint64
admin
modbus decode "[65535, 65535, 65535, 65535]" "uint64"
mentdb
[18446744073709551615]

modbus decode <json_registers> <type> <json_params>


Description

    Turn registers into numbers with parameters: byte_order (big or little: inside each register), word_order (big or little: the order of the registers)

Parameters

    json_registers:   A JSON array of registers - String - required
    type:   The type - String - required
    json_params:   The parameters - String - required
admin
modbus decode "[0, 16812]" "float32" "{\"word_order\": \"little\"}"
mentdb
[21.5]
Bytes swapped in each word (BADC)
admin
modbus decode "[44097, 0]" "float32" "{\"byte_order\": \"little\"}"
mentdb
[21.5]
Both (DCBA)
admin
modbus decode "[0, 44097]" "float32" "{\"byte_order\": \"little\", \"word_order\": \"little\"}"
mentdb
[21.5]
Used in use cases (1 recipe)

    Integrator & ETL developer › Turn the registers of an energy meter into numbers, and prepare a setpoint
Often used with

    modbus encode

modbus encode <values> <type>


Description

    Turn a number or a JSON array of numbers into registers for modbus write_registers, big endian. A value out of the range of the type is refused

Parameters

    values:   A number or a JSON array of numbers - String - required
    type:   int16, uint16, int32, uint32, int64, uint64, float32 or float64 - String - required
admin
modbus encode "21.5" "float32"
mentdb
[16812, 0]
Two int32
admin
modbus encode "[7, -1]" "int32"
mentdb
[0, 7, 65535, 65535]

modbus encode <values> <type> <json_params>


Description

    Turn numbers into registers with parameters: byte_order and word_order (big or little)

Parameters

    values:   A number or a JSON array of numbers - String - required
    type:   The type - String - required
    json_params:   The parameters - String - required
admin
modbus encode "21.5" "float32" "{\"word_order\": \"little\"}"
mentdb
[0, 16812]
Used in use cases (1 recipe)

    Integrator & ETL developer › Turn the registers of an energy meter into numbers, and prepare a setpoint
Often used with

    modbus decode