 |
QP
0.7-SNAPSHOT
Control software for the ??SRT telescope
|
|
QP
0.7-SNAPSHOT
Control software for the ??SRT telescope
|
This is a control program for the Glasgow University AR 1420 telescope.
Version qp 0.7-SNAPSHOT (6b2b6ddfce01 v0.7b2+7, 2017-07-18 17:57 +0100), released 2017 XXX XX.
The details below are provisional, and the interface will almost certainly change between releases, with no respect for backward compatibility before release 1.0.
The source code is on bitbucket.
The control program starts off with no memory of previous operations. It has a set of calibrations hard-coded into it which are approximately correct for the Glasgow observatory, but these are intended to be sane rather than accurate. The following procedure should be adopted by a user-facing control program operating this one.
Calibration. The command c starts a calibration run, which estimates the speed at which the axis motors can drive the telescope. At the end of this process, it prints out a line of the form >c n n. If this line, with these numbers, is supplied to the system at startup, instead of the bare c command, it will recreate the calculated calibration.
NOTE: this is probably not necessary, since release 0.6, since the scaling here is now handled completely by the Kalman filters on the two drives. Better than a calibration run, therefore, is to send the telescope to its home position (as below), and then 'warm up' the filters by slewing to two or three points about a radian apart. TBC.
T command.O command. This should happen after the time is set, in order to calculate local sidereal time correctly.gH. This should be done even though the calibration step leaves the telescope approximately in this position, since the action of homing the telescope also resets the system's internal state concerning the telescope's actual pointing.The controller is controlled by sending commands via the serial line, running at 115200 baud. Each of the commands consists of a one- or two-letter command followed by zero or more arguments, which may be letters, integers or floats, as appropriate; the commands are case-sensitive. Each line should be terminated by a newline (or carriage-return); blanks lines are ignored. The numbers should be separated from other arguments by spaces. Numbers which are required to be floats are required to have a decimal point. There is little error-checking.
The system returns a variety of status responses. These are either comma-separated values with a 'type' code in the first column (details to come), or else are generally human-readable responses, with the first character indicating the type of response.
#comments: Lines starting with a hash (#) are 'comments' – simple status updates. They are intended to be at least approximately human-readable, and the content is not guaranteed to be stable. These lines may also be cropped, if writing them to the output buffer would fill that buffer up and therefore require the processor to wait for the buffer to clear (non-comment lines are not cropped this way, even if this forces the processor to be idle).!errors: Lines starting with an exclamation mark are errors. The text after the exclamation mark is intended to be human-readable.>responses: Lines starting with a greater-than sign and a letter (>x) are responses from a particular command (see eg the c command below), and are supposed to be interpreted by the controlling program rather than presented to a user. The format of such lines is expected to be stable (eventually).comma,separated,values: Other lines consist of a comma-separated sequence of values. Each of these lines starts with a string label, az, alt, and so on, as described below.The available commands are as below. Some commands return confirmation of their action, and possibly some further information. Successful responses are those marked with ‘_Reply_’ below. All commands may additionally report comments as noted above. Commands may instead report an error as above, instead of a successful response.
c
Starts a calibration run. The result is stored internally.
Reply: The result is written back to the serial line in the form >c nnn nnn.
c float float ...
Allows the caller to specify pre-known calibration values. The line that should be supplied here is the line that was written back after a previous c call.
Reply: >c nnn nnn, echoing the arguments.
g ...
Go to positions indicated by coordinates, or one of a number of 'well-known' places, as indicated below.
If the telescope believes itself to be at one of the endstops, then it will print >g E az alt, where the az and alt are the coordinates of the current position in clicks (these coordinates may not be terribly useful). Detecting the endstop is unreliable – it depends on not detecting any click activity for a few seconds, when it expects some – so this signal should be treated with some scepticism. If it has reached the endstop, then the telescope's notion of its position has probably become unreliable.
gh az alt
Drive to the given horizontal coordinates, and stop. Both arguments are floats, in radians, giving azimuth (east from north) and altitude (north from horizontal).
Reply: When the telescope arrives at its destination, it prints the response >g A float float to the serial port, reporting the final azimuth and altitude in radians.
ge ra dec
Drive to the given equatorial coordinates (RA and Dec), and stop. Both coordinates are floats, in radians. Neither this control system, nor the telescope, are accurate enough that we have to worry about the epoch in which the coordinates are given.
Reply: When the telescope arrives at its destination, it prints the response >g A float float to the serial port, reporting the final azimuth and altitude in radians.
gH
Go to the 'home' position. This position is defined as the place where the telescope ends up if it is driven all the way to its easternmost end-stop, and all the way down. The actual azimuth and altitude of this point is calibrated using the O command.
This is effectively a ‘reset’ command for the system's notion of position.
After the telescope arrives at its home position, it updates its internal notion of the telescope's position with the calibrated coordinates of the home position as provided by the O command.
The telescope's reported position should not be regarded as reliable, between issuing this command and the telescope arriving at the home position and resetting.
Reply: >g E nnn nnn reporting that the telescope has reached its endstops, and... FIXME: this would more sensibly report angles, if those are available.
gU
Drive the telescope upwards, until the system reaches one of the end-stops, until it receives one of the other similar movement commands, or it receives the stop command x.
This command, and the corresponding down/east/west commands, should generally not be used for moving the telescope, since they are intended to be low-level commands. Instead, use the nu/d/e/w commands to nudge the telescope by small amounts.
Nonetheless, the telescope should retain an accurate notion of its position. If for some reason it does not, it can be reset by driving it home with gH.
If you use the gU command to drive the telescope over the zenith, it will produce an error, and the control software will probably have to be restarted.
These commands may be removed in future revisions of the software.
Reply: None.
gD
Drive the telescope downwards.
gE
Drive the telescope eastwards.
gW
Drive the telescope westwards.
nu [float]
Nudge the telescope up by a small amount, ‘delta’, given in radians. This command is equivalent to a gh command moving the telescope to a position ‘delta’ higher in altitude. If ‘delta’ is not provided, the default is 0.01 rad (about 0.5 deg; yes, giving an argument in degrees would be more convenient, but it seems best to be consistent in the argument type).
Reply: g A float float reports that the telescope has arrived, and notes its new current coordinates.
nd [float]
As with nu, but nudging the telescope down.
ne [float]
As with nu, but nudging the telescope east.
nw [float]
As with nu, but nudging the telescope west.
O lat lon dlat dlon az alt span
Gives the location of the telescope/observatory and the pointing of the 'home position'. The first two arguments are respectively observatory latitude and longitude, and the second two are deltas to that, to give the telescope effective latitude and longitude, taking into account misalignments of the telescope's axes. The fifth and sixth are the azimuth and altitude of the telescope's home position; this home position is the eastmost and most depressed position. The seventh argument is the (positive) total angle between the two azimuthal end-stops; thus the westmost endstop has azimuth equal to the home azimuth (argument 5) plus the span (argument 7), normalised to [0,2pi).
All arguments are floats, given in radians. The longitude is east-longitude, in [0, 2pi), and the telescope effective position is taken to be (lat+dlat, lon+dlon). The azimuth is in radians east of north, and the altitude in radians zenithwards from the horizontal.
Reply: none.
O
Queries the orientation coordinates.
Reply: Returns >O float float float float float float float, giving the current status of these values in the same form as the seven-argument command.
q
When an activity, such as a slew or tracking, is commanded, it immediately replaces any current activity. If the command q is given, then the next activity to be commanded will not replace the current one, but will be queued up behind it, and replace it when that activity is finished. The queue has a fixed maximum size, and if too many items are queued, the system will return an error (though this isn't fatal).
Reply: none.
S
Return status information, describing the controller's view of the world.
This is intended to be for overall status and calibration information. Routine status information should be read from the periodic status output in the s,... line.
Reply: returns a string in the form >S [key=val].... The Taz position is radians east of north.
s int
Change the status cadence to the given number of milliseconds. If this is changed to zero, then status messages are switched off.
Reply: none.
s char...
Adjust the status fields which are shown. The fields are selected for printing by a single character in the given list. The fields are always printed in the same order shown below, thus s za and s az both display the azimuth followed by the altitude (and nothing else). By default, only a selection of fields are shown, which are equivalent to the command s tzaCd.
The fields are as given below.
Reply: none.
T year mon day hour min sec
Set the current date-time. The first five are integers, the last is a float. The time is in UT.
Reply: none.
ts [speed]
DO NOT USE This command does not currently work.
Track a sidereal rotation. If no speed is provided, we rotate about the celestial pole at one sidereal day per solar day. If a speed is provided, it is a float, in rad/s clockwise about the celestial pole (sidereal rotation is 15'/min x 1.00274, or 7.2e-5 rad/s).
ta speed
Track in azimuth at the given speed, provided in rad/s, with positive meaning tracking in increasing azimuth; thus westwards.
NOTE: this function is under-tested, and it should probably not be used at present.
v
Display the version of the telescope control software.
Reply: The response is of the form >v integer string string. The integer is the version encoded as major*10000 + minor*100 + release (so version 1.2.34 would turn into 10234. The first string indicates the release status, and will be RELEASE if it's a formal versioned release. The second string is the repository revision hash.
x
Stop the telescope moving. This cancels the current activity, and de-queues any queued activity.
Reply: none.
X
Stow the telescope in the pointing-upright position. This cancels any other current and queued activities.
Reply: g A float float reports that it has arrived, and notes the new current coordinates.
The CSV status outputs from the running program are as follows (note that these are still rather unstable.
az,int,int,float,float,int
An azimuth click, which is produced each time the telescope drive produces a 'click' when it passes a reed switch. These happen every half degree. The columns are:
The azimuth and altitude should be accurate to less than half a degree, and are obtained as offsets from the calibrated coordinates of the home position. The azimuth in clicks is a running count of clicks, and so should differ by either +1 or -1 from the previously reported value.
alt,int,int,float,float,int
An altitude click, which is produced each time the telescope drive produces a 'click' when it passes a reed switch. These happen every half degree. The columns are as above, except that the final column is altitude (north of home position) in clicks.
s, flags, various...
Status: the status line is produced at a regular interval, and is intended to contain information about the current status of the telescope and its movements. This is distinct from the output of the S command, which includes some of this information, but is intended to be for overall status and calibration information.
The output flags is a hex value indicating what status fields are being output in the following columns.
The comma-separated columns are as documented for the s command above, and they appear in the order listed there.
As well as these commands, if the system detects an exclamation mark (!) in the input, then it regards this as a recoverable fault, clears the input buffer, and jumps to (and then immediately leaves) the fault handler. This is an 'emergency-stop' feature. The x command, in contrast, is handled as a normal command, and should be used in preference for 'normal' stop actions.
The set of commands, and their behaviour, is still somewhat in flux.
>g A float float, giving the final position; this adds the A to distinguish this from the (note unreliable) >g E ... message.g{U,D,E,W} commands. This does not guarantee that this will be true in future, nor that these commands will definitely be retained.n{u,d,e,w} commands; these should generally be used in place of the g{U,D,E,W} commands.ts) currently doesn't work. Highlighted in the documentation, but not disabled in the code.gh and ge commands now produce >g float float when they arrive at their destinatione and E to the 'status' indicators, to indicate estimated angular position errorgh). A commanded slew into the empty sector will be refused (with a ! error response), and slews will not go through the empty sector.#), which are now a lot terser. These lines may also be cropped, if writing them to the output buffer would fill that buffer up and therefore require the processor to wait for the buffer to clear (non-comment lines are not cropped this way, even if this forces the processor to be idle).X command to stow the telescope in the pointing-upright position.status output, and added fieldsv command.s, az and alt) now report position as radians in azimuth, not east-of-south.status output configurable with alternative s command.ge command, to drive to coordinates in RA-Decge, gw, gu, and gd to gE, gW, gU, and gD.gh arguments are now in radians rather than degrees (less intuitive but more consistent).q command, and support for queueing in activities.cpp. Added a further associated column to the loop() status output.Initial release
1.8.8