NAME

NexStarCtl - API to control NexStar compatible telescopes

SYNOPSIS

 use NexStarCtl;
 
 my $port = open_telescope_port("/dev/XXX"); 
 if (!defined $port) {
	print "Can not open communication port.\n";
	exit;
 }
 
 # check if the mount is aligned
 if (tc_check_align($port)) {
 	print "The telescope is aligned.\n";
 } else {
 	print "The telescope is not aligned.\n";
 }
 
 # Read the stored coordinates of the location
 my ($lon,$lat) = tc_get_location_str($port);
 if (! defined($lon)) {
 	print "Telescope did not respond\n";
 	close_telescope_port($port);
 	exit;
 }
 print "Location coordinates:\n LON=$lon\n LAT=$lat\n";

 my ($date,$time,$tz,$dst) = tc_get_time_str($port);
 # ...
 # Do some other stuff
 # ...
 
 close_telescope_port($port);

DESCRIPTION

This module implements the serial commands supported by the Celestron NexStar hand control (HC) and SkyWatcher/Orion SynScan HC. This applies to the Celestron: NexStar GPS, NexStar GPS-SA, NexStar iSeries, NexStar SE Series, NexStar GT, CPC, SLT, Advanced-VX, Advanced-GT, CGE, CGEM etc. SkyWatcher: EQ5, HEQ5, EQ6 (Pro), AZ-EQ5 GT, AZ-EQ6 GT, EQ8 etc. and the corresponding Orion mounts.

Communication to the hand control is 9600 bits/sec, no parity and one stop bit via the RS-232 port on the base of the hand control.

Communication can be established over TCP/IP if nexbridge is running on the computer connected to the telescope.

For extended example how to use this perl module look in to the distribution folder for nexstarctl/nexstarctl.pl. This program is a complete console tool to control NexStar telescopes based on NexStarCtl module.

NOTE: For SkyWatcher/Orion mounts it is highly recommended to enforce protocol version checking (see enforce_protocol_version()) as the AUX commands are not supported or may behave erratically.

TELESCOPE COMMUNICATION

open_telescope_port(port_name)

Opens a communication port to the telescope by name (like "/dev/ttyUSB0") and returns it to be used in other functions. If the port_name has "tcp://" prefix the rest of the string is interpreted as an IP address and port where to connect to (like "tcp://localhost:9999"). In case of error undef is returned.

NOTE: To be used with TCP you need to run nexbridge on the remote computer.

read_telescope(port, len) =item read_telescope(port, len , vl)

Reads data from the telescope. On error or in case less than len bytes are read undef is returned. If "vl" is true the function will return success if "#" is read before the len bytes are read.

write_telescope(port, data)

Writes data to the telescope and the result of write is returned.

close_telescope_port(port)

Closes the communication port to the telescope.

enforce_protocol_version(port, ver)

Enforce protocol minimal version checking. If a specific command is not supported by the firmware version given in ver, the corresponding tc_*() call will fail as unsupported and return undef (in this case $NexStarCtl::error will be set to -5). If version is VER_AUX, version enforcement is disabled and all commands are enabled but some may fail, because they may not be supported by the current hand controller firmware. To avoid this use VER_AUTO (or omit it) to set the version to the value reported by the currently connected hand controller. By default protocol version enforcement is disabled and the unsupported commands will either timeout or return erratic results. Because of this, calling enforce_protocol_version() with VER_AUTO or no ver parameter right after open_telescope_port() is highly recommended. The predefined versions are: VER_1_2, VER_1_6, VER_2_2, VER_2_3, VER_3_1, VER_4_10 and VER_4_37_8.

NOTE: The non-documented (AUX) commands are available only when the enforcement is disabled.

guess_mount_vendor(port)

This function guesses the manufacturer of the mount by a slight difference in the protocol. The firmware version command returns 2 bytes for Celestron mounts and 6 bytes for SkyWatcher mounts (since version 4.37.8). On success the guessed value is returned (VNDR_CELESTRON or VNDR_SKYWATCHER). On error undef is returned.

NOTE: SkyWather mounts with firmware before 4.37.8 will be threated as Celestron in this case enforce_vendor_protocol() can be used.

enforce_vendor_protocol(vendor)

This function enforces protocol of the specified vendor to be used overriding the guessed one. Valid vendor IDs are VNDR_CELESTRON and VNDR_SKYWATCHER. This way the commands not supported by the vendor version of the protocol will fail and $NexStarCtl::error will be set to -5. On success the vendor ID is returned otherwise it returns undef.

TELESCOPE COMMANDS

tc_check_align(port)

If the telescope is aligned 1 is returned else 0 is returned. If no response received, undef is returned.

tc_get_orientation(port)

Get the telescope orientation. "E" or "W" is returned for East and West respectively. If no response received, undef is returned.

tc_goto_rade(port, ra, de)

