intrref.doc
DRAFT COPY 12/27/89 UPDATED 3/3/90 PROGRAMMER'S REFERENCE HPC INTERFACE 3/30/90 CONTENTS COMMUNICATIONS 4 PC TO HPC MESSAGES 4 HPC TO PC MESSAGES 5 COMMAND QUEUEING 6 LOW LEVEL COMMUNICATIONS CONSIDERATIONS 6 MOVE ROBOT 8 MOVE SPEEDS AND SONAR CONSIDERATIONS 8 ROTATE THEN MOVE ROBOT 8 ROTATE THEN MOVE ABORT MESSAGES 9 ARC MOVES 9 ARC MOVES ABORT MESSAGES 10 MOVE SUCCESS MESSAGES 11 MOVE CANCEL BYTE 11 MOVE ABORT MESSAGE SONAR BYTE 11 MOVE ABORT AND ERROR CODES 12 SELF TEST 13 EXTENSIVE TEST 14 SELF TEST CANCEL BYTE 14 SELF TEST ABORT MESSAGES AND CODES 15 LIGHTS 15 LIGHTS CANCEL BYTE 16 TURN A SPECIFIC LIGHT ON/OFF 16 TURN ALL LIGHTS ON/OFF 17 TURN EYES ON/OFF 17 LIGHTS RETURN MESSAGES AND CODES 17 CONTROL 17 PAUSE CATEGORY 17 PAUSE RETURN MESSAGES AND CODES 18 CONTINUE CATEGORY 18 CONTINUE RETURN MESSAGES AND CODES 18 FORCE READ INTERNAL 19 FORCE READ INTERNAL ERROR MSGS AND CODES 19 TILT ENABLE 19 TILT ENABLE ERROR MESSAGES AND CODES 19 CANCEL NOP 20 CANCEL NOP RETURN MESSAGES AND CODES 20 SONAR ENABLE/DISABLE 20 SONAR ENABLE/DISABLE RETURN MESSAGES & CODES 21 SONAR ON/OFF 21 SONAR ON/OFF RETURN MESSAGES AND CODES 21 REMOTE CONTROL ON/OFF 21 REMOTE ON/OFF RETURN MESSAGES & CODES 22 SET REMOTE CONTROL ADDRESS 22 SET CONTROL ADDRESS RETURN MESSAGES & CODES 22 SET REMOTE CONTROL DUPLICATE FILTER 23 SET DUP FILTER RETURN MESSAGES AND CODES 23 SEND REMOTE CONTROL KEYSTROKE 23 SEND REMOTE CONTROL RETURN MESSAGES & CODES 23 REMOTE CONTROL DATA WORD FORMAT 24 INDIVIDUAL SONAR ENABLE/DISABLE 24 INDIV ENABLE/DISABLE RETURN MESSAGES & CODES 25 INDIVIDUAL ENABLE/DISABLE CANCEL BYTE FORMAT 25 SET SONAR LIMIT 25 SET SONAR LIMIT RETURN MESSAGES AND CODES 25 SET SONAR LIMIT CANCEL BYTE FORMAT 26 SET INFRA-RED REFERENCE 26 SET IR REF CANCEL BYTE FORMAT 26 SET IR REF RETURN MESSAGES AND CODES 26 HEAD CALIBRATION ENABLE/DISABLE 27 HEAD CAL EN/DISABLE RETURN MESSAGES & CODES 27 READ INTERNAL 27 READ INTERNAL RETURN MESSAGES AND CODES 28 READ INTERNAL DATA BYTE DESCRIPTIONS 28 READ TEMPERATURE 28 READ BATTERY 28 READ TILT 28 READ SMOKE SENSOR 28 READ RAW A/D VALUE 29 READ EXTERNAL 29 READ HEAD SONAR 29 READ HEAD SONAR RETURN MESSAGES AND CODES 29 READ SONAR 30 READ SONAR CANCEL BYTE FORMAT 30 READ SONAR RETURN MESSAGES AND CODES 30 READ INFRA-RED SENSOR 31 SCAN HEAD AND INFRA-RED SENSOR 31 SCAN HEAD AND IR CANCEL BYTE FORMAT 32 SCAN HEAD AND IR RETURN MESSAGES AND CODES 32 READ HEAD POSITION 32 READ LIGHT INTENSITY 33 READ INFRA-RED STATUS 34 MOVE HEAD 34 HEAD SPEEDS AND POSITION ACCURACY 34 MOVE HEAD 35 HOME HEAD 35 MOVE HEAD CANCEL BYTE FORMAT 35 MOVE HEAD RETURN MESSAGES AND CODES 36 BEACON 36 LIGHTSHOWS 37 TURN INDIVIDUAL SHOW ON/OFF 37 SET LIGHT SHOW ORDER 37 TURN ALL LIGHT SHOWS ON/OFF 38 LIGHTSHOW RETURN MESSAGES AND CODES 38 APPENDIX 39 SAMPLE PC TO HPC COMMUNICATIONS PSUEDO CODE 39 COMMUNICATIONS PC TO HPC MESSAGES Messages sent by the PC to the HPC are in the following byte format: 02(STX)/MSG LENGTH/CATEGORY & OPTION/<--- DATA ---->/CANCEL BYTE STX - The receipt of a single Start of Text (02) signifies the start of a message. Other valid two's in the message are differentiated from STX's by sending a second two immediately after the data two. A single two sent without a second always means start of a message. MSG LENGTH - This byte tells the HPC how many bytes are in the message. The message length includes the length byte through the cancel byte. It does not include the STX byte. Any data two is counted as one byte in the message length even though it is doubled in the actual transmission. Since the minimum message includes length, category and option, and cancel bytes, the message length will never be less than three. This always allows the STX to be sent as a single two. CATEGORY & OPTION - The high nibble of this byte is the category number (could also be called the job or task number) that the message is being sent to. The low nibble is the option (command) that is to be performed within the category . DATA - Information required to perform the command. This data may vary in length from 0 to 6 bytes as described in the detailed category and option descriptions. CANCEL BYTE - This is a bit field byte with the bits having the following significance: Bits 0 thru 2 - For move robot and move head commands these bits set the speed from 0 (no movement) thru 7 (highest speed). Other commands may ignore these bits or use them for different purposes. See the detailed category and option descriptions for how these bits are used for a particular command. Bit 3 - The cancel bit from which the byte takes its name. In general, the setting of this bit causes preceding commands, if any, within the same category to be discarded. The command with the cancel bit set will be executed immediately. This bit generally is meaningful to the move robot and move head categories, but other categories may also be affected by the cancel bit. See the detailed category and option descriptions for how this bit may affect a category and option. Bit 4 - The ON/OFF bit. For categories and options using this bit, setting the bit turns something on and resetting (clearing) the bit turns something off. See the detailed descriptions for usage within a specific command. Bit 5 - The LEFT/RIGHT bit. For robot and head move usage. Setting the bit means left, resetting the bit means right. Left and right are as Newton sees them travelling forward. Bit 6 - The CONTINUE bit. At the end of robot or head moves, if this bit is reset (cleared), Newton slows down smoothly to a stop. If the continue bit is set in a following command in the category queue, Newton does not slow down and stop between commands. Setting the continue bit means that the next command in the category queue will be executed smoothly as a continuation of the preceding command. If the currrently executing command is the last command in the queue, the move will come to a controlled stop even if its continue bit is set. This allows a series of continued commands to come to a controlled end. To override the final slowdown of a series if desired, send a final command with the movement data set to zero and the continue bit set. The last command with a movement will see another continue command and will simply shut off the movment motor(s) after the commanded movement is made. The zero movement command will then be processed as successfully completed. Bit 7 - The INTERNAL REQUEST bit. This bit is used internally by the HPC when sending a command from one category (task) to another. THIS BIT MUST NEVER BE SET WHEN SENDING A MESSAGE FROM THE PC TO THE HPC!!!!! Unpredictable results and return messages may occur if the bit is set. Loss of return status messages is almost sure to result from setting this bit. HPC TO PC MESSAGES Messages sent by the HPC to the PC are in the following byte format: 02(STX)/MSG LENGTH/CATEGORY & OPTION/<--- DATA ----> STX - This byte the same as in the PC to HPC communications. See PC to HPC for a description. MSG LENGTH - This byte is the same as in the PC to HPC communications. See the PC to HPC for a description. CATEGORY & OPTION - This byte will be the same as that sent for the message being answered. Commands are answered in the order in which received. It is the responsibilty of the PC programming to maintain order between commands and replies within the same category and option. DATA - From one to six bytes depending upon message. See the detailed category and option descriptions for what is returned in these bytes. COMMAND QUEUEING Messages to the HPC are queued at two levels. The communications interrupt handler first places received bytes into a 128 byte first level queue. A higher level routine that is run on a scan basis as a task processes the bytes from this queue, and when a complete message has been received and assembled, places the message into the category's job queue. Each category has its own 64 byte message queue. If the first level queue is completely filled, and another byte is received, the HPC will echo back the one's complement of the byte when it acknowleges receipt of the byte. This is the only indication of the buffer overflow. The received byte is not otherwise processed, and may be resent without error when the first level queue has room for it. If a category's message queue does not have room for a new message, an error message of the following format will be sent back to the PC: 02(STX)/MSG LENGTH/CATEGORY & OPTION/34(JOB BUFFER FULL ERROR) Once again, the message is discarded, and can be resent when the queue has emptied enough to hold the message. LOW LEVEL COMMUNICATIONS CONSIDERATIONS When the PC sends a byte to the HPC, the HPC non maskable interrupt line is asserted, and the HPC BUSY bit is set (IO port 301 HEX, bit 1). When the HPC is done servicing its interrupt it resets the busy bit. The PC must not send when the busy bit is set or the HPC will not see another interrupt and the interface may lock up waiting for a transmission acknowlege that never comes because the HPC never saw the interrupt. To send a byte to the HPC, first make sure that the HPC busy bit is not asserted, then write a one to port 301H to identify this interrupt as a transmission to the HPC interrupt. Then write the byte being sent to port 300H. When the byte has been sent to the HPC, the HPC will acknowlege receipt of the byte by clearing the interrupt ID bit (IO port 301H, bit 0), and writing the received byte back to the PC at port 300H. Writing the byte back to the port will generate an interrupt (IRQ2) to the PC. The PC then should read the 301H port to see if the interrupt is an echo (ACK) of the last byte written to the PC or a new byte (interrupt ID bit = 1) in a message from the HPC. If the interrupt is an echo, the next byte in the message may then be sent (if the HPC is not busy), or the new HPC to PC byte must be read and processed. WHETHER OR NOT the interrupt is an acknowlege of the last byte sent to the PC or a new message byte, the data port (IO port 300H) must be read once and once only. This tells the HPC that the PC has serviced the interrupt and the HPC can send to the PC again. Not reading the data port will hang communications since the HPC will wait forever without seeing that the PC has serviced the interrupt. Reading the port more than once may clear an HPC interrupt before it actually has been serviced. When a message byte has been received from the HPC, write a 0 to port 301H (check HPC busy first and don't do until HPC not busy) to identify the interrupt as an acknowlege interrupt. Then write the byte received back to port 300H to tell the HPC that you have received the byte. If writing a low level routine to interface with the HPC, remember that data two's are sent twice, and the second two is not included in the message length. See the appendix for psuedo code of a PC to HPC communications interrupt handler. If a message is received with a count byte greater than 10 (no command is longer than this), the message is discarded, and the following error message is returned to the PC: 02(STX)/3/CATEGORY & OPTION/37(MSG TOO LONG ERROR) This error message is sent as soon as the category and option byte is received. The rest of the message is discarded. This means the error message may be sent before completion of the message transmission. If a message is received by a category that has a length different from that expected for the option specified, the message is discarded, and the following error message is returned: 02(STX)/3/CATEGORY & OPTION/36(MSG LENGTH ERROR) If a message is received with an invalid category specified, the message is discarded, and NO error return is provided to the PC. If a message is received with an an invalid option number for the category, the message is discarded, and the following message is returned: 02(STX)/3/CATEGORY & OPTION/35(UNIMPLEMENTED ERROR) MOVE (CATEGORY ZERO) MOVE SPEEDS AND SONAR CONSIDERATIONS Newton moves at the following velocities for the commanded speeds: Speed 1 - 0.59 fps (feet per second) Speed 2 - 0.67 fps Speed 3 - 0.78 fps Speed 4 - 0.92 fps Speed 5 - 1.12 fps Speed 6 - 1.45 fps Speed 7 - 2.03 fps The center lower (drop off) sonar is read once every 0.13 seconds. This means that at speed seven Newton may move 3.2 inches after a drop off is within range before he is aware of the danger. The other sonars are read once every 0.39 seconds, so Newton moves 9.5 inches between sonar updates at speed seven. These figures must be allowed for when programs depend upon Newton's sonar collision avoidance features. OPTION ZERO - ROTATE THEN MOVE ROBOT Command message format: 02(STX)/7/00H/DEGREES LO/DEGREES HI/FEET LO/FEET HI/CANCEL BYTE This command makes Newton rotate about the center point between the drive wheels, and then move in a straight line. When sent with degrees equal zero, it serves as Newton's straight line move command. When sent with feet equal zero, only the commanded rotation occurs. If sent with both feet and degrees zero, and the cancel bit set, it will flush the command queue and stop Newton. Sending the command with zero data and the cancel bit cleared just results in a command executed successfully return message. Positive degree values cause Newton to rotate counter clock wise (left), and negative degrees cause clockwise (right) rotation. The degrees should be limited to 0 through +/- 359. No range checking is done on this value by the HPC, and erroneous moves and return messages could result from exceding the range. Except for the lower center drop off limit, no sonar checking is done during the rotate part of this option. The rotate and move can be used to recover from a sonar collision condition without disabling the sonar unless the condition is caused by the lower center drop off limit as indicated by bit 7 of the abort message sonar byte. The distance to move in the straight line part of the option must be specified in tenths of feet. The value sent can range from +32767 to -32766 with the following results: +32767 sent - Newton keeps on moving indefinitely until a cancel command is received or an error (collision,tilt, or stall) condition is detected. +1 thru +2325 - Newton will move the commanded distance, and then stop. If a cancel is received or an error condition is detected during the move, the move is aborted. +2326 thru +32766 - The distance is truncated to 2325 and handled as above. No notification is sent to the PC of the truncation. 0 sent - No straight line move is done. Newton sees the command as successfully completed. -1 thru -100 - Newton moves the commanded distance in reverse. Since the lower sonars are not pointing in the direction of travel, only 10 feet can be commanded at one time in the negative direction. -101 thru -32766 - The distance is truncated to -100 and handled as above. No notification is sent to the PC of the truncation. ROTATE THEN MOVE ABORT MESSAGES The general form of rotate and move abort messages is: 02(STX)/8/00H/ABORT CODE/DEGREES LO/DEGREES HI/ FEET LO/FEET HI/SONAR Where degrees and feet are the amounts actually moved. See the category zero abort code descriptions for the possible codes returned and the sonar byte description. Any commands pending in the command queue will be canceled if the abort is caused by a tilt, collision, or stall condition. Any commands thus canceled will also send an abort message with the cancel code. OPTIONS ONE AND TWO - ARC MOVES Command message format: 02(STX)/6/01H OR 02H/FEET(1) OR DEGREES(2) LO/FEET OR DEGREES HI /RADIUS/CANCEL BYTE These commands make Newton travel in an arc which would eventually form a circle of the radius commanded. The commands are identical in effect, just specified differently. Using option one, the distance to move in the arc is specified in tenths of feet. Using option two, the distance is specified in degrees of arc. The radius is in tenths of feet, and is always relative to the center point between Newton's drive wheels. Sending an arc move command with a radius of .7 feet will result in a swivel move about the inner wheel. The actual radius is approximately .63 feet for the swivel moves and is set by the HPC programming. A radius of zero causes rotation about the center point between Newton's drive wheels as if it were the first part of the rotate then move command (option 0). However, rotations of more than 359 degrees can be commanded. If a distance arc is commanded with 0 radius, maximum degrees will be used for the arc, i.e. 32767 positive or -32766 if negative. Distance arcs are converted to degrees for execution. If an arc of say 90 degrees is desired, specify the arc in degrees, since distance in tenths of feet may not give the correct arc. For example, a 1.0 foot arc command with .7 (swivel) radius will result in Newton turning approximately 87 degrees. To get a 90 degree turn use the arc degree command. If an arc command is sent to the HPC with a radius between 0 and .7 feet, Newton will swivel about the point within his tread width calculated from the radius commanded. As in the straight line moves, any distance specified that is more negative (Newton commanded to go backwards) than -10.0 feet will be truncated to -10.0 feet without notifying the PC of the truncation. Also, for any combination of radius and distance or degrees that would result in any wheel traveling farther than 232.5 feet, the distance will be truncated to 232.5 feet without notifying the PC. The sign of the commanded distance or arc degrees is used in combination with the LEFT/RIGHT bit of the cancel byte to determine the direction the arc and whether Newton moves forward or backward. See Figure nn. for the effect of different combinations of positive and negative data together with the LEFT/RIGHT bit. ARC MOVES ABORT MESSAGES The general form of arc move abort messages is: 02(STX)/6/01H OR 02H/ABORT CODE/FEET OR DEGREES LO /FEET OR DEGREES HI/SONAR Where feet or degrees are the amounts actually moved. See the category zero abort code descriptions for the possible codes returned and the sonar byte description. Any commands pending in the command queue will be canceled if the abort is caused by a tilt, collision, or stall condition. Any commands thus canceled will also send an abort message with the cancel code. CATEGORY ZERO SUCCESS MESSAGES When a category zero command successfully runs to completion, a success message is returned to the PC in the format: 02(STX)/3/0nH/1 (SUCCESS) Where n is the option number of the command completed. CATEGORY ZERO CANCEL BYTE Bits 0 thru 2 - Speed from 0 thru 7. 1 (slowest) thru 7 (fastest) are valid. Sending 0 with valid data values causes an abort message to the PC and the command is otherwise ignored. Bit 3 - Cancel bit. If set, all previous commands (including the currently executing command), if any, in the category zero job queue are discarded, and the command is executed immediately. Sending a category zero command with cancel set and with zero data values flushes the command queue and stops Newton, and a success message is returned. Stopping Newton using this technique will, however, result in an uncontrolled coast stop, and Newton will probably not stop straight. To make a controlled stop, send a cancel command with the distance set equal to the preceding command's speed. Any and all commands canceled return an abort message indicating that they have been canceled. Bit 4 - ON/OFF bit. This bit is ignored in category zero. Bit 5 - LEFT/RIGHT bit. Used in category zero arc moves. See the arc move descriptions and diagram for the effect of this bit. Bit 6 - Continue bit. Newton normally does a controlled straight line smooth stop at the completion of a command. If any succeding command in the job queue has the continue bit set, Newton does not stop between commands, but continues immediately into the next without stopping. Bit 7 - Always reset. See the bit description in the communication section of this document. ABORT MESSAGE SONAR BYTE DESCRIPTION All category zero abort messages include the sonar detection status packed into a bitfield byte called the SONAR byte. The bits are set for an alarm status or reset for non-alarm status as follows: Bit 0 - Sonar zero has detected an echo closer than its collision alarm distance set point. Bits 1 thru 3 - Same as above for sonars 1 thru 3 respectively. Bit 4 - Sonar zero has detected an echo beyond its drop off alarm distance set point. Bits 5 thru 7 - Same as above for sonars 1 thru 3 respectively. If a sonar has been disabled via the control category enable/disable sonar options, these bits will be invalid for the sonar(s) so disabled. The bits will still be valid for the sonar(s) that are enabled. This byte may be used to determine which sonar has sensed a collision. If the sonars have been turned off using the control category sonar on/off option, these bits are invalid and of no meaning. CATEGORY ZERO ABORT CODES #3 - COLLISION ERROR - Sent when the echo distance for an enabled sonar is below the collision distance set point or beyond the drop off distance set point. Which sonars are in alarm and the type of alarm can be determined by examining the SONAR byte. A collision error also cancels any and all succeding commands in the move job queue. Commands so cancelled each send an abort message with the cancel code. #04 - CANCEL CODE - Command has been canceled by a succeding command with the cancel bit set in the cancel byte, or by a preceding collision abort. All commands in the queue and the currently executing command canceled send this code in an abort message. The command having the cancel bit set does not return a cancel code unless it is in turn canceled by another command with cancel set. #04 - CANCEL ALL CODE - Command has been canceled by using the control category cancel option. As above, all commands in the queue and the currently executing command send this code in an abort message. The control category sends a success message after all executing and pending commands have been canceled. After sending a control category cancel do not send another move command to be executed until the control success message is received, or the new command may be canceled also. #5 - JOB PAUSED - Sent when the job has been temporarily suspended using the control category suspend option. Paused jobs can also be canceled. #6 - LEFT STALLED ERROR - Sent when only the left motor encoder pulses are missing. #7 - RIGHT STALLED ERROR - Same as above except for right motor. #8 - BOTH STALLED ERROR - Sent when Newton gets no encoder pulses from both wheel motors while they are commanded to move. #9 - TILT ERROR - Sent when Newton's tilt sensor has been actuated. #16 - ZERO MOVE SPEED ERROR - Sent when a command is issued with the speed bits in the cancel byte equal to zero. NOTE: Codes 34 thru 38 are sent in a three byte format. See the communications section of this document. #34 - JOB BUFFER FULL ERROR CODE - See the Queues section under communications. #35 - UNIMPLEMENTED ERROR - Sent if an option number greater than 2 is sent. See the low level communications considerations section under communcations. #36 - MSG LENGTH ERROR - Sent if the message length does not agree with that expected for the option commanded. See the low level communications considerations section under communications. #37 - MSG TOO LONG ERROR - See the low level communications considerations section under communications. #38 - REJECTED WHILE REMOTE ERROR - Sent if a command is sent while Newton is being controlled by the hand held remote control. The command is discarded. #41 - JOB RESUMED - Sent when a paused job has been resumed using the control category resume option. SELF TEST (CATEGORY ONE) Command message format: 02(STX)/3/1nH/CANCEL BYTE Where n is the option desired. Three options will be implemented for the selftest category in future firmware revisions. They are: Option 0 - Short test. Option 1 - Regular test. Option 2 - Extensive test. At this time only an abbreviated version of option two, the extensive test, is implemented in Newton. Sending an option number other than two will result in the return of an unimplemented error message. OPTION TWO - EXTENSIVE TEST Return message format: 02(STX)/6/12H/DATA 0/DATA 1/DATA 2/DATA 3 The data bytes in the return message are bitfields, with bit set indicating a fault condition. The bit assignments are: DATA 0 - Bit 0 - Not used. Bit 1 - Temperature sensor shorted or open. Bit 2 - Tilt sensor actuated. Bit 3 - Light sensor faulty. Bit 4 - Battery voltage low. Bit 5 - Left motor fault. Bit 6 - Right motor fault. Bit 7 - Head motor fault. DATA 1 - Bit 0 - One or more sonars faulty. Bit 1 - Plus 5 volts out of limits. Bit 2 - Negative 5 volts out of limits. Bit 3 - Plus 12 volts out of limits. Bit 4 - Negative 12 volts out of limits. Bit 5 - Not used. Bit 6 - Not used. Bit 7 - Not used. DATA 2 - Bit 0 - Motor cable fault. Bit 1 - Light cable fault. Bit 2 - Head cable fault. Bit 3 - Opto cable fault. Bit 4 - Not used. Bit 5 - Not used. Bit 6 - Not used. Bit 7 - Not used. DATA 3 - Bit 0 - Not used. Bit 1 - Not used. Bit 2 - Not used. Bit 3 - Not used. Bit 4 - Not used. Bit 5 - Not used. Bit 6 - Not used. Bit 7 - Not used. CATEGORY ONE CANCEL BYTE All bits except bit 7, which must always be reset, are ignored in the selftest routine. However, cancelling the move robot or move head category while selftest is moving the robot or head will result in the return of a cancel message from selftest. If a move category is paused and resumed while selftest is using the move, the pause and resume messages will come from the move category, and selftest will also be paused and resumed, but will send no message to that effect. CATEGORY ONE ABORT MESSAGES AND CODES All category one abort messages use the three byte format: 02(STX)/3/1nH/ABORT CODE Possible abort codes returned are: #34,#35,#36, & #37 - JOB BUFFER FULL, UNIMPLEMENTED, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #4 - CANCEL CODE - Sent if a move robot or move head cancel is received while selftest is moving the robot or head. #4 - CANCEL ALL CODE - Sent if a move robot or move head cancel is done using the control category cancel option while selftest is moving the robot or head. LIGHTS (CATEGORY TWO) Newton has 28 lights numbered 0 thru 27. All lights except numbers 0 thru 3 are also used in Newton's light shows. Lights 0 and 1 are Newton's eyes, and lights 2 and 3 are power indicators. These four lights are always under the control of category two. Lights are removed from the lightshows (if any) and placed under control of category two any time a command with a non zero time is received for the light. Sending a command to a light with the time set to zero returns the light control to the lightshows. Countdown of the time to zero without a succeding light command for the light also returns the light to the lightshows. Each light can handle two commands, one command running, and another command to be run when the current time period expires. If another non cancel and non zero command is received with the individual light command queue full, an error message is sent to the PC. It should be noted that a success message is generated by category two as soon as the command is accepted. The HPC does NOT wait until the end of the time out to send the success message. In fact even a light command entered into the one command queue generates an immediate success message. Nor is any message sent at the end of the time out period or at the start of execution of a queued command. A currently executing command that is canceled also does not send a canceled message. In fact the only possible return messages other than success returned from the lights category are the communications errors and the individual light command queue full error messages. All light options except turn eyes on/off include time in seconds. Sending time equal 0 returns lights 4 thru thru 27 to the lightshows if any are running. If no lightshows are running, and always for lights 0 thru 3, sending time zero toggles the light on/off. Sending time equal 65535 (0FFFFH) turns the light on or off forever. A light turned on or off forever can be reurned to control by sending another command with the cancel bit set in the cancel byte. It can be returned to the lightshows by sending a zero time command. This also cancels any running or queued command. The actual maximum time for control is limited to 4294 seconds (1 hr 11 min 34 sec). Time values sent that are from 4295 thru 65534 will be truncated to 4294 seconds without notification to the PC. CATEGORY TWO CANCEL BYTE Bits 0 thru 2 - Ignored. Bit 3 - Cancel bit - If set command is executed immediately and the individual light single command queue is flushed. If set in an all lights command, the command operates all lights (except eyes and power) immediately and flushes all individual queues. Sending a time value of zero to individual lights also acts as a cancel and returns the light to the lightshows. Bit 4 - ON/OFF bit - If set, the light is turned on for the specified time period. If cleared, the light is turned off for the specified time period. Bits 5 & 6 - Ignored. Bit 7 - Always reset. OPTION 0 - TURN A SPECIFIC LIGHT ON/OFF Command format: 02(STX)/6/20H/LIGHT NUMBER/TIME LO/TIME HI/CANCEL BYTE Turns the individual light specified on or off for the time period sent. This command will also control lights 0 thru 3 for individual control of the eyes and power lights. Any existing command with time equal on forever will be overridden (cancelled) by a new command. BUG NOTE: In this version of firmware, countdown of time to zero of an eye light or power light causes the eye or power light to be affected by the light shows. Use on/off forever or eyes on/off to control these lights without lightshow blinking. OPTION 1 - TURN ALL LIGHTS ON/OFF Command format: 02(STX)/5/21H/TIME LO/TIME HI/CANCEL BYTE Turns all of the lights 4 thru 27 on or off for the specified time period. This command does not affect the eye or power lights. It does cancel all current and pending individual light commands for lights 4 thru 27. OPTION 2 - TURN EYES ON/OFF Command format: 02(STX)/3/22H/CANCEL BYTE Turns eyes on or off indefinitely. Cancels any current or pending option 0 commands to the eyes (lights 0 & 1). CATEGORY TWO RETURN MESSAGES AND CODES All category two return messages use the three byte format: 02(STX)/3/2nH/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #35 - UNIMPLEMENTED ERROR will also be sent if an invalid light number is sent. #127 - ONE LIGHT Q FULL ERROR - Sent when a light's individual single command queue is full, and another command is received for that light that does not have the cancel bit set and/or is not a cancel type. CONTROL (CATEGORY THREE) OPTION 0 - PAUSE CATEGORY nn Message format: 02(STX)/3/30H/CANCEL BYTE (CATEGORY NUMBER) Suspend the currently executing and queued commands in the specified category until a continue (option 1) is sent, or a cancel is received by the suspended category. The suspended category will send a message to the PC showing that it has paused, and then option zero will send a success message. Only categories 0 and 6 (move robot & move head) can be paused. All eight bits of the cancel byte are used for the job number. CONTROL OPTION ZERO RETURN MESSAGES AND CODES All option zero return messages use the three byte format: 02(STX)/3/30H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #35 - UNIMPLEMENTED ERROR will also be sent if the pause command is sent with a category other than 0 or 6. #4 - JOB NOT RUNNING will be returned if the paused category has no commands running or in its queue. OPTION 1 - CONTINUE CATEGORY nn Message format: 02(STX)/3/31H/CANCEL BYTE (CATEGORY NUMBER) Start a category previously paused using option 0. The previously suspended category will send a message to the PC showing that it has restarted, and then option one will send a success message. Only categories 0 and 6 (move robot & move head) can be continued. All eight bits of the cancel byte are used for the job number. CONTROL OPTION ONE RETURN MESSAGES AND CODES All option one return messages use the three byte format: 02(STX)/3/31H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #35 - UNIMPLEMENTED ERROR will also be sent if the continue command is sent with a category other than 0 or 6. If the category specified is not in a paused state when this command is received, a success message is sent to the PC, and the category resumed does not send any message. OPTION TWO - FORCE READ INTERNAL UPDATE Message format: 02(STX)/3/32H/CANCEL BYTE Sending this command forces the READ INTERNAL category to send its messages as if Newton had just powered on. See the read internal category description for details. The cancel byte is ignored. CONTROL OPTION TWO RETURN MESSAGES AND CODES All option two return messages use the three byte format: 02(STX)/3/32H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION THREE - TILT ENABLE/DISABLE Message format: 02(STX)/3/33H/CANCEL BYTE If sent with the ON/OFF bit in the cancel byte cleared, the tilt sensor abort checking when Newton executes a move is turned off. Sending the command with the ON/OFF bit set will turn tilt sensor checking on. The HPC startup default is tilt enabled. CONTROL OPTION THREE RETURN MESSAGES AND CODES All option three return messages use the three byte format: 02(STX)/3/33H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION FOUR - CANCEL NOP Message format: 02(STX)/4/34H/CATEGORY NUMBER/CANCEL BYTE If the cancel bit is set in the cancel byte, cancel the current job in the category and all jobs in the category queue. Only categories 0 and 6 can be canceled. Sending category equal 255 causes both categories to be cancelled. Sending this message with the cancel bit cleared is a NOP that returns a success message. Each pending or running job that is canceled sends a cancel message of its own to the PC. After all are canceled the control option 4 success message is sent to the PC. All bits other than the cancel bit of the cancel byte are ignored. This command will cancel and flush the category job queue even if the category is in a paused state. CONTROL OPTION FOUR RETURN MESSAGES AND CODES All option four return messages use the three byte format: 02(STX)/3/34H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #35 - UNIMPLEMENTED ERROR will also be sent if the cancel nop command is sent with a category other than 0, 6, or 255. Sending the command with an invalid category number, but with the cancel bit cleared, will result in a success message. If the category specified has no jobs running, pending, or paused when this command is received, a success message is sent to the PC, and the category canceled does not send any message. OPTION FIVE - SONAR ENABLE/DISABLE Message format: 02(STX)/3/35H/CANCEL BYTE If sent with the ON/OFF bit in the cancel byte cleared, the sonar collision checking when Newton executes a move is turned off. The sonars themselves still operate, and values returned from the read external category for the sonars will still be valid. Sending the command with the ON/OFF bit set will turn sonar collision checking on. This command turns all sonar checking on or off, and overrides the individual sonar control. The HPC startup default is sonar enabled. CONTROL OPTION FIVE RETURN MESSAGES AND CODES All option five return messages use the three byte format: 02(STX)/3/35H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION SIX - SONAR ON/OFF Message format: 02(STX)/3/36H/CANCEL BYTE If sent with the ON/OFF bit in the cancel byte cleared, the sonars are turned off completely, and collision checking when Newton executes a move is turned off. Zero distance values will be returned from the read external read sonar commands. Sending the command with the ON/OFF bit set will turn the sonars back on, and the sonar enable/disable will be at the same state as when the sonars were turned off. When the sonars are turned off this command turns all sonar checking off, and overrides the individual sonar control. The HPC startup default is sonar on. CONTROL OPTION SIX RETURN MESSAGES AND CODES All option six return messages use the three byte format: 02(STX)/3/36H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION SEVEN - REMOTE CONTROL ON/OFF Message format: 02(STX)/3/37H/CANCEL BYTE If sent with the ON/OFF bit in the cancel byte cleared, the key presses from the optional remote control are not sent to the PC. If the ON/OFF bit is set, the remote control keys are sent to the PC as directed by the set remote address and set remote duplicate filter commands' status. The HPC startup default is remote control on. CONTROL OPTION SEVEN RETURN MESSAGES AND CODES All option seven return messages use the three byte format: 02(STX)/3/37H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION EIGHT - SET REMOTE CONTROL ADDRESS Message format: 02(STX)/4/38H/ADDRESS/CANCEL BYTE The remote control transmitter can be set to have one of 20 different addresses. If this command is sent with the ON/OFF bit set, only keystrokes coming from the transmitter with the address specified will be sent to the PC. If the ON/OFF bit is cleared, all keystrokes, regardless of the address, will be sent to the PC as conditioned by the set remote duplicate filter command's status. The HPC startup default is to send all keystrokes regardless of address. Valid addresses range from 1 thru 20. Sending an invalid address will probably cause loss of keystrokes since address range checking is not done by the HPC. CONTROL OPTION EIGHT RETURN MESSAGES AND CODES All option eight return messages use the three byte format: 02(STX)/3/38H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION NINE - SET REMOTE CONTROL DUPLICATE FILTER Message format: 02(STX)/3/39H/CANCEL BYTE If a key is continually held down on the remote control transmitter, an autorepeat feature keeps on sending the key several times a second. If this command is sent with the ON/OFF bit set, only the first keystroke of an autorepeat sequence will will be sent to the PC. If the ON/OFF bit is cleared, all keystrokes of the autorepeat sequence will be sent to the PC as conditioned by the set remote address command's status. The HPC startup default is to send only the first keystroke. CONTROL OPTION NINE RETURN MESSAGES AND CODES All option nine return messages use the three byte format: 02(STX)/3/39H/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION TEN - SEND REMOTE CONTROL KEYSTROKE Message format: 02(STX)/4/3AH/KEYSTROKE LO/KEYSTROKE HI This is a message only sent from the HPC to the PC. If it is sent to the HPC an unimplemented error will be returned. It is sent to the PC when a keystroke has been received from the remote control transmitter as conditioned by the set remote address and set remote duplicate filter commands. By default, the HPC will never send this message until the remote control is enabled using the remote control on/off option. CONTROL OPTION TEN ERROR MESSAGES AND CODES All option ten error messages use the three byte format: 02(STX)/3/3AH/ABORT CODE Possible abort codes returned are: #34,#35,#36, & #37 - JOB BUFFER FULL, UNIMPLEMENTED, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #127 - NOISE KILL ERROR - If more than 25 remote control interrupts are detected within 127 seconds without a valid keystroke being received, the remote control is shut off to prevent noise from interfering with the HPC operation. If and when this happens, an error message with the noise kill error is sent to the PC. After the message is sent, the PC must send a remote on/off command with the on/off bit set if it wants to continue to receive remote control keystrokes. REMOTE CONTROL DATA WORD FORMAT Bit 15 - Set if keystroke is long (12 bit) format. Cleared if word is short (11 bit) format. Long word format: Bits 14 thru 12 - Always zero. Bits 11 & 10 - Toggle bits. These bits are incremented 0 thru 3 in a circular manner for each individual keystroke. During sucessive strokes of an autorepeat sequence they are not incremented. When the remote duplicate filter is off, these bits can be used to tell auto repeat keys (which will have identical successive words) from press-release-press again strokes of the same key (succeding otherwise identical words will have different toggle bits). Bits 9 thru 6 - Long format raw address as received by the HPC for addresses 8 thru 20. Refer to the SAA3007 transmitter IC data sheet for conversion of these bits to the corresponding address 1 thru 20. Short word format: Bits 14 thru 11 - Always zero. Bits 10 & 9 - Toggle bits as described above. Bits 8 thru 6 - Short format address bits for addresses 1 thru 7. Both formats: Bits 5 thru 0 - The actual keystroke code. This is referred to as the "command code" in the SAA3007 data sheet. OPTION ELEVEN - INDIVIDUAL SONAR ENABLE/DISABLE Message format: 02(STX)/3/3BH/CANCEL BYTE If sent with the ON/OFF bit in the cancel byte cleared, the sonar collision checking for the individual sonar limit specified in the cancel byte is turned off when Newton executes a move. The sonar itself still operates, and values returned from the read external category for the sonar will still be valid. Sending the command with the ON/OFF bit set will turn the particular sonar collision checking on. The HPC startup default is all sonar limits enabled. CONTROL OPTION ELEVEN RETURN MESSAGES AND CODES All option five return messages use the three byte format: 02(STX)/3/3BH/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION ELEVEN CANCEL BYTE FORMAT Bits 0 & 1 - Number of the sonar whose limit check is affected. Bit 2 - If set the far (drop off) limit check is enabled or disabled. If cleared the near (collision) limit check is enabled or disabled. Bit 4 - ON/OFF bit - If set, the limit check is enabled. If cleared, the limit check is disabled. All other bits - Ignored, except bit seven must be 0. OPTION TWELVE - SET SONAR LIMIT Message format: 02(STX)/5/3CH/FEET LO/FEET HI/CANCEL BYTE This command sets individual near or far limits for sonar collision and drop off detection. As in the option 11 individual sonar control option the cancel byte specifies the sonar and limit affected by the command. The distance is specified in tenths of feet. The cancel bit has no effect in this command. CONTROL OPTION TWELVE RETURN MESSAGES AND CODES All option five return messages use the three byte format: 02(STX)/3/3CH/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION TWELVE CANCEL BYTE FORMAT Bits 0 & 1 - Number of the sonar whose limit setpoint is affected. Bit 2 - If set the far (drop off) limit set point is set to the specified distance. If cleared the near (collision) setpoint check is set to the specified distance. All other bits - Ignored, except bit seven must be 0. OPTION THIRTEEN - SET IR REFERENCE Command format: 02(STX)/4/3DH/REFERENCE BYTE/CANCEL BYTE This command sets the reference output (0 thru 255) for the ir sensor. The reference is initialized to 080H on startup. the reply message format is: 02(STX)/3/3DH/1(SUCCESS) OR ERROR CODE OPTION THIRTEEN CANCEL BYTE All bits are ignored, except that bit seven must be zero. OPTION THIRTEEN ERROR MESSAGES Error messages are returned to the PC in the usual three byte format: 02(STX)/3/3DH/ERROR CODE Possible error codes are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION FOURTEEN - HEAD CALIBRATION ENABLE/DISABLE Message format: 02(STX)/3/3EH/CANCEL BYTE If the ON/OFF bith is set in the command cancel byte, the calibration is enabled. If the ON/OFF bit is cleared, calibration is disabled. Setting the CANCEL bit and the ON/OFF bit will force a calibration on the next commanded head move. CONTROL OPTION FOURTEEN RETURN MESSAGES AND CODES All option fourteen return messages use the three byte format: 02(STX)/3/3EH/1(SUCCESS) OR ABORT CODE Possible abort codes returned are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION FIFTEEN Control option fifteen is unimplemented. READ INTERNAL VALUE (CATEGORY FOUR) With one exception, option 15, read internal messages are only sent from the HPC to the PC to keep the PC up to date on sensor values. The exception allows reading the raw binary value for any one of the seven A/D converter readings kept current by the HPC. Sending a command to category 4 with the option set to other than 15 will result in an unimplemented error message being sent to the PC. The category four messages will be sent upon any change in the option's data. Messages from category four are not sent until after the first full message of any type has been received from the PC. This allows the PC to initialize its communication interface before messages are sent from the HPC. Since these messages are sent only upon change, it is the responsibility of the PC programming to keep the values available to application programs. Update of the read internal values (if different from the defaults) may be forced using the control category option two. CATEGORY FOUR RETURN MESSAGES AND CODES All category four return messages use the three byte format: 02(STX)/3/4nH/DATA OR ABORT CODE With n being the option number. Possible abort codes returned are: #34, #35, & 37 - JOB BUFFER FULL, UNIMPLEMENTED & MSG TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. CATEGORY FOUR DATA BYTE DESCRIPTIONS OPTION ZERO - READ TEMPERATURE The data byte contains the current temperature in degrees Fahrenheit. A data byte of zero indicates detection of an open sensor. A data byte of 255 indicates detection of a shorted sensor. PC programming should assume a value of zero (open sensor) upon startup. OPTION ONE - READ BATTERY The data byte contains the current approximate percent of battery charge. The possible values are 80, 60, 40, 20, 10, 5, and 0 per cent. If the value is 80, the battery is charged to somewhere between 80 and 100 per cent. If the value is 60, the battery is charged somewhere between 60 and 80 per cent, etc.. If the value is zero, Newton had better be on his way to his charger. PC programming should assume a value of zero upon startup. OPTION TWO - READ TILT A one in the data byte indicates tilted. A zero in the data byte indicates not tilted. An application program may assume not tilted, unless the tilted value is sent. The not tilted value will only be sent upon return from tilted to not tilted. OPTION THREE - READ SMOKE SENSOR A one in the data byte indicates smoke detected. A zero in the data byte indicates no smoke detected. An application program may assume no smoke, unless the smoke value is sent. The no smoke value will only be sent upon return from smoke to no smoke. OPTIONS FOUR THRU FOURTEEN Options four thru fourteen are not implemented. OPTION FIFTEEN - READ RAW VALUE This is the only read internal command that can be sent to the HPC without error. The format is: 02(STX)/3/4FH/CANCEL BYTE The reply message will be in the standard category 5 format with the data byte being the raw 8 bit binary value A/D conversion value for the A/D channel specified in the cancel byte sent. Bits 0 thru 2 of the cancel byte are used to specify one of the seven A/D converter channels. All other cancel bits are ignored, except that of course bit 7 must be zero. Note that it may be impossible to differentiate between a data communications error message and a valid message that has data that happens to be the same as an error code. READ EXTERNAL (CATEGORY FIVE) OPTION ZERO - READ HEAD SONAR Command format: 02(STX)/5/50H/DEGREES LO/DEGREES HI/CANCEL BYTE This command rotates the head to the specified position, and then reads the head sonar and returns the sonar reading in tenths of feet to the PC. If the sonars are turned off, a distance of zero is returned. The reply message format is: 02(STX)/4/50H/FEET LO/FEET HI OPTION ZERO CANCEL BYTE The cancel byte is ignored, except the bit seven must be zero. OPTION ZERO ABORT AND ERROR MESSAGES Abort or error messages are returned to the PC in the usual three byte format: 02(STX)/3/50H/ABORT OR ERROR CODE Abort messages do not include any data showing where the command was when aborted. Possible abort and error codes are: #4 - CANCEL CODE - Returned if the move head category (category six) is canceled while rotating the head to the specified degrees. #4 - CANCEL ALL CODE - Returned if the move head category is canceled by the control cancel option while rotating the head to the specified position. #10 - HEAD STALL CODE - Returned if the head motor stalls while attempting to move to the specified position. #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. If the move head category is paused while this command is executing, this option will be paused automatically without sending a paused message to the PC. The pause and resume messages will be sent from category six, move head. OPTION ONE - READ SONAR Command format: 02(STX)/3/51H/CANCEL BYTE This command returns the sonar reading for the sonar specified in the cancel byte to the PC in tenths of feet to the PC. If the sonars are turned off, a distance of zero is returned. The reply message format is: 02(STX)/4/51H/FEET LO/FEET HI OPTION ONE CANCEL BYTE Bits 0 & 1 - Number of the sonar to read, 0 thru 3. All other bits are ignored, except that bit seven must be zero. OPTION ONE ERROR MESSAGES Error messages are returned to the PC in the usual three byte format: 02(STX)/3/51H/ERROR CODE Possible error codes are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION TWO - READ INFRA-RED SENSOR Command format: 02(STX)/3/52H/CANCEL BYTE This command returns whether or not there has been a change in the infra-red detector reading since the last time this option was commanded. The initial (startup) ir bit setting is assumed to be zero. To ascertain the absolute ir bit setting use the option six command. This command does not return the setting of the ir bit, but only whether the bit has changed one or more times since the last call to this function. The ir reading may have changed several times, and may even be the same as before the last call to this function. The reply message format is: 02(STX)/3/52H/DATA Where the data byte will be zero for no change, and one for change. OPTION TWO CANCEL BYTE All bits are ignored, except that bit seven must be zero. OPTION TWO ERROR MESSAGES Error messages are returned to the PC in the usual three byte format: 02(STX)/3/52H/ERROR CODE Possible error codes are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION THREE - SCAN HEAD AND INFRA-RED SENSOR Command format: 02(STX)/3/53H/CANCEL BYTE This command moves the head to the full left (counter clockwise) position, and the moves the head clockwise at the speed specified in the cancel byte until the infra-red sensor detects a change, then it stops the head move and sends the head position to the PC. It stops after 360 degrees have been covered with no changes. The reply message format is: 02(STX)/4/53H/DEGREES LO/DEGREES HI Degrees will be set to the head position at which the change was detected. If no change has been detected a value of 999 degrees will be returned. OPTION THREE CANCEL BYTE Bits 0 thru 2 - Head move speed. 1 (slowest) thru seven (fastest). The rest of the bits are ignored, except the bit seven must be zero. OPTION THREE ABORT AND ERROR MESSAGES Abort or error messages are returned to the PC in the usual three byte format: 02(STX)/3/53H/ABORT OR ERROR CODE Abort messages do not include any data showing where the command was when aborted. Possible abort and error codes are: #4 - CANCEL CODE - Returned if the move head category (category six) is canceled while rotating the head. #4 - CANCEL ALL CODE - Returned if the move head category is canceled by the control cancel option while rotating the head. #10 - HEAD STALL CODE - Returned if the head motor stalls while attempting to move the head. #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #128 - ZERO HEAD SPEED ERROR - Returned if this option is called with speed of zero. If the move head category is paused while this command is executing, this option will be paused automatically without sending a paused message to the PC. The pause and resume messages will be sent from category six, move head. OPTION FOUR - READ HEAD POSITION Command format: 02(STX)/3/54H/CANCEL BYTE This command returns the current head position in degrees. One degree is full left (CCW), and 347 degrees is full right (CW). The reply message format is: 02(STX)/4/54H/DEGREES LO/DEGREES HI OPTION FOUR CANCEL BYTE All bits are ignored, except that bit seven must be zero. OPTION FOUR ERROR MESSAGES Error messages are returned to the PC in the usual three byte format: 02(STX)/3/54H/ERROR CODE Possible error codes are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. OPTION FIVE - READ LIGHT INTENSITY Command format: 02(STX)/3/55H/CANCEL BYTE This command returns the relative light intensity (0 - 255) as read by the A/D converter. The reply message format is: 02(STX)/3/55H/DATA OPTION FIVE CANCEL BYTE All bits are ignored, except that bit seven must be zero. OPTION FIVE ERROR MESSAGES Error messages are returned to the PC in the usual three byte format: 02(STX)/3/55H/ERROR CODE Possible error codes are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. Note that there is no way to differentiate between an error message and a valid return where the data happens to equal an error code. OPTION SIX - READ IR STATUS Command format: 02(STX)/3/56H/CANCEL BYTE This command returns the current IR bit; one equals on, and zero equals off. The reply message format is: 02(STX)/3/56H/ON(1) OR OFF(0) OPTION SIX CANCEL BYTE All bits are ignored, except that bit seven must be zero. OPTION SIX ERROR MESSAGES Error messages are returned to the PC in the usual three byte format: 02(STX)/3/56H/ERROR CODE Possible error codes are: #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. No other errors will be sent by this option. MOVE HEAD (CATEGORY SIX) HEAD SPEEDS AND POSITION ACCURACY The head angular velocities for the command speeds are as follows: Speed 1 - 47 +/- 3% degrees per second Speed 2 - 54 +/- 3% Speed 3 - 65 +/- 5% Speed 4 - 80 +/- 5% Speed 5 - 104 +/- 6% Speed 6 - 150 +/- 9% Speed 7 - 165 (approx.) For speed seven, the motor is simply turned on at maximum power, and not controlled. The head position encoder has 480 counts per revolution for an accuracy of 0.75 degree per count. Backlash in the head gear train and other tolerances make actual control to this tolerance impractical. If the head position is within two encoder counts of the commanded position, the move will be seen as successfully completed. Thus, the head position accuracy is basically 2 degrees, although readings from the read head position function of category five are accurate to one degree. OPTION ZERO - MOVE HEAD Command format: 02(STX)/5/60H/DEGREES LO/DEGREES HI/CANCEL BYTE This command rotates the head to the specified position, zero degrees being full left (CCW) and 359 degrees being full right (CW). It should be noted that Newton's head will not actually move to zero degrees. A command sent with zero degrees actually results in a move that will be to 1 degree. Also, since the head rotation stop prevents full 360 degree movement, a move to 359 degrees will actually cause a move to 347 degrees. The true position will be returned when read back by the read head position option of category five. The reply message format is: 02(STX)/3/60H/1(SUCCESS) OR ERROR OR ABORT CODE OPTION ONE - HOME HEAD Command format: 02(STX)/3/61H/CANCEL BYTE This command moves the head to the straight ahead (180 degree) position. The reply message format is: 02(STX)/3/61H/1(SUCCESS) OR ERROR OR ABORT CODE CATEGORY SIX CANCEL BYTE Bits 0 thru 2 - Speed from 0 thru 7. 1 (slowest) thru 7 (fastest) are valid. Sending 0 with valid data values causes an abort message to the PC and the command is otherwise ignored. Bit 3 - Cancel bit. If set, all previous commands (including the currently executing command), if any, in the category six job queue are discarded, and the command is executed immediately. Sending a category six option zero command with zero data values flushes the command queue and stops Newton's head, and a success message is returned. Any and all commands canceled return an abort message indicating that they have been canceled. Bit 4 - ON/OFF bit. This bit is ignored in category six. Bit 5 - LEFT/RIGHT bit. Ignored. Bit 6 - Continue bit. Newton normally does a controlled smooth stop at the completion of a head move to "zero in" on the final position. If the current or any succeding command in the job queue has the continue bit set, Newton does not stop between commands, but continues immediately into the next without stopping. If another command is not in the queue, the head's momentum may cause overshoot of the commanded position. In this case, the true position may be determined thru the read head position option of category five. Bit 7 - Always reset. See the bit description in the communication section of this document. CATEGORY SIX ABORT AND ERROR CODES Abort messages do not include any data showing where the command was when aborted, and are sent in the standard three byte format. Possible abort and error codes are: #4 - CANCEL CODE - Returned if the move head category (category six) is canceled while rotating the head to the specified degrees. #4 - CANCEL ALL CODE - Returned if the move head category is canceled by the control cancel option while rotating the head to the specified position. #5 - JOB PAUSED - Sent when a head move has been temporarily suspended using the control category suspend option. Paused jobs can also be cancelled. #10 - HEAD STALL CODE - Returned if the head motor stalls while attempting to move to the specified position. #34,#36, & #37 - JOB BUFFER FULL, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. #38 - REJECTED WHILE REMOTE ERROR - Returned if a command is sent while Newton is being controlled by the hand held remote control. The command is discarded. #41 - JOB RESUMED - Sent when a paused job has been resumed using the control category resume option. BEACON (CATEGORY SEVEN) NO CATEGORY SEVEN OPTIONS ARE IMPLEMENTED AT THIS TIME. Sending a message to category seven will result in the return of an unimplemented error message. LIGHT SHOWS (CATEGORY EIGHT) Newton has 7 light shows available numbered 0 thru 6. By default, upon startup the shows are run continuously, sequencing zero thru six and then back to zero. The lightshow options provide ways to manipulate the shows. The use of Newton's lights in the light shows is overridden by the light commands of category one. Refer to the category one description for the interplay between the categories. As in the individual light commands, reply messages are generated immediately, not when the command time period has expired. Unlike the individual light commands, there is no indiviual command queue, and any command received will override preceding commands even if there is time remaining from the preceding command's time period. OPTIONS ZERO THRU SIX - TURN INDIVIDUAL SHOW ON/OFF This turns off the running of a specified lightshow in the current sequence (see option 2) for the specified time interval in seconds if the ON/OFF bit in the cancel byte is cleared. At the end of the time period the lightshow is turned on again. If the ON/OFF bit is set, the show is run until the end of the time period, at which time it is shut off. Sending time equal 65535 or 0 turns on the show forever. As in the individual light commands, the maximum time interval is limited to 4294 seconds (1 hr 11 min 34 sec), and times sent between 4294 and 65535 will be truncated to 4294 without notifying the PC. The command message format is: 02(STX)/5/8nH/TIME LO/TIME HI/CANCEL BYTE Where n is the lightshow number to be turned on or off. All bits except the ON/OFF bit in the cancel byte are ignored, except bit seven must be zero. OPTIONS SEVEN THRU THIRTEEN Options seven thru thirteen are unimplemented. Sending a command to category eight with one of these options will result in the return of an unimplemented error message. OPTION FOURTEEN - SET LIGHT SHOW ORDER Active light shows are run in the sequence specified in an internal list. The startup order is 0,1,.....,6. After the last show in the list is run, the sequence starts over at the beginning. If a show in the list is off, that show is skipped and the next is run instead. By changing the order of the list and/or individually turning shows on and off, any combination of shows, or a single show only, can be set for Newton to run. The command format is: 02(STX)/5/8EH/SHOW NUMBER/ORDER NUMBER/CANCEL BYTE If the show number or order number is sent greater than six, an unimplemented error message will be generated. The cancel byte is ignored, except bit seven must be zero. OPTION FIFTEEN - TURN ALL LIGHT SHOWS ON/OFF This turns off the running of any lightshows in the current sequence (see option 2) for the specified time interval in seconds if the ON/OFF bit in the cancel byte is cleared. At the end of the time period the sequence is turned on again. If the ON/OFF bit is set, the shows are run until the end of the time period, at which time they are shut off. Sending time equal 65535 or 0 turns on the shows forever. As in the individual light commands, the maximum time interval is limited to 4294 seconds (1 hr 11 min 34 sec), and times sent between 4294 and 65535 will be truncated to 4294 without notifying the PC. At the end of a time on period, the lights will be left in the last controlled light setting. The command message format is: 02(STX)/5/8FH/TIME LO/TIME HI/CANCEL BYTE All bits except the ON/OFF bit in the cancel byte are ignored, except bit seven must be zero. CATEGORY EIGHT ERROR MESSAGES AND CODES All category eight error messages use the three byte format: 02(STX)/3/8nH/ERROR CODE Possible error codes returned are: #34,#35,#36, & #37 - JOB BUFFER FULL, UNIMPLEMENTED, MSG LENGTH, & MESSAGE TOO LONG ERRORS. See the communications section of this document for details. APPENDIX ONE SAMPLE PC TO HPC COMMUNICATIONS PSUEDOCODE IRQ2 HANDLER Enter interrupt - save all,etc. Read port 301H Bit 0 set? Yes - Process RX from HPC. Else - Must be ack interrupt - Process TX to HPC. Exit interrupt - restore all. EOI to PIC. Process RX from HPC: Read the char from port 300H Put in circular RX buffer Read port 301H Bit 1 set? No - HPC is not busy - write 0 to port 301 to ID this as an ack of the char being received. Write char to port 301. Yes - HPC is busy. Save char in variable for Hi level program & set flag to tell Hi level to do ack when HPC not busy. Done with interrupt process RX from HPC Process TX to HPC: Any more to Send? No - Read port 300H to clear the interrupt for the HPC. Clear TX busy flag for Hi level. Done with interrupt process TX to HPC. YES - Read port 301H Bit 1 set? No - HPC is not busy - write 1 to port 301 to ID this as a TX to the HPC. Write next char to port 300. Read port 300 to clear interrupt for the HPC. Done with interrupt process TX to HPC. Yes - HPC is busy - Clear TX busy flag for Hi level. Set flag to tell Hi level to send next when HPC not busy. Read port 300 to clear interrupt for HPC. Done with interrupt process TX to HPC. This is the Hi level process loop: BEGIN LOOP IF Hi level send next flag set; disable ints read port 301. bit 1 cleared? HPC not busy - Out 1 to 301 to ID as TX to HPC. Write next char to 300. Clear Hi level send next flag. Set TX busy flag. enable ints IF Hi level send ack flag set and TX busy flag cleared: disable ints read port 301 bit 1 cleared? HPC not busy - Out 0 to 301 to ID as ack to HPC. Get ack char saved by int routine & write to 300. Clear Hi level send ack flag. enable ints IF chars are in buffer to be sent and TX busy flag cleared and Hi level send next flag cleared: disable ints read port 301 bit 1 cleared? HPC not busy - Out 1 to 301 to ID as TX to HPC. Write next char to 300. Clear Hi level send next flag. Set TX busy flag. enable ints IF unprocessed char in RX buffer: Process char END LOOP