Skip to content

Commit

Permalink
docs: Add simulator REST API documentation
Browse files Browse the repository at this point in the history 
Add documentation skeleton for the simulator API skeleton. The
documentation provides information about the existing endpoints, their
parameters and the expected responses (as examples).

Signed-off-by: Esa Laakso <esa.laakso@fidelix.com>
  • Loading branch information
@efdx
efdx committed Aug 1, 2024
1 parent 8ea603f commit b18d97f
Show file tree
Hide file tree
Showing 5 changed files with 339 additions and 1 deletion.
14 changes: 14 additions & 0 deletions doc/source/library/simulator/calls_request.rst
View file
Original file line number Diff line number Diff line change
@@ -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,
}
167 changes: 167 additions & 0 deletions doc/source/library/simulator/calls_response.rst
View file
Original file line number Diff line number Diff line change
@@ -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"
}
7 changes: 7 additions & 0 deletions doc/source/library/simulator/registers_request.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
.. code-block:: json
{
"range_start": 16,
"range_end": 16,
"submit": "Register"
}
34 changes: 34 additions & 0 deletions doc/source/library/simulator/registers_response.rst
View file
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
118 changes: 117 additions & 1 deletion doc/source/library/simulator/restapi.rst
View file
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit b18d97f

Please sign in to comment.