How do you Communicate with C2A Via a TCP Socket?

C2A allows a third party application to communicate through a TCP port. This ability is useful, for example, to obtain the properties of the current view or to force the display of a particular field.

C2A communicates with a third party application through the TCP port 5876. The command which can be sent to C2A, and the responses sent by C2A through the same port, are described in the following table. Cases in command names (as well as in possible values sent in parameters) are ignored by C2A. All commands must be terminated by a “;” character. All numeric values must use the international decimal separator, i.e. « . » (in order to facilitate the transfer of scripts between countries having different language conventions). The parameters of international settings on the PC running C2A are therefore ignored.

All responses C2A makes to commands are terminated by ASCII character CR followed by LF (chr(13)+chr(10)).  If the commands have been correctly interpreted, C2A sends back a string of return values separated by « ; » (if applicable) then the string OK and finally the characters CR and LF. If an error is encountered in processing commands, an error message is returned in the form Error;<Error Message> followed by CR+LF.

Command

Response

Description

SetRA=<value>;

OK
Error;<error message >

This command allows you to specify the right ascension of the centre of the current view. The value passed by the command must be expressed in decimal hours and must be between 0 inclusive and 24 exclusive.

SetDE=<value >;

OK
Error;<error message>

This command allows you to specify the declination of the centre of the current view. The value passed by the command must be expressed in decimal degrees between -90 and 90 inclusive.

SetFieldX=<value >;

OK
Error;<error message>

This command allows you to specify the width of the current view. The value passed by the command must be expressed in decimal degrees between 0.00014 and 200 inclusive.

SetFieldY=<value >;

OK
Error;<error message>

This command allows you to specify the height of the current view. The value passed by the command must be expressed in decimal degrees between 0.00014 and 200 inclusive.

SetLatitude=< value >;

OK
Error;<error message>

This command allows you to specify the latitude of the current observing location. The value passed by the command must be expressed in decimal degrees between -90 and 90 inclusive. Latitudes must be calculated positively North of the equator and negatively South.

SetLongitude=<value >;

OK
Error;<error message>

This command allows you to specify the longitude of the current observing location. The value passed by the command must be expressed in decimal degrees between -180 and 180 inclusive. Longitudes must be calculated positively East and negatively West.

SetDateTime=<value >;

OK
Error;<error message>

This command allows you to specify the current date and time to use in c2a. The possible values to be passed in the parameter are as follows:

• currentut   Asks c2a to use current system date and time assuming that the system is set to universal time. 

• currentlocal  Asks c2a to use current system date and time assuming that the system is set to local time. 

• DD/MM/AAAA Hh:Mm:Ss   Asks C2A to use the fixed date and time which is passed in the parameter. It is imperative that the hour is in Universal Time. Formats for date and time must conform to those given, that is to say, day, month, year, hours minutes and seconds. It is imperative that all values are given as 2 characters (4 for the year) and be padded by 0s. 

SetMapType=<value >;

OK
Error;<error message>

This command allows you to specify the type of map to be used in the current view. Two values can be passed as a parameter corresponding to the two kinds of map available in C2A, that is to say:

• field   Asks C2A to display a map of « field » type (with north at the top of the screen if no rotation or symmetry applied). This is the only type of view in which symmetries (horizontal or vertical) and rotations can be applied.

• horizon   Asks C2A to display a map of « horizon » type (such that the nearest horizon is at the bottom of the screen). It is not possible to apply symmetries or rotations to this type of view.

SetHSymmetry=<value >;

OK
Error;<error message>

This command lets you say that you wish to apply a horizontal symmetry (horizontal flip) to the current field. It can only be used in views of « field » type (i.e. it is ignored if the current type of view is « horizon »).

SetVSymmetry=<value>;

OK
Error;<error message>

This command lets you say that you wish to apply a vertical symmetry (vertical flip) to the current field. It can only be used in views of « field » type (i.e. it is ignored if the current type of view is « horizon »).

SetRotation=<value>;

OK
Error;<error message>

This command lets you specify a rotation to be applied to the current field. This rotation must be expressed in degrees in the trigonometric sense and be between -359,999 and 359,999 inclusive. Field rotation can only be applied in views of « field » type (i.e. it is ignored if the current type of view is « horizon »).

