boards/esp32: Heltec WiFi LoRa 32 V2 board added

fixup! boards/esp32: Heltec WiFi LoRa 32 V2 board added

boards/esp32-heltec-lora32-v2/Makefile

@@ -0,0 +1,5 @@
+MODULE = board
+
+DIRS = $(RIOTBOARD)/common/esp32
+
+include $(RIOTBASE)/Makefile.base

boards/esp32-heltec-lora32-v2/Makefile.dep

@@ -0,0 +1 @@
+include $(RIOTBOARD)/common/esp32/Makefile.dep

boards/esp32-heltec-lora32-v2/Makefile.features

@@ -0,0 +1,11 @@
+# common board and CPU features
+include $(RIOTBOARD)/common/esp32/Makefile.features
+
+# additional features provided by the board
+FEATURES_PROVIDED += periph_adc
+FEATURES_PROVIDED += periph_i2c
+FEATURES_PROVIDED += periph_pwm
+FEATURES_PROVIDED += periph_spi
+FEATURES_PROVIDED += esp_rtc_timer_32k
+
+FEATURES_PROVIDED += arduino

boards/esp32-heltec-lora32-v2/Makefile.include

@@ -0,0 +1 @@
+include $(RIOTBOARD)/common/esp32/Makefile.include

boards/esp32-heltec-lora32-v2/doc.txt

