Connection Module

seestarpy.connection.close_connections()

Close and discard all pooled Seestar connections.

Safe to call anytime; the next send_command() transparently reconnects. Registered to run at interpreter exit.

seestarpy.connection.current_ip()

Return the IP the current call should target.

Resolution order:

  1. the per-thread active IP set by multiple_ips() (if any), then

  2. the module-level DEFAULT_IP.

Always use this (not DEFAULT_IP directly) when resolving the target host at call time, so multi-Seestar broadcasts stay correct.

seestarpy.connection.find_available_ips(n_ip, timeout=2)

Find all Seestars on the local network using parallel mDNS lookups.

Resolves hostnames seestar.local, seestar-2.local, …, seestar-<n_ip>.local in parallel and updates the module-level AVAILABLE_IPS dictionary with the results. Use this when controlling multiple Seestars from a single script.

Parameters:

  • n_ip (int) – Maximum Seestar index to search for. For example, n_ip=3 will probe seestar.local, seestar-2.local, and seestar-3.local.

  • timeout (float, optional) – Maximum time in seconds to wait for all lookups. Default is 2.

Examples

>>> from seestarpy import connection as conn
>>> conn.find_available_ips(3)
✓ Found seestar.local at 192.168.1.243
✓ Found seestar-2.local at 192.168.1.244
✗ seestar-3.local has no active IP address
Use connection.AVAILABLE_IPS to get active addresses
>>> conn.AVAILABLE_IPS
{'seestar.local': '192.168.1.243', 'seestar-2.local': '192.168.1.244'}
seestarpy.connection.find_seestar()

Find a Seestar on the local network using mDNS hostname resolution.

Attempts to resolve seestar.local via DNS. This function is called automatically when the seestarpy package is imported, and its result is used to set DEFAULT_IP.

If the Seestar is not found (e.g. you are connected to a different network), DEFAULT_IP falls back to "10.0.0.1" — the Seestar’s own Wi-Fi hotspot address.

Returns:

The IP address of the Seestar if found, otherwise None.

Return type:

str or None

Examples

>>> from seestarpy import connection as conn
>>> conn.find_seestar()
Seestar found at: 192.168.1.243
'192.168.1.243'
seestarpy.connection.multiple_ips(func)

Decorator that allows a function to run against multiple IP addresses. Pass ips at call time to override DEFAULT_IP.

seestarpy.connection.resolve_ips(call_time_ips)

Resolve the ips= kwarg to a flat list of IP-address strings.

Accepts the same shapes as multiple_ips(): None (current DEFAULT_IP), an int (2 → seestar-2.local), a hostname or IP string, the literal "all", or a list mixing any of these. Unknown entries are dropped (with a warning printed) so the result is always a non-empty list of resolved IPs when input is valid.

seestarpy.connection.send_command(params)

Send a JSON-RPC command to the Seestar over TCP.

Sends the JSON payload to the current target (see current_ip()) on port DEFAULT_PORT over a persistent, authenticated connection (reused across calls; see PERSIST_CONNECTIONS) and waits for the \r\n-terminated reply whose id matches, skipping any unsolicited events the device interleaves on the socket.

Most users will not call this directly — use the functions in seestarpy.raw or the top-level convenience API instead.

Parameters:

params (dict) – A dictionary with at least a "method" key. An optional "params" key provides method-specific arguments. For example: {"method": "scope_park", "params": {"equ_mode": True}}.

Returns:

The parsed JSON-RPC response dictionary with keys 'jsonrpc', 'Timestamp', 'method', 'result', 'code', and 'id'.

Return type:

dict

Raises:

ConnectionError – If the command could not be delivered and answered even after one reconnect attempt.

Examples

>>> from seestarpy.connection import send_command
>>> send_command({"method": "test_connection"})
{'jsonrpc': '2.0', 'Timestamp': '...', 'method': 'test_connection',
 'result': 'ok', 'code': 0, 'id': 1}
seestarpy.connection.set_default_ip(n)

Set DEFAULT_IP to the n-th Seestar in AVAILABLE_IPS.

This is a convenience shorthand so you can switch between Seestars with a single integer instead of typing full hostnames or IPs.

The mapping follows the Seestar naming convention:

  • 1 → seestar.local

  • 2 → seestar-2.local

  • 3 → seestar-3.local

  • etc.

Parameters:

n (int) – Seestar number (1-based).

Raises:

KeyError – If the corresponding hostname is not in AVAILABLE_IPS. Call find_available_ips() first to populate the dictionary.

Examples

>>> from seestarpy import connection as conn
>>> conn.find_available_ips(3)
>>> conn.set_default_ip(2)
DEFAULT_IP → 192.168.1.83 (seestar-2.local)