SetFieldMarker=<id>,<valx>,<valy>,<rot>;

OK
Error;<error message>

This command lets you specify a CCD rectangular Field Marker. It is equivalent to the setting of a CCD Field Marker with the type Rectangle 2 in C2A's GUI (see the section Field Markers). This command must be used with 4 arguments separated with commas: <id> must be A or B to indicate which Rectangle 2 Field Marker you want to set (A otr B). <valx> is the Field Marker dimension on the X axis and <valy> is the Field Marker dimension on the Y axis. These two values must be expressed in decimal degrees and be greater than or equal to 0 and smaller than or equal to 90°. They do not have to be integer values. Finally, <rot> is the rotation to apply to the Field Marker (in the counter-clockwise direction) and it must be greater than or equal to 0 and stritcly smaller than 360 °. It does not have to be an integer value either.

GetRa;

<value>;OK
Error;<error message>

The command GetRa lets you request the right ascension of the centre of the current view. The value returned is in decimal hours.

GetRaHms;

<xxhyymzzs>;OK
Error;<error message>

The command GetRaHms lets you request the right ascension of the centre of the current view (just like the GetRa command)  but expressed in the form « xxhyymzzs » where xx, yy and zz are the values in hours, minutes and seconds on 2 digits.

GetDe;

<value>;OK
Error;<error message>

The command GetDe allows you to request the declination of the centre of the current view. The value returned is in decimal degrees.

GetDeDms;

<xx°yy’zz">;OK
Error;<error message>

The command GetDeHms lets you request the declination of the centre of the current view (just like the GetDe command)  but expressed in the form « xxºyy’zz"» where xx, yy and zz are the values in degrees, minutes and seconds on 2 digits.

GetFieldX;

<value>;OK
Error;<error message>

The command Get FieldX allows you to request the width of the current view. The value returned is in decimal degrees.

GetFieldXDms;

<xx°yy’zz">;OK
Error;<error message>

The command GetFieldXDms lets you request the width of the current view (just like the GetFieldX command) but expressed in the form « xxºyy’zz"» where xx, yy and zz are the values in degrees, minutes and seconds on 2 digits.

GetFieldY;

<value>;OK
Error;<error message>

The command Get FieldY allows you to request the height of the current view. The value returned is in decimal degrees.

GetFieldYDms;

<xx°yy’zz">;OK
Error;<error message>

The command GetFieldYDms lets you request the height of the current view (just like the GetFieldX command) but expressed in the form « xxºyy’zz"» where xx, yy and zz are the values in degrees, minutes and seconds on 2 digits.

GetLatitude;

<value>;OK
Error;<error message>

This command lets you obtain the latitude of the observing location currently used by C2A. The value returned is expressed in decimal degrees between -90 and 90 inclusive. Latitudes are counted positive in the northern hemisphere and negative in the southern.

GetLatitudeDms;

<xx°yy’zz">;OK
Error;<error message>

The command GetLatitudeDms lets you obtain the latitude of the current observing location (just like the GetLatitude command) but expressed in the form « xxºyy’zz"» where xx, yy and zz are the values in degrees, minutes and seconds in 2 digits. Latitudes are counted positive in the northern hemisphere and negative in the southern.

GetLongitude;

<value>;OK
Error;<error message>

This command allows you to obtain the longitude of the observing location currently used by C2A. The value returned is expressed in decimal degrees between -180 and 180 inclusive. Longitudes are counted positive towards the east and negative to west.

GetLongitudeDms;

<xx°yy’zz">;OK
Error;<error message>

The command GetLongitudeDms lets you obtain the longitude of the current observing location (just like the GetLongitude command) but expressed in the form « xxºyy’zz"» where xx, yy and zz are the values in degrees, minutes and seconds in 2 digits. Longitudes are counted positive towards the east and negative to west.

GetDateTimeUT;

<DD/MM/AAAA hh:mm:ss>;OK
Error;<error message>

This command returns the date and time (as Universal Time) currently being used by C2A. The returned format is always the same regardless of the regional time settings of the machine running C2A, namely, day, month, year, hours, minutes and seconds. All values are given as 2 digits (4 for the year) and are padded with 0.

