Generalized Serial Rotator Driver for Radio Eyes

version 1.0.9 Added ACK variable. Added WAITFORAZ and WAITFOREL parameters.
version 1.0.6 Changed default RTHRESHOLD to 1
version 1.0.4 Added TRACEFILE command for easier debugging.

The idea behind this driver is provide an interface to a custom designed rotator interface using an RS232 (com port) connection. The commands used to send AZ and EL antenna move requests and position reads to and from the antenna rotators are customizable through use of an initialization string. This string is part of the Telescope Definition File and is placed in the DEVICE INI textbox when using the Radio Eyes Telescope Definition Creator. This driver is likely to be used by someone who has created a rotator interface using a microcontroller to handle the low level operations of reading encoders, turning on motors, etc. There is simple emulator available for you to test with documented at the bottom of this page.

The picture above shows a typical definition for a telescope using the generalized Serial Rotator Driver. The Device INI box is full of special initialization commands, each separated by a pipe symbol | . While it looks rather cumbersome, it is not too difficult create this initialization string in a text editor. Depending upon your needs you may be able to omit many of the options in the string. Below is a list of each of the setting options that may be included in the string. In practice, you would place the option name, an equals sign, and the desired value for the setting followed by the pipe symbol. Option names are all capitalized.

Communication Port Setup Options

COMPORT - The com port number used on the computer to communicate with the device. Example COMPORT = 2

SETTINGS - A string representing the baud rate, parity, number of data bits, and number of stop bits. Each of these parameters is separated by an underscore character ( _ ) Example: SETTINGS = 1200_N_8_1. The default value is 9600_N_8_1

OUTBUFFERSIZE - The number of characters in the comport output buffer. Probably OK at the default value of 512.

INBUFFERSIZE - The number of characters in the comport input buffer. Probably OK at the default of 1024.

RTHRESHOLD - Receive threshold number of characters. By default this value is set to 1 (driver version 1.0.6 and later) and thus any number of characters received will trigger the driver to process the characters it has received from the external device. If the value is set to 2 or more then no processing of the incoming characters occurs until the that number of characters has been received from the device. Probably best to just use the default.

STHRESHOLD - Probably best to leave at the default of 0.

COMHANDSHAKING - This value determines the type of handshaking that occurs between the computer and the RS232 device. The following values are possible:

Value	Description
0	(Default) No handshaking.
1	XON/XOFF handshaking.
2	RTS/CTS (Request To Send/Clear To Send) handshaking.
3	Both Request To Send and XON/XOFF handshaking.

Message Formats

Notice that many of the configurable options end with either PRE or POST. These are hints to the function of these options which are all used to mark the beginning and ending respectively of data messages to and from the rotator controller. A message from the controller to the PC might be:

Controller -> AZPRE + AZIMUTH + AZPOST -> PC

Here the AZPRE and AZPOST parts of the message would be replaced by whatever you define for these options. AZIMUTH would be replaced by the value for the azimuth position read by the rotator. The format for a message from the PC to the controller might be:

PC -> SELPRE + ELEVATION + SELPOST -> Controller

This command would tell the controller to move the antenna to a given ELEVATION. Notice that the start and stop markers for this command begin with S. This S prefixes all AZ and EL commands sent from the PC to the controller.

The actual format of the AZIMUTH and ELEVATION parts of the message can take 3 possible forms:

Two byte binary with the LSB sent first (designated bB).
Two byte binary with the MSB sent first (designated Bb).
Ordinary string representing the decimal value.

You specify the format you want to use with AZFORMAT, ELFORMAT, SAZFORMAT, and SELFORMAT options. The string format for the decimal representation can be optioned using a format string compatible with Visual BASIC. Examples:

AZFORMAT = 000.00 would always return six numbers. If the azimuth was 27.2, the controller would write 027.20 in its message to the PC. If the decimal point is present in the format string it is used in the sent string.
SELFORMAT = #0 could be either one or two characters long. The # sign means do not put a zero here if you don't have to. So the PC could send 36 or 8 for elevation values, for example.

In some cases the controller may send an acknowledgement to the PC that it has received a command. For example, the PC sends a move command to the controller and the controller sends back a CHR(13). This is the case with the Yaesu GS232 controller. In this case you would define the ACK value (below) to be CHR(13).

Custom Equations

