Protocol Emulator

The protocol emulator is used to directly establish Modbus or Siemens S7 slaves within GatewayRuntime, providing readable and writable simulation data to PLCs, host computers, configuration software, acquisition programs, and protocol testing tools. It is suitable for protocol joint debugging, point table verification, abnormal scene reproduction, training demonstrations, and automated testing, without the need to install additional standalone simulation software.

Pages use a unified three-level configuration model:

Hierarchical	Function
Simulation Channel	Manage listening endpoints, serial ports, startup status, safety limits, diagnostic capacity, and fault injection.
Built-in protocol plugin	Select Modbus Slave or S7Slave from the dropdown to determine the protocol packet and address space.
Simulation variables	Define protocol address, data type, initial value, access permissions, and automatic change patterns.

Difference from Collection Configuration

Protocol emulators use GatewayRuntime as a protocol server or slave. Collection Configuration usually uses GatewayRuntime as a client or master station to read field devices. Protocol simulation channels, protocol plugins, and simulation variables are managed only on this page.

Function Entry

Log in to GatewayRuntime Web and enter the "Developer Configuration → Protocol Emulator".

Screenshot Description

The screenshots on this page are from the actual running page of the current GatewayRuntime, used to display the workbench layout, default parameters, and configuration entry. The sample channel in the screenshot is stopped and no variables are configured; actual running data is based on the user's own channel and client.

On the left side of the page is a list of simulation channels, at the top are the commands for refresh, import, edit, and run, and the workspace on the right contains the following content.

Region	Description
Run Summary	Displays listening endpoints, current client, number of requests, request rate, protocol errors, Reserved memory and the number of running generators.
Variables	Paginate variables, current values, change modes, and access modes, and perform add, batch add, write, pause, continue, save current value, and delete.
Raw memory	Read hexadecimal and ASCII data by protocol memory area; When permission is granted, it can preview and write to the original bytes.
Client	View connection endpoints, session phases, S7 negotiation PDUs, number of requests, error counts, and incoming traffic.
Messages and Events	Query lifecycle, connections, requests, protocol errors, variable changes, and security denial events by page.
Configuration	View protocols, security, diagnostics, and a complete configuration summary for the current channel.

When the browser width does not exceed 1024px, the channel list will automatically be included in the channel button to the left of the current channel name. Clicking this button allows you to switch or create a new channel in the drawer; The workspace occupies the remaining width, and filters, pagination, and forms are rearranged into two or single columns.

Preparations Before Configuration

Before configuration, determine the test client's protocol, network location, and target point table.

Information	Content to be confirmed
Protocol Role	The tester must be connected as a Modbus master or S7 client GatewayRuntime.
Protocol plugin	Modbus client: Select Modbus Slave; For the S7 client, select S7Slave.
Channel Type	Network Listening uses TcpService; Modbus RTU serial port testing uses SerialPort.
Listen to endpoints	Confirm available network card addresses, ports, firewalls, and port occupancy.
Address Space	Confirm the Modbus station number and ribbon, or the I/Q/M/DB area and DB number of S7.
Write Scope	Clarify which variables are allowed to be written by the client and which can only be modified by the page or generator.
Data patterns	Determine fixed values, waveforms, random quantities, sequences, pulse or string templates, and update cycles.
Event Scale	Before long-term stress testing, determine event capacity, record successful requests, and capture the original packet.

Creating a New Simulation Channel

1. On the left side, click "Protocol Emulator" under the title "Add" to the right.
2. Enter the channel name in "Channel Configuration."
3. In the "Protocol Plugin" dropdown, select Modbus Slave or S7Slave.
4. Go to "Transmission Configuration," select the channel type, and fill in the monitoring or serial port parameters.
5. Complete the Modbus or S7 Slave parameters according to the selected protocol.
6. Check "Permissions & Security," "Diagnostics," and "Fault Injection."
7. Click "Save". After saving, configure the variables first, then start the channel.

Channel configuration

Configuration items	Description
Channel Name	The unique name of the current simulation channel, recommended to include the protocol and purpose, such as modbus-line-demo.
Protocol Plugin	dropdown to select Modbus Slave or S7Slave. If you need to switch to another protocol after creation, you should create a new channel and re-verify the variable address.
Auto-start	After starting, the simulation channel will automatically start when GatewayRuntime starts. Before officially activating, confirm that the listening port and variable configurations are correct.
Description	Record the test subject, person in charge, port purpose, or joint debugging scope.

