# esp32

#### REQUIREMENTS

Follow the [setup guide](https://docs.viam.com/set-up-a-machine/) to install and run `viam-micro-server` before configuring an `esp32` board.

Viam recommends purchasing the ESP32 with a development board. The following ESP32 microcontrollers are supported:

- ESP-32-WROVER Series

Your microcontroller should have at least the following resources available to work with `viam-micro-server`:

- 2 Cores + 384kB SRAM + 2MB PSRAM + 8MB Flash

To test your board as you configure it, power it on. If you plan to connect hardware to the board’s pins, connect the hardware while it’s powered off. To configure an `esp32` board, navigate to the **CONFIGURE** tab of your machine’s page and select **JSON** mode.

#### Info

The `esp32` [board](https://docs.viam.com/reference/components/board/) model is not currently available when configuring your machine using **Builder** mode.

Copy the following JSON template and paste it into your configuration inside the `"components"` array:

- [JSON Template](https://docs.viam.com/reference/components/board/micro-rdk/esp32/#configure-an-esp32-board-0)
- [JSON Example](https://docs.viam.com/reference/components/board/micro-rdk/esp32/#configure-an-esp32-board-1)

```json

```

Copy

```json

```

Copy

Edit and fill in the attributes as applicable. Click the **Save** button in the top right corner of the page.

The following attributes are available for `esp32` boards:

| Name                | Type   | Required? | Description                                                                                                         |
|---------------------|--------|------------|---------------------------------------------------------------------------------------------------------------------|
| `analogs`           | array  | Optional   | Attributes of any pins that can be used as analog-to-digital converter (ADC) inputs. See [configuration info](https://docs.viam.com/reference/components/board/micro-rdk/esp32/#analogs). |
| `i2cs`              | array  | Optional   | Any Inter-Integrated Circuit (I2C) pins’ bus index and name. See [configuration info](https://docs.viam.com/reference/components/board/micro-rdk/esp32/#i2cs). |
| `digital_interrupts`| array  | Optional   | Any digital interrupts’ GPIO number. See [configuration info](https://docs.viam.com/reference/components/board/micro-rdk/esp32/#digital_interrupts). |
| `pins`              | array  | Optional   | The GPIO number of any GPIO pins you wish to use as input/output with the [board API](https://docs.viam.com/reference/apis/components/board/#api). |

Any pin not specified in either `"pins"` or `"digital_interrupts"` cannot be interacted with through the [board API](https://docs.viam.com/reference/apis/components/board/#api). Interaction with digital interrupts is only supported with the [board API](https://docs.viam.com/reference/apis/components/board/#api); these digital interrupts cannot be used as software interrupts in driver implementations.

## `analogs`

The following properties are available for `analogs`:

| Name  | Type     | Required? | Description                                           |
|-------|----------|------------|-------------------------------------------------------|
| `name`| string   | **Required** | Your name for the analog reader.                      |
| `pin` | integer  | **Required** | The GPIO number of the ADC’s connection pin, wired to the board. |

### `i2cs`

The following properties are available for `i2cs`:

| Name        | Type    | Required? | Description                                       |
|-------------|---------|------------|---------------------------------------------------|
| `name`      | string  | **Required** | `name` of the I2C bus.                           |
| `bus`       | string  | **Required** | The index of the I2C bus. Must be either `i2c0` or `i2c1`. |
| `data_pin`  | integer | Optional   | The GPIO number of the data pin. Default: `11`. |
| `clock_pin` | integer | Optional   | The GPIO number of the clock pin. Default: `6`. |
| `baudrate_hz` | integer | Optional   | The baudrate in HZ of this I2C bus. Default: `1000000` |
| `timeout_ns` | integer | Optional   | Timeout period for this I2C bus in nanoseconds. Default: `0` |

### `digital_interrupts`

The following properties are available for `digital_interrupts`:

| Name  | Type     | Required? | Description                                               |
|-------|----------|------------|----------------------------------------------------------|
| `pin` | integer  | **Required** | The GPIO number of the board’s GPIO pin that you wish to configure the digital interrupt for. |

### PWM signals on `esp32` pins

You can set PWM frequencies with Viam through the [`GPIOPin` API](https://docs.viam.com/reference/apis/components/board/#api). Refer to the [Espressif documentation for valid frequencies and duty resolutions](https://docs.espressif.com/projects/esp-idf/en/v5.4/esp32/api-reference/peripherals/ledc.html#supported-range-of-frequency-and-duty-resolutions). A configured `esp32` board can support a maximum of four different PWM frequencies simultaneously, as the boards only have four available timers.

For example:

| Pin | PWM Frequency (Hz) |
|-----|---------------------|
| 12  | 2000                |
| 25  | 3000                |
| 26  | 5000                |
| 32  | 6000                |

At this point, if you want to add another PWM signal, you must do the following:

1. Set the PWM frequency before the duty cycle.
2. Set the PWM frequency to one of the above previously set frequencies.

For example, you can set pin 33 to 2000 Hz:

| Pin      | PWM Frequency (Hz) |
|----------|---------------------|
| 12, 33  | 2000                |
| 25       | 3000                |
| 26       | 5000                |
| 32       | 6000                |

Then, follow these requirements to change the PWM frequencies of a pin:

1. If no other pins have a signal of the same frequency (for example, pins 25, 26, and 32), you can freely change their PWM frequency.
2. If one or more pins are sharing the old frequency (for example, pins 12 and 33):
   1. If there are less than 4 active frequencies, you can change the PWM frequency freely because there will be a timer available.
   2. If there are already 4 active frequencies, changing the PWM frequency of the pin will raise an error because there are no timers available. Free a timer by setting the PWM frequencies of all of the pins to 0.