GCPositionControl Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | GCPositionControl.h |
Overview
The GCPositionControl object allows you to control Galileo’s rotational position for a given axis. You can access the instance through the positionControlForAxis: method of the Galileo singleton instance.
Control is performed by setting a target position in reference to an origin. Galileo will attempt to rotate to reach the target position as fast and as smoothly as possible. Setting the target position whilst Galileo is already moving will cause Galileo to abandon the current movement and begin moving towards the new target position.
Accessing and setting control properties
smallestAngleIncrement
The smallest angle, in degrees, that the accessory can reliably move.
@property (nonatomic, readonly) double smallestAngleIncrementDiscussion
It is possible to attempt to move in increments smaller than smallestAngleIncrement, however the precision of such movements is not guaranteed. Attempts to move in increments less than the smallestAngleIncrement will result in actual movements less than or greater than the desired movement. However, the sum of many such small movements will still add up to the expected amount over a long enough sequence.
Declared In
GCPositionControl.h
holdPositionWhenStationary
Indicates whether the motors should actively hold position when Galileo is not moving.
@property (nonatomic) BOOL holdPositionWhenStationaryDiscussion
When the value of this property is NO, the motors will idle when stationary, reducing power consumption and permitting the user to manually rotate the device. This is the default setting.
When the value of this property is YES, the motors will actively hold a fixed position whilst stationary. This will increase power consumption and will also prevent the user from phyiscally manipulating the unit to rotate to a specific position. However, this setting is useful in certain scenarios when accurately holding a fixed position is required.
Warning: When setting this value to YES, care must be taken to ensure that it is set to NO once no longer required. Failure to do so will lead to increased power consumption and potential user frustration since the device will be locked in a given orientation. Furthermore, use of this setting with a high value for torque is strongly discouraged, as this is likely cause heating and damage the motors.
Declared In
GCPositionControl.h
torque
Motor torque setting as a percentage of maximum possible.
@property (nonatomic) double torqueDiscussion
A larger torque setting is useful to prevent stalling at greater velocities. Use a smaller torque setting to conserve power during low velocity operation.
Warning: Using a torque setting larger than the default for extended periods may causing heating and damage the motors, especially when holdPositionWhenStationary is set to YES.
Declared In
GCPositionControl.h
speed
Speed, in degrees per second. Positive valued (negative values will be normalised).
@property (nonatomic) double speedDiscussion
Galileo will attempt to accelerate up to and down from this speed during movement. Galileo will not exceed this speed. When modifying this property, be sure that the magitude remains with interval defined by minSpeed and maxSpeed. Illegal values will be normalised to within this range.
Warning: Small values of speed will result in the estimated position drifting over time during motion. This is due to computational constraints on the Galileo hardware. Therefore, larger values of speed (above 50.0 degrees/second) are recommended when accurate motion is required. Values below 5.0 degrees/second are liable to produce movement inaccuracies of 5 - 10%.
Declared In
GCPositionControl.h
maxSpeed
The maximum speed Galileo is able to move at, in degrees per second.
@property (nonatomic, readonly) double maxSpeedDeclared In
GCPositionControl.h
minSpeed
The minimum speed Galileo is able to move at, in degrees per second.
@property (nonatomic, readonly) double minSpeedDiscussion
Warning: Small values of speed will result in the estimated position drifting over time during motion. This is due to computational constraints on the Galileo hardware. Therefore, larger values of speed (above 50.0 degrees/second) are recommended when accurate motion is required. Values below 5.0 degrees/second are liable to produce movement inaccuracies of 5 - 10%.
Declared In
GCPositionControl.h
acceleration
Acceleration, in degrees per second per second. Positive valued (negative values will be normalised).
@property (nonatomic) double accelerationDiscussion
During movement, Galileo will accelerate and decelerate up to and down from the specified velocity at this rate. When modifying this property, be sure that the magitude remains with interval defined by minAcceleration and maxAcceleration. Illegal values will be normalised to within this range.
Declared In
GCPositionControl.h
maxAcceleration
The maximum acceleration Galileo is capable of, in degrees per second per second.
@property (nonatomic, readonly) double maxAccelerationDeclared In
GCPositionControl.h
minAcceleration
The minimum acceleration Galileo is capable of, in degrees per second per second.
@property (nonatomic, readonly) double minAccelerationDeclared In
GCPositionControl.h
Accessing positional information
currentPosition
The current position, in degress.
@property (nonatomic, readonly) double currentPositionDeclared In
GCPositionControl.h
targetPosition
The target position, in degress, the accessory is set to.
@property (nonatomic, readonly) double targetPositionDeclared In
GCPositionControl.h
atTargetPosition
True if the accessory is idle at the target position. False if the accessory is still moving in an attempt to reach the target postion.
@property (nonatomic, readonly, getter=isAtTargetPosition) BOOL atTargetPositionDeclared In
GCPositionControl.h
Resetting the origin
– resetOriginToCurrentPosition
Resets the origin to the current position.
- (BOOL)resetOriginToCurrentPositionReturn Value
TRUE if the reset was sucessful. FALSE if reset failed due to device still in motion.
Discussion
After calling this function, all future absolute commands will be in reference to the current position. It is not recommended that you reset the origin whilst the accessory is in motion, therefore you should check the value of atTargetPosition before calling this method.
Declared In
GCPositionControl.h
Controlling absolute position
– setTargetPosition:completionBlock:waitUntilStationary:
Rotate Galileo to a new position.
- (void)setTargetPosition:(double)newTargetPosition completionBlock:(void ( ^ ) ( BOOL wasCommandPreempted ))completionBlock waitUntilStationary:(BOOL)waitUntilStationaryParameters
newTargetPosition |
The target position, in degrees, in relation to the origin. |
|---|---|
completionBlock |
The block to be executed on completion or preemption. |
waitUntilStationary |
If |
Discussion
If another method call changes the target position before it has been reached then the previous command will be preempted and the accessory will immediately begin moving towards the new target position. If a completion block is provided then it will be executed either when the target is reached or when the command is preempted.
If waitUntilStationary is TRUE then the call will block until the target position is reached. If the command is preempted, the call will continue to block until any new target is reached and the accessory is stationary.
Setting target position using absolute control commands will use modulo arithmetic. Movement will be in either clockwise or anticlockwise direction depensing on the shortest path to the target position.
Warning: You should not call this method from the main thread with waitUntilStationary set to TRUE. This will lock up the device since some accessory events are processed on the main thread.
Declared In
GCPositionControl.h
– setTargetPosition:notifyDelegate:waitUntilStationary:
Rotate Galileo to a new position.
- (void)setTargetPosition:(double)newTargetPosition notifyDelegate:(id<GCPositionControlDelegate>)delegate waitUntilStationary:(BOOL)waitUntilStationaryParameters
newTargetPosition |
The target position, in degrees, in relation to the origin. |
|---|---|
delegate |
The delegate to be notified on completion or preemption. |
waitUntilStationary |
If |
Discussion
If another method call changes the target position before it has been reached then the previous command will be preempted and the accessory will immediately begin moving towards the new target position. If a delegate is provided then it will be notified either when the target is reached or when the command is preempted.
If waitUntilStationary is TRUE then the call will block until the target position is reached. If the command is preempted, the call will continue to block until any new target is reached and the accessory is stationary.
Setting target position using absolute control commands will use modulo arithmetic. Movement will be in either clockwise or anticlockwise direction depensing on the shortest path to the target position.
Warning: You should not call this method from the main thread with waitUntilStationary set to TRUE. This will lock up the device since some accessory events are processed on the main thread.
Declared In
GCPositionControl.h
Controlling relative position
– incrementTargetPosition:completionBlock:waitUntilStationary:
Rotate Galileo to a new position, relative to it’s current target position. Rotation is clockwise for positive valued increment amounts and anti-clockwise otherwise.
- (void)incrementTargetPosition:(double)amount completionBlock:(void ( ^ ) ( BOOL wasCommandPreempted ))completionBlock waitUntilStationary:(BOOL)waitUntilStationaryParameters
amount |
The amount, in degrees, to increment the target position by. |
|---|---|
completionBlock |
The block to be executed on completion or preemption. |
waitUntilStationary |
If |
Discussion
If another method call changes the target position before it has been reached then the previous command will be preempted and the accessory will immediately begin moving towards the new target position. If a completion block is provided then it will be executed either when the target is reached or when the command is preempted.
If waitUntilStationary is TRUE then the call will block until the target position is reached. If the command is preempted, the call will continue to block until any new target is reached and the accessory is stationary.
Setting target position using relative control commands will NOT use modulo arithmetic. Movement will be in either clockwise or anticlockwise direction depensing on if the target position is greater than or less than the current position.
Warning: You should not call this method from the main thread with waitUntilStationary set to TRUE. This will lock up the device since some accessory events are processed on the main thread.
Declared In
GCPositionControl.h
– incrementTargetPosition:notifyDelegate:waitUntilStationary:
Rotate Galileo to a new position, relative to it’s current target position. Rotation is clockwise for positive valued increment amounts and anti-clockwise otherwise.
- (void)incrementTargetPosition:(double)amount notifyDelegate:(id<GCPositionControlDelegate>)delegate waitUntilStationary:(BOOL)waitUntilStationaryParameters
amount |
The amount, in degrees, to increment the target position by. |
|---|---|
delegate |
The delegate to be notified on completion or preemption. |
waitUntilStationary |
If |
Discussion
If another method call changes the target position before it has been reached then the previous command will be preempted and the accessory will immediately begin moving towards the new target position. If a delegate is provided then it will be notified either when the target is reached or when the command is preempted.
If waitUntilStationary is TRUE then the call will block until the target position is reached. If the command is preempted, the call will continue to block until any new target is reached and the accessory is stationary.
Setting target position using relative control commands will NOT use modulo arithmetic. Movement will be in either clockwise or anticlockwise direction depensing on if the target position is greater than or less than the current position.
Warning: You should not call this method from the main thread with waitUntilStationary set to TRUE. This will lock up the device since some accessory events are processed on the main thread.
Declared In
GCPositionControl.h