Motor API

The motor API allows you to give commands to your motor components for operating a motor or getting its current status.

The motor component supports the following methods:

API

SetPower

Set the portion of max power to send to the motor (between -1 and 1). A value of 1 represents 100% power forwards, while a value of -1 represents 100% power backwards.

Power is expressed as a floating point between -1 and 1 that scales between -100% and 100% power. Supported by viam-micro-server.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• power ( float) (required): Power between -1 and 1 (negative implies backwards).
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

SetRPM

Spin the motor indefinitely at the specified speed, in revolutions per minute. If rpm is positive, the motor will spin forwards, and if rpm is negative, the motor will spin backwards.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• rpm ( float) (required): Speed at which the motor should rotate.
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

GoFor

Spin the motor the specified number of revolutions at specified revolutions per minute. When rpm or revolutions is a negative value, the motor spins in the backward direction. If both rpm and revolutions are negative, the motor spins in the forward direction.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• rpm ( float) (required): Speed at which the motor should move in rotations per minute (negative implies backwards).
• revolutions ( float) (required): Number of revolutions the motor should run for (negative implies backwards).
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

GoTo

Turn the motor to a specified position (in terms of revolutions from home/zero) at a specified speed in revolutions per minute (RPM). Regardless of the directionality of the rpm, the motor will move towards the specified target position. This blocks until the position has been reached.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• rpm ( float) (required): Speed at which the motor should rotate (absolute value).
• position_revolutions ( float) (required): Target position relative to home/zero, in revolutions.
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

ResetZeroPosition

Set the current position (modified by offset) to be the new zero (home) position.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• offset ( float) (required): The offset from the current position to new home/zero position.
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

GetPosition

Report the position of the motor based on its encoder. The value returned is the number of revolutions relative to its zero position. This method raises an exception if position reporting is not supported by the motor. Supported by viam-micro-server.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• ( float): : Number of revolutions the motor is away from zero/home.

Example:

For more information, see the Python SDK Docs.

GetProperties

Report a dictionary mapping optional properties to whether it is supported by this motor. Supported by viam-micro-server.

• Python
• Go
• TypeScript
• Flutter

Parameters:

Returns:

• ( viam.components.motor.motor.Motor.Properties): : Map of feature names to supported status.

Example:

For more information, see the Python SDK Docs.

IsPowered

Return whether or not the motor is currently running, and the portion of max power (between 0 and 1; if the motor is off the power will be 0). Stepper motors will report true if they are being powered while holding a position, as well as when they are turning.

• Python
• Go
• TypeScript
• Flutter

Parameters:

Returns:

• (Tuple[ bool, float]): : A tuple containing two values; the first [0] value indicates whether the motor is currently powered, and the second [1] value indicates the current power percentage of the motor.

Example:

For more information, see the Python SDK Docs.

IsMoving

Return whether the motor is actively moving (or attempting to move) under its own power. Supported by viam-micro-server.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• ( bool): : Whether the motor is moving.

Example:

For more information, see the Python SDK Docs.

Stop

Cut the power to the motor immediately, without any gradual step down. Supported by viam-micro-server.

• Python
• Go
• TypeScript
• Flutter

Parameters:

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

GetGeometries

Get all the geometries associated with the motor in its current configuration, in the frame of the motor. The motion and navigation services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

• Python

Parameters:

Returns:

• ( List[viam.proto.common.Geometry]): : The geometries associated with the Component.

Example:

For more information, see the Python SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

• Go

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• deps (Dependencies): The resource dependencies.
• conf (Config): The resource configuration.

Returns:

• (error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the component API. Most models do not implement DoCommand. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own motor and want to add features that have no corresponding built-in API method, you can implement them with DoCommand.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• command (Mapping[ str, ValueTypes]) (required): The command to execute.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• (Mapping[ str, viam.utils.ValueTypes]): : Result of the executed command.

Raises:

• (NotImplementedError): Raised if the Resource does not support arbitrary commands.

Example:

For more information, see the Python SDK Docs.

GetResourceName

Get the ResourceName for this motor.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• name ( str) (required): The name of the Resource.

Returns:

• ( viam.proto.common.ResourceName): : The ResourceName of this Resource.

Example:

For more information, see the Python SDK Docs.

Close

Safely shut down the resource and prevent further use.

• Python
• Go

Parameters:

• None.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.