Transmission Configuration

The channel type belongs to "Transmission Configuration". Network services and serial ports are channel capabilities, not protocol plugins.

Channel Type	Supported Protocol	Key Parameters	Description
TcpService	Modbus, S7Slave	listen addresses, ports, listening queues, TCP NoDelay Handshake timeout	GatewayRuntime listens to the port and waits for the client to connect actively.
SerialPort	Modbus	serial port, baud rate, data bits, parity bits, stop bits, flow control, receive timeout, frame intervals,	used for Modbus RTU serial slave station simulation. The S7Slave does not use serial ports.

TcpService Common Settings:

Configuration Items	Description
Listening address	127.0.0.1 Only local connections are allowed; LAN joint debugging and filling in the designated network card address; To monitor all network cards, you can enter 0.0.0.0.
Ports	Modbus TCP commonly uses 502, S7 commonly uses 102; Non-administrator test environments can use unoccupied high-level ports.
Listen queue	Control the number of connections waiting to be received. Generally, the default value is maintained, and during concentrated stress testing, adjustments are made according to the planned number of clients.
TCP NoDelay	reduces the wait time for small packets, and protocol debugging usually remains enabled.
Handshake Timeout	The maximum waiting time for the protocol handshake to complete after client connection. When network latency is high, it can be appropriately increased.

port and network exposure

Listening 0.0.0.0 will open the port to all accessible network cards. The production network should be configured simultaneously with "allowed subnets," operating system firewalls, and border access policies; do not rely solely on ports without making them public.

Configure Modbus Slave

After selecting Modbus Slave, the channel supports the following combinations.

Simulation Method	Channel Type	Message Format
Modbus TCP	TcpService	Modbus TCP
RTU over TCP	TcpService	Modbus RTU
Modbus RTU Serial	SerialPort	Modbus RTU

Modbus Parameter

Configuration Items	Description
Station Number	One or more slave station numbers can be configured, ranging from 1 to 247 and cannot be duplicated within the same channel.
Number of coils	Allocate the Coil address space for read/write booleans.
Discrete Input Quantity	Allocate Discrete Input address space for read-only Booleans.
Number of input registers	Allocate Input Register address space for read-only register data.
Maintain the number of registers	Allocate the Holding Register address space for read/write register data.
Default byte order	Set the default byte/word order for multi-register values; Individual variables can still be configured individually.
Strict address mode	Refuses access beyond allocated space or without valid mappings after enabled.

Variable addresses can be structured in format, for example:

address example	meaning
S=1;F=1;0	Station number 1, functional area 1, coil offset 0.
S=1;F=2;0	Station number 1, ribbon 2, discrete input offset 0.
S=1;F=3;0	Station number 1, Function Area 3, Offset 0 holding register.
S=1;F=4;0	Station number 1, ribbon 4, input register offset 0.
S=1;F=3;10.3	Keep the register offset to bit 3 in 10.

Configure S7Slave

After selecting S7Slave, GatewayRuntime runs as the real S7 slave/server, establishes connections via ISO-on-TCP, and handles COTP and Setup Communication, Read Var, and Write Var. It does not convert the S7 address into a Modbus address.

Configuration Items	Description
Frame Number / Slot Number	Used to determine the local S7 connection identifier, it should match the client connection parameters.
Local TSAP	local TSAP used by GatewayRuntime, such as 0x0101.
Allowed remote TSAPs	Client TSAPs that can be restricted to which sessions can be established; If left vacant, assess according to the on-site safety strategy.
Maximum PDU Length	the maximum PDU length negotiated by the S7 session; client settings cannot exceed server capacity.
Input area bytes	Allocate volume to Area I.
Output bytes in the output area	Allocate Q area capacity.
Flag area bytes	Allocate volume to the M section.
Data Block	Configure one or more DB numbers and the number of bytes per DB.
Strict address mode	When enabled, rejects access beyond the I/Q/M/DB allocation range.

The S7Slave variable can be mapped to the following address areas:

Address Example	Meaning
IX0.0	Input Region Byte 0 Bit, Bit 0.
QW10	Words with output area offset by 10.
MD20	double word with the logo area offset by 20.
DB1.DBX0.0	DB1 byte 0, bit 0.
DB1.DBW2	DB1 offsets the word by 2.
DB1.DBD4	DB1 offset by 4 double words.

Permissions and Security