@@ -0,0 +1,221 @@
+/*
+ * 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_heltec-lora32-v2 Heltec WiFi LoRa 32 V2 boards
+ * @ingroup     boards_esp32
+ * @brief       Support for Heltec WiFi LoRa 32 V2 boards
+ * @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. [Using the OLED Display](#oled_display)
+    5. [Optional Hardware Configurations](#optional_hardware)
+3. [Flashing the Device](#flashing)
+
+## <a name="overview"> Overview </a> &nbsp;&nbsp; [[TOC](#toc)]
+
+Heltec WiFi LoRa 32 V2 is an ESP32 development board with 8 MB Flash that uses
+the EPS32 chip directly. It integrates
+
+- a SemTech SX1276 or SX1278 for LoRaWAN communication and
+- a SSD1306 0.96-inch 128x64 OLED display connected via I2C.
+
+Since the board is
+[open source hardware](https://github.com/Heltec-Aaron-Lee/WiFi_Kit_series),
+a number of clones are available.
+
+\htmlonly<style>div.image img[src="https://heltec.org/wp-content/uploads/2019/07/SAM_0748_800X800.png"]{width:400px;}</style>\endhtmlonly
+\image html "https://heltec.org/wp-content/uploads/2019/07/SAM_0748_800X800.png" "Heltec WiFi Lora 32 V2"
+
+## <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)]
+
+Heltec WiFi LoRa 32 V2 has the following on-board components:
+
+- SemTech SX1278 or SX1276 for LoRaWAN communication
+- SSD1306 0.96-inch 128x64 OLED display connected via I2C
+- external 32.768 kHz crystal for RTC
+
+There are two hardware versions of the board:
+
+- SemTech SX1278 for LoRaWAN communication in the 433 MHz band
+- SemTech SX1276 for LoRaWAN communication in the 868/915 MHz band
+
+Since many GPIOs are broken out, they can be used for different purposes
+in different applications. For flexibility, some GPIOs might be listed in
+various peripheral configurations. For example, GPIO0 is used in the ADC
+channel definition \ref ADC_GPIOS and the PWM channel definition \ref PWM0_GPIOS.
+
+This is possible because GPIOs are only used for a specific peripheral
+interface when
+
+- the corresponding peripheral module is used, e.g., module `periph_i2c`, or
+- a corresponding init function is called e.g., \ref adc_init, \ref dac_init
+  and \ref pwm_init, or
+- the corresponding peripheral interface is used for the first time, e.g.,
+  \ref spi_acquire.
+
+That is, the purpose for which a GPIO is actually used depends on which module
+or function is used first.
+
+@note GPIOs 19, 4, 5, 14, 15, 16, 18, 32, 33, 34, 35, 21, 26, and 27 are
+used for board control functions and should not be used for other purposes
+unless you exactly know what you are doing.
+
+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_heltec_lora_32_v2_table_board_configuration
+Function        | GPIOs  | Remarks |Configuration
+:---------------|:-------|:--------|:----------------------------------
+BTN0            | GPIO0  | low active  | |
+LED0            | GPIO25 | high active | |
+ADC             | GPIO36, GPIO39, GPIO37, GPIO38, <br>GPIO0, GPIO2, GPIO12, GPIO13, <br>GPIO4, GPIO15 | | \ref esp32_adc_channels "ADC Channels"
+DAC             | | | \ref esp32_dac_channels "DAC Channels"
+PWM_DEV(0)      | GPIO25, GPIO0, GPIO2, GPIO17 | | \ref esp32_pwm_channels "PWM Channels"
+PWM_DEV(1)      | GPIO22, GPIO23 | | \ref esp32_pwm_channels "PWM Channels"
+I2C_DEV(0):SDA  | GPIO4 | | \ref esp32_i2c_interfaces "I2C Interfaces"
+I2C_DEV(0):SCL  | GPIO15 | I2C_SPEED_FAST is used | \ref esp32_i2c_interfaces "I2C Interfaces"
+SPI_DEV(0):CLK  | GPIO5 | VSPI is used | \ref esp32_spi_interfaces "SPI Interfaces"
+SPI_DEV(0):MISO | GPIO19 | VSPI is used | \ref esp32_spi_interfaces "SPI Interfaces"
+SPI_DEV(0):MOSI | GPIO27 | VSPI is used | \ref esp32_spi_interfaces "SPI Interfaces"
+SPI_DEV(0):CS0  | GPIO18 | VSPI is used | \ref esp32_spi_interfaces "SPI Interfaces"
+UART_DEV(0):TxD | GPIO1  | Console (configuration is fixed) | \ref esp32_uart_interfaces "UART interfaces"
+UART_DEV(0):RxD | GPIO3  | Console (configuration is fixed) | \ref esp32_uart_interfaces "UART interfaces"
+UART_DEV(1):TxD | GPIO10 | not available in **qout** and **qio** flash mode | \ref esp32_uart_interfaces "UART interfaces"
+UART_DEV(1):RxD | GPIO9  | not available in **qout** and **qio** flash mode | \ref esp32_uart_interfaces "UART interfaces"
+OLED RESET      | GPIO16 | | |
+</center>
+<br>
+@note
+- The configuration of ADC channels contains all ESP32 GPIOs that can be used
+  as ADC channels.
+- GPIO9 and GPIO10 can only be used in **dout** and **dio**
+  \ref esp32_flash_modes "flash modes".
+
+For detailed information about the configuration of ESP32 boards, see
+section \ref esp32_comm_periph "Common Peripherals".
+
+### <a name="oled_display"> Using the OLED Display </a> &nbsp;&nbsp; [[TOC](#toc)]
+
+The 0.96-inch OLED display with 128x64 pixels uses the widely used SSD1306
+controller. It is connected via `I2C_DEV(0)`. It can be used with the `pkg/u8g2`
+package. For this purpose, the `pkg/u8g2` package has to be used in the
+application Makefile
+```
+USEPKG += u8g2
+```
+and function `u8g2_Setup_ssd1306_i2c_128x64_noname_f` has to be called to
+setup the right driver, for example:
+```
+#include "u8g2.h"
+#include "u8x8_riotos.h"
+
+#define SSD1306_I2C_ADDR    (0x3c)
+
+u8x8_riotos_t user_data = {
+    .device_index = I2C_DEV(0),
+    .pin_cs = GPIO_UNDEF,
+    .pin_dc = GPIO_UNDEF,
+    .pin_reset = GPIO16,
+};
+
+u8g2_Setup_ssd1306_i2c_128x64_noname_f(&u8g2, U8G2_R0,
+                                       u8x8_byte_hw_i2c_riotos,
+                                       u8x8_gpio_and_delay_riotos);
+u8g2_SetUserPtr(&u8g2, &user_data);
+u8g2_SetI2CAddress(&u8g2, SSD1306_I2C_ADDR);
+u8g2_InitDisplay(&u8g2);
+u8g2_SetPowerSave(&u8g2, 0);
+```
+The `tests/pkg_u8g2` test application is a good example of how to use the
+`pkg/u8g2` package. It can be compiled for the board with the following command:
+```
+TEST_OUTPUT=4 TEST_I2C=0 TEST_ADDR=0x3c TEST_PIN_RESET=GPIO16 \
+TEST_DISPLAY=u8g2_Setup_ssd1306_i2c_128x64_noname_f \
+BOARD=esp32-heltec-lora32-v2 make -C tests/pkg_u8g2/ flash
+```
+
+### <a name="optional_hardware"> Optional Hardware Configurations </a> &nbsp;&nbsp; [[TOC](#toc)]
+
+MRF24J40-based IEEE 802.15.4 radio modules and ENC28J60-based Ethernet
+network interface 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_HELTEC_LORA32_V2
+
+#if MODULE_MRF24J40
+#define MRF24J40_PARAM_CS       GPIO12      /* MRF24J40 CS signal    */
+#define MRF24J40_PARAM_RESET    GPIO22      /* MRF24J40 RESET signal */
+#define MRF24J40_PARAM_INT      GPIO23      /* MRF24J40 INT signal   */
+#endif
+
+#if MODULE_ENC28J80
+#define ENC28J80_PARAM_CS       GPIO12      /* ENC28J80 CS signal    */
+#define ENC28J80_PARAM_RESET    GPIO22      /* ENC28J80 RESET signal */
+#define ENC28J80_PARAM_INT      GPIO23      /* ENC28J80 INT signal   */
+#endif
+
+#endif
+```
+For other parameters, the default values defined by the drivers can be used.
+
+@note The **RESET** signal of MRF24J40 and ENC28J60 based modules can also
+be connected to the **RST** pin of the board
+(see \ref esp32_heltec_lora_32_v2_pinout "pinout") to keep the configured
+GPIO free for other purposes.
+
+### <a name="pinout"> Board Pinout </a> &nbsp;&nbsp; [[TOC](#toc)]
+
+The following figure shows the pinout of the defined default configuration
+for Heltec WiFi LoRa 32 V2 boards. 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_heltec_lora_32_v2_table_board_configuration "optional functions"
+in table board configuration.
+
+The corresponding board schematics can be found
+[here for SX1276 version](https://github.com/Heltec-Aaron-Lee/WiFi_Kit_series/blob/master/SchematicDiagram/WiFi_LoRa_32(V2)/WIFI_LoRa_32_V2(868-915).PDF) and
+[here for SX1278 version](https://github.com/Heltec-Aaron-Lee/WiFi_Kit_series/blob/master/SchematicDiagram/WiFi_LoRa_32(V2)/WiFi_LoRa_32_V2(433%2C470-510).PDF).
+
+\anchor esp32_heltec_lora_32_v2_pinout
+@image html "https://gitlab.com/gschorcht/RIOT.wiki-Images/raw/master/esp32/Heltec_WiFi_LoRa_32_V2_pinout.png?inline=false" "WiFi LoRa 32 V2 Pintout Diagram"
+
+## <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-heltec-lora32-v2 ...
+```
+For detailed information about ESP32 as well as configuring and compiling RIOT for ESP32 boards, see \ref esp32_riot.
+ */

