Version 0.2 Rough initial draft January 1996
Version 0.3 Next draft March 1996
Version 1.0 First official version May 1996
Version 2.0 After major software upgrade August 1996
1.2 Introduction to the Autofib-2 control system
1.3 Starting the Autofib-2 control system
1.4 Stopping the Autofib-2 control system
2.2 Setting up the data modules
2.3 Read task
2.4 Write task
2.5 Receive task
2.6 Watchdog task
3.2 Command interpreter
3.3 Main control task
3.4 Software flags
3.5 Command and mechanism error codes
3.6 Hard coded variables
4.2 Engineering mimic
4.3 Engineering user interface
5.2 File formats
6.2 Network layer tools
6.3 Application layer tools
7.2 Restoring the OS/9 hard disk
8.2 Network layer
8.3 Application layer
8.4 Engineering interface
8.5 Other software tools
9.2 Setting up internet numbers
9.3 Updating emergency floppy disks
10.2 Command interpreter task dying
10.3 Accessing hardware from two points
10.4 Corruption of network messages
10.5 Poor centroiding on guide fibres
10.6 Failure to detect missing fibres
10.7 Make fails when rebuilding code
10.8 FTP file transfer failure
10.9 Note on monitormode
Appendix B Data format within OS/9 data modules
Appendix C Network message description
The instrument control system runs on a VME based microcomputer running the OS/9 operating system. The control system is programmed exclusively in the C programming langauage using software libraries provided as part of the C compiler and those supplied with various parts of the VME hardware. In addition to this manual the reader should consult the following manuals:
TP32V cpu board hardware manual
DMC300 motion control card hardware manual
BVME780 framegrabber hardware manual
RAVE software library manual
OS/9 Operating system manual
OS/9 Technical manual
OS/9 C compiler manual
TCP/IP software manual
Greenspring Industry Pack carrier manual
Greenspring ADC Industry Pack manual
Greenspring Digital IO Industry Pack manual
1.1 Introduction to OS/9
OS/9 is a multi tasking multi user operating system. In many respects OS/9 is similar to UNIX but with slightly different command names. On powering up the VME rack the OS/9 system will automatically boot from either the hard disk or a floppy disk (switchable). By default a TCP/IP telnet and ftp service is started, but the Autofib-2 control system is not started as this should be done manually (see section 1.3).
On booting, the computer automatically runs a script file called startup in the /h0 directory. This file contains all of the required system startup procedures, for instance it initialises a RAM disk and loads various device drivers and managers into memory and starts the TCP/IP software running. As a last step this file starts off a terminal monitor (tsmon) which monitors various serial ports (currently /term and /t2) for active input. Note that the serial port /t1 is reserved for use by the Sension Network Interface Unit.
Four manuals are available from Microware for OS/9, an operating system manual, a technical reference manual, a TCP/IP reference manual and a C languauge reference manual. These manuals are contained in two dark grey ring binders. Also included in the grey ring binders is the RAVE software manual.
Two user accounts are defined on the OS/9 system, the usernames are Autofib and System, these are not case sensitive. Each account has its own root directory and unique prompt set up in the password file in the /h0/sys directory. Access to the startup and password files is available only from the system account. Executable code for the operating system commands is kept in the /h0/cmds directory.
Two editors based on emacs are available on the OS/9 system, umacs and microemacs, umacs comes packaged with the OS/9 operating system and documentation is provided in the operating system documentation but this editor does not allow for the use of the cursor keys on the VT420 terminal provided with Autofib, the microemacs editor is perferred for this reason. Microemacs may be invoked by typing me[return] or by typing me filename[return]. The cursor keys allow easy movement within the file and most of the standard keypad keys have functions assigned to them (see figure 1).
Ascii files may be printed via the print device /lpt1. This is a centronix parallel printer that may be connected to the 25 way D type connector on the rear of the VME crate using the cable supplied for this purpose. The command to print a file (for example test.c) is:
pr -t -h=0 test.c >/lpt1&[return]
The -t option prevents the file name being printed at the top of each page and the -h option sets the page header to zero lines. The output must be explicitly redirected to the print device and unless you are willing to wait a while, the process should be run in background (&).
1.2 Introduction to the AUTOFIB-2 Control System
Access to the Autofib-2 control system is normally from the AUTOFIB account on the micro computer, one other account exists, SYSTEM which should only be used for system maintenance and backup purposes. Autofib control system code development should be done from the Autofib account to avoid the possibility of executable images or source code belonging to the System account and unusable from the normal Autofib account.
The Autofib-2 control system consists of a number of tasks running in the background on the instrument micro computer. Four tasks provide the Utility Network interface between the instrument and the outside world. Two tasks provide for instrument status reporting and control. One task provides an engineering mimic display, a final task which is only started when necessary is the engineering control interface.
Communication between the various tasks is by two methods, software interrupts allow immediate passing of information between tasks, in OS/9 these are called signals. The majority of information is passed through shared memory (called data modules) between tasks. To avoid simultaneous accessing of the shared memory, the tasks check a semaphore value called an event to check that the memory resource is free. The format of the information in the shared memory areas is given in Appendix B. Further information on events, signals and data modules may be found in the OS/9 technical reference manual.
1.3 Starting the AUTOFIB-2 Control System
Reboot the computer to ensure all of the hardware is completely reset, not doing this may mean that the software will not function correctly and parts of the system may crash. After logging in on the AUTOFIB account type:
startall [return]
This sets up all of the shared memory and starts all the control system processes up in the correct order. Startall is simply a batch file which in turn executes two other batch files in the Autofib root directory, these files are called startnet and startapp for starting the network layer and application layer respectively.
By default the output from the various processes is redirected to the nil device. If output from the various print statements is required then the startup batch files may be edited to redirect the output to the printer device and the printer connected. For example the startapp batch file contains the line
cmd_intrp>>>/nil&
which serves to start the cmd_intrp process running in background at priority 128 (by default) with standard output and error output redirected to the nil device. Editing this line to give
cmd_intrp>>>/lpt1&
will start the same process running in background with output redirected to the printer (which must be connected and switched on to avoid crashing or hanging the micro computer).
After starting the control system running, a list of the processes running may be displayed by typing:
procs [return]
the following processes should be present:
control - main control task
cmdintrp - command interpreter
read - network layer read task
receive - network layer receive task
write - network layer write task
watchdog - network layer watchdog task
esdrave - engineering mimic
shell - command line shell
procs - procs process displaying the information
If any processes are missing it is likely that a problem has occurred and the system should be rebooted and checked over before attempting to restart the control system. These are only the processes belonging to the Autofib account, a more complete list of the processes running on the micro computer may be obtained by typing
procs -e[return]
which will show a full list of the Autofib and System processes.
1.4 Stopping the Autofib-2 control system
From the OS/9 prompt type:
stopall [return]
This stops all the processes in the correct order and tidies up the shared memory. Stopall is simply a batch file which in turn executes two other batch files in the Autofib root directory, these files are called stopnet and stopapp for stopping the network and application layers respectively. These batch files call a series of programs in the correct order to kill individual tasks. It is not sufficient to kill a process as this will leave data modules, events and signals in rather a messy state, therefore each task has a termination program which tidies up the system interfaces as well as killing the task.
Note that the micro computer should be rebooted before restarting the control system particularly if the micro is connected to a Sension Network Interface Unit (NIU).
The network layer software has been written from scratch to provide the functionality required by the Utility Network protocols (WHT-ER412 V1.0). Reading and writing of network messages is performed over a serial line (device /t1) allowing simple connection to a Sension Network Interface Unit (NIU).
Network messages are passed between the various tasks in a series of fifo tables. These tables are stored in shared memory using the OS/9 concept of data modules. The required data modules and semaphore events are set up by a program called table.c which is executed before the main network layer tasks are started.
Data modules are protected areas of memory which may be accessed by a program using simple OS/9 C library functions. In the source code provided as part of the network and application layers this access is wrapped up as part of a series of simple functions to prevent two programs accessing the same data modules simultaneously using semaphores. Also provided are simple functions to inquire the size of the fifo queue, to add a message to the queue and remove the oldest message from the queue.
The relationship between the various network layer tasks and datamodules and the data flow is shown in figure 2.
2.2 Setting up data modules
The startnet batch file runs a program called table to create the various areas of shared memory (data modules) and semaphore events associated with the data modules. The source code for this program is contained within table.c in the /h0/autofib/network directory.
The table program creates a total of 13 datamodules, most of which are fifo queues, a few a simple lists of information and one is a random access list. For each data module the table program has to create the data module, create an event to act as a semaphore for the data module set certain information within the data module. For the fifo queue based data modules the pointer to the next free space is set to 1 and the queue length is set to 0. For the list based data modules all the information values are simply set to zero and for the random access datamodule the queue size is set to zero and all the records are set to be empty.
The data modules created by the table program are given in the table below.
TABLE..........................TYPE.................................INITIALISATION
RTABLE.........................FIFO..................................Set pointer to first freee element to 1 and size to 0
RBUFFER......................FIFO..................................Set pointer to first freee element to 1 and size to 0
ATABLE........................FIFO..................................Set pointer to first freee element to 1 and size to 0
MTABLE........................FIFO..................................Set pointer to first freee element to 1 and size to 0
TLOGTABLE................FIFO..................................Set pointer to first freee element to 1 and size to 0
ERTABLE.......................FIFO..................................Set pointer to first freee element to 1 and size to 0
ETTABLE......................FIFO..................................Set pointer to first freee element to 1 and size to 0
COMMANDQ..............FIFO..................................Set pointer to first freee element to 1 and size to 0
AF2_STATUS................LIST...................................Zero all values
PROCDATA..................LIST...................................Put system time in first element
NET_DIAGNOSTICS....RANDOM.........................Set queue size to 0 and set all elements to be free
2.3 Read task
The source code for the read task is in the file read.c in the /h0/autofib/network directory.
The read task is responsible for reading in the messages as they arrive in the RS232 buffer from the serial line, doing some initial processing then placing the assembled message in an output buffer (RBUFFER) for further processing by the receive task.
On execution the read task starts by setting up various once only parameters. These include setting up a software interrupt handler, linking to various datamodules required for later operation and setting up a watchdog alarm to trigger watchdog signals. The process also links to two data modules called RBUFFER and NET_DIAGNOSTICS. RBUFFER is a fifo queue for the network messages received by the read task, NET_DIAGNOSTICS is a simple list of integer values used as counters for various errors that may occur within the network layer.
After the inital setting up of parameters the read task enters a loop which is only terminated if a test flag is set by the process receiving a terminate signal. During the loop the task performs the following operations:
1. Beginning of loop, test if terminate signal has been received
2. If no characters are waiting to be read from the serial buffer then sleep for 10 system ticks (1 tick is 1/200 second) then reenter loop.
3. If characters are waiting to be read, then read a single character from the serial buffer, act on the character depending on its type.
4. Go back to beginning of loop.
When the read task receives a terminate signal the endless loop is broken and the read task tidies up its data module and serial port access before ending safely.
The various actions performed by the read task depend on the type of character read in from the serial buffer as follows:
SYN (control V) Clear message buffer, reset counters, if currently in the middle of receiving a message record a NOT_EXPECTING_SYN error.
EOT (control D) Check that the first character in the message buffer is a SYN, if
not then record a NOT_EXPECTED_EOT error. Check the size of the RBUFFER queue, if there is room for a message then strip the SYN and EOT and add the message to the queue, else record a RBUFFER_FULL error and ignore the message.
XON (control Q) If last received control flow character was a XOFF then tell write task to start transmitting characters else ignore this character.
XOFF (control S) If the last received control flow character was a XON then tell write task to stop transmitting characters else ignore this character.
Other character Check if the character is printable or carriage return or linefeed, if not ignore the character and increment error counter for not allowed characters. If allowed then add character to message buffer and increment buffer position counter.
2.4 Write task
The source code for the write task is in the write.c file in the /h0/autofib/network directory.
The write task is responsible for determining which messages are to be sent over the utility network and transmitting them at the correct time as a string of single characters from the serial port (/t1).
The write task accesses four OS/9 data modules for the passing of information between processes and the outside world. One of these data modules (NET_DIAGNOSTICS) is shared between the three network layer tasks for storing diagnostic information about various error conditions that may have occured. Two other data modules (ATABLE and TTABLE) contain lists of acknowledgements and message responses waiting to be transmitted, see figure 2 for the relationship between the various tasks and the data modules. ATABLE is a simple fifo queue of the acknowledgements waiting to be transmitted. TTABLE is a more complicated random access list with entries containing such information as the number of times a message has to be transmitted, the time of next transmission as well as the message itself. The format of this data stored within TTABLE is fully described in Appendix B. The final data module is only accessed when the write task starts up, PROCDATA contains a series of character strings, the first is a zero reference time required by the write and receive tasks, subsequent entries are the process identification numbers of the various processes in the control system, this allows another process to enquire the identification numbers in order to send a terminate signal to the correct processes when it is required to shut down the control system.
On execution the write task initially sets up various required parameters and access permissions, these include installing a signal handler, adding its process identification and getting a zero date from shared memory, linking to the three data modules, setting up write access to the serial port and initialising various counters. The process enters a loop which is only terminated if the process receives a terminate signal. In the loop the process performs the following steps:
1. Start of loop, check if the loop has been terminated.
2. Calculate time since last control flow character (XCHAR) was sent, if necessary send the current XCHAR and update the time of sending the last XCHAR.
3. If transmission is currently enabled (i.e. no XOFF characters have been received) and if current in the middle of sending a message then write the next character in the message to the serial port and increment the message string character. If this is the last character of the message then set a flag to indicate that the process is no longer transmitting a message. Go to the end of the loop (step 7).
4. If transmission is currently enabled but no message is currently being sent then look for a message to send. First check if any acknowledgements are waiting to be sent in ATABLE as acknowledgements to received messages have priority over messages waiting to be transmitted. If there are acknowledgements waiting, remove the oldest from ATABLE, make this acknowledgement the current message for transmission, zero various counters and set a flag to indicate that the process is currently sending a message and go to step 7. If no acknowledgements are waiting to be transmitted (ATABLE is empty), then look for a message to transmit in TTABLE, if a message is ready to send, extract the message from TTABLE, zero various counters , set a flag to indicate that the process is transmitting a message and go to step 7.
5. If there are no acknowledgements or messages waiting to be transmitted the sleep for 10 system ticks.
6. If transmission is disabled then sleep for 10 system ticks.
7. End of loop
If the process exits the main loop then a terminate signal has been received and the process tidies up access to the various data modules and serial port before terminating safely.
The procedure for finding out if there is a message waiting to be transmitted in TTABLE is more complicated than for a simple fifo queue as it involves messages which may have to be sent more than once at a specified interval, therefore this procedure is now briefly described. The code for this procedure is contained in the find_entry() function in the write.c source code file.
The purpose of find_entry() is to maintain a data module called TTABLE, this involves removing old messages and keeping messages that have not yet been acknowledged up to date and putting them up for retransmission at the correct interval. The two standard header items at the beginning of the data module, the pointer to the first free entry and the number of messages currently in the data module are present but only the number of messages in the data module (or size entry) is used as this data module is not accessed in a fifo manner. Find_entry performs the following steps:
1. On being called from the main write task loop the find_entry function checks the size of TTABLE, if it is zero then no messages are waiting to be sent and the function returns to the main loop.
2. If the size of TTABLE is non zero then there are possibly messages waiting to be sent, first the function checks all the messages in the data module to see if they are acknowledged messages, if so they are removed from the data module and size is decremented.
3. If size is zero then no messages are waiting to be sent and the function returns to the main loop.
4. Find_entry has now determined that messages are waiting to be sent so it loops through all the entries in the data module looking for a message to send, the first message it finds will be the next message sent. A message will be considered ready for sending if either it has never been transmitted before, or if it has been transmitted before then the time of next transmission for that message has been reached.
5. Set gotmessage flag to False.
6. Loop through all the entries in the data module, check if gotmessage flag is False.
7.If a message is present in the current entry, get the message status, time of next transmission and number of transmissions left.
8. If the message status is zero, then the message has never been transmitted before. Assign a message identification number, check all the message data fields, decrement the number of transmissions left, set message status to unity, set time of next transmission to the current time plus the retry delay, copy the message in the correct format to a message buffer and log the message that is to be transmissed in TLOG_TABLE. Finally set the gotmessage flag to TRUE and go to the end of the loop.
9. If the message status is unity, the message has been transmitted but not acknowledged yet. If the number of transmissions left is zero then remove the message, set the message flag to zero and decrement size.
10. If the time of next transmission is smaller than the current time then it is time to retransmit the message, so reset the time of next transmission, decrement the number of transmissions left, copy the message in correct form to the message buffer and set gotmessage flag to True, go to the end of the loop.
11. End of loop through the data module entries.
12. Return message buffer to calling task with status flag to indicate if the search for a message to transmit was successful.
2.5 Receive task
The receive tasks job is to remove the incoming meesages from RBUFFER, process them and if necessary place the processed message in RTABLE for the application layer to deal with. The source code for the receive task is in receive.c in the /h0/autofib/network directory.
The receive task accesses the following data modules:
RTABLE, RBUFFER, ATABLE, TTABLE, MTABLE, NET_DIAGNOSTICS and RLOG_TABLE.
RTABLE, RBUFFER, ATABLE, MTABLE and RLOG_TABLE are all operated as fifo lists, TTABLE is a random access list and NET_DIAGNOSTICS is a simple list of counter values. The relationship between the receive task and the various data modules is shown in figure 2.
On execution of the receive task various parameters are initially set up, these include installing a signal handler, setting up access to all of the required data modules, creating a watchdog alarm and placing the receive tasks process identification number in the PROCDATA data module while obtaining the process identification numbers of the write and watchdog tasks.
As with the other tasks in the network layer the receive task spends most of its time in a loop which is only broken if the task is sent a terminate signal. On entering the loop the following steps are performed:
1. Start of loop, test if a terminate signal has been received
2. If RTABLE is currently full, sleep for 10 ticks to allow the application layer to empty RTABLE then go step 9.
3. If RBUFFER contains any messages, extract the oldest message, else go to step 9.
4. Check the header infomation in the extracted message.
5. Decode the message source, destination, id number, type and the individual commands (upto three commands within the message).
6. If the message is an acknowledgement then remove the acknowledged message from TTABLE and go to step 9.
7. If message is not a broadcast message, create an acknowledgement string and add it to ATABLE for transmission.
8. Check in MTABLE to see if the message has been received before, if it has not been received before then write the message in a slightly different format to RTABLE for the application layer to deal with and copy the message to RLOG_TABLE which provides a log of the last 20 received messages.
9. End of loop.
2.6 Watchdog task
The watchdog task monitors the activity of the other three network layer tasks and if any one of the tasks appears to be missing it will safely bring down the complete network layer. Unfortunately this does cause problems with the application layer. The origin of this task lies in the early unreliability of the network layer, however this has now largely been solved.
As originally conceived the watchdog task would also monitor the application layer and tidy this up safely in the event of a problem but this has not been implemented as it may not always be advisable to kill the control task when it is busy moving fibres in the event of a network layer crash.
Each task in the network layer picks up the process identification number of the watchdog task and also sets up an alarm to trigger the process to send a signal to the watchdog process every few seconds. The watchdog task counts the signals it has received and if one task's counter gets out of step with those of the other processes then it is assumed that the process has died and the watchdog process shuts down the remaining processes and tidies up the data modules and events.
The application layer processes and acts upon all incoming messages to the control system whether from the engineering interface or the utility network layer. It consists of two tasks, a command interpreter and a control task. Copies of instrument status parameters are kept as a fixed format list in a data module (AF2_STATUS) accessed by the command intrpreter, main control and the engineering interface tasks. The relation ship between the tasks and the data modules is shown in figure 3.
3.2 Command interpreter task
The command interpreter task identifies and preprocesses all incoming messages from both the engineering interface and the network layer. By providing this common task for both sets of incoming messages the control task is made independent of the source of the message. The command interpreter selects between the two sources of messages. Messages from the currently selected source are processed normally, messages from the other source are rejected with a command error. The two currently recognised command sources are LOCAL (engineering interface) and REMOTE (command from Utility Network).
Incoming messages group broadly into five types:
ISTAT or type 200, an immediate status request to the micro computer,
DSTAT or type 201, a delayed status request to the micro computer,
MOVE or type 101, an action request to the micro computer,
STOP or type 100, a immediate stop command to the micro computer,
INIT or type 102, an initialise request to the micro computer.
In general commands to the micro computer will consist of groups of three messages arriving together, for instance, PRO101(0) PRO200 PRO201 is a command to move the off axis probe to position 0 and provide immediate and delayed status reponses. The group of three messages will be processed as three separate messages working from left to right.
The command interpreter task handles the different types of commands in the following ways. ISTAT commands are always processed and replied to by the sending of the appropriate response (type 800). Information for the status responses is obtained from shared memory which is kept up to date by the main control task.
MOVE, INIT and STOP commands will be checked for command errors and if the contain no errors they will be passed on to the control task via a fifo message queue. If the message does not come from the currently selected source this is interpreted as a command error and the message gets no further. The command error will be reported by the ISTAT following the MOVE,INIT or STOP message.
DSTAT commands will only be passed onto the control task to be processed if the message comes from the currently selected source.
There are a few exceptions to the above rules, most notably MOVE, ISTAT and DSTAT messages connected with the command source mechanism (SRC) which are all dealt with entirely by the command interpreter. This mechanism provides a means to change the currently selected command source and must obviously work even when the wrong command source is selected. Also STOP commands (only one exists at the moment) are identified by the command interpreter and a software interrupt sent to the main control task for immediate action thus bypassing the normal message queue.
3.3 Main Control task
All messages not dealt with by the command interpreter are queued to the main control task. This task deals with each command in turn (with the exception of the STOP command mentioned above). This inability to operate on messages simultaneously is not a problem as the robot is only capable or performing one action at a time.
Each message is extracted from the command queue, identified and its parameters checked, then the required action or response is made before proceeding to the next message in the queue. If no messages are waiting, then the control task simply updates all of the instrument status parameters then sleeps for a short while before checking again if any messages are waiting.
It is the main control task that performs all control of the AUTOFIB-2 robot hardware and maintains the memory copy of the instrument status in the AF2_STATUS datamodule which is accessed by the command interpreter and control tasks to answer ISTAT and DSTAT requests. The main control task is also responsible for all error checking and the software interlocks that prevent the user from damaging the hardware.
On receipt of an INIT or MOVE message the mechanism is identified and the appropriate function called to deal with an action on that mechanism as indicated in the tables below.
INIT (102) Function called Location of messages source code PRO probe_init probe.c ROB robot_init robot.c
MOVE (101) messages POW af2_state power.c LGT af2_inspect status.c BCK af2_backillum status.c LOG af2_logresults status.c CON af2_setupfield setup.c MON af2_monitor status.c PRO moveprobe probe.c ROB af2_robot robot.c RES af2_reset status.c FIB af2_fibstatus status.c SER af2_setservo status.c ESD af2_esd status.c CEN af2_centroid tvstuff.c VID af2_setvid tvstuff.c
These functions then decode the parameters of the message and process them. If the command is unable to be processed due to an instrument safety conflict a mechanism error will be set and the command ignored. If the robot is able to process the command it will start to do so immediately, there is no means to specify execution of commands at a specific time. If an error occurs during execution of a command it will set a mechanism error for that mechanism and terminate processing immediately.
On completion of processing an action command (successfully or not) the next message in the command queue is extracted and processed. If the next command is prevented by a previous error condition this will be reported by a unique mechanism error to indicate this situation. An example of this would be the LOSTFIBRE error which indicates that a previously lost fibre means that the robot is currently unable to move any further fibres.
On receipt of a DSTAT request the control task identifies the mechanism and extracts the required information from the AF2_STATUS datamodule. If a previous MOVE or INIT has left a mechanism error flagged the DSTAT respnse is the means by which this will be reported back to the controlling dtask.
If monitor mode is enables for any nodes on the utility network system then in addition to sending status responses (800,801) to any ISTAT or DSTAT requests intermediate resposnes are sent at the beginning of an action (803) and on completion of an action request (804) to those nodes. For actions which take some time to complete (CON101) addtional 803 messages are set after each complete fibre movement to provide an instrument update to the ICL noticeboard and mimic.
3.4 Software interlocks
A number of internal software flags within the application layer prevent the user damaging the hardware. When dealing with moving fibres two flags in particular allow for the safe handling of fibres.
The global variable fibre_no is the number of the fibre the robot thinks it currently has in the gripper jaws, if the robot thinks the gripper jaws are empty this variable is set to 999. At many points in the software the value of this variable is checked and if it is not 999 then certain actions may be prevented (picking up a fibre, moving outside of the park circle radius, moving outside of that fibres patrol area etc). this flag can be reset to 999 using the RESETCURRFIB engineering command, however this should only be done in carefully controlled circumstances.
The global variable fibre_error is set to either TRUE or FALSE (see the file af2defs.h for the definitions of these symbols), if set to TRUE this means that a fibre has been lost and by testing against this condition all further movement of fibres is prevented until the fibre has been successfully recovered (which automatically resets the fibre_error variable to FALSE). Under normal circumstances it should not be necessary to reset this flag manually as this is done as part of the recovery procedure for a lost fibre, but if absolutely necessary this can be done using the RESETLOSTFLAG command from the engineering interface. Note that it is not possible to reset this flag by rebooting the micro computer as its value is stored on disk and read in when the application layer is restarted.
3.5 Application layer error codes
The error codes returned as part of the status responses by the command interpreter and the main control task are defined in the following tables, note that the no error condition is reported as 00 hex.
Command errors:
ERROR NAME Hex Explanation TSKACTIV 0x01 Not implemented for Autofib-2 OUTRANGE 0x02 Supplied parameter outside allowed range BADPARAM 0x03 Wrong type of parameter BADFRMAT 0x04 Wrong number of parameters LISTFULL 0x05 Not used BADFUNCT 0x06 Requested function does not exist BADSOURCE 0x0a Micro is not accepting commands from this source
Mechanism errors:
ERROR NAME Hex Explanation TIMEOUT 0x01 An AF2 mechanism has timed out NOPOWER 0x02 No instrument power MOTORSDISABLED 0x03 Cant move robot or probe, no motor power PREVERROR 0x04 Cant do anything as a fatal error has previously occurred POWERFAIL 0x05 Failed to turn on/off instrument power MOTORFAIL 0x06 Failed to turn on/off motor power SERVOINACTIVE 0x07 Servo amplifier not registering as active INSPLIGHTFAIL 0x08 Failed to turn on/off inspection lights BCKILLUMFAIL 0x09 Failed to turn on/off guide fibre back illumination
PROINITFAIL 0x0a Failed to initialise off axis probe PROLIMIT 0x0b Off axis probe in a limit switch PROPOSERR 0x0c Off axis probe is has returned an excessive position error PROILGLMV 0x0d Cant move probe as it will collide with robot PRONINIT 0x0e Cant move probe until it has been initialised PRONEEDSROBINIT 0x0f Cant move probe until robot has been initialised
ERRORNAME Hex Explanation TEMPOUTRANGE 0x10 Instrument temperature is outside of allowed range NOFIBMODULE 0x11 Cant turn on motors without fibre module in place FIBERR 0x20 Error when attempting to change status of fibre NOFIBINFO 0x21 No fibre information available yet INVFIBNO 0x22 Invalid fibre number for current module FIBUNAVAILABLE 0x23 Fibre specified is unavailable FIBBADPLACEMENT 0x24 Not currently used ROBINITFAIL 0x30 Initialisation of robot failed ROBNEEDSPROINIT 0x31 Cant initialise robot until probe has been initialised ROBLIMIT 0x32 Robot in limit switch ROBXPOSERR 0x33 Robot position error on X axis ROBYPOSERR 0x34 Robot position error on Y axis ROBZPOSERR 0x35 Robot position error on Z axis ROBTPOSERR 0x36 Robot position error on theta axis ROBILGLMOV 0x37 Moving robot would cause collision with probe ROBNINIT 0x38 Cant move robot as it is not initialised 0x39 Not currently used ROBFIBMOVILGL 0x3a Cant move robot there while carrying fibre FIBREINJAWS 0x3b Cant perform action as fibre still in gripper jaws
ERROR NAME Hex Explanation ROBPARKERR 0x3c Error when parking robot LOSTFIBRE 0x3d Cant move another fibre until lost fibre is recovered ROBSTUCK 0x3e Failed to extract robot from limit switch ROBPICKUPERR 0x3f Obsolete, replaced by errorcodes 0x48-0x4b ROBPUTDOWNERR 0x40 Obsolete, replaced by errorcodes 0x4c-0x4d GRIPTOOLOW 0x41 Cant move robot when gripper too close to fibres NOAIRPRESS 0x42 Air pressure low or has failed ROBOFFERR 0x43 Offsetting robot would take it out of its allowed range (but offset value is legal so not OUTRANGE error) ROBILGLFIBPOS 0x44 Moving fibre there would cause fibre-fibre crash ROBBADCENTROID 0x45 Centroid failed during placement of fibre BADFIDUCIAL 0x46 Fiducial number out of range for current target ROBLOADFAIL 0x47 Failed to locate fibre in loadfibre/recover command NOSECONDFIBRE 0x48 Cant pickup a second fibre when one is in gripper NOKNOWNFIBRE 0x49 No known fibre at this position NOFIBREVISIBLE 0x4a Cant see fibre that is to be picked up MOVETOPLATEFAIL 0x4b Failed to move gripper towards plate during pickup NOFIBTOPLACE 0x4c No fibre in jaws to pplace on fieldplate LOWERTOPLATEFAIL 0x4d Failed to lower gripper to fieldplate during putdown NOBACKILLUM 0x50 Cant move fibres without back illumination CONTARGETMISSING 0x51 Cant open target *.fib file CONHEADERERR 0x52 Error in header information in *.fib file CONFIBREADERR 0x53 Error reading in fibre info in *.fib file CONNXTFLDERR 0x54 Error creating NEXTFIELD.DAT file CONFIBMOVERR 0x55 Error as robot cant move unavailable fibre CONCONFLICT 0x56 Conflicting or illegal information in *.fib file CONSETUPERR 0x57 Error occurred during target field setup CON_STOPPED 0x58 Setup was aborted due to external command CONCGPFAIL 0x59 Failed to find a means to configure the next field CENTROIDFAIL 0x60 Failed to find image to centroid
The method of reporting errors was chosen to conform with the expectation of the instrument Itask as a detailed specification for this performance has never been made. Commands sent to the instrument consist of a MOVE followed by an ISTAT and DSTAT, the ISTAT should contain any command error in the move command, the ISTAT should contain any mechanism error that occurred as a result of the MOVE command.
3.6 Hard coded system variables
A number of variables required for operation of the application layer are hard coded into the source code. These are normally mechanical offsets which require calibration and should not be changed unless the instrument is stripped down and reassembled. These variables are very different to those set in the af2params.dat file which contains mainly software parameters which might be changed during use of the instrument.
The following positions are defined as symbols in the af2defs.h include file. The exact values should be checked by examining the file, changed values should be commented for subsequent checking.
Z axis limits - ZMAX,ZMIN
Z axis fibre carrying height - UPPER
Z axis fieldplate position - PLATE
Theta axis limits - TMIN,TMAX
Theta axis home position - T_OFFSET
X axis limits - XMIN,XMAX
X axis home position - XZERO
X axis park position - PARKX
Yaxis limits - YMIN,YMAX
Y axis home position - YZERO
Y axis park position - PARKY
Probe limits - MIN_PROBE,MAX_PROBE
The offset between the gripper rotation/optical axis and the off axis probe is kept as two global variables (xview_offset and yview_offset) which are initialised with the correct values at the start of the main() function in the control.c source code file. See the technical manual for details on calibrating this offset.
The gripper fibre viewing tv system has its image scale and orientation carefully calibrated. The x and y image scales and the rotation of the x axis of the tv with respect to the x axis of the robot are stored as local variables (xscale,yscale,alpha) in the findfibre() function in the tvstuff.c sorce code file. See the technical manual for details of determining these values.
The engineering interface consists of two processes which provide a text command interface and a graphical mimic display. A schematic of the whole engineering interface and its interaction with the application layer software is shown in figure 3.
4.2 Engineering mimic
The engineering mimic is generated by a single task which is automatically started at the same time as the rest of the control system. The mimic task is called esdrave and runs at a very low priority to avoid loading the rest of the control system. The engineering mimic display is only actively maintained when the control system is running in local mode (i.e. being controlled from the engineering user interface.
The engineering mimic task runs in a continuous loop, picking up the information about the status of the instrument from shared memory and if necessary displaying the information by writing to a graphics device which is a spare BVME780 card using the RAVE software library.
On accessing the shared memory, the mimic task first picks up two pieces of information, the current control mode and the current mimic display page. If the control system is in remote mode then if the display is currently active it is shut down and the process sleeps for a short period, else no further action is taken and the process sleeps for a short period. If the control system is in local mode then the mimic process checks the current page to display. The current page can be in the range 0 to 5. If page 0 (the null page) is current then the process shuts down the mimic and sleeps for a short while. If any other page is selected, the process picks up the information for that page and displays it by writing to the graphics device.
The source code for the engineering mimic process is in the /h0/esd directory together with a early text based version and a makefile.
4.3 Engineering user interface
The engineering interface may be started by logging in to the AUTOFIB account on the Autofib-2 micro computer and typing:
eng [return]
This will start a text interface allowing control of AUTOFIB-2. Text commands may be entered directly at the keyboard. If necessary the command "help" will display the allowed list of engineering commands. By entering "help" followed by the command name and the usage of the command will be displayed. Commands are not case sensitive.
Two commands are never displayed:
"extended" may be used to allow extra commands that are not normally available as they are possibly dangerous to the instrument. After entering the "extended" command a password will be prompted for. These commands remain available until their use is restricted again with the following command. The commands whose use is thus restricted will now appear in the command list displayed after entering the "help" command.
"restricted" will prevent the use of the dangerous commands, no password is required.
A full engineering command list may be found in Appendix A.
The Autofib account root directory is /h0/autofib where /h0 is the system root directory
on the hard disk (/h0). In the autofib account root directory are kept the batch files necessary for starting and stopping the control system.
All executable images that have been developed for Autofib-2 are kept in the /h0/autofib/exec directory, this directory is in the search path and so does not need to be specified explicitly.
The source code and makefile for the network layer is kept in the /h0/autofib/network directory.
The source code and makefile for the application layer is kept in the /h0/autofib/appsource directory.
The source code and makefile for the engineering mimic is kept in the /h0/autofib/esd directory.
The source code and makefile for the engineering interface is kept in the /h0/autofib/eng directory.
Utility programs are divided into testprograms (/h0/autofib/testprogs), network layer tools (/h0/autofib/tools/net_tools) and application layer tools (/h0/autofib/tools/app_tools), each directory contains a makefile to build the programs in the directory.
Datafiles required for the operation of the control system are kept in the /h0/autofib/datafiles directory. This includes the following files:
af2params.dat
large_fibres.dat
small_fibres.dat
special_fibres.dat
large_etable.dat
small_etable.dat
special_etable.dat
movefibre.dat
fiberror.dat
ftpget
A description of the content of each of these files may be found in section 5.2.
Configuration files for target fields are kept in the /h0/autofib/configfiles directory. This is where the *.fib files obtained from the VAX instrumentation computer are temporarily kept. This directory is automatically emptied of all *.fib files every time the fibres are reconfigured so the only files remaining should be a few special configurations which have the *.dat extension. The following files should be present in this directory:
large_parked.dat
large_circle.dat
small_parked.dat
small_circle.dat
special_parked.dat
special_circle.dat
Logfiles containing information about recent fibre movements are kept in the /h0/autofib/logfiles directory. Results of fibre placements are automatically appended to the file logfile increasing its length with every fibre movement. It might be useful to rename this file at the beginning of every observing run, a new file called logfile will be created after the next fibre movement when the old version is renamed. If errors occur when moving a fibre a line is appended to the file errorlog in the logfiles directory allowing a list of all fibre placement errors to be maintained.
Also stored in the /h0/autofib/logfiles directory are datafiles created during testing of Autofib, these are the reference.dat file which is appended to every time a measurement of the reference fibres in the large fibre module is made and the random.dat file which contains position measurements of a fibre created by the random and static commands in the engineering interface. These two files have new data appended to the end of the file and should be renamed for processing and or deleted when tidying up the directory.
5.2 Control system file formats
5.2.1 af2params.dat
A free format ascii file where the content of each line is defined by a keyword as the first string on the line. A star indicates a comment and the rest of the line is ignored. All other key words indicate starting values of parameters for the control system. If some of these lines are missing the control system will attempt to use sensible values but this should not be relied upon and may cause serious problems. The recognised key words and their meaning are given in the following table. keywords may be in upper,lower or mixed case.
Keyword Meaning of parameter * Comment ortho Value of non orthogonality from grid tests xscale X axis scale yscale Y axis scale xgain X axis servo loop gain ygain Y axis servo loop gain zgain Z axis servo loop gain tgain theta axis servo loop gain pgain off axis probe servo loop gain xki X axis servo loop gain integrator yki Y axis servo loop gain integrator zki Z axis servo loop gain integrator tki theta axis servo loop gain integrator pki off axis probe servo loop gain integrator xyspeed XY axis maximum speed (microns/s) zspeed Z axis maximum speed (encoder counts/s) tspeed theta axis maximum speed (encoder counts/s) pspeed off axis probe maximum speed (encoder counts/s) xyacc XY axis acceleration (microns/s/s) zacc Z axis acceleration (encoder counts/s/s) tacc theta axis acceleration (encoder counts/s/s) pacc off axis probe acceleration (encoder counts/s/s) tolerance fibre placement tolerance (microns) iterations maximum number of iterations after initial fibre placement attempt esd_page initial engineering status display to show vidmode gripper fibre viewing system tv mode jaw_delay delay for jaws to open/close (system clock ticks) datadir location of *.fib files on Vax machine vax computer running observing system user username for account running observing system pass password for account running observing system simulate flag to indicate whether to run control system in real or simulation mode
5.2.2 reference.dat
An ascii file containing one line for each measurement of a reference fibre in the fieldplate. As the reference fibres are measured together as a set of four the measurements are grouped together as a set of four lines. Further measurements of the reference fibres are simply appended to the end of the file. An example file showing two sets of measurements is shown below.
1 176132 -153168
2 176850 127399
3 -129906 -162790
4 -129430 109481
1 176145 -153062
2 176858 127491
3 -129880 -162714
4 -129423 109553
The nominal positions of the reference fibres are shown below, these are the positions the robot is driven to in order to measure the reference fibre positions but due to the repeatability of the fibre module reassembly and flexure of the fibre module the fibres will not be in exactly these locations.
Position 1 176700,-153300
Position 2 177300,127600
Position 3 -129550,-162700
Position 4 -129050,109800
5.2.3 logfile
A free format ascii file containing one line for each fibre placement. The line contains the following information:
1. Fibre number,
2. number of iterations required to place within requested tolerance,
3. x position error,
4. y position error,
5. x fibre position,
6. y fibre position.
5.2.4 random.dat
A free format ascii file to which additional measurements are simply appended. Each line of the file consists of a single measurment and gives the fibre number and measured x,y position separated by spaces. If the file does not exist (having been deleted or renamed) a new file is created.
Note that if repeatability tests are being performed on more than one fibre or under several instrument attitudes it is the responsibility of the tester to rename this file to avoid the generation of a single file whcih large amounts of data concatenated together.
5.2.5 errorlog
A free format ascii file containing one line for each fibre placement error that occurs. Each line contains the following information:
Pickup or putdown error,
Fibre number
From fibre x,y position
To fibre x,y position
Timestamp
For example:
Pickup error, Fibre 73 From: -13899,-92141 To: -16537,-88467 Timestamp
Note that the timestamp information does not currently work so the string 'timestamp' is inserted (see note on timetest.c program in section 6.1).
This file may be accessed from OS/9 and the engineering interface using the lasterror command.
5.2.6 xxxxx_fibres.dat
This set of files (with xxxxx replaced by large,small or special) are ascii format but with a very strict line length and content and should not be manually edited unless the user knows exactly what they are doing. Ignoring this and changing the length of some lines could have disastrous consequences to the database of the locations of the fibres.
The first 15 lines of the file contain essential information about the fibre module itself, the remaining information contains in one line per fibre all the information about the individual fibres. The header information is ordered as follows:
Line 1 Title (not used directly)
Line 2 Blank
Line 3 Key word for fibre module (LARGE SMALL or SPECIAL)
Line 4 Number of fibre pivots (whether populated or not)
Line 5 Number of guide fibres (whether enables of not)
Line 6 Number of empty pivots
Line 7 Maximum allowed non radial angle for a fibre in degrees
Line 8 Maximum extension of a fibre from its pivot in microns
Line 9 Tube diameter in microns
Line 10 Fibre button width in microns
Line 11 Fibre button length in microns
Line 12 Rough diameter of fibre in arcsec
Line 13 Physical radius of fibre pivot circle in microns
Line 14 Radius of park circle in microns
Line 15 Radius of fibre load ring in microns
Each line of fibre data contains the following information:
Fibre number
Fibre status
Fibre pivot x,y position
Fibre x,y position
Fibre theta position in arcmin (same coordinate convention as used by the gripper)
Fibre position error last time it was placed by the robot.
The fibre status may be in the range 0-6 to indicate the following:
0 Missing fibre or empty pivot 1 Enabled spectroscopic fibre 2 Enabled guide fibre 3 Disabled spectroscopic fibre 4 Disabled guide fibre 5 Dead spectroscopic fibre 6 Dead guide fibreShown below are the header information and the data for the first 10 fibres of the large fibre module as an example. (But note that due to the use of a word processor the line lengths and spacings are not an accurate representation of the actual data file).
AUTOFIB-2 LARGE FIBRES DATA FILE
LARGE FIBRES
136 N PIVOTS
10 N GUIDES
1 N UNUSED
4.000000 NON RADIAL ANGLE
350000 FIBRE LENGTH
1500 TUBE WIDTH
2500 BUTTON_WIDTH
7000 BUTTON LENGTH
2.5 ARCSEC FIBRES
349000 PIVOT RADIUS
126000 PARK RADIUS
134000 LOAD RADIUS
1 4 0 349000 -70 134046 1 0 0
2 3 16118 348627 6895 133861 147 0 0
3 3 32201 347511 13327 133342 302 0 0
4 3 48216 345653 18210 132865 481 0 0
5 3 64128 343057 24080 131593 643 0 0
6 3 79903 339729 30418 130762 799 0 0
7 3 95508 335677 36828 129169 951 0 0
8 3 110909 330908 43012 127380 1106 0 0
9 3 126073 325432 48555 125221 1269 0 0
10 3 140968 319263 54278 122774 1428 0 0
5.2.7 xxxxx_etable.dat
These files contain the fibre placement error lookup tables for each of the fibre modules.
These files (where xxxxx is either large,small or special) consist of a simple ascii file containing 5 columns of numbers which one row for each fibre. To start with (on day zero) the file was generated with the first column containing the fibre number follwed by four columns with zeroes, each of the four additional columns representing four error terms used when placing fibres. As the robot learns how to predict where to place the fibres it updates the error table. The units of the table are microns. A few lines are shown below for an example (dummy error table values for fibres 1-3).
1 25 54 23 12
2 -34 50 67 -23
3 75 90 120 -40
To start the system on day one (but not subsequently under normal circumstances) it is necessary to have a zero errortable, this is contained in the file zero_etable.dat and consists of zero zero errortable entries for 136 fibres (as required for the large fibre module. If required this may be edited to give more or fewer fibre entries and then copied to the required filename.
If the current error table file is deemed to be obsolete (the fibres have been physically rearranged in the fibre module) then the error table should be zeroed in the above manner and the robot will learn the new values automatically as it handles the fibres, note that it will take several placements for each fibre to thoroughly update the error tables for all fibres.
5.2.8 move_fibre.dat
A one line ascii file containing information regarding the last fibre movement attempted by the robot. For example the string
Moving fibre 73 from -13899,-92141 to -16537,-88467\n\0
gives the information that the robot last moved (or attempted to move) fibre number 73 from x,y position -13899,-92141 to x,y position -16537,-88467. This file is overwritten for each successive fibre movement. As this file contains the information required to recover a lost fibre it is important that no further fibre movements are attempted if a fibre is lost.
The information in the movefibre.dat file may be accessed directly from the OS/9 prompt using the lastmove utility or from the engineering interface using the lastmove command.
5.2.9 fiberror.dat
A one line ascii file containing the string "TRUE\n\0" or "FALSE\n\0". This file is read in by the application layer and the string used to set the fiberror flag to TRUE or FALSE to indicate whether a critical fibre placement error has occurred. If TRUE then this flag prevents further fibre placements until a successfull recovery takes place and the flag is reset to FALSE at which point the file on disk is updated. Keeping this information in a file prevents the software flag being bypassed by rebooting the instrument microcomputer.
5.2.10 ftpget
An ascii batch file generated by the application layer every time it requires to get a new configuration file from the instrument control Vax using ftp access. each line is a legal OS/9 or ftp command.
The three directories group the source code according to type of program:
network layer tools /h0/autofib/tools/net_tools
application layer tools /h0/autofib/tools/app_tools
test programs /h0/autofib/testprogs
6.1 Test programs
The various test programs in this directory were written to test new ideas and test hardware before making large modifications to the control system, a few of these programs are extremely useful. The following source code files are present in this directory:
adctest.c A program to exercise the analogue to digital converter industry pack, see the technical manual for a description.
af2status.c A program to display all of the current hardware status values.
atan2.c A program to test the implementation of the atan2() function which is not part of the standard maths library distributed with OS/9.
circgen.c A program to generate a standard circle of fibres configuration using the current fibre data files. The current data files are obtained from the /h0/autofib/datafiles directory and the output files are generated in the /h0/autofib/configfiles directory. Currently only the large and small fibre modules are catered for. Existing output files are overwritten.
digio.c A program to exercise the digital IO industry pack board, see the technical manual for a further description.
dmc300.c A program to test communications with the Galil motion control cards and provide simple interactive control of the various motors and encoders within Autofib-2.
drift.c A simple program to find the minimum and maximum X,Y position in a data set, used for a quick look at repeatability test data.
encoders.c An old program used to check the rotary encoders against the linear encoders for the X and Y axes, now superceded by the grid test procedure.
grid.c The source code for the grid test procedure, see the technical manual for the method opf performing grid tests.
netsoak.c A program to test the network layer by artificially sending a stream of network messages out from the micro and back to the micro.
parkdata.c A program to generate a standard fibres data file and error look up table file. The source code should be edited to indicate which fibres are guide fibres, disabled fibres etc. The output files are generated in the current directory, there is no input data file. This program currently only generates data files for the large fibre module.
parkgen.c A program to generate the standard park configuration required for each of the fibre modules using the current fibre data files. The current data files are obtained from the /h0/autofib/datafiles directory and the output files are generated in the /h0/autofib/configfiles directory. Currently only the large and small fibre modules are catered for. Existing output files are overwritten.
process.c A program to give a brief idea of the positioning accuracy by calculating from the logfile how many fibre placements have been within certain radii of the requested position.
random.c Test program to check a random number generator as there is no such generator within the OS/9 C function library.
sema1.c, sema2.c A pair of programs to test the use of OS/9 events as semaphores.
stopnetsoak.c A program to halt execution of the netsoak program.
timetest.c A program to test the generation of a string containing the current system time, this was to be used to timestamp the transmitted and received log of messages but while it worked in a standalone program it could never be made to work in the network later software (receive and write tasks) without crashing the respective tasks so it was never implemented. It was also attempted to use this code in timestamping the log of fibre placement errors but again it caused the termination of the calling program with no explanation and so has not been implemented.
makefile A makefile to compile all the source code in this directory.
6.2 Network layer tools
The source code for the various network layer tools programs are kept in the /h0/autofib/tools/net_tools directory. Each tool may be invoked by simply typing in its name (without the file extension) as built versions are kept in the /h0/autofib/exec directory. The following programs are provided:
delev.c A program to delete software events from the micro computer, used when shutting down the network layer to tidy up the system so that it can be restarted easily.
diagnostics.c A program to access the data module called NET_DIAGNOSTICS provided by the network layer software, the program reads in the information in the data module and displaying it on the screen.
putetab.c A program for testing the engineering interface, this enabled a message to be inserted into the ERTABLE data module to be picked up by the application layer.
readetab.c A program to read and display the contents of the ERTABLE data module.
readetran.c A program to read and display the contents of the ETTABLE data module.
readrbuf.c A program to read and display the contents of the RBUFFER data module where incoming messages are queued between the read and receive tasks.
readtab.c A program to read and display the contents of the RTABLE data module.
rlog.c A program to read and display the contents of the RLOG_TABLE data module, this displays a log of the last 20 received messages
stop_watch.c A program to read in the process id of the watchdog task from the PROCDATA data module and send a terminate signal to the watchdog task.
stopread.c A program to read in the process id of the read task from the PROCDATA data module and send a terminate signal to the read task.
stopreceive.c A program to read in the process id of the receive task from the PROCDATA data module and send a terminate signal to the receive task.
stopwrite.c A program to read in the process id of the write task from the PROCDATA data module and send a terminate signal to the write task.
tlog.c A program to read and display the contents of the TLOG_TABLE data module, this provides a log of the last 20 transmitted messages.
transmit.c A program to manually transmit a network message from the micro computer by inserting the message in the correct format into the TTABLE data module.
makefile A make file to build all of the source code in the directory.
6.3 Application layer tools
The source code for the various application layer tools programs are kept in the /h0/autofib/tools/app_tools directory. Each tool may be invoked by simply typing in its name (without the file extension) as built versions are kept in the /h0/autofib/exec directory. The following programs are provided:
monitor.c A program to interrogate the AF2_STATUS data module for a list of the nodes logged into the micro computer in monitor mode.
readcomq.c A program to read and display the contents of the COMMANDQ data module, this data module holds the queue of action messages between the command interpreter and the main control task.
see.c A program to interrogate AF2_STATUS for the status of a specified mechansim, type see [return] for a list of supported mechanisms, or type see XXX YYY ZZZ [return] where XXX, YYY and ZZZ are mechanism codes.
stopcmdintrp.c A program to read in the process id of the command interpreter task from the PROCDATA data module and send a terminate signal to the command interpreter task.
stopcontrol.c A program to read in the process id of the main control task from the PROCDATA data module and send a terminate signal to the main control task.
stopesdrave.c A program to read in the process id of the engineering mimic task from the PROCDATA data module and send a terminate signal to the engineering mimic task.
lastmove.c A program to display the last fibre movement attempted by the robot.
lasterror.c A program to display the last fibre placement error that occurred.
makefile A make file to build the contents of the directory.
As the hard disk in the VME rack has a capacity almost 4 times larger than required, backups of the whole disk are simply made by storing a compressed version of the whole disk in a single file which is then copied using ftp to a remote machine for safe storage. Steps to make a backup are as follows:
1. Login to the micro computer as SYSTEM
2. chd /h0/backupdir
3. ensure the directory is empty (or you will make a backup of a backup file)
4. chd /h0
5. fsave -f/h0/backupdir/filename where filename is a unique name.
6. chd /h0/backupdir and check that filename is present, it should be approximately 7MB in size.
7. ftp filename to remote host making sure that type is set to binary.
7.2 Restoring the OS/9 hard disk
7.2.1 Restoring the complete disk
It is assumed that the hard disk of the Autofib-2 micro computer has been damaged or corrupted beyond repair. Instructions are given for rebuilding the complete OS/9 system from a backup file stored on another computer as described in the previous section.
1. Boot the micro computer from the supplied floppy disk
2. When finished swap the floppy disk for the TCP/IP floppy disk.
3. Type startinet& [return] and wait to complete.
4. Swap floppy disks back to boot disk.
5. Type tmode nopause [return].
6. Type format /h0fmt -c=8 [return]
proceed? y [return]
this is a hard disk are you sure? y [return]
physical format desired? y [return]
physical verify desired? y [return]
enter volume name: Autofib-2 system disk [return]
wait several minutes to complete
7. Type chd /h0 [return]
8. Get backup file from wherever is has been kept using ftp, making sure that the file type has been set to binary. Put the file in the root directory (/h0) on the micro computer disk.
9. Type dir [return], you should see the backup file.
10. Type frestore -f=/h0/filename -qes [return] where filename is the name of the backup file. See the OS/9 manual for details of the use of the frestore utility.
11. Type del filename [return] to delete the backup file.
12. Type chd /h0/cmds/bootobjs [return]
13. Type os9gen /h0fmt -z=bootlist_h0 [return]
14. Boot computer from hard disk
7.2.2 Restoring selected files
Assuming that the Autofib-2 micro computer is functioning correctly, ftp the most recent backup file into the /h0/backupdir directory. Change into the /h0/backupdir directory. Use the Frestore utility provided by OS/9 to restore a selected file from the backup file (see the OS/9 operating system manual for details of the interactive use of the Frestore utility).
OS/9 provides a make utility which is used extensively to build the executable code. The makefiles provided all store intermediate files on a RAM disk, so if the micro is rebooted then all intermediate files are lost and sometimes lengthy rebuilds will be necessary.
All of the Autofib-2 source code is kept in directories together with a makefile which will automatically compile and link the source code in that directory. The executable images are placed in the /h0/autofib/exec directory to keep them separate from the operating system executable images which are kept in the /h0/cmds directory.
All source code requiring use of the symbols defined in the Autofib-2 code explicitly refer to the af2defs.h include file in the /h0/autofib/appsource directory. This avoids having disagreeing duplicates of the same file and/or definitions.
8.2 Network layer
The source files for the network layer are kept in the /h0/autofib/network directory. The files required are:
read.c source for read task
write.c source for write task
receive.c source for receive task
watchdog.c source for watchdog task
table.c source for program to set up shared memory
also in the directory is a makefile to automatically build the software.
8.3 Application layer
The source files for the application layer are kept in the /h0/autofib/appsource directory.
af2defs.h contains general definitions for all autofib software
errorcodes.h contains definitions of the error codes
globals.h contains global variable definitions for the control task
prototypes.h contains function prototypes for the control task
cmdintrp.c contains the source code for the command interpreter task.
control.c contains the main() function for the control task.
probe.c functions for control of the off axis probe
power.c functions for control of the instrument and motor power
pickup.c functions for picking up and placing fibres
move.c functions for moving the robot in x,y,z and theta
robot.c functions for initialising and high level control of the robot
robot2.c functions for specialised control of the robot
tvstuff.c functions for control of the framegrabber system
outcom.c functions for communication with the Galil motion cards
status.c functions for general status reporting and ttl control
8.4 Engineering interface
The engineering interface is kept in two directories, the source code for the mimic display is kept in the /h0/autofib/esd directory:
esdrave.c source code for graphical mimic display
esdtext.c source code for early version of text based mimic
makefile make file for rebuilding above two source files
the source code for the engineering interface is kept in the /h0/autofib/eng directory:
eng.c source code for the engineering interface.
makefile make file for the engineering interface source file
8.5 Other software tools
The source code for various tools and test programs is kept in directories together with a makefile for all the source code in that directory, to rebuild code in a directory it is simply necessary to type make[return] in the directory.
It is important that the TCP/IP software be updated if the Internet address of the micro computer is changed. It is obvious that the micro computer should be updated for it to function correctly (allowing the transfer of fibre data files and configuration files) but it is most important that the floppy disks that provide TCP/IP access in emergency are updated and tested. If this is not done then it may prove impossible to restore the hard disk from a backup in the event of a disk failure.
9.2 Setting up Internet numbers
To change the internet number of the micro computer it is first necessary to disconnet the ethernet cable, reboot the computer and log in on the System account.
Step Command
change to /h0/isp/drivers directory chd isp/drivers[return]
edit if_devices me if_devices
change inetaddr and bdaddr to new values
exit editor
generate assembler file ifgen<if_devices[return]
change to am7990 directory chd am7990[return]
rebuild driver make[return]
change to executables directory chd objs[return]
check date of executable dir -e le0_tp32
change back to root directory chd[return]
change to etc directory chd etc[return]
edit hosts file to update internet numbers me hosts[return]
change necessary internet numbers
create new inet database idbgen[return]
reboot computer and connect to ethernet
9.3 Updating emergency floppy disks
The emergency floppy disks should be created and tested before they are needed as it does not appear to be simple to make the inetnet address of the configurable after booting from the floppy disk. Everything apart from the rebuild (make) command works from the floppy disk provided, so it should only be necessary to copy the rebuilt executable into the correct directory as well as carrying out the other steps.
This early problem seems to be less significant although it still can occur. Under heavy loading the network layer semaphore system for managing shared memory fails and checking within the individual network layer tasks shuts down the network layer. This will become apparent at the ICL control level by a warning message (AF2: lost contact with instrument) and a red warning on the ICL mimic display. Although a huge amount of effort has been put into tracking this problem it would seem to be at the operating system level (ie that masking and queuing of software signals while waiting for events to come into range). To reduce the problem the use of software signals has been drastically reduced.
To diagnose the problem it is necessary to log into the micro computer under the autofib account and type procs[return], check the displayed list of current processes against those in section 1.3. If a significant number of the network tasks are missing it will be necessary to reboot the micro computer and restart the control system (see section 1.3)
Note that if only the command interpreter task is missing this is a very different problem with another solution (see section 10.2).
This problem is most likely to occur when starting the control system if the micro computer has not been rebooted and network messages are waiting in the RS232 buffer.
10.2 Command interpreter dies
Again the symptom of this problem is the error message AF2: Lost contact with instrument or the red warning on the ICL mimic. If on logging into the micro computer however the only missing task is the cmd_intrp task (the command interpreter) it should not be necessary to reboot the micro computer. In fact it may cause more problems if the micro computer is rebooted. If this problem occurs while the robot is reconfiguring the fibres it should be left to complete before attempting to fix the problem.
The command interpreter may be restarted by entering the following command line at the OS/9 prompt:
cmd_intrp>>>/nil&[return]
The ICL session should show that contact is regained almost immediately as the command interpreter processes the backlog of waiting messages.
10.3 Problems when accessing hardware from two sources
At present only one task accesses the Autofib-2 hardware under normal operation (the main control task). If another task is started which also accesses the hardware (for example the af2status program or the dmc300 test program) it is likely that there will be a conflict in communicating with some of the hardware and one or other of the tasks will die which potentially disastrous results if the robot happens to be moving fibres at the time.
10.4 Corruption of network messages
At the ICL prompt this will be noted by an error message showing a network message with a mising character, for example CO801 instead of CON801. This happens when the micro computer cpu becomes overloaded and is unable to keep up with a steady stream of network messages from the dtask.
To avoid this overloading the use of the engineering status display is not allowed while the application layer is in remote mode and likely to receive large numbers of network messages.
If using the control system in local mode then the engineering status display can be set to page 0 if the control system is still connected to the utility network to reduce CPU loading.
10.5 Poor centroiding on guide fibres
The current fibre centroiding algorithm is really set up for the spectroscopic fibres, the problem with the guide fibres is the pattern of 7 individual fibres and the uneven illumination of each of the seven fibres. An attempt is made in the guide fibre back illumination system to mask off the outer ring leaving one illuminated fibre and this works to some extent. However the small size of the remaining fibre means that the accuracy of the guider fibre is not as high as would be preferred.
10.6 Occasional failure to detect a missing fibre image
The centroiding algorithm determines the threshold level of each fibre image to be 90% of the brightest pixel on a coase sampled grid. A quick check is then made of the number of pixels above this threshold intensity. For the fibre to be present the number of pixels above this threshold is quite small but if no fibre is present the threshold intensity is set very low and a large number of pixels break the threshold level. Thus it is possible to determine by the number of pixels above the threshold intensity whether a fibre is present in the image.
The value at which the cut off between a missing fibre and a valid fibre is made was determined by experiment using fibres of widely varying levels of illumination.
This algorithm breaks down if the fibre image is too bright (for example when the fibre backillumination is switched on and before it settles down) or if an image with no fibre present is extra noisy (for example a cosmic ray) and the threshold intensity is set too high.
10.7 make fails when rebuilding code
When rebuilding souce code using the makefiles provided and the OS/9 make utility, occasionally make will fail with the error message 'no output files'. I have no idea why this happens but a reboot or emptying the ram disk (del /dd/tmp/*.*) usually cures the problem allowing the user to attempt the rebuild again.
10.8 Ftp of configuration data file fails
The ftp of the configuration data file from the Vax Instrumentation control computer is done as a batch file (ftpget) run in a subprocess. Unfortunately this means that no diagnostics are available if the file transfer fails. On failing the file transfer a by product is a zero length configuration file which means that subsequently the micro software will return a CONHEADERERR error rather than a CONTARGETMISSING error. This can be misleading to say the least.
To check the operation of the ftp process you can execute the ftpget batch file directly from the /h0/autofib/datafiles directory and check its operation. Likely causes of failure are the use of incorrect user account parameters in the af2params.dat file.
10.9 Note on use of monitormode
On starting up the control system on the micro computer the default is for no nodes to be logged in with monitormode enabled. In normal circumstances the control system will be up and running before the observing system and when the observing system is brought up it will automatically log on to enable monitormode.
Problems will occur if the micro computer is rebooted or the observing system is brought up before the micro control system. In this case the user should explicitly log the observing system in to enable monitor mode or risk all the fibre information on the noticeboard and hence in the data image headers being out of date and useless.
The command to enable monitormode from ICL is: AF2_MONITORMODE ON[return].
At the micro, the register of nodes with monitormode enabled may be displayed by typing MONITOR[return] at either the OS/9 or engineering interface prompt.
Figures
Figure 1 Keypad function layout for microemacs screen editor
Figure 2 Network layer software schematic
Figure 3 Application layer software schematic
The first group of commands are issued directly to the operating system at the OS/9 prompt as they are either part of the operating system or are implemented as standalone programs. These commands may be used during normal operation of the instrument unlike some of the test programs which are not designed to be used which the robot is operational
(eg grid.c, dmc300.c, digio.c)
ENG Start the engineering interface, exit using the QUIT command.
MONITOR Display a list of nodes currently logged in to Autofib-2 with monitor mode enabled.
DIAGNOSTICS Display the current network layer diagnostics.
TRANSMIT Transmit a message via the network layer, different fields will be prompted for, input is case sensitive and should be entered in upper case only.
RLOG Display log of last 20 received messages.
TLOG Display log of last 20 transmitted messages.
STOPALL Shut down the control system safely.
STARTALL Start up the control system (nb do not use while the control system is running.
SEE xxx Display the status of a mechanism. No mechanism code will display usage and a list of valid mechanism codes.
LASTMOVE Display the last fibre move attempted by the robot. This consists of fibre number and origin and destination positions of the fibre.
LASTERROR Display the last error that occurred when moving a fibre.
The following commands are issued to the control system via the engineering interface. The engineering command interface is started by typing eng [return] at the OS/9 prompt on the micro computer. The OS/9 prompt may be obtained either at the engineering terminal (if connected) or by logging into the micro computer as Autofib using a telnet link. When started the engineering interface prompts the user to enter the HELP command for further information if necessary, typing HELP allows the user to access a very simple help menu, typing HELP followed by the command name gives the user basic information about the command and it required parameters. Commands are not case sensitive.
BACKILLUM state Turn the guide fibre backillumination to state (ON or OFF). WARNING ensure that the Westinghouse tv is not powered up or serious damage will result. Autofib assumes that the guide fibre illumination state is the same as the spectroscopic fibres backillumination state. Therefore if the guide fibres are not backilluminated but the spectroscopic fibres are backilluminated then the control system will not allow the movement of any fibre as the software will check that the backillumination (ie guide fibre backillumination) is ON. Conversely if the guide fibre backillumination is on but the spectroscopic fibre backillumination has failed then the control system is unable to prevent attempted movement of a fibre.
CENTROID Find the centroid of the image currently seen by the fibre viewing system of the robot gripper. Reports the position in microns from the centre of the tv.
DIAGNOSTICS As for the command issued at the OS/9 level. This command is generated by running a subprocess to run the diagnostics.c program at the OS/9 level.
DISABLEFIBRE n Temporarily disable spectroscopic fibre n from use. This command may be reversed using the ENABLEFIBRE command. Once disabled it is not possible to move the fibre, view the fibre or perform any actions with the fibre. Note that disabling a fibre MAY make target fields already configured illegal. The park and circle configurations are automatically regenerated when a fibre is disabled.
DISABLEGUIDE n Temporarily disable guide fibre n from use. This command may be reversed using the ENABLEGUIDE command. Once disabled it is not possible to move the fibre, view the fibre or perform any actions with the fibre. Note that disabling a fibre MAY make target fields already configured illegal. The park and circle configurations are automatically regenerated when a guidefibre is disabled.
ENABLEFIBRE n Enable use of spectroscopic fibre n. This command reverses the effect of the DISABLEFIBRE command which temporarily disabled the fibre. Range 1-number of fibres in the current fibre module, this command will only work on spectroscopic fibres. The park and circle configurations are automatically regenerated when a fibre is enabled.
ENABLEGUIDE n Enable use of guide fibre n. This command reverses the effect of the DISABLEGUIDE command which temporarily disabled the fibre. Range 1-number of fibres in the current fibre module, this command will only work on guide fibres. The park and circle configurations are automatically regenerated when a fibre is enabled.
EXTENDED This command is not listed in the help menu system, once used this command allows the used of a few dangerous commands. A password is required for successful completion of this command. The extended command mode remains in force until the RESTRICTED command below) is given.
EXTRACT Extract the robot from an X or Y limit switch. The robot checks if the robot is in a limit switch and is necessary overrides the limit switch to restore power to the motors and drive the robot out of the limit switch before removing power. The robot must then be powered up and initialised in the normal manner. This command is most likely to be used if the WAKE command fails due to the motor power failing to turn on when the robot is left in a limit switch.
GRIPPER state Change the gripper jaws status to the state supplied, state may be either OPEN or CLOSED.
HARDRESET Perform full reset of software flags and VME hardware. The motors and instrument power will be swtiched off and a full reinitialisation will be required.
HEALTH Send a health monitor message to the application layer to test the response.
HELP commandname Access the engineering help menu. Commandname is an optional commandname for which more detailed information is required. Leaving out the commandname means that a one line summary of all commands will be listed.
ITERATIONS n Set the maximum muber of retries allowed in the fibre placement process, range is 0-9, default value is set on starting up the control system in the af2params.dat file.
INIT Initialise the off axis probe and robot in that order. Instrument and motor power must be on.
KILLFIBRE n Permanently remove spectroscopic fibre n from use. This command may only be reversed by manually editing the current fibres data file record for the fibre. After using this command it will be impossible to use the robot to park or otherwise move the fibre.
KILLGUIDE n Permanently remove guide fibre n from use. This command may only be reversed by manually editing the current fibres data file record for the fibre. After using this command it will be impossible to use the robot to park or otherwise move the fibre.
LASTERROR As for the command issued at the OS/9 level. This command is generated by running a subprocess to run the lasterror.c program at the OS/9 level.
LASTMOVE As for the command issued at the OS/9 level. This command is generated by running a subprocess to run the lastmove.c program at the OS/9 level.
LIGHTS state Turn the internal inspection lights to state (ON or OFF). WARNING ensure that the Westinghouse TV is not powered up or serious damage could result.
LOADFIBRE n flag Update the position of fibre n in memory and on disk. flag determines the method used to determine the fibre position. Flag = 0, it is assumed that the fibre has been centred in the gripper tv system by moving the robot and therefore the current robot position is used as the current fibre position. Flag = 1, it is assumed that the fibre is currently visible in the gripper tv system but the position is determined by centroiding the image and adding the offsets from the centre of the tv to the current gripper tv position. Flag = 2, it is assumed that the robot has been moved to the last known position of the fibre and that it may not be visible, a spiral search covering an area of approximately 5mm by 5mm is conducted which stops if a fibre image is found which does not correspond to another known fibre. The fibre image position is determined using a centroid and this position used to update the fibre records.
LOADMODULE Check and update the position of all the usable fibres (i.e. not dead or disabled) in the current fibre module. This command may take a while (20-30 minutes).
LOCAL Set the control system to accept action commands from the engineering interface only, status requests may still be made from the utility network, no parameters.
LOGGING state Switch the placement accuracy logging to state (ON or OFF).
MONITOR As for the command issued at the OS/9 level. This command is generated by running a subprocess to run the monitor.c program at the OS/9 level.
MOTORS state Switch the motor power to state (ON or OFF). If the instrument power is required to be turned on then this will be done automatically.
MOVEFIBRE n x y Move fibre n to x,y using the robot after checking that this will not cause a collision.
MOVEPROBE p Move the off axis probe to position p. Range is 0-150000 with 0 being fully out of the field and 150000 being fully into the edge of the field. In reality only the two extreme positions are of any use.
MOVEROBOT x y Move the robot gripper to position x,y in microns. Range of parameters is size of patrol area of the robot. values???
NETRESET Reset the network layer software error counters. See the results by entering the DIAGNOSTICS command to display the current network layer diagnostics information.
OFFSETFIBRE n dx dy Offset fibre n by dx,dy microns. Check that this will not cause a collision and move the fibre.
OFFSETROBOT dx dy Offset the robot by dx,dy microns. Range of dx,dy is -2000 to 2000. Larger offsets should be done using a MOVEROBOT command. If it is attempted to move the robot outside its allowed area using this command an error will be returned.
PARKFIBRE n Park fibre n using the robot after checking that this will not cause a collision.
PARKROBOT Park the robot out of the field.
POWER state Switch the instrument power to state (ON or OFF). If the motor power is required to be turned off then this will be done automatically.
QUADRANT n Move the fibre viewing system so that it is viewing and adjacent (but overlapping) section of the fieldplate to that currently being viewed. If we assume that the current position is surrounded by 8 equal area sections of fieldplate (as in a 3 by 3 grid) then the top left section is quadrant 1 and the sections are numbered in clockwise order. Range of n is 1-8. If this command is to be used for searching for fibres it is recommended that a sequence of commands to patrol a spiral search area is written down.
QUIT Exit from the engineering interface, no parameters.
RANDOM fibno number This command gets the robot to measure the position of fibre fibno a total of number times moving to a random position between each measurement. Results are appended to a file random.dat in the /h0/autofib/logfiles directory.
RECOVER This command should be used directly after a pickup or putdown failure in order to recover and check the location of the last fibre that was moved, no parameters. If a fibre is recovered successfully the internal fiberror flag is reset allowing further fibres to be moved.
REFERENCE Measure the positions of the four reference fibres in the fieldplate. This command has no real use at present. Results are appended to file reference.dat in the /h0/autofib/logfiles directory.
REMOTE Set the control system to accept action commands from the utility network only, status requests may still be made from the engineering interface, no parameters.
RESETCURRFIB Reset the current fibre variable fibre_no (see section 3.4) This command is dangerous in that it is this variable which limits the movement of the robot while it thinks it is carrying a fibre and prevents the robot trying to pickup a second fibre. It may be necessary to use this command if a failure has occurred leaving a fibre stuck in that jaws as the automatic recover command will not work with a fibre stuck in that jaws. in this case place the fibre on the plate using low level restricted commands then use the RESETCURRFIB command and then the normal RECOVER command.
RESETLOSTFLAG Reset the lost fibre flag fibre_error (see section 3.4) This command is dangerous in that it is only this variable which prevents further fibres being moved if a previous fibre has been lost.
RESTRICTED This command removes access to dangerous commands granted by the EXTENDED command (above). The restricted command mode is the default on starting the engineering interface.
RINGFIBRE n Tell the application layer that fibre n has been manually placed in the load ring. Note that using this command without actually moving the fibre in question could seriously compromise the anticollision software and result in damage to the instrument.
RLOG As for the command issued at the OS/9 level. This command is generated by running a subprocess to run the rlog.c program at the OS/9 level.
SETMIMIC n Set the current engineering mimic display page to n in the range 0-5.
Page 0 null page
Page 1 live video from robot
Page 2 basic text information
Page 3 advanced text information
Page 4 graphical display
Page 5 zoomed in view of graphical display
SETSERVO axis speed accl This command changes the current servo loop parameters for the axis specified, the other two parameters required are the new speed in microns/s and the new acceleration in microns/s/s. There is an upper limit built into the micro code that prevents speeds and acceleration exceeding the maximum tested values being used.
SETUP target Move all the fibres to the configuration described in the file target.fib. If necessary obtain this file from the Vax observing system computer. This command may take upto 30 minutes to complete.
SETVIDEO mode threshold Set the current gripper tv video mode, mode may be either THRESHOLD, NORMAL or INVERSE, for threshold and inverse mode the value of the threshold is required between 0 and 255. Currently NORMAL video mode is used by default.
SLEEP Put the robot into normal hibernation mode, park the robot but leave the offaxis probe in its current position (in case autoguiding is necessary) then switch off the motor and instrument power.
STATIC fibno number This command gets the robot to measure the position of fibre fibno a total of number times withoutmoving the robot between each measurement. Results are appended to a file random.dat in the /h0/autofib/logfiles directory.
STOPSETUP This command sends an immediate STOP the current field setup command to the application layer, if the robot is currently configuring the next target field it will stop at the next safe opportunity (i.e. when the current fibre has been placed).
TELL_LOG Inquire and report the current state (on or off) of the fibre placement accuracy logging, no parameters.
TELL_TRANSFORM Inquire and report the current scale and orthogonality parameters for the robot.
TELLFIB n Inquire and report the status of a fibre. The fibre number n must be supplied in the range 1- number of fibres in the current fibre module.
TELLMIMIC Inquire and report the current active engineering mimic page, no parameters.
TELLPOS Inquire and report the robot and probe positions, no parameters.
TELLSERVO Inquire and report the current DC servo loop parameters for each axis, no parameters.
TELLSOURCE Inquire and report the current command source, no parameters.
TELLSTAT Inquire and report the instrument status, no parameters.
TELLTEMP Inquire and report the current instrument temperature, no parameters.
TELLVIDEO Inquire and report the current fibre viewing frame grabber mode, no parameters.
TLOG As for the command issued at the OS/9 level. This command is generated by running a subprocess to run the rlog.c program at the OS/9 level.
TMOVE t Rotate the theta axis to position t. Note that this command is available in extended command mode only (see EXTENDED/RESTRICTED commands) and is potentially hazardous to the instrument. This command will only appear in the help menu if the engineering interface is in extended mode.
TOLERANCE n Set the fibre placement accuracy tolerance to n microns, range allowed is 0-60 microns, default value is set on starting up the control system in the af2params.dat file.
VIEWFIBRE n Move the gripper/fibre viewing system to the location of fibre n. Range of n is 1-number of fibres. Missing, disabled or dead fibres may return an error.
VIEWFIDUCIAL n Move the mobile sky viewing probe to the position of spare fiducial object n. Before sending a message to the application layer 900 is added to the object number as the spare fiducials are recognised by nuumbers in the range 901-950. Range for object number is 1-50 but an individual target field may have fewer than 50 spare fiducual objects.
VIEWOBJECT n Move the mobile sky viewing probe to the position of the object entering fibre n. Range 1-number of fibres in the current module.
VIEWSKY x y Move the robot carriage so that the mobile sky viewing probe is located at the x,y position supplied.
WAKE Perform a normal initialisation sequence for the robot, power up the instrument and motors, initialise the offaxis probe then the robot. No parameters.
WHICHFIBRE Report which fibre a setup or loadmodule failed on.
ZMOVE z Move the gripper Z axis to position z. Note that this command is available in extended command mode ony (see EXTENDED/RESTRICTED commands) and is potentially hazardous to the instrument. This command will only appear in the help menu if the engineering interface is in extended mode.
To access the area of memory it is necessary for a program to open the data module, an address to the beginning of the pointer is returned on successful completion. It is then necessary to calculate a pointer to the beginning of the useful memory, this calculation must be the same whether data is being read from or written to the memory.
Each data module has a variable size block of header information at the beginning and a a fixed length trailer at the end of the data module. Because of the variable size of the header information it is simplest to calculate the start of useful memory by working from the end of the data module and counting back to the start of the useful memory knowing the amount of memory requested. More information about the structure and properties of data modules may be found in the OS/9 technical reference manual.
After getting the address of the start of the data module, it is possible to get the address of the start of the module name (which is at the start of the trailer information) by adding the address of the start of the data module to the offset to the module name. This offset is always kept in a specified position in the module header (offset 0x0c from the beginning of the data module).
Once the address of the beginning of the name of the module is known, the beginning of the useful memory may be calculated by subtracting the size the data module was created with.
Example:
addr is the address of the beginning of the data module.
ptr is a pointer to an integer.
offset is the offset to the name of the data module.
startmem is a pointer to the start of useful memory.
size is the size in bytes that the data module was created with.
0x0c is the location of the offset to the name of the module (defined number)
ptr = (int *)(addr +0x0c) calculate pointer to the address of the name
offset = *ptr get value of offset
startmem = (char *)(addr +offset -size) calculate start of useful memory
The following data modules RTABLE, RBUFFER, ATABLE, TTABLE, MTABLE, TLOGTABLE, RLOGTABLE, ERTABLE, ETTABLE and COMMANDQ are all created identically for use in a fifo manner and will now be described together with slight differences in use noted later.
These data modules are all created assuming the use of two counters (each short integers or two bytes) and twenty entries each of 256 bytes. The first two bytes of useable memory are used to store the pointer to the next free entry, this is initialised to 1 and incremented everytime a message is added wrapping back to 1 when the end of the table is reached. The second two bytes are used to store the size of the queue of messages in the data module, this is initialised to 0 and incremented everytime a message is added to the datamodule and decremented everytime a message is removed. The remainder of the useful memory is used to store upto 20 messages of upto 256 characters each as a simple string of characters. Regardless of the length of the message it is assigned 256 bytes so that it is simple to find the first character in the message by simply offsetting by 4+((n-1)256) bytes for the nth message.
MTABLE, RLOGTABLE and TLOGTABLE use the usual fifo operation except that messages are never removed from the data module, as new messages are added the oldest message in the table is simply overwritten if there are no free entries.
TTABLE is created in the same manner as the fifo data modules, but its contents are used in a different manner for random access. The data module is created with 4 bytes for counters and 256 bytes for each of twenty messages. The pointer to the next free message is not used but the size counter is used to record how many messages are currently in the data module waiting for transmission. A pointer to each message may be calculated as before by offsetting from the start of useable memory by 4+((n-1)256) bytes for the nth message, but the message is not stored as a simple string of characters.
The contents of each message entry in the data module is now described, the reader is also referred to the table below. The first byte of each entry is a flag to indicate if the entry is currently in use, 0 for empty, 1 for in use. The second byte is a status flag to indicate the current status of a message, 0 indicates that the message has never been transmitted before, 1 indicates that the message has been transmitted at least once before. The next four bytes are not used (in forth systems this is the address of the copy status variable). The next four bytes are a four character string containing the message identification number. The next four bytes are an integer containing the time of next transmission. The next four bytes are an integer containing the number of transmissions left. Bytes 19 to 43 contain the destination of the message with a byte count of the length of the destination in the first byte. The next two bytes contain the message type. The next four bytes contain an integer representing the length of the data field. The actual message data is stored in bytes 50 upwards to the end of the entry.
The remaining data modules (PROCDATA, AF2_STATUS and NET_DIAGNOSTICS) are simple lists of information with a particular piece of information always being stored as a character or integer in the same location within the data module and accessed by a fixed offset within the data module.
Name Offset Function Notes (bytes) 0 FLAG 1 byte binary value STAT_OFF 1 STATUS 1 byte binary value ADDR_OFF 2 Address of copy status Not used variable ID_OFF 6 ID Number 4 bytes ascii TONT_OFF 10 Time of next transmission 4 byte integer NOTL_OFF 14 Number of transmissions left 4 byte integer DEST_OFF 18 Destination, byte count in Upto 24+1 bytes first byte TYPE_OFF 43 Message type 2 bytes ascii DATALEN_OFF 45 Length of data field 4 byte integer DATA_OFF 49 Data field ascii string
Format of TTABLE datamodule
PROCDATA is created with a size of 200 bytes to enable is to contain eight 25 byte strings each containing a identification string and a value containing either the process id or a zero date value as in the following table.
Entry Bytes Content number 1 0-24 ZERODATE datestring 2 25-49 WRITETASK process id 3 50-74 RECEIVETASK process id 4 75-99 READTASK process id 5 100-124 WATCHDOGTASK process id 6 125-149 CONTROLTASK process id 7 150-174 COMMANDINTRPTASK process id 8 175-199 ESDRAVETASK process id
NET_DIAGNOSTICS is created with a size of 200 bytes, sufficient to contain a list of 50 integer values as counters for various errors in the network layer software although only 21 are currently used. The various counters are accessed by fixed offsets from the start of useable memory as in the following table.
Error Explanation Offset (bytes) 0 READERR Number of read errors 4 WRITERR Number of write errors 8 NOT_EXPECT_SYN SYN char not expected 12 NOT_EXPECT_EOT EOT char not expected 16 TOO_LONG Message too long (>256) 20 NOT_ALLOWED Illegal character received 24 RBUFFER_FULL Number of times rbuffer has filled 28 NRMESS Number of received messages 32 NRHEADERR Number of received messages with header errors 36 NRACKN Number of acknowledgements received 40 NRACKBFR Number of acknowledgements received before 44 NRBRDCST Number of received broadcasts 48 NRMESBFR Number of messages received before 52 RTABLE_FULL Number of times rtable has filled 56 NTFIRST Number of messages transmitted for the first time 60 NTWRMESS Number of messages for transmission with header errors 64 NTBRDCST Number of broadcasts transmitted 68 NTLINKFAIL Number of transmitted messages not acknowledged. 72 NTMESS Number of messages transmitted 76 NTACKN Number of transmitted acknowledgements 80 NXCHAR Number of transitions from not transmitting to transmitting state
The final data module AF2_STATUS is created with a size of 10100 bytes, this may be broken down as 100 integer status values, 4 strings of 25 characters and upto 160 strings of 60 characters.
The 100 integer status values represent the various parameters of each mechanism within the instrument. The four strings of upto 25 characters are the names of remote nodes that have logged into the Autofib control system in monitor mode. The 160 records each 60 characters long each contain a string with information about a particular fibre. The 100 integer status values are defined in the following table, they are grouped by mechanism. Note that three items are not integer but use two integers (8 bytes) as these are in fact double precision floating point numbers (these are the three PER parameters).
Offset Name Parameter (Integer) 0 CON_CMD CON command error 1 CON_MECH mechanism error 2 CON_STAT current status 3 CON_SEC seconds to completion 4 CON_ACCURACY rms accuracy 5 CON_NFIDS number of spare fiducials defined 6 BCK_CMD BCK command error 7 BCK_MECH mechanism error 8 BCK_STAT back illumination status 9 LGT_CMD LGT command error 10 LGT_MECH mechanism error 11 LGT_STAT current inspection lights status 12 POW_CMD POW command error 13 POW_MECH mechanism error 14 POW_PWRSTAT current instrument power status 15 POW_MTRSTAT current motor power status 16 MID_CMD MID command error 17 MID_MECH mechanism error 18 MID_ID current fibre module identification 19 MID_NPIV number of pivots defined 20 MID_NSPEC number of spectroscopic fibres 21 MID_NGUIDE number of guide fibres 22 MID_UNUSED number of empty pivots 23 PRO_CMD PRO command error 24 PRO_MECH mechanism error 25 PRO_POS probe position 26 PRO_INITSTAT probe initialising status 27 PRO_LIMIT probe limit switch status 28 ROB_CMD ROB command error 29 ROB_MECH mechanism error 30 ROB_XPOS robot gripper x position 31 ROB_YPOS robot gripper y position 32 ROB_ZPOS robot gripper z position 33 ROB_TPOS robot gripper theta position 34 ROB_XVIEW mobile probe x sky viewing position 35 ROB_YVIEW mobile probe y sky viewing position 36 ROB_XLIM robot x limit switch status 37 ROB_YLIM robot y limit switch status 38 ROB_GRIP gripper jaws status 39 ROB_TOL current fibre placement tolerance 40 ROB_ITER current maximum number of iterations 41 ROB_INIT robot initialising status 42 SER_CMD SER command error 43 SER_MECH mechanism error 44 SER_XYSP xy maximum speed 45 SER_ZSP z speed 46 SER_TSP theta speed 47 SER_PSP probe speed 48 SER_XYACC xy maximum acceleration 49 SER_ZACC z acceleration 50 SER_TACC theta acceleration 51 SER_PACC probe acceleration 52 CEN_CMD CEN command error 53 CEN_MECH mechanism error 54 CEN_XOFF tv x offset of fibre centroid 55 CEN_YOFF tv y offset of fibre centroid 56 VID_CMD VID command error 57 VID_MECH mechanism error 58 VID_THRESHFLAG current gripper tv mode 59 VID_THRESHVAL current tv lut threshold value if needed 60 ESD_CMD ESD command error 61 ESD_MECH mechanism error 62 ESD_PAGE current engineering mimic page number 63 SRC_CMD SRC command error 64 SRC_MECH mechansim error 65 SRC_CURR current command source 66 FIB_CMD FIB command error 67 FIB_MECH mechanism error 68 FIB_N fibre number 69 FIB_STAT fibre status 70 FIB_PIVX pivot x 71 FIB_PIVY pivot y 72 FIB_FIBX fibre x 73 FIB_FIBY fibre y 74 FIB_THETA fibre theta 75 FIB_XERR fibre x placement error 76 FIB_YERR fibre y placement error 77 TMP_CMD TMP command error 78 TMP_MECH mechanism error 79 TMP_TEMP current instrument temperature 80 PER_CMD PER command error 81 PER_MECH mechansim error 82 PER_XSCALE x axis encoder scale 83 " 84 PER_YSCALE y axis encoder scale 85 " 86 PER_ORTHO xy axis non-orthogonality 87 " 88 LOG_CMD LOG command error 89 LOG_MECH mechansim error 90 LOG_STATE Current placement accuracy logging state 91 FNO_CMD FNO command error 92 FNO_MECH FNO mechanism error 93 FNO_FIBNO FNO fibre number 94 not used 95 not used 96 not used 97 not used 98 MON_CMD MON command error 99 MON_NUMB number of nodes logging in monitor mode
The four 25 character strings are used to store the names of nodes logged in to the Autofib control system in monitor mode, if a node logs out from monitor mode the string is cleared and MON_NUMB is decremented.
The remaining 160 strings 60 characters long store the current information about each fibre, this information is read in when the instrument is powered up and updated everytime a fibre is moved. The information is simply a list of numbers separated by spaces. When the information is requested for a particular fibre the correct record is copied to the FIB mechanism area of AF2_STATUS and accessed in the normal way to other mechanisms.
Network message command types recognised are:
100 Abort action
101 Request action of mechanism
102 Initialise mechanism
200 Request immediate status return from mechanism
201 Request delayed status return when action on mechanism is complete
Network message status returns have the following types.
800 Immediate status return in response to ISTAT (code 200)
801 Delayed status return issued to a node when an operation completes in response to a delayed status request (code 201) from that node.
802 Unexpected movement of mechanism
803 Initiation message issued to any node on the monitor node list at the beginning of an operation that takes an appreciable time to complete.
804 Completion message issued to any node on the monitor node list on completion of an action.
Autofib-2 consists of the logical mechanisms describes in the following table. A number of these mechanisms are not recognised by the Observing system Dtask as they are only accessable from the engineering interface.
Mechanism Description BCK guide fibre back illumination CEN Centroid CON Configure a field ESD Engineering status display FIB Fibre information FNO Fibre number problems last occurred at HMS Health monitor LGT Inspection lights LOG Fibre placement logging MID Fibre module MON Monitor mode list NET Network layer reset PER Orthogonality and encoder scales POW Instrument and motor power PRO Off axis probe RES Reset parts of application layer ROB Robot positioner SER Servo parameters SRC Current command source TMP Instrument housing temperature VID Gripper frame grabber
The allowed network messages and their format is now described in detail for each mechanism in the above table.
BCK: Guide fibre back illumination
Commands BCK101(c1)/200/201
where c1 is the required status of the back illumination (ON or OFF)
Returns BCK800/801/803/804(p1,p2,p3)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is current status of back illumination in string format (ON or OFF)
CEN: Centroid gripper tv image
Commands CEN101/200/201
Returns CEN800/801(p1,p2,p3,p4)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is x offset of fibre image from centre of tv (in microns)
p4 is y offset of fibre image from centre of tv (in microns)
CON: Configure new target field
Commands CON101(c1)/100/200/201
where c1 is a string containing the new target field filename (no extension)
Returns CON800/801/803/804(p1,p2,p3,p4,p5,p6)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is status string, FINISHED,PROCESSING,MOVING or ABORTED
p4 is an estimate of the number of seconds to complete configuration
p5 is the final rms positioning error in microns
p6 is the number of spare fiducial objects in target field
ESD: Change display page of engineering status display
Commands ESD101(c1)/200/201
where c1 is the page number of the required page of the engineering mimic
Returns ESD800/801(p1,p2,p3)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the current displayed page
FIB: Set /report fibre details
Commands FIB101(c1,c1)/200(c1)/201(c1)
where c1 is the fibre number
c2 is the new value for the fibre status to be changed
Returns FIB800/801/803/804(p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the fibre umber
p4 is the fibre status value
0 missing
1 spectroscopic fibre
2 guide fibre
3 disabled spectroscopic fibre
4 disabled guide fibre
5 dead spectroscopic fibre
6 dead guide fibre
p5 is the fibre pivot x coordinate in microns
p6 is the fibre pivot y coordinate in microns
p7 is the fibre tip x coordinate in microns
p8 is the fibre tip y coordinate in microns
p9 is the fibre button theta coordinate in arcmin
p10 is the fibre x position error in microns
p11 is the fibre y position error in microns
FNO: Report number of fibre that caused problems during a target field setup, load module etc.
Command FNO200
Returns FNO800(p1,p2,p3)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the number of the fibre that caused problems (or zero)
HMS: Health monitor response
Command HMS200
Returns HMS800(p1,p2)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
LGT: Inspection lights
Commands LGT101(c1)/200/201
where c1 is the required state of the inspection lights (ON or OFF)
Returns LGT800/801/803/804(p1,p2,p3)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the current state of the inspection lights (ON or OFF)
LOG: Fibre positioning logging behaviour
Commands LOG101(c1)/200/201
where c1 is the required state of logging (ON or OFF)
Returns LOG800/801(p1,p2,p3)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the current state of logging (ON or OFF)
MID: Fibre module interrogation
Commands MID200
Returns MID800(p1,p2,p3,p4,p5,p6,p7)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the name of the fibre module (SMALL, LARGE, SPECIAL or NONE)
p4 is the number of pivots (max number of allowed fibres)
p5 is the number of spectroscopic fibres
p6 is the number of guide fibres
p7 is the number of missing fibres
MON: Monitor mode logging in/out
Commands MON101(c1)/200/201
where c1 is the required state of monitor mode (0 or 2 supported)
Returns MON800/801(p1,p2)
where p1 is two digit hexadecimal command error
p2 is the monitor mode level for the node requesting the information
NET: Network layer reset
Commands NET101
Returns none
PER: XY carriage orthogonality and scales
Commands PER200/201
Returns PER800/801(p1,p2,p3,p4,p5)
where p1 is a two digit hexadecimal command error
p2 is a two digit hexadecimal mechanism error
p3 is the current value of the xscale variable
p4 is the current value of the yscale variable
p5 is the current non-orthogonality
POW: Instrument and motor power
Commands POW101(c1,c2)/200/201
where c1 is the required status for the instrument power (ON or OFF)
c2 is the required status for the motor power (ON or OFF)
note that not all combinations are allowed, for instance instrument power must be ON to turn on motor power and turning OFF instrument power means that motor power will be turned OFF as well.
Returns POW800/801/803/804(p1,p2,p3,p4)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the instrument power status (ON or OFF)
p4 is the motor power status (ON or OFF)
PRO: Off axis probe
Commands PRO101(c1)/102/200/201
where c1 is the required probe position (0 -150000) where 0 is fully out of the field.
Returns PRO800/801/802/803/804(p1,p2,p3,p4,p5)
where p1 is two digit hexadecimal command error
p2 is two digit hexadecimal mechanism error
p3 is the current probe position in microns
p4 is the status of the probe
0 is no initialised
1 is initialising
2 is initialised
p5 is the limit switch status
-1 probe is in reverse limit
1 probe is in foward limit
0 probe is ok
9 probe is showing excessive position error
RES: Application layer reset mechanism
Commands RES101(c1)
where c1 is the level of reset required (1,2,3)
Returns none
ROB: Robot positioner control
Commands ROB101(c1,c2,c3,c4)/102/200/201
where c1 is a four character code for the action required of the robot
c2 is an integer parameter
c3 is an integer parameter
c4 is an integer parameter
The use of the 3 integer parameters is dependant on the character code defining the action to be taken. More detail of the character codes and parameters is given in the table below.
Returns ROB800/801/802/803/804(p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14)
where p1 is a two digit hexadecimal command error
p2 is a two digit hexadecimal mechanism error
p3 is the x position of robot (microns)
p4 is the y position of the robot (microns)
p5 is the z position of the robot (encoder counts)
p6 is the theta position of the gripper (arcmin)
p7 is the x posiiton of the mobile probe (microns)
p8 is the y position of the mobile probe (microns)
p9 is the x axis status (-1,0,1,9 as for the probe above)
p10 is the y axis status (-1,0,1,9 as for the probe above)
p11 is the gripper jaw status string (OPEN or CLOSED)
p12 is the positioning tolerance in microns
p13 is the max number of iterations
p14 is the initialised status (0,1,2 as for the probe above)
SER: DC servo loop speed and acceleration
Commands SER101(c1,c2,c3)/200/201
where c1 is the axis to apply the new speed and acceleration to (X,Y,Z,T,P)
c2 is the required speed (micron/s)
c3 is the required acceleration (micron/s/s)
Returns SER800/801(p1,p2,p3,p4,p5,p6,p7,p8,p9,p10)
where p1 is a two digit hexadecimal command error
p2 is a two digit hexadecimal mechanism error
p3 is the x,y maximum speed (micron/s)
p4 is the z maximum speed (count/s)
p5 is the theta axis maximum speed (count/s)
p6 is the off axis probe maximum speed (count/s)
p7 is the x,y acceleration (microns/s/s)
p8 is the z acceleration (count/s/s)
p9 is the theta acceleration (count/s/s)
p10 is the probe acceleration (count/s/s)
SRC: Command source
Commands SRC101(c1)/200/201
where c1 is the required source for commands (LOCAL or REMOTE)
Returns SRC800/801(p1,p2,p3)
where p1 is a two digit hexadecimal command error
p2 is a two digit hexadecimal mechanism error
p3 is the current command source (LOCAL or REMOTE)
TMP: Instrument temperature sensor
Commands TMP200
Returns TMP800(p1,p2,p3)
where p1 is a two digit hexadecimal command error
p2 is a two digit hexadecimal mechanism error
p3 is the instrument temperature (floating point number, one decimal place, degrees Celsius
VID: Gripper tv video mode
Commands VID101(c1,c2)/200/201
where c1 is the required video mode (NORMAL, THRESHOLD or INVERSE)
c2 is an integer parameter for the threshold intensity
Returns VID800/801(p1,p2,p3,p4)
where p1 is a two digit hexadecimal command error
p2 is a two digit hexadecimal mechanism error
p3 is the current video mode string
p4 is the current threshold intensity value
Table of actions for robot mechanism
c2,c3,c4 are the integer parameters supplied as part of the network message, if none are required or not all three are required then the unused parameters should be supplied with a value of zero.
Robot action Meaning of action code Parameters required code (c1) EXTR Extract robot from xy none limit ITER Set number of c2 = number of iterations iterations JAWS Move gripper jaws c2 = jaw state (0 = open, 1 = closed) LMOD Load fibre module none LOAD Load fibre c2 = fibre number, c3 = flag (0,1,2) MFIB Move fibre to new x,y c2 = fibre number, c3,c4 = new x,y MOVE Move robot to new xy c2 = new x, c3 = new y OFIB Offset fibre by dx,dy c2 = dx, c3 = dy OSET Offset robot by dx,dy c2 = dx, c3 = dy PARK Park robot safely none PFIB Park fibre out of field c2 = fibre number QUAD Offset robot into c2 = square number to offset robot adjacent (1-8) square RALL Inform software that none all fibres are in load ring RAND Perform random moves c2 = fibre number, c3 = no. of with centroids to test moves repeatability of robot c4 = flag (0 = static centroids, 1 = random movements between centroids) RCVR Recover last fibre to none be lost REFF Measure reference none fibres RING Inform software that c2 = fibre number fibre is in load ring TMOV Move theta axis c2 = new theta position TOLR Change position c2 = new tolerance (microns) tolerance VFIB Move gripper over fibre c2 = fibre number VOBJ Move mobile probe over c2 = fibre or object number fibre or object VSKY Move mobile probe to c2 = x, c3 = y x,y ZMOV Move Z axis c2 = new Z position