API Reference

This section contains the automatically generated documentation for the project modules.

INDI Driver

Celestron AUX INDI Driver

This module implements an INDI driver for Celestron mounts using the AUX protocol. It uses the indipydriver library for INDI communication and ephem for astronomical calculations.

Configuration is loaded from config.default.toml and config.toml.

class celestron_aux.celestron_indi_driver.CelestronAUXDriver(driver_name: str = 'Celestron AUX')

Bases: IPyDriver

INDI Driver for Celestron mounts.

Manages INDI properties, hardware communication via AUX bus, and coordinate transformations with multi-point SVD alignment support.

async equatorial_to_steps(ra_hours: float, dec_deg: float, time_offset: float = 0, base_date: Any | None = None) → Tuple[float, float]

Converts RA/Dec to motor encoder steps.

async get_firmware_info() → None

Retrieves model and version info from the mount.

async get_tracking_rates(ra: float, dec: float, base_date: Any | None = None) → Tuple[float, float]

Calculates current tracking rates in steps/second.

async goto_position(target_azm: int, target_alt: int, ra: float | None = None, dec: float | None = None, force_approach: str | None = None) → bool

Executes a GoTo movement with optional anti-backlash approach. Checks against slew limits before moving.

async handle_abort(event: Any) → None

Immediately stops all mount motion.

async handle_abort_motion(event: Any) → None

Immediately stops all mount movement.

async handle_alignment_config(event: Any) → None

Handles clearing alignment or pruning.

async handle_connection(event: Any) → None

Handles CONNECT/DISCONNECT switches.

async handle_cordwrap(event: Any) → None

Enables or disables cord wrap prevention on the mount.

async handle_cordwrap_pos(event: Any) → None

Sets the cord wrap prevention position on the mount.

async handle_equatorial_goto(event: Any) → None

Handles GoTo or Sync command using RA/Dec coordinates.

async handle_focuser(event: Any) → None

Moves the focuser to the specified position.

async handle_goto(event: Any) → None

Handles GoTo command using raw encoder steps.

async handle_gps_refresh(event: Any) → None

Manually refreshes location and time from the GPS module.

async handle_guide_rate(event: Any) → None

Updates guiding/tracking rates.

async handle_home(event: Any) → None

Moves the mount to the home position (index or 0,0).

async handle_limits(event: Any) → None

Updates internal slew limits.

async handle_location(event: Any) → None

Sets the geographic location in the mount.

async handle_motion_ns(event: Any) → None

Handles manual North/South slew commands.

async handle_motion_we(event: Any) → None

Handles manual West/East slew commands.

async handle_park(event: Any) → None

Moves the mount to the park position (0,0 steps).

async handle_std_slew_rate(event: Any) → None

Maps standard INDI slew rates to 1-9 scale.

async handle_track_mode(event: Any) → None

Starts or stops tracking.

async handle_unpark(event: Any) → None

Clears the parked status.

async hardware() → None

Periodically poll hardware status.

is_move_allowed(azm_steps: float, alt_steps: float) → bool

Checks if the given position (in steps) is within configured limits.

async read_mount_position(base_date: Any | None = None) → None

Periodically reads encoder steps and updates RA/Dec.

async rxevent(event: Any) → None

Main event handler for INDI property updates.

async slew_by_rate(axis: AUXTargets, rate: int, direction: int) → None

Sends a rate-based slew command to a motor axis.

async slew_to(axis: AUXTargets, steps: int, fast: bool = True) → bool

Sends a position-based GoTo command to a motor axis.

async steps_to_equatorial(azm_steps: float, alt_steps: float, base_date: Any | None = None) → Tuple[float, float]

Converts motor encoder steps to RA/Dec.

async sync_time() → bool

Synchronizes mount RTC with system time.

async update_alignment_status() → None

Updates INDI properties with alignment model stats.

async update_gps_data() → bool

Polls GPS module for status and location data.

update_observer(time_offset: float = 0, base_date: Any | None = None) → None

Updates ephem Observer state from INDI location properties.

async write_location_to_mount() → bool

