[dev] Fix premature shutdown in simulator example and update README instructions

[FedericoMusa]

Versions
Python: 3.13

OS: Windows 10 (MINGW64)

Pymodbus: 4.0.0.dev8 (branch dev)

Modbus Hardware: None (Simulator)

Pymodbus Specific
Server: tcp - async (Simulator)

Client: tcp - async (Simulator)

Description
I am reporting an inconsistency in the current dev branch regarding the simulator's usability as a standalone tool.

Premature Shutdown in Example: The examples/simulator.py script is currently structured as a one-shot test. As seen in the attached code snippet, it calls await task.stop() immediately after the test calls, which triggers a graceful shutdown of both the Modbus and HTTP servers.

Web UI Inaccessibility: Because of this immediate shutdown, the Web UI (listening on port 8081) becomes unreachable for manual interaction.

Documentation Gap: The README.rst still points to the deprecated v3_simulator.py script, which no longer exists in the examples/ directory.

Expected behavior: The simulator example should remain persistent to allow users to interact with the Web interface. I have verified that replacing task.stop() with a persistent wait allows the Web UI to function correctly.

Code and Logs
Execution Log (Premature Shutdown):

Plaintext
2026-02-09 17:20:29,987 INFO base:89 Server listening.
2026-02-09 17:20:30,180 INFO http_server:226 Stopping modbus server
2026-02-09 17:20:30,181 INFO base:93 Server graceful shutdown.
2026-02-09 17:20:30,181 INFO http_server:232 Modbus server Stopped

Code causing the issue (examples/simulator.py):

[janiversen]

Thanks for the report.

I have now reread the README.rst and cannot find a link to any simulator script, can you please point out where the link is so we can fix it.

Examples are just that, they are meant to be adapted to your needs ! simulator.py shows how to start the simulator, connect a client, and stop it...full circle.

The installation adds pymodbus.simulator as a script, which you can run with your own configuration.

[FedericoMusa]

Hi Jan!

Thanks for the clarification on the project's philosophy. After re-examining the code, I completely agree: examples/simulator.py is a perfect "full-circle" integration demo and should remain that way.

The confusion stemmed from the fact that the persistent entry point (pymodbus.simulator) was not mentioned in the documentation, leading new users to rely on the example script for exploring the Web UI.

Changes in this PR:

README.rst: Added a new section "Ready to go simulator" that documents the official pymodbus.simulator command. This provides a clear, persistent path for users to interact with the Web UI.

examples/simulator.py: Reverted to its original state. I've ensured the file is identical to the dev branch to keep the PR clean and focused solely on documentation.

I’ve also renamed the branch and cleaned up the commit history to reflect this "docs-first" approach. Ready for your review!