# Motion and Mobility

In this section you can find all of Misty's API calls for motion and mobility.

### **MoveArm**

Moves one or both of Misty's arms up and down.

**Example Code**

{% hint style="success" %}

```python
misty.move_arm("left", 50, 100)
```

{% endhint %}

When moving Misty's arms, it's helpful to understand their orientation.

* At 0 degrees, Misty's arms point straight forward along her X axis, parallel to the ground.
* At +90 degrees, Misty's arms point straight down towards the ground.
* At +/- 180 degrees, Misty's arms would face straight back, pointing toward her backpack; however, Misty's arms are not currently configured to move to this position.
* At -90/+270 degrees, Misty's arms would point straight up towards her head, perpendicular to the ground; however, the upward movement of Misty's arm movement is currently limited to -29 degrees.

**Parameters**

{% code overflow="wrap" %}

```python
misty.move_arm(self, arm : str = None, position : float = None, velocity : float = None, duration : float = None, units : str = None)
```

{% endcode %}

* `Arm` (string) - The arm to move. You must use either `left`, `right`, or `both`.
* `Position` (double) - The new position to move the arm to. Use the `Units` parameter to determine whether to use `position`, `degrees`, or `radians`. Defaults to `degrees`.
* `Velocity` (double) - Optional. A value of 0 to 100, specifying the speed with which the arm should move. Defaults to `null`.
* `Units` (string) - Optional. A string value of `degrees`, `radians`, or `position` that determines which unit to use in moving Misty's arms.

### **MoveArms**

Moves one or both of Misty's arms. You can control both arms simultaneously or one at a time.

**Example Code**

{% hint style="success" %}

```python
misty.move_arms(40, 40, 100, 100)
```

{% endhint %}

When moving Misty's arms, it's helpful to understand their orientation.

* At 0 degrees, Misty's arms point straight forward along her X axis, parallel to the ground.
* At +90 degrees, Misty's arms point straight down towards the ground.
* At +/- 180 degrees, Misty's arms would face straight back, pointing toward her backpack; however, Misty's arms are not currently configured to move to this position.
* At -90/+270 degrees, Misty's arms would point straight up towards her head, perpendicular to the ground; however, the upward movement of Misty's arm movement is currently limited to -29 degrees.

**Parameters**

{% code overflow="wrap" %}

```python
misty.move_arms(self, leftArmPosition : float = None, rightArmPosition : float = None, leftArmVelocity : float = None, rightArmVelocity : float = None, duration : float = None, units : str = None)
```

{% endcode %}

* `LeftArmPosition` (double) - Optional. The new position of Misty's left arm. Use the `Units` parameter to determine whether to use `position`, `degrees`, or `radians`. Defaults to `degrees`.
* `RightArmPosition` (double) - Optional. The new position of Misty's right arm. Use the `Units` parameter to determine whether to use `position`, `degrees`, or `radians`. Defaults to `degrees`.
* `LeftArmVelocity` (double) - Optional. A value of 0 to 100 specifying the speed with which the left arm should move. Defaults to `null`.
* `RightArmVelocity (`double) - Optional. A value of 0 to 100, specifying the speed with which the right arm should move. Defaults to `null`.
* `Units` (string) - Optional. A string value of `degrees`, `radians`, or `position` that determines which unit to use in moving Misty's arms.

### **MoveHead**

Moves Misty's head to a new position along its pitch, roll, and yaw axes.

**Example Code**

{% hint style="success" %}

```python
misty.move_head(-10, 30 ,0 ,100)
```

{% endhint %}

For the value ranges (by unit) for each direction of head movement, see the table below:

| Dimension | Degrees                  | Position               | Radians                       |
| --------- | ------------------------ | ---------------------- | ----------------------------- |
| pitch     | -40 (up) to 26 (down)    | -5 (up) to 5 (down)    | -0.1662 (up) to 0.6094 (down) |
| roll      | -40 (left) to 40 (right) | -5 (left) to 5 (right) | -0.75 (left) to 0.75 (right)  |
| yaw       | -81 (right) to 81 (left) | -5 (right) to 5 (left) | -1.57 (right) to 1.57 (left)  |

