motor

Initializing the motor Class

An IQ Motor object is created using one of the following constructors:

This motor constructor creates a motor object with gears defaulting to 1.0.

Parameter	Description
index	The Port on the IQ (1st gen) Brain the Motor is connected to.
reverse	A boolean value to reverse the direction the Motor spins forward in. The default is false.

// Construct a Motor connected to Port 1 which runs 
// in reverse.
motor Motor1 = motor(PORT1, true);

This motor constructor creates a motor object with reverse defaulting to false.

Parameter	Description
index	The Port on the IQ (1st gen) Brain the Motor is connected to.
gears	The gear setting or gear ratio of the motor.

// Construct a Motor connected to Port 1 with a 1.0
// gear setting.
motor Motor1 = motor(PORT1, 1);

This motor constructor creates a motor object with no default parameter values.

Parameter	Description
index	The Port on the IQ (1st gen) Brain the Motor is connected to.
gears	The gear setting or gear ratio of the motor.
reverse	A boolean value to reverse the direction the Motor spins forward in.

// Construct an IQ Motor with a 1.0 gear setting
// that runs in reverse.
motor Motor1 = motor(PORT1, 1, true);

This Motor1 object will be used in all subsequent examples throughout this API documentation when referring to motor class methods.

Class Methods

spin()

This is a non-blocking function and allows the next command to run without delay.

This method is called in the following ways:

The spin(dir) command is used to spin a Motor in the specified direction forever at the default velocity set by the setVelocity() command, until a spin or stop command is used, or the project is stopped.

Parameters	Description
dir	A valid DirectionType.

Returns: None.

// Spin Motor1 forward.
Motor1.spin(forward);

The spin(dir, velocity, units) command is used to spin a Motor in the specified direction forever at a specified velocity until a spin or stop command is used, or the project is stopped.

Parameters	Description
dir	A valid DirectionType.
velocity	The velocity at which the Motor will spin.
units	A valid VelocityUnit or percent.

Returns: None.

// Spin Motor1 forward at 100 rpm.
Motor1.spin(forward, 100, rpm);

The spin(dir, voltage, units) command is used to spin a Motor in the specified direction forever at a specified voltage until a spin or stop command is used, or the project is stopped.

Parameters	Description
dir	A valid DirectionType.
voltage	The voltage at which the Motor will spin.
units	A valid VoltageUnit.

Returns: None.

// Spin Motor1 forward at 100 millivolts.
Motor1.spin(forward, 100,::mV);

spinToPosition()

This function can be a blocking or non-blocking command depending on if the wait parameter is used.

This method is called in the following ways:

The spinToPosition(rotation, units, waitForCompletion) command is used to spin a Motor to an absolute rotation in the specified units.

Parameters	Description
rotation	The position to spin the Motor to.
units	A valid RotationUnit.
waitForCompletion	Determines whether the command will block subsequent commands (wait=true) or allow immediate execution (wait=false). If unspecified, the default for the wait parameter is wait=true.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 to the absolute position 1080 degrees.
Motor1.spinToPosition(1080, degrees);

The spinToPosition(rotation, units, velocity, units_v, waitForCompletion) command is used to spin a Motor to an absolute rotation in the specified units.

Parameters	Description
rotation	The position to spin the Motor to.
units	A valid RotationUnit.
velocity	The velocity with which the Motor will spin.
units_v	A valid VelocityUnit.
waitForCompletion	Determines whether the command will block subsequent commands (wait=true) or allow immediate execution (wait=false). If unspecified, the default for the wait parameter is wait=true.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 to the absolute position 1080 degrees 
// at 100 percent velocity.
Motor1.spinToPosition(1080, degrees, 100,::pct);

spinFor()

This can be a blocking or non-blocking command depending on if the wait parameter is used.

This method is called in the following ways:

The spinFor(time, units) command is used to spin the Motor for a specified duration.

Parameters	Description
time	The amount of time to spin the Motor for.
units	A valid TimeUnit.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 for 10 seconds
Motor1.spinFor(10, seconds);

The spinFor(dir, time, units) command is used to spin the Motor for a specified duration in a specified direction.

Parameters	Description
dir	A valid DirectionType.
time	The amount of time to spin the Motor for.
units	A valid TimeUnit.

// Spin Motor1 forward for 10 seconds
Motor1.spinFor(forward, 10, seconds);

The spinFor(time, units, velocity, units_v) command is used to spin the Motor for a specified duration at a specified velocity.