tc_goto_rade_p(port, ra, de)

Slew the telescope to RA/DEC coordinates ra, de (in decimal degrees). Function tc_goto_rade_p uses precise GOTO. If RA is not in [0;360] function returns -1. If DEC is not in [-90;90] -2 is returned. If no response received, undef is returned.

tc_goto_azalt(port, az, alt)

tc_goto_azalt_p(port, az, alt)

Slew the telescope to AZ/ALT coordinates az, alt (in decimal degrees). Function tc_goto_azalt_p uses precise GOTO. If AZ is not in [0;360] function returns -1. If ALT is not in [-90;90] -2 is returned. If no response received, undef is returned.

tc_get_rade(port)

tc_get_rade_p(port)

Returns the the current telescope RA/DEC coordinates ra, de (in decimal degrees). Function tc_get_rade_p uses precise GET. If no response received, undef is returned.

tc_get_azalt(port)

tc_get_azalt_p(port)

Returns the the currents telescope AZ/ALT coordinates az, alt (in decimal degrees). Function tc_get_azalt_p uses precise GET. If no response received, undef is returned.

tc_sync_rade(port, ra, de)

tc_sync_rade_p(port, ra, de)

Syncs the telescope to RA/DEC coordinates ra, de (in decimal degrees). Function tc_sync_rade_p uses precise sync. If RA is not in [0;360] function returns -1. If DEC is not in [-90;90] -2 is returned. If no response received, undef is returned.

tc_goto_in_progress(port)

Returns 1 if GOTO is in progress else 0 is returned. If no response received, undef is returned.

tc_goto_cancel(port)

Cancels the GOTO operation. On success 1 is returned. If no response received, undef is returned.

tc_echo(port, char)

Checks the communication with the telescope. This function sends char to the telescope and returns the echo received. If no response received, undef is returned.

tc_get_model(port)

This function returns the mount model as a number. See CELESTRON documentation. If no response received, undef is returned.

tc_get_version(port)

This function returns the mount version as a strng or as major and minor numbers in array context See CELESTRON documentation. If no response received, undef is returned.

tc_get_location(port)

This function returns the stored location coordinates lon, lat in decimal degrees. Negative longitude is WEST. Negative latitude is SOUTH. If no response received, undef is returned.

tc_get_location_str(port)

This function returns the stored location coordinates lon and lat as strings. If no response received, undef is returned.

tc_set_location(port,lon,lat)

This function sets the location coordinates lon, lat in decimal degrees. Negative longitude is WEST. Negative latitude is SOUTH. If the coordinates are invalid -1 is returned. If no response received, undef is returned.

tc_get_time(port)

This function returns the stored time (in Unix time format), timezone (in hours) and daylight saving time(0|1). If no response received, undef is returned.

tc_get_time_str(port)

This function returns the stored date, time (as strings), timezone (in hours) and daylight saving time(0|1). If no response received, undef is returned.

tc_set_time(port, time, timezone, daylightsaving)

This function sets the time (in Unix time format), timezone (in hours) and daylight saving time(0|1). On success 1 is returned. If no response received, undef is returned. If the mount is known to have RTC (currently only CGE and AdvancedVX) and NexStarCtl::use_rtc is defined and != 0 (default is 0), the date/time is set to the RTC too.

NOTE: Do not set NexStarCtl::use_rtc if the mount is SkyWatcher otherwise tc_set_time() may fail.

tc_get_tracking_mode(port)

Reads the tracking mode of the mount and returns one of the folowing: TC_TRACK_OFF, TC_TRACK_ALT_AZ, TC_TRACK_EQ_NORTH (Celestron only), TC_TRACK_EQ_SOUTH (Celestron only), TC_TRACK_EQ (SkyWatcher only) and TC_TRACK_EQ_PEC (Sky-Watcher only). If no response received, undef is returned.

tc_set_tracking_mode(port, mode)

Sets the tracking mode of the mount to one of the folowing: TC_TRACK_OFF, TC_TRACK_ALT_AZ, TC_TRACK_EQ_NORTH, TC_TRACK_EQ_SOUTH, TC_TRACK_EQ and TC_TRACK_EQ_PEC. For Sky-Watcher TC_TRACK_EQ_NORTH, TC_TRACK_EQ_SOUTH and TC_TRACK_EQ do the same thing. For Celestron TC_TRACK_EQ is interpreted as TC_TRACK_EQ_NORTH or TC_TRACK_EQ_SOUTH depending on the geographic latitude of the location (Northern or Southern hemisphere). If the mode is not one of the listed -1 is returned. If no response received, undef is returned.

tc_slew_fixed(port, axis, direction, rate)

Move the telescope the telescope around a specified axis in a given direction with fixed rate.