**Parameters**

{% code overflow="wrap" %}

```python
misty.move_head(self, pitch : float = None, roll : float = None, yaw : float = None, velocity : float = None, duration : float = None, units : str = None)
```

{% endcode %}

* Pitch (double) - Value that determines the up or down position of Misty's head movement.
* Roll (double) - Value that determines the tilt ("ear" to "shoulder") of Misty's head.
* Yaw (double) - Number that determines the left to right turn position of Misty's head.
* Velocity (double) - Optional. The percentage of max velocity that indicates how quickly Misty should move her head. Value range: 0 to 100. Defaults to 10.
* Duration (double) - Optional. Time (in seconds) Misty takes to move her head from its current position to its new position.
* Units (string) - Optional. A string value of `degrees`, `radians`, or `position` that determines which unit to use in moving Misty's head. Defaults to `degrees`.

### **Drive**

Drives Misty forward or backward at a specific speed until cancelled.

**Example Code**

{% hint style="success" %}

```python
misty.drive(60,60)
```

{% endhint %}

When using the Drive command, it helps to understand how linear velocity (speed in a straight line) and angular velocity (speed and direction of rotation) work together:

* Linear velocity (-100) and angular velocity (0) = driving straight backward at full speed.
* Linear velocity (100) and angular velocity (0) = driving straight forward at full speed.
* Linear velocity (0) and angular velocity (-100) = rotating clockwise at full speed.
* Linear velocity (0) and angular velocity (100) = rotating counter-clockwise at full speed.
* Linear velocity (non-zero) and angular velocity (non-zero) = Misty drives in a curve.

**Parameters**

```python
misty.drive(self, linearVelocity : float = None, angularVelocity : float = None)
```

* `LinearVelocity` (double) - A percent value that sets the speed for Misty when she drives in a straight line. Default value range is from -100 (full speed backward) to 100 (full speed forward).
* `AngularVelocity` (double) - A percent value that sets the speed and direction of Misty's rotation. Default value range is from -100 (full speed rotation clockwise) to 100 (full speed rotation counter-clockwise). **Note:** For best results when using angular velocity, we encourage you to experiment with using small positive and negative values to observe the effect on Misty's movement.

### **DriveArc**

Drives Misty in an arc. Misty continues driving until her current heading matches the desired absolute heading passed into this command.

**Example Code**

{% hint style="success" %}

```python
misty.drive_arc(0, 1, 4000, "false")
```

{% endhint %}

To get Misty's current heading, use the value for `yaw` from the [`IMU`](https://docs.mistyrobotics.com/misty-ii/robot/sensor-data/#imu) named object. To calculate Misty's velocity, use: `((desired_heading - current_heading) * (π/180) * radius) / (timeMs/1000)`.

**Parameters**

{% code overflow="wrap" %}

```python
misty.drive_arc(self, heading : float = None, radius : float = None, timeMs : float = None, reverse : bool = None)
```

{% endcode %}

* `Heading` (double) - The absolute heading Misty should obtain when the arc is complete. To set the absolute heading, use either: 0 - 360, where 0 is straight ahead, 90 is directly to the left, 180 is straight behind, and 270 is directly to the right, or: -180 to 180, where 0 is straight ahead, 90 is directly to the left, 180 and -180 are straight behind, and -90 is directly to the right.
* `Radius` (double) - The radius (in meters) of the arc.
* `TimeMs` (double) - The duration (in milliseconds) that Misty drives.
* `Reverse` (boolean) - Optional. If `true`, Misty drives in reverse. Default is `false`.

### **DriveHeading**

Drives Misty forward or backward in a straight line. While driving, Misty continuously adjusts her current heading to maintain the desired absolute heading.

**Example Code**

{% hint style="success" %}

```python
misty.drive_heading(0, 10, 4000, "false")
```

{% endhint %}

For a smooth driving experience, Misty's current heading should be within two degrees of the desired absolute heading before she executes the `DriveHeading` command. Variations of greater than two degrees result in large correction velocities. You can use the `DriveArc` command to face Misty in the direction of the heading you want her to maintain. Then, use the `DriveHeading` command to drive Misty forward or backward in a straight line. To calculate Misty's velocity, use `distance / (timeMs/1000)`.

