diff --git a/doc/source/library/simulator/calls_request.rst b/doc/source/library/simulator/calls_request.rst new file mode 100644 index 0000000000..1e8e274e26 --- /dev/null +++ b/doc/source/library/simulator/calls_request.rst @@ -0,0 +1,14 @@ +.. code-block:: json + + { + "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, + } \ No newline at end of file diff --git a/doc/source/library/simulator/calls_response.rst b/doc/source/library/simulator/calls_response.rst new file mode 100644 index 0000000000..f3cb303fdb --- /dev/null +++ b/doc/source/library/simulator/calls_response.rst @@ -0,0 +1,167 @@ +.. code-block:: json + + { + "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": "IllegalFunction", + "selected": false + }, + { + "value": 2, + "text": "IllegalAddress", + "selected": false + }, + { + "value": 3, + "text": "IllegalValue", + "selected": false + }, + { + "value": 4, + "text": "SlaveFailure", + "selected": false + }, + { + "value": 5, + "text": "Acknowledge", + "selected": false + }, + { + "value": 6, + "text": "SlaveBusy", + "selected": false + }, + { + "value": 7, + "text": "MemoryParityError", + "selected": false + }, + { + "value": 10, + "text": "GatewayPathUnavailable", + "selected": false + }, + { + "value": 11, + "text": "GatewayNoResponse", + "selected": false + } + ], + "function_response_clear_after": 1, + "call_rows": [], + "foot": "not active", + "result": "ok" + } \ No newline at end of file diff --git a/doc/source/library/simulator/registers_request.rst b/doc/source/library/simulator/registers_request.rst new file mode 100644 index 0000000000..24e5ece1aa --- /dev/null +++ b/doc/source/library/simulator/registers_request.rst @@ -0,0 +1,7 @@ +.. code-block:: json + + { + "range_start": 16, + "range_end": 16, + "submit": "Register" + } \ No newline at end of file diff --git a/doc/source/library/simulator/registers_response.rst b/doc/source/library/simulator/registers_response.rst new file mode 100644 index 0000000000..1bdfa70c89 --- /dev/null +++ b/doc/source/library/simulator/registers_response.rst @@ -0,0 +1,34 @@ +.. code-block:: json + + { + "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" + } + ] + } \ No newline at end of file diff --git a/doc/source/library/simulator/restapi.rst b/doc/source/library/simulator/restapi.rst index a976a9e1e2..bb7d7915b7 100644 --- a/doc/source/library/simulator/restapi.rst +++ b/doc/source/library/simulator/restapi.rst @@ -1,4 +1,120 @@ Pymodbus simulator ReST API =========================== -TO BE DOCUMENTED. +This is still a Work In Progress. There may be large changes to the API in the +future. + +There is a skeleton API for the Pymodbus simulator. The API is a simple copy of +having most of the same features as in the Web UI. + +The API provides the following endpoints: + +- /api/registers_json +- /api/calls_json +- /api/server_json +- /api/log_json + +Registers Endpoint +------------------ + +/api/registers_request +^^^^^^^^^^^^^^^^^^^^^^ + + 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: + + .. include:: registers_request.rst + + Response Example: + + .. include:: registers_response.rst + +Calls Endpoint +-------------- + +The calls endpoint is used to handle ModBus response manipulation. + +/api/calls_request +^^^^^^^^^^^^^^^^^^ + + 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: + + .. include:: calls_request.rst + + Response: + + Unfortunately, the endpoint response contains extra clutter due to + not being finalized. + + .. include:: calls_response.rst + +Server Endpoint +--------------- + +The server endpoint has not yet been implemented. + +Log Endpoint +------------ + +The log endpoint has not yet been implemented. \ No newline at end of file