************************************** Features common to all motor functions ************************************** Certain features are common to all motor functions, and this also means that all motors have certain identical fields in their control data structures. It might be useful to look at these common motor features before using the specific different types of motor. Below is a brief discussion of common features of all motors, followed by a specification of common control data structure fields. ------------------------------ "Before" and "After" functions ------------------------------ In common with many other HeliOS objects, motors have provision for automatically running code specified by you "Before" and "After" the main motor code. This means that you can add any special customised features to the action of any motor. You can supply "Before" and "After" functions in the form of machine code or HeliOS high level code: if fact you can supply BOTH if you wish! It is obviously faster and better to use machine code, but if time is not really critical HeliOS code is often fast enough to work perfectly well. When your code is called the HeliOS system will automatically supply you with a pointer to the current motor control data structure either on the stack (HeliOS code) or in register A0 (machine code). ----- Flags ----- Every motor has a "Flags" field in its control data structure, and each type of motor has its own interpretation of this flags field. In general the "Flags" field controls the mode of action of a motor, and can be used to do things such as temporarily disabling operation or even removing the motor permanently from the HeliOS motor system. --------- CountDown --------- All motors incorporate a "CountDown" function similar to the one found in other HeliOS objects. This function allows you to specify a CountDown period after which the value you have placed in the "CDFlags" field will be copied into the "Flags" field. If you have placed code pointers in the "CDForth" or "CDCode" fields this code will also be run when the CountDown completes. The CountDown function only operates when the CountDown field is set to a non-null value and after the CountDown has completed this field is automatically reset to zero. To summarize the CountDown function: 1. It only operates when CountDown is set to non-null. 2. It resets itself to null after completion. 3. It transfers "Flags" value upon completion. 4. It optionally runs "CDForth" or "CDCode" upon completion. ---- Skip ---- All motors have the facility to skip the processing of "frames" to implement intermittent, periodic or delayed operation. If a non-zero value is stored in "SkipCount" this parameter will specify how many frames to skip between each iteration of the motor. If a zero value is stored in "SkipCount" the motor will run at full speed with its code processed every frame. -- ID -- Every motor has a unique ID which you MUST specify to tell HeliOS what sort of motor this is. -------------- User data area -------------- All motors contain a set of "User data" fields which are unused by HeliOS and are free for your own use. This allows you to set up individual data areas for every motor, and this is often very useful because it allows you to keep together all variables etc. associated with each motor. *********************************************************** Control data structure fields common to all motor functions *********************************************************** ----- Note: ----- In the text below the titles of the fields are all referred to by name as "Motor_xxxxxxx", whereas in real use you would need to use the correct specific designated name for each particular motor type. For example, the first field in a "Path" motor structure would need to be referred to by the symbolic name "Path_BeforeForth". These fields are also fully described in the detailed documentation for each motor type. ------------------------------ The commonly occurring fields: ------------------------------ Motor_BeforeForth This field, if non-null, contains the CFA af a HeliOS command which will be run BEFORE each iteration of the Motor function. A 32-bit pointer to the Motor control structure will be placed on the stack when the HeliOS BEFORE command is called, so you must take care to clear the stack. Motor_BeforeCode This field, if non-null, contains a pointer to a machine code routine which will be run BEFORE each iteration of the Motor function. A 32-bit pointer to the Motor control structure will be placed in address register A0 when the BEFORE command code is called. Motor_AfterForth This field, if non-null, contains the CFA af a HeliOS command which will be run AFTER each iteration of the Motor function. A 32-bit pointer to the Motor control structure will be placed on the stack when the HeliOS AFTER command is called, so you must take care to clear the stack. Motor_AfterCode This field, if non-null, contains a pointer to a machine code routine which will be run AFTER each iteration of the Motor function. A 32-bit pointer to the Motor control structure will be placed in address register A0 when the AFTER command code is called. Motor_Flags This field contains the Motor function control flags. Each type of motor has its own useage for this field so you need to refer to specific motor documentation. Motor_CountDown Sets up a CountDown, so that after the number of "ticks" specified in this field the CDFlags value will be stored into the Flags field of the Motor command structure. This function is switched off after each CountDown. Motor_CDFlags If a CountDown is being done, the value in this field will be placed in the "Flags" field of the Motor command structure when the CountDown is complete. Motor_CDForth This field contains either null or the CFA of a HeliOS function which you wish to be executed after CountDown has completed. Motor_CDCode This field contains either null or a pointer to a machine code routine which you wish to be executed after CountDown has completed. Motor_SkipTimer This field is used to store the internal timer status of the Motor. Motor_SkipCount This value gives the time delay between each iteration of the Motor function. The Motor will skip however many "ticks" are specified here between each active cycle. A SkipCount value of "0" gives full speed operation. Motor_ID This MUST be set to a special identification value which is unique for each type of motor, so you need to refer to specific motor documentation. Motor_UserDataPtr This is a "free" field which you can use as you wish. Motor_UserData1 This is a "free" field which you can use as you wish. Motor_UserData2 This is a "free" field which you can use as you wish. Motor_UserData3 This is a "free" field which you can use as you wish. Motor_UserData4 This is a "free" field which you can use as you wish. Motor_UserData5 This is a "free" field which you can use as you wish. Motor_UserData6 This is a "free" field which you can use as you wish. Motor_UserStatus This is a "free" field which you can use as you wish. **************************************************************************** End ****************************************************************************