Prior to formatting, the data part of the azimuth or elevation message may optionally be acted upon by a user defined equation. This can greatly simplify the rotator control internal coding in some cases. The equations are defined in strings in the AZEQUATION, ELEQUATION, SAZEQUATION, and SELEQUATION message options. The equation is applied by the driver and so obviously always takes place in the PC. In the case of data being sent from the PC to the controller the equation is applied to either the desired azimuth or elevation. Then the result is formatted using the SAZFORMAT or SELFORMAT options as appropriate. This is then packaged up in the start and stop markers and sent to the controller.

New Azimuth (256.7) -> SAZEQUATION (AZIMUTH*10) -> 2567 -> SAZFORMAT(bB) -> CHR(7)+CHR(10) -> SAZPRE+CHR(7)+CHR(10)+SAZPOST -> Controller

In the above example, Radio Eyes (via the TCPP) requests a new azimuth of 256.7 degrees. The generalized serial rotator driver applies the user defined equation of AZIMUTH*10 and the result is 2567. The format required by our controller is bB, that is, two bytes binary with the least significant byte sent first. The driver determines that this would be satisfied by sending the bytes CHR(7)+CHR(10) . It then adds the user defined prefix and suffix markers, SAZPRE and SAZPOST and passes on the result to the controller.

The equation parser is the same one used in the Radio-SkyPipe data collection program. It acts upon the variable AZIMUTH or ELEVATION , all caps. A complete list of available commands for the equation parser can be found here.

When AZEQUATION or ELEQUATION are used they are applied to the azimuth or elevation readings passed back from the controller to the PC. The equation is applied after the message from the controller has been read according to the AZFORMAT or ELFORMAT definitions.

Leave the equation options blank if you do not want to apply an equation.

Message Options

Note: In some cases, you may want to supply values that include un-typeable characters, the space character, or even the pipe symbol itself. You must then supply the character by its ASCII value within square brackets, and proceeded by the letters CHR. For example, the ASCII value for the space character is 32, and you could indicate it by CHR[32] .

ACK - Define this value if you expect an acknowledgement character or phrase from the controller after issuing a move or stop command. The acknowledgement is usually disgarded, however it will be reported in a tracefile if one is being kept. If the ACK is also part of a position (AZ or EL) returned by the controller it should be handled as part of the AZPOST or ELPOST options.

AZPRE - Prefix to azimuth value reported by the controller to the PC. This would include any characters preceding the azimuth value. For example, if your device reported the azimuth preceded by the characters 'AZ: ' then you would use AZPRE = AZ: . Your device will almost always use a prefix for such reports to indicate the nature of the value being sent to the PC.

AZPOST - Suffix added to the reported azimuth. For example: AZPOST = CHR[13] would indicate that the device used the carriage return character after reported in azimuth. Most devices will use a suffix like this to indicate the end of the parameter has been sent

ELPRE - Prefix to elevation value reported by the controller to the PC. This would include any characters preceding the azimuth value. For example, if your device reported the azimuth preceded by the characters 'EL: ' then you would use ELPRE = EL:

ELPOST - Suffix added to the reported azimuth. For example: ELPOST = CHR[13] would indicate that the device used the carriage return character after reported in azimuth.

LIMITPRE - Prefix to limit switch value reported by the controller to the PC.

LIMITPOST- Suffix added to the limit switch change reported to the PC.

AZFORMAT - Format string that determines how the azimuth position is sent to the PC. This will be bB, Bb, or a numeric format string as described above.

ELFORMAT- Format string that determines how the elevation position is sent to the PC. This will be bB, Bb, or a numeric format string as described above.

AZEQUATION - Equation string that represents a mathematical function applied to the azimuth after it is read from the controller.

ELEQUATION- Equation string that represents a mathematical function applied to the elevation after it is read from the controller.

WAITFORAZ - Number of milliseconds the driver should wait for the azimuth to be reported by the controller after the PC has requested an azimuth report from the controller. If this value is set greater than zero then the driver will pause until the azimuth is reported or the number of milliseconds specified has elapsed.

WAITFOREL - Number of milliseconds the driver should wait for the elevation to be reported by the controller after the PC has requested an elevation report from the controller. If this value is set greater than zero then the driver will pause until the elevation is reported or the number of milliseconds specified has elapsed.

