> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Car Control

This tutorial guides you through the process of controlling vehicles in the AirGen simulation environment. You'll learn how to initialize a car, access its state, and apply various control commands including forward movement, steering, reverse, and braking.

<Note>
  Notebook for this example can be found: [Here](https://grid.generalrobotics.dev/shared/9c91bc1b-c71f-451a-ac73-a03ed726c458)
</Note>

## Getting Started

First, let's initialize an AirGen car object. This is your entry point to controlling vehicles in the GRID platform.

```python theme={null}
from grid.robot.wheeled.airgen_car import AirGenCar
airgen_car_0 = AirGenCar()
```

This code creates an instance of a car that we can control in our simulation. The `AirGenCar` class provides an interface to the underlying vehicle simulation.

<Tip>
  All client methods accept an optional `robot_name`. With a single car you can omit it; for multiple cars pass the matching key from your session configuration (for example, `robot_name="car0"`).
</Tip>

## Basic Car Control

After initializing our car, we need to import the AirGen library and access the car's current state. We'll then disable automatic speed control to manually control the vehicle.

```python theme={null}
import airgen
import time

# Get current car state 
car_state = airgen_car_0.client.getCarState()

# Disable automatic speed control
airgen_car_0.client.enableCarSpeedControl(False)
```

Now we can create a `CarControls` object and set properties to control the car's movement:

```python theme={null}
# Create control object
car_controls = airgen.CarControls()

# Set throttle (range 0-1) and steering (range -1 to 1)
car_controls.throttle = 0.5  # 50% throttle
car_controls.steering = 0.0  # Straight ahead

# Apply controls to the car
airgen_car_0.client.setCarControls(car_controls)
print("Going forward...")

# Let car drive for 3 seconds
time.sleep(3)   

# Stop the car by setting controls back to default
print("Stopping...")
airgen_car_0.client.setCarControls(airgen.CarControls())
```

<img src="https://mintcdn.com/scaledfoundations/SPchGUdKgmObHOPW/assets/airgen-examples/car-control/cc-forward.gif?s=c6a3a989b2fdd8c7effc3aa8ac642f60" alt="Car moving forward" width="100%" data-path="assets/airgen-examples/car-control/cc-forward.gif" />

## Steering Control

Let's explore how to steer the car while moving forward:

```python theme={null}
# Go forward + steer right
car_controls.throttle = 0.5  # 50% throttle
car_controls.steering = 1    # Full right turn (range is -1 to 1)
airgen_car_0.client.setCarControls(car_controls)
print("Going forward, steering right")

# Let car drive for 3 seconds
time.sleep(3)

# Stop the car
print("Stopping...")
airgen_car_0.client.setCarControls(airgen.CarControls())
```

<Note>
  The steering value ranges from -1 (full left) to 1 (full right), with 0 representing straight ahead.
</Note>

<img src="https://mintcdn.com/scaledfoundations/SPchGUdKgmObHOPW/assets/airgen-examples/car-control/cc-turn.gif?s=2dcd509df4d5bff7a626df667c31be90" alt="Car steering " width="100%" data-path="assets/airgen-examples/car-control/cc-turn.gif" />

## Reverse Operation

To move the car in reverse, we need to set the gear to manual and select reverse:

```python theme={null}
# Go in reverse
car_controls.throttle = 0.5        # 50% throttle
car_controls.is_manual_gear = True # Enable manual gear selection
car_controls.manual_gear = -1      # Set to reverse gear
car_controls.steering = 0          # Straight ahead
airgen_car_0.client.setCarControls(car_controls)
print("Going reverse...")

# Let car drive for 3 seconds
time.sleep(3)
```

<img src="https://mintcdn.com/scaledfoundations/SPchGUdKgmObHOPW/assets/airgen-examples/car-control/cc-reverse.gif?s=b60867b8cfd4be0e19f8d25143e40af0" alt="Car in Reverse " width="100%" data-path="assets/airgen-examples/car-control/cc-reverse.gif" />

## Applying Brakes

Finally, let's see how to apply brakes to stop the car:

```python theme={null}
# Apply brakes
car_controls.is_manual_gear = False # Change back to automatic gear
car_controls.manual_gear = 0        # Reset gear selection
car_controls.throttle = 0           # No throttle
car_controls.brake = 1              # Full braking (range 0-1)
airgen_car_0.client.setCarControls(car_controls)
print("Applying brakes...")

# Let brakes work for 3 seconds
time.sleep(3.5)

# Release the brakes
car_controls.brake = 0
```

## Car Control Parameters

The `CarControls` object supports several parameters:

| Parameter        | Range   | Description                                                     |
| ---------------- | ------- | --------------------------------------------------------------- |
| throttle         | 0 to 1  | Controls acceleration (0 = no throttle, 1 = full throttle)      |
| steering         | -1 to 1 | Controls turning (-1 = full left, 0 = straight, 1 = full right) |
| brake            | 0 to 1  | Controls braking (0 = no brake, 1 = full brake)                 |
| handbrake        | boolean | Applies the handbrake when set to True                          |
| is\_manual\_gear | boolean | Enables manual gear selection when True                         |
| manual\_gear     | integer | Gear selection (-1 = reverse, 0 = neutral, 1+ = forward gears)  |