Skip to content

Commit 8acc3ad

Browse files
efdxefdx
committed
docs: Add simulator REST API documentation
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 <[email protected]>
1 parent b74184a commit 8acc3ad

File tree

5 files changed

+339
-1
lines changed

5 files changed

+339
-1
lines changed

‎doc/source/library/simulator/calls_request.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. code-block:: json
2+
3+
{
4+
"submit": "Simulate"
5+
"response_clear_after": 0,
6+
"response_cr": "",
7+
"response_cr_pct": 0,
8+
"response_split": "",
9+
"split_delay": 1
10+
"response_delay": 0,
11+
"response_error": 0,
12+
"response_junk_datalen": 0,
13+
"response_type": 0,
14+
}

‎doc/source/library/simulator/calls_response.rst

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
.. code-block:: json
2+
3+
{
4+
"simulation_action": "ACTIVE",
5+
"range_start": null,
6+
"range_stop": null,
7+
"function_codes": [
8+
{
9+
"value": 3,
10+
"text": "read_holding_registers",
11+
"selected": false
12+
},
13+
{
14+
"value": 2,
15+
"text": "read_discrete_input",
16+
"selected": false
17+
},
18+
{
19+
"value": 4,
20+
"text": "read_input_registers",
21+
"selected": false
22+
},
23+
{
24+
"value": 1,
25+
"text": "read_coils",
26+
"selected": false
27+
},
28+
{
29+
"value": 15,
30+
"text": "write_coils",
31+
"selected": false
32+
},
33+
{
34+
"value": 16,
35+
"text": "write_registers",
36+
"selected": false
37+
},
38+
{
39+
"value": 6,
40+
"text": "write_register",
41+
"selected": false
42+
},
43+
{
44+
"value": 5,
45+
"text": "write_coil",
46+
"selected": false
47+
},
48+
{
49+
"value": 23,
50+
"text": "read_write_multiple_registers",
51+
"selected": false
52+
},
53+
{
54+
"value": 8,
55+
"text": "diagnostic_status",
56+
"selected": false
57+
},
58+
{
59+
"value": 7,
60+
"text": "read_exception_status",
61+
"selected": false
62+
},
63+
{
64+
"value": 11,
65+
"text": "get_event_counter",
66+
"selected": false
67+
},
68+
{
69+
"value": 12,
70+
"text": "get_event_log",
71+
"selected": false
72+
},
73+
{
74+
"value": 17,
75+
"text": "report_slave_id",
76+
"selected": false
77+
},
78+
{
79+
"value": 20,
80+
"text": "read_file_record",
81+
"selected": false
82+
},
83+
{
84+
"value": 21,
85+
"text": "write_file_record",
86+
"selected": false
87+
},
88+
{
89+
"value": 22,
90+
"text": "mask_write_register",
91+
"selected": false
92+
},
93+
{
94+
"value": 24,
95+
"text": "read_fifo_queue",
96+
"selected": false
97+
},
98+
{
99+
"value": 43,
100+
"text": "read_device_information",
101+
"selected": false
102+
}
103+
],
104+
"function_show_hex_checked": false,
105+
"function_show_decoded_checked": false,
106+
"function_response_normal_checked": true,
107+
"function_response_error_checked": false,
108+
"function_response_empty_checked": false,
109+
"function_response_junk_checked": false,
110+
"function_response_split_checked": true,
111+
"function_response_split_delay": 1,
112+
"function_response_cr_checked": false,
113+
"function_response_cr_pct": 0,
114+
"function_response_delay": 0,
115+
"function_response_junk": 0,
116+
"function_error": [
117+
{
118+
"value": 1,
119+
"text": "IllegalFunction",
120+
"selected": false
121+
},
122+
{
123+
"value": 2,
124+
"text": "IllegalAddress",
125+
"selected": false
126+
},
127+
{
128+
"value": 3,
129+
"text": "IllegalValue",
130+
"selected": false
131+
},
132+
{
133+
"value": 4,
134+
"text": "SlaveFailure",
135+
"selected": false
136+
},
137+
{
138+
"value": 5,
139+
"text": "Acknowledge",
140+
"selected": false
141+
},
142+
{
143+
"value": 6,
144+
"text": "SlaveBusy",
145+
"selected": false
146+
},
147+
{
148+
"value": 7,
149+
"text": "MemoryParityError",
150+
"selected": false
151+
},
152+
{
153+
"value": 10,
154+
"text": "GatewayPathUnavailable",
155+
"selected": false
156+
},
157+
{
158+
"value": 11,
159+
"text": "GatewayNoResponse",
160+
"selected": false
161+
}
162+
],
163+
"function_response_clear_after": 1,
164+
"call_rows": [],
165+
"foot": "not active",
166+
"result": "ok"
167+
}