Writes current Latitude/Longitude to the mount’s GPS/RTC.

celestron_aux.celestron_indi_driver.apply_refraction(alt_deg: float) → float

Adds atmospheric refraction to true altitude to get apparent altitude.

celestron_aux.celestron_indi_driver.deep_merge(base: dict, override: dict) → dict

Recursively merges two dictionaries.

celestron_aux.celestron_indi_driver.load_config()

Loads configuration from TOML files with deep merge.

celestron_aux.celestron_indi_driver.main() → None

Entry point for the INDI driver.

celestron_aux.celestron_indi_driver.remove_refraction(alt_deg: float) → float

Subtracts atmospheric refraction from apparent altitude to get true altitude.

AUX Protocol

Celestron AUX Protocol Library

This module implements the binary communication protocol used by Celestron telescope mounts via the AUX bus. It provides classes for command creation, parsing, and asynchronous communication over Serial or TCP.

References

• NexStar AUX Command Set documentation

• indi-celestronaux C++ implementation

class celestron_aux.celestron_aux_driver.AUXCommand(command: AUXCommands, source: AUXTargets, destination: AUXTargets, data: bytes = b'')

Bases: object

Represents a single Celestron AUX bus command packet.

command

The command to execute.

Type:

AUXCommands

source

The sender of the command.

Type:

AUXTargets

destination

The target device.

Type:

AUXTargets

data

Optional payload.

Type:

bytes

length

Length of (source + destination + command + data).

Type:

int

MAX_CMD_LEN = 32

START_BYTE = 59

fill_buf() → bytes

Serializes the command into a byte buffer for transmission.

Returns:

The complete packet (START | LEN | SRC | DST | CMD | DATA… | CS).

Return type:

bytes

get_data_as_int() → int

Converts command data bytes to a big-endian integer.

Returns:

The integer value of the payload.

Return type:

int

classmethod parse_buf(buf: bytes) → AUXCommand

Parses a byte buffer into an AUXCommand object.

Parameters:

buf (bytes) – Received bytes.

Returns:

The parsed command object.

Return type:

AUXCommand

Raises:

ValueError – If the start byte is invalid or buffer is too short.

set_data_from_int(value: int, num_bytes: int) → None

Sets the command data payload from an integer.

Parameters:

• value (int) – The integer value.

• num_bytes (int) – Number of bytes to use (1, 2, or 3).

class celestron_aux.celestron_aux_driver.AUXCommands(value)

Bases: Enum

Enumeration of Celestron AUX bus commands.

FOC_GET_HS_POSITIONS = 44

GET_VER = 254

GPS_GET_DATE = 59

GPS_GET_LAT = 1

GPS_GET_LONG = 2

GPS_GET_SATS = 56

GPS_GET_TIME = 51

GPS_LINKED = 55

GPS_SET_DATE = 60

GPS_SET_LAT = 49

GPS_SET_LONG = 50

GPS_SET_TIME = 52

GPS_TIME_VALID = 54

MC_AUX_GUIDE = 38

MC_AUX_GUIDE_ACTIVE = 39

MC_DISABLE_CORDWRAP = 57

MC_ENABLE_CORDWRAP = 56

MC_GET_APPROACH = 252

MC_GET_AUTOGUIDE_RATE = 71

MC_GET_CORDWRAP_POS = 60

MC_GET_MODEL = 5

MC_GET_POSITION = 1

MC_GOTO_FAST = 2

MC_GOTO_SLOW = 23

MC_LEVEL_DONE = 18

MC_LEVEL_START = 11

MC_MOVE_NEG = 37

MC_MOVE_POS = 36

MC_POLL_CORDWRAP = 59

MC_SEEK_DONE = 24

MC_SEEK_INDEX = 25

MC_SET_APPROACH = 253

MC_SET_AUTOGUIDE_RATE = 70

MC_SET_CORDWRAP_POS = 58

MC_SET_NEG_GUIDERATE = 7

MC_SET_POSITION = 4

MC_SET_POS_GUIDERATE = 6

MC_SLEW_DONE = 19