Parameters	Description
time	The amount of time to spin the Motor for.
units	A valid TimeUnit.
velocity	The velocity with which the Motor will spin.
units_v	A valid VelocityUnit.

// Spin Motor1 for 10 seconds at 100 rpm.
Motor1.spinFor(10, seconds, 100, rpm);

The spinFor(dir, time, units, velocity, units_v) command is used to spin the Motor for a specified duration at a specified velocity in a specified direction.

Parameters	Description
dir	A valid DirectionType.
time	The amount of time to spin the Motor for.
units	A valid TimeUnit.
velocity	The velocity with which the Motor will spin.
units_v	A valid VelocityUnit.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 forward for 10 seconds at 100 rpm.
Motor1.spinFor(forward, 10, seconds, 100, rpm);

The spinFor(rotation, units, waitForCompletion) command is used to spin the Motor for a specific rotation. The rotation is relative to the current rotation of the Motor.

Parameters	Description
rotation	The rotation value for the motor to spin for.
units	A valid RotationUnit.
waitForCompletion	Determines whether the command will block subsequent commands (wait=true) or allow immediate execution (wait=false). If unspecified, the default for the wait parameter is wait=true.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 for 1000 degrees.
Motor1.spinFor(1000, degrees);

The spinFor(dir, rotation, units, waitForCompletion) command is used to spin the Motor for a specific rotation in a specific direction. The rotation is relative to the current rotation of the Motor.

Parameters	Description
dir	A valid DirectionType.
rotation	The rotation value for the motor to spin for.
units	A valid RotationUnit.
waitForCompletion	Determines whether the command will block subsequent commands (wait=true) or allow immediate execution (wait=false). If unspecified, the default for the wait parameter is wait=true.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 forward for 1000 degrees.
Motor1.spinFor(forward, 1000, degrees);

The spinFor(rotation, units, velocity, units_v, waitForCompletion) command is used to spin the Motor for a specific rotation. The rotation is relative to the current rotation of the Motor.

Parameters	Description
rotation	The rotation value for the Motor to spin for.
units	A valid RotationUnit.
velocity	The velocity with which the Motor will spin.
units_v	A valid VelocityUnit.
waitForCompletion	Determines whether the command will block subsequent commands (wait=true) or allow immediate execution (wait=false). If unspecified, the default for the wait parameter is wait=true.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 for 1000 degrees at 25 rpm.
Motor1.spinFor(1000, degrees, 25, rpm);

The spinFor(dir, rotation, units, velocity, units_v, waitForCompletion) command is used to spin the Motor for a specific rotation in a specific direction. The rotation is relative to the current rotation of the Motor.

Parameters	Description
dir	A valid DirectionType.
rotation	The rotation value for the motor to spin for.
units	A valid RotationUnit.
velocity	The velocity with which the Motor will spin.
units_v	A valid VelocityUnit.
waitForCompletion	Determines whether the command will block subsequent commands (wait=true) or allow immediate execution (wait=false). If unspecified, the default for the wait parameter is wait=true.

Returns: A Boolean that signifies when the motor has reached the target rotation.

// Spin Motor1 forard for 1000 degrees at 25 rpm.
Motor1.spinFor(forward, 1000, degrees, 25, rpm);

stop()

This is a non-blocking command and allows the next command to run without delay.

This method is called in the following ways:

The stop() command is used to stop a Motor, setting the Motor to 0 velocity and configuring the current stopping mode. The default Brake Type is coast, unless previously changed using the setStopping() command.

Returns: None.

// Spin Motor1 for 2.5 seconds.
Motor1.spin(forward);

wait(2.5 seconds);

// Stop Motor1.
Motor1.stop();

The stop(mode) command is used to stop a Motor using a specific Brake Type.

Parameters	Description
mode	A valid BrakeType.

Returns: None.

// Spin Motor1 for 2.5 seconds.
Motor1.spin(forward);

wait(2.5 seconds);

// Stop Motor1 using the hold Brake Type.
Motor1.stop(hold);

setVelocity()

The setVelocity(velocity, units) command is used to set the default velocity for a Motor. This velocity setting will be used for subsequent calls to any motion functions if a specific velocity is not provided.

Parameters	Description
velocity	The new velocity to set for the Motor.
units	A valid VelocityUnit or percent.

Returns: None.

setReversed()

The setReversed(value) command sets the Motor direction to be reversed. Constructing a Motor with the reverse parameter set to true has the same result as Motor1.setReversed(true)