**Parameters**

{% code overflow="wrap" %}

```python
misty.drive_heading(self, heading : float = None, distance : float = None, timeMs : float = None, reverse : bool = None)
```

{% endcode %}

* `Heading` (double) - The absolute heading Misty should maintain. To set the absolute heading, use either: 0 - 360, where 0 is straight ahead, 90 is directly to the left, 180 is straight behind, and 270 is directly to the right, or: -180 to 180, where 0 is straight ahead, 90 is directly to the left, 180 and -180 are straight behind, and -90 is directly to the right.
* `Distance` (double) - The distance (in meters) that Misty should drive.
* `TimeMs` (double) - The duration (in milliseconds) that Misty should drive.
* `Reverse` (boolean) - If `true`, Misty drives in reverse. Default is `false`.

### **DriveTime**

Drives Misty forward or backward at a set speed, with a given rotation, for a specified amount of time.

**Example code**

{% hint style="success" %}

```python
misty.drive_time(40,40,1000,30)
```

{% endhint %}

When using the DriveTime command, it helps to understand how linear velocity (speed in a straight line) and angular velocity (speed and direction of rotation) work together:

* Linear velocity (-100) and angular velocity (0) = driving straight backward at full speed.
* Linear velocity (100) and angular velocity (0) = driving straight forward at full speed.
* Linear velocity (0) and angular velocity (-100) = rotating clockwise at full speed.
* Linear velocity (0) and angular velocity (100) = rotating counter-clockwise at full speed.
* Linear velocity (non-zero) and angular velocity (non-zero) = Misty drives in a curve.

**Parameters**

{% code overflow="wrap" %}

```python
misty.drive_time(self, linearVelocity : float = None, angularVelocity : float = None, timeMs : int = None, degree : float = None)
```

{% endcode %}

* `LinearVelocity` (double) - A percent value that sets the speed for Misty when she drives in a straight line. Default value range is from -100 (full speed backward) to 100 (full speed forward).
* `AngularVelocity` (double) - A percent value that sets the speed and direction of Misty's rotation. Default value range is from -100 (full speed rotation clockwise) to 100 (full speed rotation counter-clockwise). **Note:** For best results when using angular velocity, we encourage you to experiment with using small positive and negative values to observe the effect on Misty's movement.
* `TimeMs` (integer) - A value in milliseconds that specifies the duration of movement. Misty will not drive if you pass in a value of less than 100 for this parameter.
* `Degree` (double) - (optional) The number of degrees to turn. **Note:** Supplying a `Degree` value recalculates linear velocity.

### **DriveTrack**

Drives Misty left, right, forward, or backward, depending on the track speeds specified for the individual tracks.

**Example Code**

{% hint style="success" %}

```python
misty.drive_track(30,70)
```

{% endhint %}

**Parameters**

{% code overflow="wrap" %}

```python
misty.drive_track(self, leftTrackSpeed : float = None, rightTrackSpeed : float = None)
```

{% endcode %}

* `LeftTrackSpeed` (double) - A value for the speed of the left track, range: -100 (full speed backward) to 100 (full speed forward).
* `RightTrackSpeed` (double) - A value for the speed of the right track, range: -100 (full speed backward) to 100 (full speed forward).

### **Halt**

Stops all motor controllers, including drive motor, head/neck, and arm.

**Example code**

{% hint style="success" %}

<pre class="language-python"><code class="lang-python"><strong>misty.halt()
</strong></code></pre>

{% endhint %}

**Parameters**

```python
misty.halt(self, motorMask : int = None) 
```

`motorMask` (int): A bitmask representing the motors to be halted. Each bit in the mask corresponds to a specific motor or group of motors. The exact definition of each bit depends on Misty's hardware and firmware configuration.

### **Stop**

Stops Misty's movement.&#x20;

**Example Code**

{% hint style="success" %}

```python
misty.stop()
```

{% endhint %}