Accepted values for axis are TC_AXIS_RA_AZM and TC_AXIS_DE_ALT. Direction can accept values TC_DIR_POSITIVE and TC_DIR_NEGATIVE. Rate is from 0 to 9. Where 0 stops slewing and 9 is the fastest speed.

On success 1 is returned. If rate is out of range -1 is returned. If no response received, undef is returned.

tc_slew_variable(port, axis, direction, rate)

Move the telescope the telescope around a specified axis in a given direction with specified rate.

Accepted values for axis are TC_AXIS_RA_AZM and TC_AXIS_DE_ALT. Direction can accept values TC_DIR_POSITIVE and TC_DIR_NEGATIVE. Rate is the speed in arcsec/sec. For example 3600 represents 1degree/sec.

On success 1 is returned. If no response received, undef is returned.

get_model_name(model_id)

Return the name of the mount by the id from tc_get_model(). If the mount is not known undef is returned.

AUX COMMANDS

The following commands are not officially documented by Celestron. Please note that these commands are reverse engineered and may not work exactly as expected.

tc_get_autoguide_rate(port, axis)

Get autoguide rate for the given axis in percents of the sidereal rate.

Accepted values for axis are TC_AXIS_RA_AZM and TC_AXIS_DE_ALT.

On success current value of autoguide rate is returned in the range [0-99]. If no response received, undef is returned.

tc_set_autoguide_rate(port, axis, rate)

Set autoguide rate for the given axis in percents of the sidereal rate.

Accepted values for axis are TC_AXIS_RA_AZM and TC_AXIS_DE_ALT. Rate must be in the range [0-99].

On success 1 is returned. If rate is out of range -1 is returned. If no response received, undef is returned.

tc_get_backlash(port, axis, direction)

Get anti-backlash values for the specified axis in a given direction.

Accepted values for axis are TC_AXIS_RA_AZM and TC_AXIS_DE_ALT. Direction can accept values TC_DIR_POSITIVE and TC_DIR_NEGATIVE.

On success current value of backlash is returned in the range [0-99]. If no response received, undef is returned.

tc_set_backlash(port, axis, direction, backlash)

Set anti-backlash values for the specified axis in a given direction.

Accepted values for axis are TC_AXIS_RA_AZM and TC_AXIS_DE_ALT. Direction can accept values TC_DIR_POSITIVE and TC_DIR_NEGATIVE. Backlash must be in the range [0-99].

On success 1 is returned. If backlash is out of range -1 is returned. If no response received, undef is returned.

tc_pass_through_cmd(port, msg_len, dest_id, cmd_id, data1, data2, data3, res_len)

Send a pass through command to a specific device. This function is meant for an internal library use and should not be used, unless you know exactly what you are doing. Calling this function with wrong parameters can be dangerous and can break the telescope!

UTILITY FUNCTIONS

notnum(n)

If "n" is a real number returns 0 else it returns 1.

precess(ra0, dec0, equinox0, equinox1)

Precesses coordinates ra0 and dec0 from equinox0 to equinox1 and returns the calculated ra1 and dec1. Where ra and dec should be in decimal degrees and equinox should be in years (and fraction of the year).

round(n)

Returns the rounded number n.

d2hms(deg)

Converts deg (in decimal degrees) to string in hours, minutes and seconds notion (like "12h 10m 44s").

d2dms(deg)

Converts deg (in decimal degrees) to string in degrees, minutes and seconds notion (like "33:20:44").

d2dms(deg)

converts deg (in decimal degrees) to string in degrees and minutes notion (like "33:20").

dms2d(string)

converts string of the format "dd:mm:ss" to decimal degrees. If the string format is invalid format, undef is returned.

hms2d(string)

Converts string of the format "hh:mm:ss" to decimal degrees. If the string format is invalid format, undef is returned.

nex2dd(string)

Converts NexStar hexadecimal coordinate string (in fraction of a revolution) of the format "34AB,12CE" to two decimal degree coordinates.

pnex2dd(string)

Converts precision NexStar hexadecimal coordinate string (in fraction of a revolution) of the format "12AB0500,40000500" to two decimal degree coordinates.

dd2nex(deg1,deg2)

Converts coordinates deg1 and deg2 (in decimal degrees) to NexStar hexadecimal coordinate string (in fraction of a revolution) of the format "34AB,12CE".

dd2nex(deg1,deg2)

Converts coordinates deg1 and deg2 (in decimal degrees) to precise NexStar hexadecimal coordinate string (in fraction of a revolution) of the format "12AB0500,40000500".

SEE ALSO

For more information about the NexStar commands please refer to the original protocol specification described here: http://www.celestron.com/c3/images/files/downloads/1154108406_nexstarcommprot.pdf

The undocumented commands are described here: http://www.paquettefamily.ca/nexstar/NexStar_AUX_Commands_10.pdf

AUTHOR

Rumen Bogdanovski, <rumen@skyarchive.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013-2014 by Rumen Bogdanovski

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.