zephyr: add sample project

This adds Zephyr's project which can be build and flashed
using west tool.

Signed-off-by: Sylvio Alves <sylvio.alves@espressif.com>

examples/zephyr_example/CMakeLists.txt

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(zephyr_flasher)
+
+zephyr_compile_definitions_ifdef(CONFIG_SERIAL_FLASHER_MD5_ENABLED MD5_ENABLED)
+
+zephyr_library_sources(
+  ../common/example_common.c
+  )
+
+zephyr_library_include_directories(
+  ../common
+  ../binaries
+  )
+
+# Embed binaries into the app.
+include(${CMAKE_CURRENT_LIST_DIR}/../common/bin2array.cmake)
+create_resources(${CMAKE_CURRENT_LIST_DIR}/../binaries/Hello-world ${CMAKE_BINARY_DIR}/binaries.c)
+set_property(SOURCE ${CMAKE_BINARY_DIR}/binaries.c PROPERTY GENERATED 1)
+
+target_sources(app PRIVATE src/main.c  ${CMAKE_BINARY_DIR}/binaries.c)

examples/zephyr_example/README.md

@@ -0,0 +1,84 @@
+# ESP32 Zephyr example
+
+## Overview
+
+This sample code demonstrates how to flash ESP32/ESP32-S2/ESP8266 from another (host) MCU using
+esp_serial_flash component API. In this case, ESP32 is also used as host MCU.
+Binaries to be flashed from host MCU to another Espressif SoC can be found in `binaries` folder
+and are converted into C-array during build process.
+
+Following steps are performed in order to re-program target's memory:
+
+1. Peripherals are initialized (GPIO for BOOT and EN pins and UART).
+2. UART1 (can be changed) through which new binary will be transfered is initialized.
+3. Host puts slave device into boot mode tries to connect by calling `esp_loader_connect()`.
+4. Binary file is opened and its size is acquired, as it has to be known before flashing.
+5. Then `esp_loader_flash_start()` is called to enter flashing mode and erase amount of memory to be flashed.
+6. `esp_loader_flash_write()` function is called repeatedly until the whole binary image is transfered.
+
+Note: In addition, to steps mentioned above, `esp_loader_change_baudrate`  is called after connection
+is established in order to increase flashing speed. This does not apply for ESP8266, as its bootloader
+does not support this command. However, ESP8266 is capable of detecting baud rate during connection
+phase, and can be changed before calling `esp_loader_connect`, if necessary.
+
+## Hardware Required
+
+* Two development boards with ESP32 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.).
+* One or two USB cables for power supply and programming.
+
+## Hardware connection
+
+Table below shows connection between two ESP32 devices.
+
+| ESP32 (host) | ESP32 (slave) |
+|:------------:|:-------------:|
+|    IO4       |      IO0      |
+|    IO2       |     RESET     |
+|    IO9       |      TX0      |
+|    IO10      |      RX0      |
+
+Note: interconnection is the same for all three targets (slaves).
+
+## Build and flash
+
+To run the example, type the following command:
+
+```c
+west build -p -b esp32
+west flash
+west espressif monitor
+```
+
+(To exit the serial monitor, type ``ctrl-c``.)
+
+For more information, check [Zephyr's Getting Started](https://docs.zephyrproject.org/latest/develop/getting_started/index.html)
+
+## Configuration
+
+For details about available configuration option, please refer to top level [README.md](../../README.md).
+Compile definitions can be specified in `prj.conf` file.
+
+Binaries to be flashed are placed in separate folder (binaries.c) for each possible target and converted to C-array. Without explicitly enabling MD5 check, flash integrity verification is disabled by default.
+
+## Example output
+
+Here is the example's console output:
+
+```
+*** Booting Zephyr OS build zephyr-v3.2.0-3548-ga1bb9c9d1736 ***
+Running ESP Flasher from Zephyr
+Connected to target
+Baudrate changed
+Erasing flash (this may take a while)...
+Start programming
+Progress: 100 %
+Finished programming
+Erasing flash (this may take a while)...
+Start programming
+Progress: 100 %
+Finished programming
+Erasing flash (this may take a while)...
+Start programming
+Progress: 100 %
+Finished programming
+```

examples/zephyr_example/boards/esp32.overlay

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2022 Espressif Systems (Shanghai) Co., Ltd.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/dt-bindings/pinctrl/esp-pinctrl-common.h>
+#include <dt-bindings/pinctrl/esp32-pinctrl.h>
+#include <zephyr/dt-bindings/pinctrl/esp32-gpio-sigmap.h>
+
+/ {
+	aliases {
+		en = &en_button;
+		boot = &boot_button;
+		uart1 = &uart1;
+	};
+
+	gpio_keys {
+		compatible = "gpio-keys";
+		en_button: en_button {
+			gpios = <&gpio0 2 (GPIO_PULL_UP | GPIO_ACTIVE_HIGH)>;
+		};
+		boot_button: boot_button {
+			gpios = <&gpio0 4 (GPIO_PULL_UP | GPIO_ACTIVE_HIGH)>;
+		};
+	};
+};
+
+&uart1 {
+	status = "okay";
+	current-speed = <115200>;
+	pinctrl-0 = <&uart1_default>;
+	pinctrl-names = "default";
+};

examples/zephyr_example/prj.conf

@@ -0,0 +1,4 @@
+# nothing here
+CONFIG_CONSOLE=y
+CONFIG_CONSOLE_GETCHAR=y
+CONFIG_NEWLIB_LIBC=y

examples/zephyr_example/sample.yaml

@@ -0,0 +1,7 @@
+sample:
+  description: ESP Serial Flasher sample code
+  name: zephyr_flasher
+tests:
+  sample.esp_flasher.zephyr_example:
+    platform_allow: esp32
+    tags: esp32

examples/zephyr_example/src/main.c

@@ -0,0 +1,81 @@
+/*
+ * ESP Flasher Library Example for Zephyr
+ * Written in 2022 by KT-Elektronik, Klaucke und Partner GmbH
+ * This example code is in the Public Domain (or CC0 licensed, at your option.)
+ * Unless required by applicable law or agreed to in writing, this
+ * software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * Copyright (c) 2023 Espressif Systems (Shanghai) Co., Ltd.
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/devicetree.h>
+#include <zephyr/drivers/gpio.h>
+#include <zephyr/sys/util.h>
+
+#include <stdio.h>
+#include <string.h>
+#include <zephyr_port.h>
+#include <esp_loader.h>
+#include "example_common.h"
+
+#define HIGHER_BAUDRATE 230400
+#define DEFAULT_BAUDRATE 115200
+
+/* Get UART DTS entry used as flash interface */
+static const struct device *esp_uart_dev = DEVICE_DT_GET(DT_ALIAS(uart1));
+/* Get GPIO pin connected to the ESP's enable pin. */
+static const struct gpio_dt_spec esp_enable_spec = GPIO_DT_SPEC_GET(DT_ALIAS(en), gpios);
+/* Get GPIO pin  connected to the ESP's boot pin. */
+static const struct gpio_dt_spec esp_boot_spec = GPIO_DT_SPEC_GET(DT_ALIAS(boot), gpios);
+
+void main(void)
+{
+	example_binaries_t bin;
+
+	const loader_zephyr_config_t config = {
+		.uart_dev = esp_uart_dev,
+		.enable_spec = esp_enable_spec,
+		.boot_spec = esp_boot_spec
+	};
+
+	printk("Running ESP Flasher from Zephyr\r\n");
+
+	if (!device_is_ready(esp_uart_dev)) {
+		printk("ESP UART not ready");
+		return;
+	}
+
+	if (!device_is_ready(esp_boot_spec.port)) {
+		printk("ESP boot GPIO not ready");
+		return;
+	}
+
+	if (!device_is_ready(esp_enable_spec.port)) {
+		printk("Bluetooth Enable GPIO not ready");
+		return;
+	}
+
+	gpio_pin_configure_dt(&esp_boot_spec, GPIO_OUTPUT_ACTIVE);
+	gpio_pin_configure_dt(&esp_enable_spec, GPIO_OUTPUT_INACTIVE);
+
+	if (loader_port_zephyr_init(&config) != ESP_LOADER_SUCCESS) {
+		printk("ESP loader init failed");
+		return;
+	}
+
+	if (connect_to_target(HIGHER_BAUDRATE) == ESP_LOADER_SUCCESS) {
+
+		get_example_binaries(esp_loader_get_target(), &bin);
+
+		flash_binary(bin.boot.data, bin.boot.size, bin.boot.addr);
+		flash_binary(bin.part.data, bin.part.size, bin.part.addr);
+		flash_binary(bin.app.data,  bin.app.size,  bin.app.addr);
+	}
+
+	loader_port_change_baudrate(DEFAULT_BAUDRATE);
+
+	loader_port_reset_target();
+}