‎doc/source/library/simulator/registers_request.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. code-block:: json
2+
3+
{
4+
"range_start": 16,
5+
"range_end": 16,
6+
"submit": "Register"
7+
}

‎doc/source/library/simulator/registers_response.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. code-block:: json
2+
3+
{
4+
"result": "ok",
5+
"footer": "Operation completed successfully",
6+
"register_types": {
7+
"bits": 1,
8+
"uint16": 2,
9+
"uint32": 3,
10+
"float32": 4,
11+
"string": 5,
12+
"next": 6,
13+
"invalid": 0
14+
},
15+
"register_actions": {
16+
"null": 0,
17+
"increment": 1,
18+
"random": 2,
19+
"reset": 3,
20+
"timestamp": 4,
21+
"uptime": 5
22+
},
23+
"register_rows": [
24+
{
25+
"index": "16",
26+
"type": "uint16",
27+
"access": "True",
28+
"action": "none",
29+
"value": "3124",
30+
"count_read": "0",
31+
"count_write": "0"
32+
}
33+
]
34+
}

‎doc/source/library/simulator/restapi.rst

Lines changed: 117 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,120 @@
11
Pymodbus simulator ReST API
22
===========================
33

4-
TO BE DOCUMENTED.
4+
This is still a Work In Progress. There may be large changes to the API in the
5+
future.
6+
7+
There is a skeleton API for the Pymodbus simulator. The API is a simple copy of
8+
having most of the same features as in the Web UI.
9+
10+
The API provides the following endpoints:
11+
12+
- /api/registers_json
13+
- /api/calls_json
14+
- /api/server_json
15+
- /api/log_json
16+
17+
Registers Endpoint
18+
------------------
19+
20+
/api/registers_request
21+
^^^^^^^^^^^^^^^^^^^^^^
22+
23+
The registers endpoint is used to read and write registers.
24+
25+
**Request Parameters**
26+
27+
- `submit` (string, required):
28+
The action to perform. Must be one of `Register`, `Set`.
29+
- `range_start` (integer, optional):
30+
The starting register to read from. Defaults to 0.
31+
- `range_end` (integer, optional):
32+
The ending register to read from. Defaults to `range_start`.
33+
34+
**Response Parameters**
35+
36+
Returns a json object with the following keys:
37+
38+
- `result` (string):
39+
The result of the action. Either `ok` or `error`.
40+
- `error` (string, conditional):
41+
The error message if the result is `error`.
42+
- `register_rows` (list):
43+
A list of objects containing the data of the registers.
44+
- `footer` (string):
45+
A cleartext status of the action. HTML leftover.
46+
- `register_types` (list):
47+
A static list of register types. HTML leftover.
48+
- `register_actions` (list):
49+
A static list of register actions. HTML leftover.
50+
51+
**Example Request and Response**
52+
53+
Request Example:
54+
55+
.. include:: registers_request.rst
56+
57+
Response Example:
58+
59+
.. include:: registers_response.rst
60+
61+
Calls Endpoint
62+
--------------
63+
64+
The calls endpoint is used to handle ModBus response manipulation.
65+
66+
/api/calls_request
67+
^^^^^^^^^^^^^^^^^^
68+
69+
The calls endpoint is used to simulate different conditions for ModBus
70+
responses.
71+
72+
**Request Parameters**
73+
74+
- `submit` (string, required):
75+
The action to perform. Must be one of `Simulate`, `Reset`.
76+
77+
The following must be present if `submit` is `Simulate`:
78+
79+
- `response_clear_after` (integer, required):
80+
The number of packet to clear simulation after.
81+
- `response_cr` (string, required):
82+
Must be present but can be any value. Turns on change rate simulation (WIP).
83+
- `response_cr_pct` (integer, required):
84+
The percentage of change rate, how many percent of packets should be
85+
changed.
86+
- `response_split` (string, required):
87+
Must be present but can be any value. Turns on split response simulation (WIP).
88+
- `split_delay` (integer, required):
89+
The delay in seconds to wait before sending the second part of the split response.
90+
- `response_delay` (integer, required):
91+
The delay in seconds to wait before sending the response.
92+
- `response_error` (integer, required):
93+
The error code to send in the response. The valid values can be one from
94+
the response `function_error` list.
95+
96+
When `submit` is `Reset`, no other parameters are required. It resets all
97+
simulation options to their defaults (off).
98+
99+
**Example Request and Response**
100+
101+
Request:
102+
103+
.. include:: calls_request.rst
104+
105+
Response:
106+
107+
Unfortunately, the endpoint response contains extra clutter due to
108+
not being finalized.
109+
110+
.. include:: calls_response.rst
111+
112+
Server Endpoint
113+
---------------
114+
115+
The server endpoint has not yet been implemented.
116+
117+
Log Endpoint
118+
------------
119+
120+
The log endpoint has not yet been implemented.

0 commit comments

Comments
 (0)