Pymodbus simulator ReST API

This is still a Work In Progress. There may be large changes to the API in the future.

The API is a simple copy of having most of the same features as in the Web UI.

The API provides the following endpoints:

  • /restapi/registers

  • /restapi/calls

  • /restapi/server

  • /restapi/log

Registers Endpoint

/restapi/registers

The registers endpoint is used to read and write registers.

Request Parameters

  • submit (string, required):

    The action to perform. Must be one of Register, Set.

  • range_start (integer, optional):

    The starting register to read from. Defaults to 0.

  • range_end (integer, optional):

    The ending register to read from. Defaults to range_start.

Response Parameters

Returns a json object with the following keys:

  • result (string):

    The result of the action. Either ok or error.

  • error (string, conditional):

    The error message if the result is error.

  • register_rows (list):

    A list of objects containing the data of the registers.

  • footer (string):

    A cleartext status of the action. HTML leftover.

  • register_types (list):

    A static list of register types. HTML leftover.

  • register_actions (list):

    A static list of register actions. HTML leftover.

Example Request and Response

Request Example:

{
    "range_start": 16,
    "range_end": 16,
    "submit": "Register"
}

Response Example:

{
    "result": "ok",
    "footer": "Operation completed successfully",
    "register_types": {
        "bits": 1,
        "uint16": 2,
        "uint32": 3,
        "float32": 4,
        "string": 5,
        "next": 6,
        "invalid": 0
    },
    "register_actions": {
        "null": 0,
        "increment": 1,
        "random": 2,
        "reset": 3,
        "timestamp": 4,
        "uptime": 5
    },
    "register_rows": [
        {
            "index": "16",
            "type": "uint16",
            "access": "True",
            "action": "none",
            "value": "3124",
            "count_read": "0",
            "count_write": "0"
        }
    ]
}

Calls Endpoint

The calls endpoint is used to handle ModBus response manipulation.

/restapi/calls

The calls endpoint is used to simulate different conditions for ModBus responses.

Request Parameters

  • submit (string, required):

    The action to perform. Must be one of Simulate, Reset.

The following must be present if submit is Simulate:

  • response_clear_after (integer, required):

    The number of packet to clear simulation after.

  • response_cr (string, required):

    Must be present but can be any value. Turns on change rate simulation (WIP).

  • response_cr_pct (integer, required):

    The percentage of change rate, how many percent of packets should be changed.

  • response_split (string, required):

    Must be present but can be any value. Turns on split response simulation (WIP).

  • split_delay (integer, required):

    The delay in seconds to wait before sending the second part of the split response.

  • response_delay (integer, required):

    The delay in seconds to wait before sending the response.

  • response_error (integer, required):

    The error code to send in the response. The valid values can be one from the response function_error list.

When submit is Reset, no other parameters are required. It resets all simulation options to their defaults (off).

Example Request and Response

Request:

{
    "submit": "Simulate"
    "response_clear_after": 0,
    "response_cr": "",
    "response_cr_pct": 0,
    "response_split": "",
    "split_delay": 1
    "response_delay": 0,
    "response_error": 0,
    "response_junk_datalen": 0,
    "response_type": 0,
}

Response:

Unfortunately, the endpoint response contains extra clutter due to not being finalized.

{
    "simulation_action": "ACTIVE",
    "range_start": null,
    "range_stop": null,
    "function_codes": [
        {
            "value": 3,
            "text": "read_holding_registers",
            "selected": false
        },
        {
            "value": 2,
            "text": "read_discrete_input",
            "selected": false
        },
        {
            "value": 4,
            "text": "read_input_registers",
            "selected": false
        },
        {
            "value": 1,
            "text": "read_coils",
            "selected": false
        },
        {
            "value": 15,
            "text": "write_coils",
            "selected": false
        },
        {
            "value": 16,
            "text": "write_registers",
            "selected": false
        },
        {
            "value": 6,
            "text": "write_register",
            "selected": false
        },
        {
            "value": 5,
            "text": "write_coil",
            "selected": false
        },
        {
            "value": 23,
            "text": "read_write_multiple_registers",
            "selected": false
        },
        {
            "value": 8,
            "text": "diagnostic_status",
            "selected": false
        },
        {
            "value": 7,
            "text": "read_exception_status",
            "selected": false
        },
        {
            "value": 11,
            "text": "get_event_counter",
            "selected": false
        },
        {
            "value": 12,
            "text": "get_event_log",
            "selected": false
        },
        {
            "value": 17,
            "text": "report_slave_id",
            "selected": false
        },
        {
            "value": 20,
            "text": "read_file_record",
            "selected": false
        },
        {
            "value": 21,
            "text": "write_file_record",
            "selected": false
        },
        {
            "value": 22,
            "text": "mask_write_register",
            "selected": false
        },
        {
            "value": 24,
            "text": "read_fifo_queue",
            "selected": false
        },
        {
            "value": 43,
            "text": "read_device_information",
            "selected": false
        }
    ],
    "function_show_hex_checked": false,
    "function_show_decoded_checked": false,
    "function_response_normal_checked": true,
    "function_response_error_checked": false,
    "function_response_empty_checked": false,
    "function_response_junk_checked": false,
    "function_response_split_checked": true,
    "function_response_split_delay": 1,
    "function_response_cr_checked": false,
    "function_response_cr_pct": 0,
    "function_response_delay": 0,
    "function_response_junk": 0,
    "function_error": [
        {
            "value": 1,
            "text": "ILLEGAL_FUNCTION",
            "selected": false
        },
        {
            "value": 2,
            "text": "ILLEGAL_ADDRESS",
            "selected": false
        },
        {
            "value": 3,
            "text": "ILLEGAL_VALUE",
            "selected": false
        },
        {
            "value": 4,
            "text": "SLAVE_FAILURE",
            "selected": false
        },
        {
            "value": 5,
            "text": "ACKNOWLEDGE",
            "selected": false
        },
        {
            "value": 6,
            "text": "SLAVE_BUSY",
            "selected": false
        },
        {
            "value": 7,
            "text": "MEMORY_PARITY_ERROR",
            "selected": false
        },
        {
            "value": 10,
            "text": "GATEWAY_PATH_UNAVIABLE",
            "selected": false
        },
        {
            "value": 11,
            "text": "GATEWAY_NO_RESPONSE",
            "selected": false
        }
    ],
    "function_response_clear_after": 1,
    "call_rows": [],
    "foot": "not active",
    "result": "ok"
}

Server Endpoint

The server endpoint has not yet been implemented.

Log Endpoint

The log endpoint has not yet been implemented.