motor_group

Initializing the motor_group Class

An IQ (1st gen) motor_group object is created by using the following constructor:

The motor_group constructor creates a motor_group object.

You can create a motor_group with any number of Motors.

// Create 2 Motors, Motor1 and Motor2 in
// Ports 1 and 2 respectively. 
motor Motor1 = motor(PORT1);
motor Motor1 = motor(PORT2);
// Using the two previously created Motors, create a
// motor_group named MotorGroup1.
motor_group MotorGroup1 = motor_group(Motor1, Motor2);

This MotorGroup1 object will be used in all subsequent examples throughout this API documentation when referring to MotorGroup 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 the Motors 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 MotorGroup1 forward.
MotorGroup1.spin(forward);

The spin(dir, velocity, units) command is used to spin the Motors 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 Motors will spin.
units	A valid VelocityUnit or percent.

Returns: None.

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

The spin(dir, voltage, units) command is used to spin the Motors 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 Motors will spin.
units	A valid VoltageUnit.

Returns: None.

// Spin MotorGroup1 forward at 100 volts.
MotorGroup1.spin(forward, 100, volt);

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 the Motors to an absolute rotation in the specified units.

Parameters	Description
rotation	The position to spin the Motors 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 Motors have reached the target rotation.

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

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

Parameters	Description
rotation	The position to spin the Motors to.
units	A valid RotationUnit.
velocity	The velocity with which the Motors 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 Motors have reached the target rotation.

// Spin MotorGroup1 to the absolute position 1080 degrees 
// at 100 percent velocity.
MotorGroup1.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 Motors for a specified duration.

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

Returns: A Boolean that signifies when the Motors have reached the target rotation.

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

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

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

Returns: A Boolean that signifies when the Motors have reached the target rotation.

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

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

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

Returns: A Boolean that signifies when the Motors have reached the target rotation.

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

The spinFor(dir, time, units, velocity, units_v) command is used to spin the Motors 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 Motors for.
units	A valid TimeUnit.
velocity	The velocity with which the Motors will spin.
units_v	A valid VelocityUnit.

Returns: A Boolean that signifies when the Motors have reached the target rotation.

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

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

Parameters	Description
rotation	The rotation value for the Motors 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 Motors have reached the target rotation.

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

The spinFor(dir, rotation, units, waitForCompletion) command is used to spin the Motors 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 Motors 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 Motors have reached the target rotation.

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

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

Parameters	Description
rotation	The rotation value for the Motors to spin for.
units	A valid RotationUnit.
velocity	The velocity with which the Motors 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 Motors have reached the target rotation.

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

The spinFor(dir, rotation, units, velocity, units_v, waitForCompletion) command is used to spin the Motors 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 Motors to spin for.
units	A valid RotationUnit.
velocity	The velocity with which the Motors 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 Motors has reached the target rotation.

// Spin MotorGroup1 forard for 1000 degrees at 25 rpm.
MotorGroup1.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 the Motors, setting them 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 MotorGroup1 for 2.5 seconds.
MotorGroup1.spin(forward);

wait(2.5 seconds);

// Stop MotorGroup1.
MotorGroup1.stop();

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

Parameters	Description
mode	A valid BrakeType.

Returns: None.

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

wait(2.5 seconds);

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

count()

The count() command returns the number of Motors in a Motor Group.

Returns: The number of Motors in the Motor Group.

setVelocity()

The setVelocity(velocity, units) command is used to set the default velocity for the Motors. 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 Motors.
units	A valid VelocityUnit or percent.

Returns: None.

setStopping()

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

Parameters	Description
mode	A valid BrakeType.

Returns: None.

resetPosition()

The resetPosition() command resets the value of all Motor encoders to 0.

Returns: None.

setPosition()

The setPosition(value, units) command is used to set the value of all Motor encoders to a specified value. The position that is returned by the position() command will be updated to this new value.

Parameters	Description
value	The new value to set for all Motor encoders.
units	A valid RotationUnit.

Returns: None.

setTimeout()

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

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

Returns: None.

isSpinning()

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

Returns: true if any Motor is on and is rotating to a target. false if all Motors are done rotating to a target.

isDone()

The isDone() command returns if all Motors are done rotating to a specific target.

Returns: true if all Motors are done rotating to a target. false if any Motor 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 the Motors in torqueUnits.

Parameters	Description
value	The new maximum torque for the Motors.
units	A valid TorqueUnit.

Returns: None.

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

The setMaxTorque(value, units) command is used to set the maximum torque for the Motors in currentUnits.

Parameters	Description
value	The new maximum torque for the Motors.
units	The only valid unit is amp.

Returns: None.

// Set maximum torque to ,05 amps.
MotorGroup1.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 the Motors.
units	The only valid unit is percent.

Returns: None.

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

direction()

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

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

position()

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

Parameters	Description
units	A valid RotationUnit.

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

velocity()

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

Parameters	Description
units	A valid VelocityUnit or percent.

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

current()

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

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

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

voltage()

The voltage(units) command returns the voltage of the first Motor in the Group.

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

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

power()

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

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

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

torque()

The torque(units) command returns the torque of the first Motor in the Group.

Parameters	Description
units	A valid TorqueUnit.

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

efficiency()

The efficiency(units) command returns the efficiency of the first Motor in the Group.

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

Returns: The efficiency of the first Motor in the Group as a percent.

temperature()

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

Parameters	Description
units	A valid TemperatureUnit or percent.

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