Parameters	Description
value	A Boolean value to set the Motor direction reversed or not.

Returns: None.

setStopping()

The setStopping(mode) command is used to set the stopping mode for a Motor. This will be the stopping mode used when the stop() command is called.

Parameters	Description
mode	A valid BrakeType.

Returns: None.

resetPosition()

The resetPosition() command resets the Motor’s encoder value to 0.

Returns: None.

setPosition()

The setPosition(value, units) command is used to set the value of a Motor’s encoder to a specific value. The position that is returned by the position() command will be updated to this new value.

Parameters	Description
value	The new position to set for the Motor’s encoder.
units	A valid RotationUnit.

Returns: None.

setTimeout()

The Motor.setTimeout(value, units) command is used to set the timeout for motor commands. If a Motor does not reach its’ commanded position prior to the completion of the timeout, the Motor will stop.

Parameters	Description
value	The new timeout to set for the Motor.
units	A valid TimeUnit.

Returns: None.

isSpinning()

The isSpinning() command returns if the Motor is currently rotating to a specific target.

Returns: true if the Motor is on and is rotating to a target. false if it is done rotating to a target.

isDone()

The isDone() command returns if the Motor is done rotating to a specific target.

Returns: true if the Motor is done rotating to a target. false if it is on and rotating to a target.

setMaxTorque()

This method is called in the following ways:

The setMaxTorque(value, units) command is used to set the maximum torque for a Motor.

Parameters	Description
value	The new maximum torque for a Motor.
units	A valid TorqueUnit.

Returns: None.

// Set maximum torque to 2 Newton Meters.
Motor1.set_max_torque(2, Nm);

The setMaxTorque(value, units) command is used to set the maximum torque for a Motor.

Parameters	Description
value	The new maximum torque for a Motor.
units	The only valid unit is amp.

Returns: None.

// Set maximum torque to ,05 amps.
Motor1.set_max_torque(.05, amp);

The setMaxTorque(value, units) command is used to set the maximum torque for a Motor as a percentage.

Parameters	Description
value	The new maximum torque for a Motor.
units	The only valid unit is percent.

Returns: None.

// Set maximum torque to 75 percent.
Motor1.set_max_torque(75, percent);

convertVelocity()

The convertVelocity(velocity, units, unitsout) command converts the velocity in the given units to the given output units based on the Motor gearing.

Parameters	Description
velocity	The velocity to convert.
units	A valid VeloctyUnit for the input velocity.
unitsout	A valid VeloctyUnit for the output velocity.

Returns: A double representing the velocity converted to the specified output units.

getMotorCartridge()

The getMotorCartridge() command returns the gear cartridge setting for the Motor.

Returns: The gear cartridge setting of the Motor.

direction()

The direction() command returns the current direction the Motor is spinning in as a directionType.

Returns: A DirectionType value representing current direction that the Motor is spinning in.

position()

The position(units) command returns the current rotation of the Motor.

Parameters	Description
units	A valid RotationUnit.

Returns: A double representing the current rotation of the Motor in the specified units.

velocity()

The velocity(units) command returns the current velocity of the Motor.

Parameters	Description
units	A valid VelocityUnit or percent.

Returns: A double representing the current velocity of the Motor in the specified units.

current()

The current(units) command returns the current being used by the Motor.

Parameters	Description
units	The only valid units for current are amp or percent.

Returns: A double representing the current being drawn by the Motor in the specified units.

voltage()

The voltage(units) command returns the electrical voltage of the Motor.

Parameters	Description
units	A valid VoltageUnit. The default is volt.

Returns: A double representing the electrical voltage of the Motor in the specified units.

power()

The power(units) command returns the power being consumed by the Motor.

Parameters	Description
units	The only valid unit for power is watt.

Returns: A double representing the current power of the Motor in the specified units.

torque()

The torque(units) command returns the torque of the Motor.

Parameters	Description
units	A valid TorqueUnit.

Returns: The torque of the Motor in the specified units.

efficiency()

The efficiency(units) command returns the efficiency of the Motor.

Parameters	Description
units	The only valid unit for efficiency is percent.

Returns: The efficiency of the Motor as a percent.

temperature()

The temperature(units) command returns the current temperature of the Motor.

Parameters	Description
units	A valid TemperatureUnit or percent.

Returns: The current temperature of the Motor in the specified units.

installed()

The installed() command returns if the Motor is connected to the IQ (1st gen) Brain.

Returns: true if the Motor is connected to the IQ (1st gen) Brain. false if it is not.