/*
 * Copyright (C) 2018 Gunar Schorcht
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
 * @defgroup    boards_esp32_olimex-esp32-evb Olimex ESP32-EVB
 * @ingroup     boards_esp32
 * @brief       Support for Olimex ESP32-EVB and ESP32-GATEWAY
 * @author      Gunar Schorcht <gunar@schorcht.net>

## <a name="toc"> Table of Contents </a>

1. [Overview](#overview)
2. [Hardware](#hardware)
    1. [MCU](#mcu)
    2. [Board Configuration](#board_configuration)
    3. [Board Pinout](#pinout)
    4. [Optional Hardware Configurations](#optional_hardware)
3. [Flashing the Device](#flashing)

## <a name="overview"> Overview </a> &nbsp;&nbsp; [[TOC](#toc)]

[Olimex ESP32-EVB](https://github.com/OLIMEX/ESP32-EVB) and [Olimex ESP32-GATEWAY](https://github.com/OLIMEX/ESP32-GATEWAY) are open source hardware boards which use the ESP32-WROOM module. The key features of the boards are:

- Ethernet LAN interface
- MicroSD card interface
- IR interface (Olimex ESP32-EVB only)
- CAN interface (Olimex ESP32-EVB only)
- two Relais (Olimex ESP32-EVB only)
- [UEXT](https://www.olimex.com/Products/Modules/UEXT/) connector with I2C, SPI and UART interfaces (Olimex ESP32-EVB only)

Using the UEXT connector, a lot of [off-board hardware modules](https://www.olimex.com/Products/Modules/) can be connected to Olimex ESP32-EVB to extend the hardware without the need for soldering iron or breadboards.

Because of the differences in the on-board hardware, it is necessary to add the following line to the makefile of the application to use the according configuration for Olimex ESP32-GATEWAY:
```
USEMODULE += olimex_esp32_gateway
```

@image html "https://gitlab.com/gschorcht/RIOT.wiki-Images/raw/master/esp32/Olimex_ESP32-EVB_GATEWAY.png?inline=false" "Olimex ESP32-EVB (left) and Olimex ESP32-GATEWAY (right)"

## <a name="hardware"> Hardware </a> &nbsp;&nbsp; [[TOC](#toc)]

This section describes

- the [MCU](#mcu),
- the default [board configuration](#board_configuration),
- [optional hardware configurations](#optional_hardware),
- the [board pinout](#pinout).

### <a name="mcu"> MCU </a> &nbsp;&nbsp; [[TOC](#toc)]

Most features of the board are provided by the ESP32 SoC. For detailed
information about the ESP32, see section \ref esp32_mcu "MCU ESP32".

### <a name="board_configuration"> Board Configuration </a> &nbsp;&nbsp; [[TOC](#toc)]

Olimex ESP32-EVB and Olimex ESP32-GATEWAY have the following on-board components:

- Ethernet LAN interface
- MicroSD card interface
- IR interface (Olimex ESP32-EVB only)
- CAN interface (Olimex ESP32-EVB only)
- two Relais (Olimex ESP32-EVB only)
- [UEXT](https://www.olimex.com/Products/Modules/UEXT/) connector with I2C, SPI and UART interfaces (Olimex ESP32-EVB only)

The following table shows the default board configuration, which is sorted according to the defined functionality of GPIOs. This configuration can be overridden by \ref esp32_app_spec_conf "application-specific configurations".

<center>
\anchor esp32_olimex-esp32-evb_table_board_configuration
Pin    | Configuration<b>*</b><br>ESP32-EVB | Configuration<b>*</b><br>ESP32-GATEWAY | Remarks / Prerequisites | Configuration
:------|:------------------|:-----------------|-|-|
GPIO13 | I2C_DEV(0):SDA    | SDCARD_CS      | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_i2c_interfaces "I2C Interfaces"
GPIO16 | I2C_DEV(0):SCL    | I2C_DEV(0):SCL   | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_i2c_interfaces "I2C Interfaces"
GPIO14 | SPI_DEV(0):CLK    | SDCARD_CLK     | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_spi_interfaces "SPI Interfaces"
GPIO2  | SPI_DEV(0):MISO   | SDCARD_MISO    | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_spi_interfaces "SPI Interfaces"
GPIO15 | SPI_DEV(0):MOSI   | SDCARD_MOSI    | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_spi_interfaces "SPI Interfaces"
GPIO17 | SPI_DEV(0):CS0    | I2C_DEV(0):SDA | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_spi_interfaces "SPI Interfaces"
GPIO1  | UART_DEV(0):TxD   | UART_DEV(0):TxD  | Console (cannot be changed) | \ref esp32_uart_interfaces "UART interfaces"
GPIO3  | UART_DEV(0):RxD   | UART_DEV(0):RxD  | Console (cannot be changed) | \ref esp32_uart_interfaces "UART interfaces"
GPIO4  | UART_DEV(1):TxD   | N/A | ESP32-EVB [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_uart_interfaces "UART interfaces"
GPIO36 | UART_DEV(1):RxD   | ADC_LINE(2)    | on ESP32-EVB available at [[UEXT1](https://www.olimex.com/Products/Modules/UEXT)] | \ref esp32_uart_interfaces "UART interfaces"
GPIO32 | Relais 1          | ADC_LINE(0)      | | \ref esp32_adc_channels "ADC Channels"
GPIO33 | Relais 2          | LED0             | | |
GPIO34 | BUTTON0           | BUTTON0          | | |
GPIO9  | PWM_DEV(0):0      | PWM_DEV(0):0     | | \ref esp32_pwm_channels "PWM Channels"
GPIO10 | PWM_DEV(0):1      | PWM_DEV(0):1     | | \ref esp32_pwm_channels "PWM Channels"
GPIO5  | CAN_DEV(0):TX     |                | | \ref esp32_can_interfaces "CAN Interfaces"
GPIO35 | CAN_DEV(0):RX     | ADC_LINE(1)    | | \ref esp32_adc_channels "ADC Channels"
GPIO12 | IR_DEV(0):TX      | N/A            | IR is not yet supported | |
GPIO39 | IR_DEV(0):RX      | ADC_LINE(3)    | IR is not yet supported | \ref esp32_adc_channels "ADC Channels"
GPIO18 | EMAC_SMI:MDIO     | EMAC_SMI:MDIO    | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO23 | EMAC_SMI:MDC      | EMAC_SMI:MDC     | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO0  | EMAC_RMII:TX_CLK  | EMAC_RMII:TX_CLK | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO21 | EMAC_RMII:TX_EN   | EMAC_RMII:TX_EN  | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO19 | EMAC_RMII:TXD0    | EMAC_RMII:TXD0   | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO22 | EMAC_RMII:TXD1    | EMAC_RMII:TXD1   | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO25 | EMAC_RMII:RXD0    | EMAC_RMII:RXD0   | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO26 | EMAC_RMII:RXD1    | EMAC_RMII:RXD1   | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
GPIO27 | EMAC_RMII:RX_DV   | EMAC_RMII:RX_DV  | LAN interface | \ref esp32_ethernet_network_interface "Ethernet MAC"
</center>

@note
- To use the board configuration for Olimex-ESP32-GATEWAY, it is necessary to add the following line to makefile of the application:<br><br>
```
USEMODULE += olimex_esp32_gateway
```
- GPIO9 and GIOP10 can only be used in **dout** and **dio** \ref esp32_flash_modes "flash modes".
- It might be necessary to remove the SD card or the peripheral hardware attached to the SPI_DEV(0) interface for flashing RIOT. Reason is that the **SPI_DEV(0)** interface uses the HSPI interface with the GPIO2 pin as the MISO signal, which has bootstrapping functionality.

For detailed information about the configuration of ESP32 boards, see section \ref esp32_comm_periph "Common Peripherals".

### <a name="optional_hardware"> Optional Hardware Configurations </a> &nbsp;&nbsp; [[TOC](#toc)]

MRF24J40-based IEEE 802.15.4 radio modules have been tested with the board. You could use the following code in your \ref esp32_app_spec_conf "application-specific configuration" to use such modules:

```
#ifdef BOARD_ESP32_OLIMEX_EVB && !MODULE_ESP32_OLIMEX_GATEWAY

#if MODULE_MRF24J40
#define MRF24J40_PARAM_CS       GPIO9       /* MRF24J40 CS signal    */
#define MRF24J40_PARAM_RESET    GPIO10      /* MRF24J40 RESET signal */
#define MRF24J40_PARAM_INT      GPIO34      /* MRF24J40 INT signal   */
#endif