PWR_GET_CURRENT = 2

PWR_GET_STATUS = 3

PWR_GET_VOLTAGE = 1

SIM_GET_SKY_POSITION = 255

class celestron_aux.celestron_aux_driver.AUXCommunicator(port: str, baudrate: int = 19200, timeout: float = 1.0)

Bases: object

Handles asynchronous communication with the AUX bus.

Supports Serial (via pyserial-asyncio) and TCP (via socket:// prefix). Implements echo-skipping for one-wire bus environments.

port

Device path (e.g. /dev/ttyUSB0) or URL (socket://host:port).

Type:

str

baudrate

Communication speed (default 19200).

Type:

int

timeout

Read timeout in seconds.

Type:

float

async connect() → bool

Establishes connection to the AUX bus.

Returns:

True if successful, False otherwise.

Return type:

bool

async disconnect() → None

Closes the connection.

reader: 'StreamReader' | None

async send_command(command: AUXCommand) → AUXCommand | None

Sends an AUX command and waits for a response.

Implements echo skipping: if the received packet matches the sent one (common on AUX bus), it is ignored, and the next packet is read.

Parameters:

command (AUXCommand) – Command to send.

Returns:

The response packet, or None on failure/timeout.

Return type:

AUXCommand

writer: 'StreamWriter' | None

class celestron_aux.celestron_aux_driver.AUXTargets(value)

Bases: Enum

Enumeration of devices on the AUX bus.

ALT = 17

ANY = 0

APP = 32

AZM = 16

BAT = 182

CHG = 183

FOCUS = 18

GPS = 176

HC = 4

HCP = 13

LIGHT = 191

MB = 1

WiFi = 181

celestron_aux.celestron_aux_driver.pack_int3_steps(val: float) → bytes

Packs a float or integer into 3 big-endian bytes.

celestron_aux.celestron_aux_driver.unpack_int3_steps(d: bytes) → int

Unpacks 3 bytes into a 24-bit unsigned integer (encoder steps).

Parameters:

d (bytes) – 3 bytes of data.

Returns:

Encoder steps.

Return type:

int

Alignment Model

Alignment Subsystem for Telescope Mounts

Provides mathematical models for coordinate transformation based on alignment stars.

class celestron_aux.alignment.AlignmentModel

Bases: object

Manages N-point alignment transformation using a 6-parameter geometric model. Compensates for Rotation, Cone Error, Non-Perpendicularity, and Index Offsets.

add_point(sky_vec: List[float] | ndarray, mount_vec: List[float] | ndarray, weight: float = 1.0, sector_size: float = 15.0, max_per_sector: int = 2) → None

Adds an alignment point using Residual-Aware Grid Thinning. Ensures even sky coverage by managing points in angular sectors.

clear() → None

Clears all alignment points and resets to identity.

get_local_matrix(target_sky_vec: List[float] | ndarray, local_bias: float) → ndarray

Returns a weighted SVD matrix (Fallback for small point counts).

transform_to_mount(sky_vec: List[float] | ndarray, target_vec: List[float] | ndarray | None = None, local_bias: float = 0.0) → List[float]

Applies transformation with optional local weighting.

transform_to_sky(mount_vec: List[float] | ndarray) → List[float]

Applies inverse transformation.

celestron_aux.alignment.angular_distance(az1: float, alt1: float, az2: float, alt2: float) → float

Calculates angular distance between two points in degrees.

celestron_aux.alignment.vector_from_altaz(az_deg: float, alt_deg: float) → List[float]

Converts Alt/Az to a 3D unit vector.

celestron_aux.alignment.vector_from_radec(ra_hours: float, dec_deg: float) → List[float]

Converts RA/Dec to a 3D unit vector.

celestron_aux.alignment.vector_to_altaz(vec: List[float] | ndarray) → Tuple[float, float]

Converts a 3D unit vector to Azimuth and Altitude (degrees).

celestron_aux.alignment.vector_to_radec(vec: List[float] | ndarray) → Tuple[float, float]

Converts a 3D unit vector to RA (hours) and Dec (degrees).