SAZPRE - Prefix to 'move to' azimuth value sent from the PC to the controller. This would include any characters preceding the azimuth value. For example, if your device reported the azimuth preceded by the characters 'AZ: ' then you would use SAZPRE = AZ: .

SAZPOST - Suffix added to the requested azimuth position sent from the PC to the controller. For example: SAZPOST = CHR[13] would indicate that the PC uses the carriage return character after a requested azimuth.

SELPRE - Prefix to 'move to' elevation value sent from the PC to the controller. This would include any characters preceding the elevation value. For example, if the PC requests the new elevation preceded by the characters 'GOTOEL: ' then you would use SELPRE = GOTOEL: .

SELPOST- Suffix added to the requested elevation position sent from the PC to the controller. For example: SELPOST = CHR[13] would indicate that the PC uses the carriage return character after a requested elevation.

SSTOP - The entire stop command that is sent from the PC to the controller to stop antenna movement.

SAZFORMAT - Format string that determines how the azimuth position is sent to the controller from the PC. This will be bB, Bb, or a numeric format string as described above.

SELFORMAT- Format string that determines how the elevation position is sent to the controller from the PC. This will be bB, Bb, or a numeric format string as described above.

SAZEQUATION - Equation string that represents a mathematical function applied to the azimuth prior to sending it to the controller.

SELEQUATION- Equation string that represents a mathematical function applied to the elevation prior to sending it to the controller.

SREADAZ - Complete command for requesting a read of the azimuth from the controller.

SREADEL - Complete command for requesting a read of the elevation from the controller.

SRESET - Complete command for requesting a reset or initialization procedure of the controller. The PC only sends this command once (if it is defined) when the initial communication connection is made from the driver in the PC to the controller.

TRACEFILE - Set = to a filename. If you use the substring [DATE] in the file name it will be replaced by YYMMDDHHMMSS formatted date/time (local) . When this command is used the commands sent by and received by the comport will be saved in the trace file. This should make it much easier to debug problems. The trace file will be automatically placed in DriverLog subdirectory of the TelescopeDrivers directory (where the Serial_Rotator_Driver.exe file is located). Only the filename should be specified. The path must be to this subdirectory so do not include the path in the filename. For example you might use TRACEFILE = LOG[DATE].txt

A Simple Serial Rotator Emulator for Testing

RE_Serial_Test is a program that can emulate an actual serial antenna controller. This program can be placed on a second computer and connected to the computer running the Control Point via a null modem cable. A null modem cable flips the transmit and receive lines between ends of the cable so that two computers can communicate over a RS232 serial cable. We are using the option for no handshaking between computers to simplify the connection.

You may have trouble finding a suitable cable but can easily make one using a couple of female DB-9 connectors and some shielded cable with at least three conductors. Affix the shield to the DB-9 shell casing and the conductors as shown in the diagram above.

The TCPP is run on one computer and the telescope definition file Serial_A.TDF is loaded into the TCPP using File / Load Telescope. This file is provided in the RE_Serial_Test program installation and you will have to copy it to the Telescope Definitions directory on your TCPP computer so that the TCPP can find it. You may have to change the com port in the ini file if it is not on Com 1. You can do this also from the TCPP by using File / Edit-Create Telescope and modifying the Device Ini section. Below is a copy of the device ini section that is used in this telescope definition.

Install and run the RE_Serial_Test program on the second computer. Select the appropriate com port for that computer using the menu. The program has a very simple interface as shown below.

Changes to the values in the Requested ALT and AZ boxes causes the values in the Actual ALT and AZ boxes to migrate to these new values. The Jump To button just causes this to happen instantly. New ALT and AZ values arriving through the com port are shown in the status bar along with any control characters as the data arrives. The only other command that is recognized in this simple tester is the HALT command. When you load the Serial_A telescope definition in the TCPP it should connect to the RE_Serial_Test program and the Actual AZ and EL boxes in the TCPP should change to reflect the AZ and EL boxes in the RE_Serial_Test program. To change the positions from the TCPP do a Manual Move or set up a connection to Radio Eyes.

Note to Programmers

This little program is written in VB6. The complete source code accompanies the RE_Serial_Test program installation. You can modify this in any way you feel helps you. If you come up with a better emulator (perhaps with limits and/or a better display) please let me know and we will post it for others. All of the parsing of the incoming commands is done through On_Comm event. A receive threshold of 1 (RTHRESHOLD) is required for this event to fire.