#endif
```
For other parameters, the default values defined by the drivers can be used.

@note
- Since the Olimex-ESP32-GATEWAY does not break out the GPIO of the HSPI interface SPI_DEV(0), it is not possible to connect such module to Olimex-ESP32-GATEWAY.
- Since the Olimex-ESP32-EVB has a lot of on-board hardware, only a few GPIOs are available for external hardware.
- The **RESET** signal of MRF24J40 based modules can also be connected to the **RST** pin of the board (see \ref esp32_olimex-esp32-evb_pinout "pinout") to keep the configured GPIO free for other purposes.

### <a name="pinout"> Board Pinout </a> &nbsp;&nbsp; [[TOC](#toc)]

The following pictures shows the pinout of Olimex ESP32-EVB and Olimex ESP32-GATEWAY boards as defined by the default board configuration. The light green GPIOs are not used by configured on-board hardware components and can be used for any purpose. However, if optional off-board hardware modules are used, these GPIOs may also be occupied, see \ref esp32_olimex-esp32-evb_table_board_configuration "optional functions" in table board configuration.

The corresponding board schematics can be found on GitHub for [Olimex ESP32-EVB board](https://github.com/OLIMEX/ESP32-EVB/raw/master/HARDWARE/REV-D/ESP32-EVB_Rev_D.pdf) and for [Olimex ESP32-GATEWAY](https://github.com/OLIMEX/ESP32-GATEWAY/raw/master/HARDWARE/Hardware%20revision%20C/ESP32-GATEWAY_Rev_C.pdf).

\anchor esp32_olimex-esp32-evb_pinout
@image html "https://gitlab.com/gschorcht/RIOT.wiki-Images/raw/master/esp32/Olimex_ESP32-EVB_pinout.png?inline=false" "Olimex ESP32-EVB pinout"
@image html "https://gitlab.com/gschorcht/RIOT.wiki-Images/raw/master/esp32/Olimex_ESP32-GATEWAY_pinout.png?inline=false" "Olimex ESP32-GATEWAY pinout"

## <a name="flashing"> Flashing the Device </a> &nbsp;&nbsp; [[TOC](#toc)]

Flashing RIOT is quite easy. The board has a Micro-USB connector with reset/boot/flash logic. Just connect the board to your host computer and type using the programming port:
```
make flash BOARD=esp32-olimex-evb ...
```
For detailed information about ESP32 as well as configuring and compiling RIOT for ESP32 boards, see \ref esp32_riot.
 */