"Permissions and Security" control protocol: whether clients can access and write to the protocol; System role permission control allows logged-in users to execute management commands on the web. Both should be configured together.

Channel Security Parameters

Configuration Items	Description
Allowed Segments	Allowed IPv4/IPv6 CIDR Connections. The default loop segment is suitable for local testing; When debugging a local area network, only the segments actually needed are added.
Allows external protocols to write to	master switches. When closing, the client's protocol write request will not modify the specification; After enabling it, also check variable access modes and external write policies.
Maximum number of clients	The total number of clients allowed to connect simultaneously in the current channel.
Number of clients per IP	The maximum number of connections allowed by the same source IP.
Idle Timeout	The number of seconds a client disconnects after a long period of inactivity.
Limit the continuous request rate per	per second for a single client request.
Burst Capacity	The number of requests allowed for short-term bursts.
Invalid Frame Disconnection Threshold	Proactively disconnects when the same connection generates too many invalid messages consecutively.

Web Role Permissions

Go to "System Management → Role Management" to assign page and button permissions to roles that need to use the protocol emulator. It is recommended to delegate according to the minimum responsibilities.

Permission groups	Executable operations
View and refresh	View channels, variables, runtime, memory, client, and pagination events.
Channel Management	Add, edit, and delete simulation channels.
Variable Management	Add, edit, batch add, and delete variables.
Operation control	start, stop, and restart channels.
Data Writing	Page Writes and Original Memory Writes.
Generator Control	Pause or continue the generator of the selected variable.
Save the current value	Save the current runtime value as the initial value for the next startup.
Client Management	Disconnect a specific client or disconnect all clients.
Incident Management	Clear diagnostic events in the current lane.
Import and Export	Import/export JSON channel configuration and Excel variable point table.

Read-only joint debugging account

Users who only need to observe the running results can be granted viewing and refresh permissions only. Pages hide or disable unauthorized commands to add, write, run, disconnect, and empty.

Configure simulation variables

After saving the channel, click "Add variable" or "Batch create variables" on the "Variables" page. The structural configuration can only be modified when the channel stops, preventing changes in the address space during client-side communication.

1. Enter the unique variable name.
2. Use the Address Assistant to select the protocol area, station number or DB number, offset, and bit number, or directly fill in the standard address.
3. Select the data type and array length.
4. Select byte order for multi-byte data in Modbus; Fill in the memory format for the string.
5. Set access mode, external write policy, and initial value.
6. When automatic changes are needed, enter the "Data Change Designer" to activate the generator.
7. Check for usage range, out-of-bounds, and address conflict prompts, then save them.

Data Type

Data Type	Description
Boolean	Boolean values, which can be mapped to bit addresses, coils, or discrete inputs.
Byte	8-bit unsigned integer.
Int16 / UInt16	16-bit signed/unsigned integers.
Int32 / UInt32	32-bit signed/unsigned integers.
Int64 / UInt64	64-bit signed/unsigned integers, pages processed as exact decimal values.
Float / Double	Single-precision / double-precision floating-point count.
Decimal	High-precision decimal numbers, suitable for test values requiring precise decimal representation.
String	Fixed or length-headed strings, also supports S7 WSTRING.

When the "array length" exceeds 1, the variable occupies a contiguous address as a fixed-length array. Before increasing the array length, check whether subsequent addresses have been occupied by other variables.

Byte Order and Strings

Configuration Items	Description
Byte order	Modbus multibyte variables can be selected ABCD,BADC,CDAB, DCBA. S7 Processing byte order according to protocol.
Number of bytes per element	Reserve fixed space for each element of the string's array.
Encoding	You can choose or fill in UTF-8,ASCII, UTF-16BE, and other codes.
Length header	Actual length information is stored in string memory; client-side parsing must be consistent.
S7 WSTRING	used only by S7Slave, distributed and encoded according to the S7 wide string format.

Access Modes and External Write Policies

Configuration Items	Behaviors
Read-only	Neither client nor page can use this variable as a regular writable point.
Read and write	Pages are writable; When the channel allows external protocols to write, the client can also write according to the external write policy.
Pages are writable and external rejection	Web pages can write values, but Modbus/S7 client writes will be rejected.
Accept and continue changing	Accept client-side writes, while the generator continues updating according to the original timeline.
Accepts and pauses the generator	Accepts client writes and pauses the variable generator to facilitate client-sent values.
Rejects external writes	Even if the channel allows external writes, the variable still rejects client-side write requests.

