WebSocket Client
A mode in which the gateway makes an outbound connection as a client to the endpoint of an external streaming server (ws / wss) and receives pushed messages in real time.
| Situation | Which mode to use |
|---|---|
| An external IT system sends values via REST POST | HTTP Push |
| An external streaming server streams values over WebSocket | WebSocket Client (this page) |
| Reading values directly from in-house PLCs | Modbus / OPC-UA, etc. |
Registration Form Fields
| Field | What to enter | Example |
|---|---|---|
| IP address | WebSocket server host | 192.168.10.99, stream.example.com |
| Port | WebSocket server port (ws=80, wss=443 by convention) | 8765, 443 |
| PATH | Endpoint path (default /) | /stream/v1 |
| TLS | Whether to use wss | false (ws) / true (wss) |
| SUBSCRIBE MESSAGE | Message sent once immediately after connection (optional) | {"op":"subscribe","topic":"line1.tempC"} |
| Collection period | Period at which the gateway reads the cached value (ms) | 1000 |
Actual connection URL: <scheme>://<host>:<port><PATH> (e.g. ws://192.168.10.99:8765/stream/v1)
Tag PLC Address Notation — 4-mode JSON
When the messages sent by the server are JSON, values are extracted with the same 4-mode decoder used for MQTT / Apache Kafka.
Assume the server pushes the following:
{"tempC": 25.7, "humid": 40.2, "running": true, "meta":{"unit":"degC"}}
| Mode | Tag PLC address | Value received |
|---|---|---|
| KEY (top-level) | tempC | 25.7 |
| KEY | humid | 40.2 |
| KEY | running | true |
| PATH (JSON Pointer) | :$.meta.unit | degC |
| RAW | _raw_ or :_raw_ (or blank) | Entire message |
| SCALAR | (when the message is not JSON) _raw_ | Message as-is |
WebSocket is a single channel, so there is no topic part — leave the portion before : empty, or just use the key by itself.
If the payload is not JSON, or you want to receive the entire message as-is, use _raw_ or leave the field blank.
Common Use Cases
| Case | How |
|---|---|
| Cloud streaming broker (real-time quotes, exchange rates, weather, etc.) | Register the JSON keys pushed by the server directly as tags |
| ROS 2 / rosbridge_server | Connect to the rosbridge WebSocket → receive topic messages |
| In-house streaming gateway | Usually plaintext ws 8080 / 8765 — tls=false |
| External secured SaaS (certificate required) | wss 443 — tls=true |
| Server requires a subscribe handshake | Enter the agreed payload in SUBSCRIBE MESSAGE |
Common Problems and Solutions
| Symptom | Cause | Solution |
|---|---|---|
| No values arriving | Server is not pushing messages | Receive directly with wscat -c ws://<host>:<port><path> and check whether lines appear in the console |
| No values arriving | Subscribe message not configured (though the server requires it) | Check the server manual and register SUBSCRIBE MESSAGE |
[WS] connect 실패: timeout | Firewall / port / DNS | Check whether the port is blocked and whether a TCP connection is possible with telnet / nc |
[WS] connect 실패: handshake | Incorrect path / TLS setting | Verify the URL <scheme>://<host>:<port><path> directly |
| TLS certificate error | Self-signed certificate | Use a properly issued certificate in production. As a temporary measure, ask your system administrator to add it to cacerts |
| Per-key JSON values are empty | Message format is not JSON | Receive with _raw_ first and check the format |