# {{ interface_name | pascal_case }} Socket Interface

{{ interface_description }}

Generated by MADSci template: `comm/socket` v{{ template_version }}

## Overview

TCP/UDP socket communication interface for direct network communication with
instruments and devices. Supports both TCP (stream) and UDP (datagram) protocols.

## Usage

```python
from {{ interface_name }}_interface import {{ interface_name | pascal_case }}Interface

# TCP connection (default)
interface = {{ interface_name | pascal_case }}Interface(host="192.168.1.100", port=5000)
interface.connect()
interface.send(b"HELLO\n")
response = interface.receive()
interface.disconnect()

# UDP connection
interface = {{ interface_name | pascal_case }}Interface(host="192.168.1.100", port=5000, protocol="udp")
interface.connect()
interface.send(b"PING")
response = interface.receive()
interface.disconnect()
```

## Testing

Use the fake interface for development and testing without a network:

```python
from {{ interface_name }}_fake_interface import {{ interface_name | pascal_case }}FakeInterface

interface = {{ interface_name | pascal_case }}FakeInterface(simulated_latency=0.0)
interface.set_response(b"OK\n")
interface.connect()
response = interface.query("STATUS")
assert response == "OK"
```

Run the test suite:

```bash
pytest test_{{ interface_name }}.py
```

## Dependencies

- Python standard library `socket` module (no external dependencies for the real interface)

## Common Pitfalls

- Ensure firewall rules allow traffic on the target port
- TCP connections may hang if the remote host is unreachable; set an appropriate timeout
- UDP does not guarantee delivery; consider adding application-level acknowledgement
- Buffer sizes should match the expected message size to avoid truncation
- Remember to handle partial receives for TCP streams (data may arrive in chunks)
