Communication Service Interfaces

Introduction

Communication Service Interfaces:
Provides network data transmission functionality in task scripts, supporting TCP (reliable transmission) and UDP (real-time transmission) protocols. All messages use UTF-8 encoding.

Port Restriction: All communication ports must be within the 70000–71000 range. Ports outside this range will raise a ValueError.

Purpose	Python
TCP Client Connection and Communication	✔
TCP Server Listen and Response	✔
UDP Send and Receive	✔
UDP Broadcast	✔

TCP Client

Python Interface

create_tcp_client(ip, port)

Function Description
Create and connect to a TCP server at the specified address, returning a TCPClient instance. Using a with statement is recommended to manage the connection lifecycle and ensure automatic disconnection.

Parameter Description

Parameter Name	Type	Required/Default	Description
ip	str	Required	Server IP address.
port	int	Required	Server port, must be within the 70000–71000 range.

Return Value

Type	Description
TCPClient	TCP client instance. Supports send(message), receive(timeout), and disconnect() methods.

Example

from daystar_api.tcp_client import create_tcp_client

# Using with statement (recommended)
with create_tcp_client("192.168.1.100", 70001) as client:
    client.send("Hello Server")
    response = client.receive(timeout=5.0)
    if response:
        print(f"Received reply: {response}")

TCPClient Key Methods:

Method	Description
send(message: str)	Send a message, automatically appends \x03 terminator.
receive(timeout: float = None)	Receive a message; returns None on timeout (no exception).
disconnect()	Disconnect from server.

TCP Server

Python Interface

create_tcp_server(port, message_callback=None)

Function Description
Create a TCP server that listens for connections in the background and returns a TCPServer instance. The server runs in a background thread, allowing the main script to continue executing.

Parameter Description

Parameter Name	Type	Required/Default	Description
port	int	Required	Listening port, must be within the 70000–71000 range.
message_callback	callable	None	Callback when a message is received; signature is callback(msg: str, client_addr: tuple). The return value will be sent back to the client as a reply.

Return Value

Type	Description
TCPServer	TCP server instance. Supports send(message, client), send_to_all(message), get_connected_clients(), and stop() methods.

Example

from daystar_api.tcp_server import create_tcp_server

def handle_message(msg, client_addr):
    print(f"Received from {client_addr}: {msg}")
    return f"Echo: {msg}"  # Return value is sent as reply

server = create_tcp_server(70001, message_callback=handle_message)

# Proactively push message to all clients
server.send_to_all("Broadcast message")

# Stop server
server.stop()

TCPServer Key Methods:

Method	Description
send(message: str, client)	Send a message to a specific client.
send_to_all(message: str)	Broadcast to all connected clients.
get_connected_clients()	Returns a list of connected clients.
stop()	Stop the server and release the port.

UDP Socket

Python Interface

create_udp_socket(port)

Function Description
Create a UDP socket that can be used for both sending and receiving simultaneously. Using a with statement is recommended to manage resources.

Parameter Description

Parameter Name	Type	Required/Default	Description
port	int	Required	Local listening port, must be within the 70000–71000 range.

Return Value

Type	Description
UDPSocket	UDP socket instance. Supports send(message, addr), receive(timeout), and enable_broadcast() methods.

Example

from daystar_api.udp_socket import create_udp_socket

# Receiver
with create_udp_socket(70002) as receiver:
    result = receiver.receive(timeout=10.0)
    if result:
        message, sender_addr = result
        print(f"Received: {message} from: {sender_addr}")
        receiver.send(f"Reply: {message}", sender_addr)

# Sender
with create_udp_socket(70001) as sender:
    sender.send("Hello UDP", ("192.168.1.100", 70002))

# UDP Broadcast
with create_udp_socket(70001) as broadcaster:
    broadcaster.enable_broadcast()
    broadcaster.send("Broadcast message", ("255.255.255.255", 70002))

UDPSocket Key Methods:

Method	Description
send(message: str, addr: tuple)	Send a message to a specified address; addr is an (ip, port) tuple.
receive(timeout: float = None)	Receive a message; returns (message, sender_addr) or None on timeout.
enable_broadcast()	Enable broadcast mode to allow sending to broadcast addresses.