# 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.

```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.

```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);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.newbluefx.com/captivate-api/advanced-api-reference/leveraging-captivate-to-connect-to-udp-servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.