# 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_device_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": "DEVICE_FAILURE",
>                 "selected": false
>             },
>             {
>                 "value": 5,
>                 "text": "ACKNOWLEDGE",
>                 "selected": false
>             },
>             {
>                 "value": 6,
>                 "text": "DEVICE_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.