WebSocket

#  What are WebSocket nodes used for in Node-RED

Node-RED provides two WebSocket nodes that serve distinct purposes and can operate in two modes.

#  Listen On

In this mode, Node-RED functions as a WebSocket server, enabling remote clients to establish connections.

  • The WebSocket-in node is responsible for receiving messages sent from remote clients.
  • The WebSocket-out node facilitates the flow to send messages either to a specific connected client or to broadcast messages to all connected clients.

#  Connect To

In this mode, Node-RED acts as a client, establishing connections with remote WebSocket servers.

  • The WebSocket-in node receives messages sent from the remote WebSocket server to Node-RED.
  • The WebSocket-out node allows the flow to send messages to the remote server.

#  WebSocket node configuration

#  Path

When you use the WebSocket node in "Listen on" mode, you'll have to specify the path or endpoint to which remote clients will establish a connection.

#  Send/Receive

  • Payload: This option sends or receives only the msg.payload as data over the WebSocket connection. It excludes any additional msg properties.
  • Entire Message: When enabled, this option allows the entire message object, including payload, and other properties to be sent or received as a JSON formatted string.

#  URL

When you use the WebSocket node in "Connect to" mode, you'll have to specify the connection URL that should use ws:// or wss:// scheme and point to an existing WebSocket listener.

#  Subprotocol

This option allows you to specify a particular WebSocket subprotocol to use during the connection handshake.

For example, if a WebSocket server requires the use of the "mqtt" subprotocol, you would configure the WebSocket node's "Subprotocol" option to "mqtt" to ensure that the WebSocket handshake includes the MQTT protocol, enabling proper communication between Node-RED and the WebSocket server.

#  Send heartbeat

Enabling this option allows specifying the time interval in seconds for sending periodic ping messages from the client to the server to maintain the connection. The server responds with a pong message to confirm the connection status.

This helps prevent the connection from being closed due to inactivity or network issues.

#  Examples

Simple Echo test

This shows both modes, with one set acting as a WebSocket Echo Server and the other connecting to that server and sending and receiving messages.

Node Documentation

WebSocket input node.

By default, the data received from the WebSocket will be in msg.payload. The socket can be configured to expect a properly formed JSON string, in which case it will parse the JSON and send on the resulting object as the entire message.

WebSocket out node.

By default, msg.payload will be sent over the WebSocket. The socket can be configured to encode the entire msg object as a JSON string and send that over the WebSocket.

If the message arriving at this node started at a WebSocket In node, the message will be sent back to the client that triggered the flow. Otherwise, the message will be broadcast to all connected clients.

If you want to broadcast a message that started at a WebSocket In node, you should delete the msg._session property within the flow.

This configuration node creates a WebSocket Server endpoint using the specified path.

This configuration node connects a WebSocket client to the specified URL.