# Motor API The motor API allows you to give commands to your [motor components](https://docs.viam.com/reference/components/motor/) for operating a motor or getting its current status. The motor component supports the following methods: | Method Name | Description | `viam-micro-server` Support | | --- | --- | --- | | [`SetPower`](https://docs.viam.com/reference/apis/components/motor/#setpower) | Set the portion of max power to send to the motor (between `-1` and `1`). | | | [`SetRPM`](https://docs.viam.com/reference/apis/components/motor/#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. | | | [`GoFor`](https://docs.viam.com/reference/apis/components/motor/#gofor) | Spin the motor the specified number of revolutions at specified revolutions per minute. | | | [`GoTo`](https://docs.viam.com/reference/apis/components/motor/#goto) | Turn the motor to a specified position (in terms of revolutions from home/zero) at a specified speed in revolutions per minute (RPM). | | | [`ResetZeroPosition`](https://docs.viam.com/reference/apis/components/motor/#resetzeroposition) | Set the current position (modified by `offset`) to be the new zero (home) position. | | | [`GetPosition`](https://docs.viam.com/reference/apis/components/motor/#getposition) | Report the position of the motor based on its encoder. | | | [`GetProperties`](https://docs.viam.com/reference/apis/components/motor/#getproperties) | Report a dictionary mapping optional properties to whether it is supported by this motor. | | | [`IsPowered`](https://docs.viam.com/reference/apis/components/motor/#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`). | | | [`IsMoving`](https://docs.viam.com/reference/apis/components/motor/#ismoving) | Return whether the motor is actively moving (or attempting to move) under its own power. | | | [`Stop`](https://docs.viam.com/reference/apis/components/motor/#stop) | Cut the power to the motor immediately, without any gradual step down. | | | [`GetGeometries`](https://docs.viam.com/reference/apis/components/motor/#getgeometries) | Get all the geometries associated with the motor in its current configuration, in the frame of the motor. | | | [`Reconfigure`](https://docs.viam.com/reference/apis/components/motor/#reconfigure) | Reconfigure this resource. | | | [`DoCommand`](https://docs.viam.com/reference/apis/components/motor/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. | | | [`GetResourceName`](https://docs.viam.com/reference/apis/components/motor/#getresourcename) | Get the `ResourceName` for this motor. | | | [`Close`](https://docs.viam.com/reference/apis/components/motor/#close) | Safely shut down the resource and prevent further use. | | ## 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](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-1-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-1-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-1-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-1-3) **Parameters:** - `power` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Power between -1 and 1 (negative implies backwards). - `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.set_power). ### 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](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-2-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-2-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-2-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-2-3) **Parameters:** - `rpm` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Speed at which the motor should rotate. - `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.set_rpm). ### 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](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-3-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-3-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-3-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-3-3) **Parameters:** - `rpm` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Speed at which the motor should move in rotations per minute (negative implies backwards). - `revolutions` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Number of revolutions the motor should run for (negative implies backwards). - `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.go_for). ### 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](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-4-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-4-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-4-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-4-3) **Parameters:** - `rpm` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Speed at which the motor should rotate (absolute value). - `position_revolutions` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Target position relative to home/zero, in revolutions. - `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.go_to). ### ResetZeroPosition Set the current position (modified by `offset`) to be the new zero (home) position. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-5-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-5-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-5-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-5-3) **Parameters:** - `offset` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): The offset from the current position to new home/zero position. - `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.reset_zero_position). ### 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](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-6-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-6-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-6-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-6-3) **Parameters:** - `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. **Returns:** - ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)): : Number of revolutions the motor is away from zero/home. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.get_position). ### GetProperties Report a dictionary mapping optional properties to whether it is supported by this motor. Supported by `viam-micro-server`. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-7-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-7-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-7-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-7-3) **Parameters:** **Returns:** - ( [viam.components.motor.motor.Motor.Properties](https://python.viam.dev/autoapi/viam/components/motor/motor/index.html#viam.components.motor.motor.Motor.Properties)): : Map of feature names to supported status. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.get_properties). ### 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](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-8-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-8-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-8-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-8-3) **Parameters:** **Returns:** - (Tuple[ [bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool), [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)]): : 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:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.is_powered). ### IsMoving Return whether the motor is actively moving (or attempting to move) under its own power. Supported by `viam-micro-server`. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-9-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-9-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-9-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-9-3) **Parameters:** - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. **Returns:** - ( [bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)): : Whether the motor is moving. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.is_moving). ### Stop Cut the power to the motor immediately, without any gradual step down. Supported by `viam-micro-server`. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-10-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-10-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-10-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-10-3) **Parameters:** **Returns:** - None. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.stop). ### GetGeometries Get all the geometries associated with the motor in its current configuration, in the [frame](https://docs.viam.com/reference/services/frame-system/) of the motor. The [motion](https://docs.viam.com/reference/services/motion/) and [navigation](https://docs.viam.com/reference/services/navigation/) services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-11-0) **Parameters:** **Returns:** - ( [List[viam.proto.common.Geometry]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Geometry)): : The geometries associated with the Component. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.get_geometries). ### Reconfigure Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place. - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-12-0) **Parameters:** - `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. - `deps` [(Dependencies)](https://pkg.go.dev/go.viam.com/rdk/resource#Dependencies): The resource dependencies. - `conf` [(Config)](https://pkg.go.dev/go.viam.com/rdk/resource#Config): The resource configuration. **Returns:** - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource). ### 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`](https://docs.viam.com/reference/sdks/docommand/). - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-13-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-13-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-13-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-13-3) **Parameters:** - `command` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), ValueTypes]) (required): The command to execute. - `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes]): : Result of the executed command. **Raises:** - (NotImplementedError): Raised if the Resource does not support arbitrary commands. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.do_command). ### GetResourceName Get the `ResourceName` for this motor. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-14-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-14-1) - [TypeScript](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-14-2) - [Flutter](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-14-3) **Parameters:** - `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource. **Returns:** - ( [viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.get_resource_name). ### Close Safely shut down the resource and prevent further use. - [Python](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-15-0) - [Go](https://docs.viam.com/reference/apis/components/motor/#tabset-referenceapiscomponentsmotor-15-1) **Parameters:** - None. **Returns:** - None. **Example:** ```python ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/motor/client/index.html#viam.components.motor.client.MotorClient.close).