boards/esp32-heltec-lora32-v2/include/arduino_board.h

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C)  2019 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.
+ */
+
+/**
+ * @ingroup     boards_esp32_heltec-lora32-v2
+ * @{
+ *
+ * @file
+ * @brief       Board specific configuration for the Arduino API
+ *
+ * @author      Gunar Schorcht <gunar@schorcht.net>
+ */
+
+#ifndef ARDUINO_BOARD_H
+#define ARDUINO_BOARD_H
+
+#include "arduino_board_common.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   The on-board LED is connected to Arduino pin 3 on this board
+ */
+#define ARDUINO_LED         (3)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ARDUINO_BOARD_H */
+/** @} */

boards/esp32-heltec-lora32-v2/include/arduino_pinmap.h

@@ -0,0 +1,64 @@
+/*
+ * Copyright (C)  2019 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.
+ */
+
+/**
+ * @ingroup     boards_esp32_heltec-lora32-v2
+ * @{
+ *
+ * @file
+ * @brief       Mapping from MCU pins to Arduino pins
+ *
+ * @author      Gunar Schorcht <gunar@schorcht.net>
+ */
+
+#ifndef ARDUINO_PINMAP_H
+#define ARDUINO_PINMAP_H
+
+#include "periph/gpio.h"
+#include "periph/adc.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @name   Mapping of MCU pins to Arduino pins
+ * @{
+ */
+#define ARDUINO_PIN_0   GPIO3       /**< Arduino Uno pin 0 (RxD) */
+#define ARDUINO_PIN_1   GPIO1       /**< Arduino Uno pin 1 (TxD) */
+
+#define ARDUINO_PIN_2   GPIO12      /**< Arduino Uno pin 2 */
+#define ARDUINO_PIN_3   GPIO25      /**< Arduino Uno pin 3 (PWM) */
+#define ARDUINO_PIN_4   GPIO13      /**< Arduino Uno pin 4 */
+#define ARDUINO_PIN_5   GPIO0       /**< Arduino Uno pin 5 (PWM) */
+#define ARDUINO_PIN_6   GPIO2       /**< Arduino Uno pin 6 (PWM) */
+#define ARDUINO_PIN_7   GPIO22      /**< Arduino Uno pin 7 */
+#define ARDUINO_PIN_8   GPIO23      /**< Arduino Uno pin 8 */
+#define ARDUINO_PIN_9   GPIO17      /**< Arduino Uno pin 9 (PWM) */
+
+#define ARDUINO_PIN_10  GPIO18      /**< Arduino Uno pin 10 (CS0 / PWM)  */
+#define ARDUINO_PIN_11  GPIO27      /**< Arduino Uno pin 11 (MOSI / PWM) */
+#define ARDUINO_PIN_12  GPIO19      /**< Arduino Uno pin 12 (MISO) */
+#define ARDUINO_PIN_13  GPIO5       /**< Arduino Uno pin 13 (SCK)  */
+
+#define ARDUINO_PIN_A0  GPIO36      /**< Arduino Uno pin A0 */
+#define ARDUINO_PIN_A1  GPIO39      /**< Arduino Uno pin A1 */
+#define ARDUINO_PIN_A2  GPIO37      /**< Arduino Uno pin A2 */
+#define ARDUINO_PIN_A3  GPIO38      /**< Arduino Uno pin A3 */
+
+#define ARDUINO_PIN_A4  GPIO4       /**< Arduino Uno pin A4 (SDA) */
+#define ARDUINO_PIN_A5  GPIO15      /**< Arduino Uno pin A5 (SCL) */
+/** @ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ARDUINO_PINMAP_H */
+/** @} */