Three-layer write check

Successful protocol write requires simultaneously satisfying the following permissions for role or page operations, the channel "Allow external protocol writes," and variable access modes/external write policies. Test points involving control logic should prioritize read-only or external denial modes.

Configure Data Changes and Seeds

Each variable can independently enable the generator. Common parameters include update cycle, startup latency, recovery strategy, algorithm version, and seed.

Change Mode	Applicable Scenarios
Fixed	Maintain a fixed value.
Ramp	Increases or decreases step size, with selectable clamping, looping, round-trip, or out-of-bounds error modes.
Sine	generates sine waves based on center value, amplitude, period, and phase.
Triangle	generates a triangle wave.
Sawtooth	generates sawtooth waves.
Square	Generate square waves based on high/low values, period, and duty cycle.
Random	Generate random values within a range according to a uniform or Gaussian distribution.
RandomWalk	Randomly walks from the initial value according to the maximum step size.
Toggle	flips periodically between Boolean true and false.
Pulse	Pulses are generated by period, high level duration, and initial level.
Sequence	Playback by step value and holding chronological order, can loop, repeat, or keep the last value.
Template	Generate strings such as batch numbers or time labels using counters and simulated time.

Deterministic Seeds

Random, RandomWalk, noise modifiers, and fault injection can all use configured seeds. The same algorithm version, seed, and configuration produce repeatable sequences suitable for automated regression testing and issue reproduction.

Operation	Recommends
Fixing the seed	Record in the test case, Ensure that each run has the same trajectory.
Generate seeds	Temporarily explore different random sequences; After confirming the issue, the generated value should be recorded.
Separating seeds	Main generator, noise, and fault injection use different seeds for easy individual reproduction.
Modifying the algorithm version	will alter the sequence results and should be fixed together with the seed in regression testing.

The numeric generator can also overlay zoom, offset, noise, mini/max clamping, quantization step size, and decimal places. First configure the basic waveform, then add modifiers item by item and preview to more quickly identify parameter issues.

Startup and Operation Control

1. Confirm that the channel is "Stopped" and complete the configuration of the channel and variable structure.
2. Click "Start" at the top. After successful startup, the summary area displays the listening endpoint and reserved memory.
3. Connect to this endpoint using the actual Modbus master or S7 client and read and write variables.
4. Observe the current value and generator status in the variable list; After selecting a variable, you can pause, continue, or save the current value as the initial value.
5. Stop the channel before modifying the structural configuration; You can use "Restart" only when re-establishing listens and sessions.

Command	Instructions
Start	allocate protocol memory and start listening or open the serial port.
Stop	Disable listening and client connections, allowing modification of channel and variable structures.
Restart	After stopping, restart as configured as currently is.
Write Value	Set the current value for a single writable variable and choose whether to apply an external write strategy.
Pause/Continue	Batch control of the generator of the selected variable.
Save the current value as the initial value	Persist the current value for the next startup recovery. For bulk storage, it is recommended to select by business grouping.

Original Memory and Client

Original Memory

"Original Memory" is used to check whether variable values match protocol bytes.

Protocols	Optional memory
Modbus	Coils, Discrete Inputs, Holding Registers, Input Registers, and select the station number.
S7Slave	Inputs, Outputs, Markers, Data Block; The Data Block also requires selecting the DB number.

After entering the byte offset and the number of bytes to be read, click "Read Memory". Before writing to hexadecimal, the page checks the coverage area; When intersecting with variable mapping, it will require reconfirmation. Original memory writes directly affect the corresponding variable and should only be used when the address layout is clearly understood.

Client

The "Client" page displays the remote endpoint of each connection, connection time, recent activity, number of requests/errors, and bytes sent and received. S7Slave also displays the session phase and negotiation PDU. If you need to terminate an abnormal connection, you can disconnect a single client or all clients.

Messages and Events

Determine the scope of records in the channel "diagnostics."

Configuration items	Description
Capture raw messages	Save hexadecimal content of requests and responses. It only activates during joint debugging and error troubleshooting to avoid recording unnecessary data.
Event Capacity	The maximum number of events held in the current channel. After reaching capacity, the oldest event is covered and will not grow indefinitely.
Maximum one-way capture byte	Limits the number of raw bytes stored in a single request or response.
Record variable changes	Record changes caused by generator writes, page writes, and protocol writes. It can be turned off when there are many high-frequency points.
Record successful requests	Record normal protocol requests. It can be turned off during prolonged high-frequency stress testing, retaining only errors and key events.