**Important!** Under most circumstances, it is best to avoid calling the `Stop` command with a `Hold` value of `true`. Holding Misty's position can strain Misty's drive motors. Stopping Misty's driving without holding her position should suffice under most circumstances and can prolong the life of your robot's drive motors.

**Parameters**

```python
misty.stop(self, hold : bool = None)
```

* `Hold` (boolean) - Optional. Defaults to `false`. If `true`, Misty's drive motors remain engaged after Misty stops moving and attempt to hold the robot in its current position. This can be useful when Misty needs to stop moving while she's on an incline; sending a `Stop` command with a `Hold` value of `true` keeps the motors engaged, so that Misty does not roll down the slope. It is generally recommended to ignore the `Hold` parameter. Stopping Misty's driving without holding her position should suffice under most circumstances and can prolong the life of your robot's drive motors.

### **DriveToLocation (Misty II Pro)**

Drives to a designated waypoint.

**Important!** Make sure to use `StartTracking` before using this command to have Misty start tracking her location, and use `StopTracking` to have her stop tracking her location after she arrives at the specified location.

**Example Code**

{% hint style="success" %}

```python
misty.drive_to_location("destination":"10:25")
```

{% endhint %}

**Parameters**

```python
misty.drive_to_location(self, destination : GridCell = None)
```

* `Destination` (string) - A colon-separated integer pair that represents the X and Y coordinates of the destination. **Note:** `GetMap` obtains the occupancy grid for the most recent map Misty has generated. Use this grid to determine the X and Y coordinates of the destination. The X coordinate of a given cell is the index of the array for the cell. The Y coordinate of a cell is the index of that cell within its array

### **FollowPath (Misty II Pro)**

Drives Misty on a path defined by coordinates you specify. Note that Misty must have a map and be actively tracking before starting to follow a path. Misty will not be able to successfully follow a path if unmapped obstacles are in her way.

**Example Code**

{% hint style="success" %}

```python
misty.follow_path(4:3,8:8,10:15)
```

{% endhint %}

**Important!** Make sure to use `StartTracking` before using this command to have Misty start tracking her location, and use `StopTracking` to have her stop tracking her location after she arrives at the specified location

**Parameters**

{% code overflow="wrap" %}

```python
misty.follow_path(self, path : str = None, velocity : float = None, fullSpinDuration : float = None, waypointAccuracy : float = None, rotateThreshold : float = None)
```

{% endcode %}

* `Path` (string) - A string of comma-separated X:Y coordinates representing waypoints on a path for Misty to track through her currently active map. Each waypoint is a colon-separated integer pair representing the X and Y coordinates of a location on Misty's currently active map. Use `GetMap` to obtain the occupancy grid for Misty's current map, and use this grid to determine the X and Y coordinates of the destination.
* `Velocity` (double) - Optional. A fraction of Misty's max velocity. Determines how fast Misty moves when driving straight while following a path. Expects a decimal value greater than 0 and less than 1. Defaults to `0.5` (50% of max velocity) if not specified.
* `FullSpinDuration` (double) - Optional. Number of seconds it takes for Misty to complete a full spin (360 degrees) while following a path. Determines how fast Misty pivots or spins when changing direction. Defaults to `15` if not specified.
* `WaypointAccuracy` (double) - Optional. How close (in meters) the robot gets to a waypoint before considering itself to have reached that waypoint. Defaults to `0.1` if not specified.
* `RotateThreshold` (double) - Optional. The angle (in degrees) Misty's path following algorithm uses to determine when Misty should pivot toward a waypoint instead of continuing to drive straight. When following a path, Misty drives straight toward her next waypoint until the bearing between the waypoint and her current heading is greater than `RotateThreshold` degrees. When the bearing reaches this threshold, Misty pivots in the direction of the waypoint until the bearing is lower than `RotateThreshold`. When Misty reaches a waypoint, she spins to face the next waypoint and drives straight. As she approaches the waypoint, any error in the original spin causes the bearing angle to grow, causing Misty to stop and turn toward the waypoint; thus, Misty may stop and pivot multiple times between one waypoint and the next. Defaults to `10` if not specified.