Motor API reference¶
The motor is one of the most used elements in sardana. A motor represents anything that can be changed (and can potentially take some time to do it).
This chapter explains the generic motor API in the context of sardana. In sardana there are, in fact, two Motor APIs. To better explain why, let’s consider the case were sardana server is running as a Sardana Tango device server:
Every motor in sardana is represented in the sardana kernel as a
PoolMotor API is not directly
accessible from outside the sardana server. This is a low level API
that is only accessbile to someone writing a server extension to sardana. At
the time of writing, the only available sardana server extension is Tango.
The second motor interface consists on the one provided by the server extension,
which is in this case the one provided by the Tango motor device interface:
Motor. The Tango motor interface tries to
mimic the as closely as possible the
A motor will have, at least, a
state, and a
position. The state
indicates at any time if the motor is stopped, in alarm or moving. The
position, indicates the current user position. Unless a motor
controller is specifically programmed not to, it’s motors will also have:
- limit switches
the three limit switches (home, upper and lower). Each switch is represented by a boolean value: False means inactive while True means active.
high level Tango Motor API: limit_switches tango attribute
motor acceleration (usually acceleration time in seconds, but it’s up to the motor controller class to decide)
motor deceleration (usually deceleration time in seconds, but it’s up to the motor controller class to decide)
- base rate
- dial position
the dial position
the offset to be applied in the motor position computation [default: 0.0]
the sign to be applied in the motor position computation [default: 1, possible values are (1, -1)]
- steps per unit
This is the number of motor steps per user position [default: 1.0]
If this is defined to be something different than 0, the motor will always stop the motion coming from the same mechanical direction. This means that it could be possible to ask the motor to go a little bit after the desired position and then to return to the desired position. The value is the number of steps the motor will pass the desired position if it arrives from the “wrong” direction. This is a signed value. If the sign is positive, this means that the authorized direction to stop the motion is the increasing motor position direction. If the sign is negative, this means that the authorized direction to stop the motion is the decreasing motor position direction.
- instability time
This property defines the time in milliseconds that the software managing a motor movement will wait between it detects the end of the motion and the last motor position reading. It is typically used for motors that move mechanics which have an instability time after each motion.
The available operations are:
- start move absolute (user position)
starts to move the motor to the given absolute user position
- stops the motor in an orderly fashion
- stops the motor motion as fast as possible (possibly without deceleration time and loss of position)
On a sardana tango server, the motor state can be obtained by reading the state attribute or by executing the state command. The diagram shows the internal sequence of calls.
The motor’s current user position can be obtained by reading the position attribute. The diagram shows the internal sequence of calls.
The most useful thing to do with a motor is, of course, to move it. To move a motor to another absolute user position you have to write the value into the position attribute.
Before allowing a movement, some pre-conditions are automatically checked by tango (not represented in the diagram):
- motor is in a proper state;
- requested position is within the allowed motor boundaries (if defined)
Then, the dial position is calculated taking into account the offset, signal as well as a possible backlash.
Afterward, and because the motor may be part of a pseudo motor system, other pre-conditions are checked:
- is the final dial position (including backlash) within the motor boundaries (if defined)
- will the resulting motion end in an allowed position for all the pseudo motors that depend on this motor
After all pre-conditions are checked, the motor will deploy a motion job into the sardana kernel engine which will trigger a series of calls to the underlying motor controller.
The motor awaits for the
to signal that the motion will be possible to return successfully from the move
The following diagram shows the motion state machine of a motor. The black state transitions are the ones which can be triggered by a user. For simplicity, only the most relevant states involved in a motor motion are shown. Error states are omitted.