Smart Telescope Control
Control and interact with Seestar Smart Telescope devices through command-line interface or HTTP API. This skill enables device discovery, telescope operations (goto, tracking, focusing, imaging), and real-time status monitoring.
Instructions
When the user requests telescope control, device management, or astrophotography automation tasks, follow these steps:
1. Understand the Project Structure
The smarttel project has these core components:
**SeestarClient** (`smarttel/seestar/client.py`) - Main orchestrator managing TCP connections, command/response lifecycle, event stream processing, and status aggregation**Connection Layer** (`smarttel/seestar/connection.py`) - Low-level async TCP handling with newline-delimited JSON**Command System** (`smarttel/seestar/commands/`) - Structured telescope commands including discovery, imaging, and settings**Event System** (`smarttel/seestar/events/__init__.py`) - 25+ strongly-typed Pydantic event classes for real-time telescope state**CLI Interface** (`cli/ui.py`) - Textual-based TUI with device discovery and status monitoring**HTTP API** (`main.py`) - FastAPI server with RESTful endpoints and Server-Sent Events streaming2. Development Environment Setup
This project uses `uv` as the package manager. Key commands:
```bash
Install/update dependencies
uv sync
Add new packages
uv add <package>
```
3. Running the Telescope Interface
Choose the appropriate interface based on user needs:
**Interactive CLI with Device Discovery:**
```bash
uv run python main.py console
```
**CLI with Direct Connection:**
```bash
uv run python main.py console --host <ip-address>
```
**HTTP API Server (default port 8000):**
```bash
uv run python main.py server --seestar-host <ip-address>
```
**HTTP API Server (custom port):**
```bash
uv run python main.py server --seestar-host <ip-address> --server-port <port>
```
4. Working with Commands
Commands are organized by type in `smarttel/seestar/commands/`:
**Simple commands** (`simple.py`) - No parameters (GetTime, GetViewState, etc.)**Parameterized commands** (`parameterized.py`) - Require parameters**Discovery** (`discovery.py`) - UDP broadcast device discovery with TUI picker**Imaging** (`imaging.py`) - Exposure and imaging control**Settings** (`settings.py`) - Device configurationAll commands use Generic type support for type-safe request/response handling.
5. Event Processing
Events are strongly-typed Pydantic models using discriminated unions. Key event types:
Real-time status: `PiStatusEvent` (battery, temperature)Goto operations: Slew, tracking eventsFocusing: Focus state and progressImaging: Frame stacking progress (`BatchStackEvent`), errors (`StackErrorEvent`)25+ total event types covering all telescope operationsEvents flow through the client's event stream parser and populate the `SeestarStatus` state object.
6. HTTP API Endpoints
When running the FastAPI server:
RESTful endpoints: `/viewstate`, etc.Real-time streaming: `/status/stream` (Server-Sent Events)Shared client instance maintains connection state across requests7. Key Architectural Patterns
**Async-first**: All I/O uses asyncio**Type Safety**: Extensive Pydantic models with Generics and discriminated unions**Event-driven**: Real-time state via parsed event stream**Command-response**: JSON-RPC-like protocol with auto-incrementing IDs**Discovery**: UDP broadcast for automatic device detection8. Development Best Practices
Maintain type safety throughout the stack using Pydantic modelsUse async/await for all I/O operationsCommands are sent as JSON over TCP; responses are newline-delimited JSONStatus is aggregated from multiple event types into unified `SeestarStatus`Keep protocol handling, command abstractions, event processing, and UI layers cleanly separated9. Common Tasks
**Adding a new command:**
1. Define command class in appropriate file under `smarttel/seestar/commands/`
2. Extend base classes with Generic type support
3. Implement request/response models using Pydantic
**Adding a new event type:**
1. Add event class to `smarttel/seestar/events/__init__.py`
2. Use Pydantic discriminated union pattern
3. Update event parser in `SeestarClient`
**Extending the API:**
1. Add endpoint to `main.py` FastAPI application
2. Use shared client instance for telescope operations
3. Return appropriate response models
10. Debugging
Connection uses message counting for debuggingClient maintains deque-based recent events bufferEvents and status updates are logged through the event streamExamples
**Discover and connect to telescope:**
```bash
uv run python main.py console
Interactive device picker displays available Seestar devices
```
**Direct connection for automation:**
```bash
uv run python main.py console --host 192.168.1.100
```
**Start API server for integration:**
```bash
uv run python main.py server --seestar-host 192.168.1.100 --server-port 8080
```
Constraints
Requires network access to Seestar Smart Telescope deviceTCP connection required for telescope communicationUDP broadcast required for device discoveryAll operations are async - must use asyncio event loopEvents are received as newline-delimited JSON streamCommand IDs auto-increment for request/response correlation