# sensor-controlled

A `sensor-controlled` base supports a robotic base with feedback control from a movement sensor.

#### Requirements

In order to use feedback control, you must provide a movement sensor that implements [AngularVelocity()](https://docs.viam.com/reference/apis/components/movement-sensor/#getangularvelocity) and [LinearVelocity()](https://docs.viam.com/reference/apis/components/movement-sensor/#getlinearvelocity). This will enable feedback control for [SetVelocity()](https://docs.viam.com/reference/apis/components/base/#setvelocity).

In order to use feedback control for [Spin()](https://docs.viam.com/reference/apis/components/base/#spin), you must also provide a movement sensor that implements [Orientation()](https://docs.viam.com/reference/apis/components/movement-sensor/#getorientation).

In order to use feedback control for [MoveStraight()](https://docs.viam.com/reference/apis/components/base/#spin), you must also provide a movement sensor that implements [Position()](https://docs.viam.com/reference/apis/components/movement-sensor/#getposition). Additionally, heading feedback control while moving straight can be used by providing a movement sensor that implements [Orientation()](https://docs.viam.com/reference/apis/components/movement-sensor/#getorientation) or [CompassHeading()](https://docs.viam.com/reference/apis/components/movement-sensor/#getcompassheading).

To configure a `sensor-controlled` base as a component of your machine, first configure the [model of base](https://docs.viam.com/reference/components/base/) you want to wrap with feedback control and each required [movement sensor](https://docs.viam.com/reference/components/movement-sensor/).
To see what models of movement sensor report which feedback, reference the appropriate column in [Movement Sensor API](https://docs.viam.com/reference/apis/components/movement-sensor/#api).

Configure a `sensor-controlled` base as follows:

- [JSON Template](https://docs.viam.com/reference/components/base/sensor-controlled/#configure-a-sensor-controlled-base-0)

The following attributes are available for `sensor-controlled` bases:

| Name | Type | Required? | Description |
| --- | --- | --- | --- |
| `movement_sensor` | array | **Required** | Array with the `name`s of any movement sensors on your base you want to gather feedback from. The driver will select the first movement sensor providing appropriate feedback for either the `SetVelocity()` or the `Spin()` endpoint.<br>If your sensor has an adjustable frequency or period, set the frequency to something greater than or equal to the `control_frequency_hz`. A higher frequency will generally result in more stable behavior because the base control loop that adjusts the machine’s behavior runs more frequently. |
| `base` | string | **Required** | String with the `name` of the base you want to wrap with sensor control. |
| `control_parameters` | object | Optional | A JSON object containing the coefficients for the proportional, integral, and derivative terms for linear and angular velocity. If you want these values to be auto-tuned, you can set all values to 0: `[ { "type": "linear_velocity", "p": 0, "i": 0, "d": 0 }, { "type": "angular_velocity", "p": 0, "i": 0, "d": 0 } ]`, and `viam-server` will auto-tune and log the calculated values. Tuning takes several seconds and spins the motors. Copy the values from the logs and add them to the configuration once tuned for the values to take effect. If you need to auto-tune multiple controlled components that depend on the same hardware, such as a sensor controlled base and one of the motors on the base, run the auto-tuning process one component at a time. For more information see [Feedback control](https://docs.viam.com/reference/components/base/sensor-controlled/#feedback-control). |
| `control_frequency_hz` | float | Optional | Adjusts the frequency that the base control loop runs at. A higher frequency will generally result in more stable behavior because the base control loop that adjusts the machine’s behavior runs more frequently, provided the movement sensors can support the higher frequency. The default base control loop frequency is 10Hz. |

## Feedback control

### SetVelocity

If you want to control your base by specifying a desired velocity in terms of distance/time, for example 5 m/s, and you have a movement sensor that measures the actual velocity, you can use the sensor to adjust the velocity. Alternatively, if your base has position reporting motors, you can use the [wheeled odometry](https://docs.viam.com/reference/components/movement-sensor/wheeled-odometry/) movement sensor to get an estimate of the necessary velocities.

Setting the `control_parameters` attribute sets up a PID control loop. Setting the `control_parameters` will automatically set up the required PID loop for a sensor controlled base.
For more information on PID or to set up a more complex control loop, see the [controls package](https://docs.viam.com/reference/controls-package/)

If you want these values to be auto-tuned, you can set all values to 0: `[ { "type": "linear_velocity", "p": 0, "i": 0, "d": 0 }, { "type": "angular_velocity", "p": 0, "i": 0, "d": 0 } ]`, and `viam-server` will auto-tune and log the calculated values. Tuning takes several seconds and spins the motors. Copy the values from the logs and add them to the configuration once tuned for the values to take effect.

#### Note

If you need to auto-tune multiple controlled components that depend on the same hardware, such as a sensor controlled base and one of the motors on the base, run the auto-tuning process one component at a time.

### Spin

When the `control_parameters` attribute is set, `Spin` implements a form of feedback control that polls the provided movement sensor and corrects any error between the desired angular velocity and the actual angular velocity using a PID control loop. `Spin` also monitors the angular distance traveled and stops the base when the goal angle is reached.

### MoveStraight

When `control_parameters` is set, `MoveStraight` calculates the required velocity to reach the desired velocity and distance. It then polls the provided velocity movement sensor and corrects any error between this calculated velocity and the actual velocity using a PID control loop. `MoveStraight` also monitors the position and stops the base when the goal distance is reached. If a compass heading movement sensor is provided, `MoveStraight` will attempt to keep the heading of the base fixed in the original direction it was faced at the beginning of the `MoveStraight` call.