The "Messages and Events" page supports keyword and event type filtering, as well as server-side pagination.

Event Content	Description
Time and Type	Distinguishes lifecycle, client connection/disconnection, protocol requests, protocol errors, variable changes, generator status, security denial, and buffer coverage.
Messages and Clients	Displays event summaries and associated clients.
Variables and Error Codes	Displays associated variables and protocol error codes.
Processing Time	Displays request processing time to help locate abnormal and slow requests.
Request/Response Message	View the captured hexadecimal request and response after clicking the event.

The event list loads only the current page at a time. Switching page numbers, page sizes, or filter criteria will re-query the server; Automatic refresh cancels expired requests and does not cause concurrent stacking and repeated refreshes. The page will also show the number of old events that have been overwritten by the circular buffer.

Fault Injection

Fault injection is used for repeatable verification of client timeouts, reconnections, and exception handling, and should not be enabled long-term in production debugging channels.

Configuration Item	Description
Enable fault injection	master switch. After turning off, do not apply delay, jitter, lost response, or active disconnect.
Fault seed	Fixed random fault sequence to facilitate reproduction of the same test process.
Fixed Latency	Adds fixed processing delay per request.
Random jitter	adds random wait on top of fixed latency.
Lost response probability	No response is sent by probability, used to verify client timeout and retry.
Disconnect after processing the number of requests	After reaching the specified number of requests, actively disconnect the client to verify automatic reconnection.

Import and Export

At the top, "Import JSON" allows you to import the full channel configuration; The "More" menu provides channels for exporting JSON, importing Excel, exporting Excel, and deleting channels.

Format	Purpose	Notes
JSON	Backup or copy of channels, protocols, security, diagnostics, faults, and variable configurations.	Before importing, you can choose to create a new channel or override a stopped channel from the same protocol, and preview first.
Excel	batch maintenance variable point tables.	Only handle variables; The channel must be stopped before the structural configuration is imported. Exporting the template first and then filling in can reduce formatting errors.

If other users have already modified the same channel during import, the page will prompt a configuration version conflict. Refresh and verify the latest configuration before re-importing; do not overwrite unknown changes directly.

Large-scale Simulation and Performance Recommendations

Scenarios	Recommendations
Many variables	Use batch creation of variables or import them in Excel; Filter by name, address, type, and access mode, manage by page, without relying on displaying all variables at once.
High-frequency automatic change	Enable generators only for variables that require dynamic behavior, set update cycles reasonably, and avoid millisecond-level changes at all points.
Long-term protocol stress testing	Set fixed event capacity; During the non-troubleshooting phase, the original packet, successful request, or high-frequency variable change record is closed.
Event queries	Use event types and keywords to narrow the scope and maintain pagination; The page only keeps the current page and does not accumulate all historical events in the browser.
Auto Refresh	Select a refresh cycle that matches the test rate. If the previous round is not yet completed, it will not be triggered concurrently to refresh again.
Multi-client	Set the total number, single IP limit, and request rate according to the planned number of connections, gradually increasing the load and observing request rates, errors, and memory summaries.

Frequently Asked Questions

Phenomena	Handling Suggestions
Client Cannot Connect	Check if the channel is started, listen for addresses and ports, operating system firewall, allowed subnets, maximum number of clients, and port usage.
Modbus request returns an incorrect address	Checkstation number, message format, ribbon, offset, allocated quantity, and strict address mode.
S7 client handshake failure	check ports, rack/slot numbers, local and remote TSAP, maximum PDU, allowed segments, and handshake timeouts.
S7 Address Read Failure	Check I/Q/M/DB address formats, whether the DB exists, DB capacity, and strict address mode.
Client write value is rejected	Check the channel in sequence for "Allow external protocol writes," variable access mode, external write policy, and request address/data type.
The value changes again after writing	The external writing strategy is "accept and continue changing." When you need to keep the write value, switch to "Accept and pause the generator."
Random results cannot be reproduced	Fixed algorithm version, generator seed, noise seed, fault seed, and initial value at startup.
Too many page events	Reduce event capacity, close successful requests or variable change records, and use type/keyword filtering and pagination.
Unable to edit channels or variables	Stop the channel first, then check whether the current role has the corresponding management permissions.

Related Links

• Collection Configuration
• Device Debugging
• User Management
• Role Management
• System Logs