> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/api-reference/io-api/tcp.md).

# TCP

### Accessing TCP Objects

TCP Client and TCP Server Objects are accessed through their Scripting IDs.

For example:

```python
sp.TCPClient1
```

and:

```python
sp.TCPServer1
```

The Object's configured network settings are used when sending data from scripting.

### Available Send Functions

Both TCP Client and TCP Server Objects provide:

```
send()
sendBytes()
sendHex()
sent_ascii_message()
sent_hex_message()
```

{% hint style="info" %}
The function names `sent_ascii_message()` and `sent_hex_message()` are intentionally shown exactly as exposed by the current scripting API.
{% endhint %}

### `sent_ascii_message()`

Sends a String through the TCP Object.

#### Syntax

```python
tcp.sent_ascii_message(message)
```

#### Parameters

| Parameter | Type  | Description     |
| --------- | ----- | --------------- |
| `message` | `str` | Message to send |

#### Returns

`None`

#### TCP Client Example

```python
sp.TCPClient1.sent_ascii_message(
    "Hello"
)
```

#### TCP Server Example

```python
sp.TCPServer1.sent_ascii_message(
    "Hello"
)
```

### `sent_hex_message()`

Sends a hexadecimal String through the TCP Object.

#### Syntax

```python
tcp.sent_hex_message(message)
```

#### Parameters

| Parameter | Type  | Description         |
| --------- | ----- | ------------------- |
| `message` | `str` | Hexadecimal message |

#### Returns

`None`

Both spaced and compact hexadecimal Strings have been verified.

#### Spaced Hexadecimal String

```python
sp.TCPClient1.sent_hex_message(
    "48 65 6C 6C 6F"
)
```

#### Compact Hexadecimal String

```python
sp.TCPClient1.sent_hex_message(
    "48656C6C6F"
)
```

The same function is available on TCP Server Objects:

```python
sp.TCPServer1.sent_hex_message(
    "48 65 6C 6C 6F"
)
```

### `send()`

`send()` is a generic TCP send function.

The following input types have been verified:

* `str`
* `bytes`
* `list`

#### Syntax

```python
tcp.send(data)
```

#### Returns

`None`

#### String

```python
sp.TCPClient1.send(
    "Hello"
)
```

#### Bytes

```python
sp.TCPClient1.send(
    b"Hello"
)
```

#### List

A list of integer values is accepted:

```python
sp.TCPClient1.send(
    [72, 101, 108, 108, 111]
)
```

The same inputs are accepted by TCP Server Objects:

```python
sp.TCPServer1.send(
    "Hello"
)
```

{% hint style="info" %}
The supported Python input types above have been verified. The exact internal conversion performed by `send()` is not covered by this reference.
{% endhint %}

### `sendBytes()`

`sendBytes()` accepts data for transmission through the TCP Object.

The following input types have been verified:

* `bytes`
* `list`
* `str`

#### Syntax

```python
tcp.sendBytes(data)
```

#### Returns

`None`

#### Bytes

```python
sp.TCPClient1.sendBytes(
    b"Hello"
)
```

#### List

```python
sp.TCPClient1.sendBytes(
    [72, 101, 108, 108, 111]
)
```

#### String

```python
sp.TCPClient1.sendBytes(
    "Hello"
)
```

The same inputs are accepted by TCP Server Objects.

{% hint style="info" %}
The accepted Python input types have been verified. The exact internal conversion performed by `sendBytes()` is not covered by this reference.
{% endhint %}

### `sendHex()`

`sendHex()` accepts a hexadecimal String.

#### Syntax

```python
tcp.sendHex(message)
```

#### Parameters

| Parameter | Type  | Description         |
| --------- | ----- | ------------------- |
| `message` | `str` | Hexadecimal message |

#### Returns

`None`

Both spaced and compact Strings have been verified.

```python
sp.TCPClient1.sendHex(
    "48 65 6C 6C 6F"
)
```

or:

```python
sp.TCPClient1.sendHex(
    "48656C6C6F"
)
```

The same function is available on TCP Server Objects:

```python
sp.TCPServer1.sendHex(
    "48 65 6C 6C 6F"
)
```

### TCP Server Connections

A TCP Server requires an active connection for outgoing messages to be delivered.

If a send function is called without an active connection, Grid Studio logs a warning:

```
No active connections in this TCP Server, message will be lost in space
```

The send function still returns:

```
None
```

{% hint style="warning" %}
A successful function call does not confirm that a TCP Server currently has an active client connection.
{% endhint %}

### Choosing a Send Function

For a String message:

```python
sp.TCPClient1.sent_ascii_message("Hello")
```

For hexadecimal data:

```python
sp.TCPClient1.sent_hex_message(
    "48 65 6C 6C 6F"
)
```

For other supported Python representations, use:

```python
send()
```

or:

```python
sendBytes()
```

### Quick Reference

| API                           | Verified Input         | TCP Client | TCP Server | Returns |
| ----------------------------- | ---------------------- | ---------- | ---------- | ------- |
| `sent_ascii_message(message)` | `str`                  | Yes        | Yes        | `None`  |
| `sent_hex_message(message)`   | `str`                  | Yes        | Yes        | `None`  |
| `send(data)`                  | `str`, `bytes`, `list` | Yes        | Yes        | `None`  |
| `sendBytes(data)`             | `bytes`, `list`, `str` | Yes        | Yes        | `None`  |
| `sendHex(message)`            | `str`                  | Yes        | Yes        | `None`  |