Leveraging Captivate to Connect to UDP Servers

Finally, many sources of data are published by TCP/UDP servers, but our data controllers usually run in the context of a web browser which can't do direct network communication. Therefore, Captivate provides an easy way to send and receive messages with TCP/UDP servers.

From a browser context, you will create a WebSocket connection to the Captivate WebSocket server using a special url.

Captivate will then make the network connection for you and proxy all messages back and forth using the following formats:

• By default, packets from the network server will be passed through exactly as they come in, packaged as a WebSocket binary message (event.data will be a Blob object).

• By passing the terminator query parameter, the packets will be accumulated, split at the terminator, and delivered as individual binary messages.

  • Be sure to percent-encode your terminator string (i.e. \r\n will be terminator=%0d%0a).

• By passing the encoding query parameter, the packets will be decoded according to the specified encoding, converted to utf-8 and sent as a WebSocket text message. Not all encodings are supported, but these common Javascript encodings are:

  • utf-8, utf-16, utf-16le, utf-16be, latin1

Connecting to a TCP server

Connect a websocket to /tcp/:address/:port.

Example using Javascript.

// assuming Captivate's WebSocket server is running on 10.0.0.1, port 9023,
// and assuming your TCP server is running on 10.0.0.2, port 1234,
// connect to it this way

// get all messages as ArrayBuffer data
let ws = new WebSocket('ws://10.0.0.1:9023/tcp/10.0.0.2/1234');
ws.onmessage = async (m) => {
  const bytes = await m.data.arrayBuffer();
  console.log(bytes);
};

// process tcp data as latin1 encoded text and split on every \r\n
let ws2 = new WebSocket('ws://10.0.0.1:9023/tcp/10.0.0.2/1234?encoding=latin1&terminator=%0d%0a');
ws2.onmessage = (m) => console.log(m.data);

Connecting to a UDP server

Connect a websocket to /udp/:address/:port.

If you use a multicast address, the connection will automatically attempt to join the multicast group.

Example using Javascript.

// all of these assume the server will send text encoded as utf-8

// send UDP packets to 10.0.0.2 port 1234
let ws = new WebSocket('ws://10.0.0.1:9023/udp/10.0.0.2/1234?encoding=utf-8');
ws.onmessage = (m) => console.log(m.data);

// join multicast group 239.0.0.1 and send/receive UDP data on port 1234
let ws_mc = new WebSocket('ws://10.0.0.1:9023/udp/239.0.0.1/1234?encoding=utf-8');
ws_mc.onmessage = (m) => console.log(m.data);

// listen to any data from any source over port 1234, use `listen` as the address
// e.g. if the server is broadcasting (255.255.255.255 or x.x.x.255)
let ws_bc = new WebSocket('ws://10.0.0.1:9023/udp/listen/1234?encoding=utf-8');
ws_bc.onmessage = (m) => console.log(m.data);