GetDateTimeLocal;

<DD/MM/AAAA hh:mm:ss>;OK
Error;<error message>

This command returns the local date and time currently being used by C2A. The returned format is always the same regardless of the regional time settings of the machine running C2A, namely, day, month, year, hours, minutes and seconds. All values are given as 2 digits (4 for the year) and are padded with 0.

GetDeltaUTC;

<value>;OK
Error;<error message>

This command returns the offset between local time and Coordinated Universal Time (UTC), also called Greenwich Mean Time (GMT) which is set in the current configuration of C2A. This value can be non-integer and is expressed in hours.

GetMapType;

<value>;OK
Error;<error message>

This command returns the type of map currently displayed by C2A The possible returned values are:

• field   This value is returned when the current view is the « field » type (that is, north at the top of the screen and no applied rotation or symmetries).

• horizon   This value is returned when the current view is the « horizon » type (that is, nearest horizon at the bottom of the screen).

GetHSymmetry;

<value>;OK
Error;<error message>

This command lets you find out if the currently displayed map has horizontal symmetry (horizontal flip). Note that only maps of the « champ » type can have symmetry (can be flipped). The possible returned values are:

• True   The map is horizontally flipped.

• False   The map is not horizontally flipped.

• N/A   The map is not of the « field » type and cannot be flipped

GetVSymmetry;

<value>;OK
Error;<error message>

This command lets you find out if the currently displayed map has vertical symmetry (vertical flip). Note that only maps of the « champ » type can have symmetry (can be flipped). The possible returned values are:


• True   The map is vertically flipped

• False   The map is not vertically flipped.

• N/A   The map is not of the « field » type and cannot be flipped

GetRotation;

<value>;OK
Error;<error message>

This command lets you find out the rotation of the current C2A field. Note that only maps of the « field » type can have rotation (« horizon » type maps are always orientated such that the nearest horizon is at the bottom of the screen). The value returned is in degrees between -359.999 and 359.999. If the current map is « horizon » type, the value returned is N/A.

Quit;

<value>;OK
Error;<error message>

This command allows you to shut down C2A. All other commands in the same sequence are processed before the C2A session is terminated. If an error is encountered while processing these commands, C2A does not terminate.

 

Several commands can be sent at the same time through the TCP port. Just separate them with “;” (it is not necessary to have spaces between commands). When several commands are sent in the same TCP sequence, they are globally interpreted and validated before the corresponding actions are taken by C2A. If all the commands sent are correct, C2A returns a single « OK » response, possibly preceded by returned values in the same order as that in which the commands were sent. Returned values are separated by semicolons.

If a command is not recognised, C2A returns an error and no command in the initial sequence is interpreted.

Examples

The following command asks C2A to create a map with the following properties:

• The type of map is « field »;

• The centre of the map is at RA=12.7 hours and DE=43.2 degrees;

• The map has a field value of 1°x1°;

• Current local system time must be used to compute the map;

• The observing location is at latitude 43.2° north and longitude 1.5° east;

• The map is to have a horizontal flip and a 45° rotation (which is valid, as the map is of « field » type).

SetRa=12.7;SetDe=43.2;SetFieldX=1;SetFieldY=1;SetDateTime=currentLoc;SetLatitude=43.2;SetLongitude=1.5;SetMapType=field;SetHSymmetry=true;SetVSymmetry=false;SetRotation=45;

C2A then displays the map and returns

OK

The following command asks C2A to return all the properties of the current map:

getRa;getRaHms;getDe;getDeDms;getFieldX;getFieldXDms;getFieldY;getFieldYDms;getLatitude;getLatitudeDms;getLongitude;getLongitudeDms;getDeltaUTC;getMapType;getDateTimeUT;getDateTimeLocal;getHSymmetry;getVSymmetry;getRotation;

The values returned by C2A are concatenated into a single string of characters:

12.699722;12h41m59s;43.200000;43°12'00\";1.000000;01°00'00\";1.000000;01°00'00\";43.211111;43°12'40\";1.516111;1°30'58\";2;field;
04/10/2008 07:27:08;04/10/2008 09:27:08;true;false;45.000000;OK

Table of Contents