| <!-- |
| Documentation/_templates/layout.html |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. The |
| ASF licenses this file to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance with the |
| License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| License for the specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <!DOCTYPE html> |
| <html class="writer-html5" lang="en" > |
| <head> |
| <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>Espressif ESP32 — NuttX latest documentation</title> |
| <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" /> |
| <link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" /> |
| <link rel="stylesheet" href="../../../_static/tabs.css" type="text/css" /> |
| <link rel="stylesheet" href="../../../_static/custom.css" type="text/css" /> |
| <link rel="shortcut icon" href="../../../_static/favicon.ico"/> |
| <!--[if lt IE 9]> |
| <script src="../../../_static/js/html5shiv.min.js"></script> |
| <![endif]--> |
| |
| <script src="../../../_static/jquery.js"></script> |
| <script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script> |
| <script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script> |
| <script src="../../../_static/doctools.js"></script> |
| <script src="../../../_static/sphinx_highlight.js"></script> |
| <script src="../../../_static/js/theme.js"></script> |
| <link rel="index" title="Index" href="../../../genindex.html" /> |
| <link rel="search" title="Search" href="../../../search.html" /> |
| <link rel="next" title="ESP32 DevKitC" href="boards/esp32-devkitc/index.html" /> |
| <link rel="prev" title="Xtensa" href="../index.html" /> |
| </head> |
| |
| <body class="wy-body-for-nav"> |
| <div class="wy-grid-for-nav"> |
| <nav data-toggle="wy-nav-shift" class="wy-nav-side"> |
| <div class="wy-side-scroll"> |
| <div class="wy-side-nav-search" > |
| |
| <a href="../../../index.html" class="icon icon-home"> NuttX |
| |
| |
| |
| </a> |
| |
| <!-- this version selector is quite ugly, should be probably replaced by something |
| more modern --> |
| |
| <div class="version-selector"> |
| <select onchange="javascript:location.href = this.value;"> |
| |
| <option value="../../../../latest" selected="selected">latest</option> |
| |
| <option value="../../../../10.0.0" >10.0.0</option> |
| |
| <option value="../../../../10.0.1" >10.0.1</option> |
| |
| <option value="../../../../10.1.0" >10.1.0</option> |
| |
| <option value="../../../../10.2.0" >10.2.0</option> |
| |
| <option value="../../../../10.3.0" >10.3.0</option> |
| |
| <option value="../../../../11.0.0" >11.0.0</option> |
| |
| <option value="../../../../12.0.0" >12.0.0</option> |
| |
| <option value="../../../../12.1.0" >12.1.0</option> |
| |
| <option value="../../../../12.2.0" >12.2.0</option> |
| |
| <option value="../../../../12.2.1" >12.2.1</option> |
| |
| <option value="../../../../12.3.0" >12.3.0</option> |
| |
| <option value="../../../../12.4.0" >12.4.0</option> |
| |
| <option value="../../../../12.5.0" >12.5.0</option> |
| |
| <option value="../../../../12.5.1" >12.5.1</option> |
| |
| </select> |
| </div> |
| |
| |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> |
| <p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../../../index.html">Home</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../introduction/index.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../quickstart/index.html">Getting Started</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../contributing/index.html">Contributing</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Supported Platforms</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="../../arm/index.html">ARM</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../risc-v/index.html">RISC-V</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../sim/index.html">Simulators</a></li> |
| <li class="toctree-l2 current"><a class="reference internal" href="../index.html">Xtensa</a><ul class="current"> |
| <li class="toctree-l3 current"><a class="current reference internal" href="#">Espressif ESP32</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#toolchain">Toolchain</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#building-from-source">Building from source</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#flashing">Flashing</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#bootloader-and-partitions">Bootloader and partitions</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#peripheral-support">Peripheral Support</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#memory-map">Memory Map</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#address-mapping">Address Mapping</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#embedded-memory">Embedded Memory</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#boundary-address-embedded">Boundary Address (Embedded)</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#external-memory">External Memory</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#boundary-address-external">Boundary Address (External)</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#linker-segments">Linker Segments</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#bit-timers">64-bit Timers</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#watchdog-timers">Watchdog Timers</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#smp">SMP</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#wi-fi">Wi-Fi</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#wi-fi-softap">Wi-Fi SoftAP</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#bluetooth">Bluetooth</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#i2s">I2S</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#using-qemu">Using QEMU</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#secure-boot-and-flash-encryption">Secure Boot and Flash Encryption</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#secure-boot">Secure Boot</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#flash-encryption">Flash Encryption</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#prerequisites">Prerequisites</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#enabling-secure-boot-and-flash-encryption">Enabling Secure Boot and Flash Encryption</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#things-to-do">Things to Do</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#supported-boards">Supported Boards</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="boards/esp32-devkitc/index.html">ESP32 DevKitC</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="boards/esp32-lyrat/index.html">ESP32-LyraT V4.3</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="boards/esp32-wrover-kit/index.html">ESP-WROVER-KIT</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="../esp32s2/index.html">Espressif ESP32-S2</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../esp32s3/index.html">Espressif ESP32-S3</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../components/index.html">OS Components</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../applications/index.html">Applications</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../reference/index.html">API Reference</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../faq/index.html">FAQ</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../guides/index.html">Guides</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../glossary.html">Glossary</a></li> |
| </ul> |
| |
| </div> |
| </div> |
| </nav> |
| |
| <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > |
| <i data-toggle="wy-nav-top" class="fa fa-bars"></i> |
| <a href="../../../index.html">NuttX</a> |
| </nav> |
| |
| <div class="wy-nav-content"> |
| <div class="rst-content"> |
| <div role="navigation" aria-label="Page navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li> |
| <li class="breadcrumb-item"><a href="../../index.html">Supported Platforms</a></li> |
| <li class="breadcrumb-item"><a href="../index.html">Xtensa</a></li> |
| <li class="breadcrumb-item active">Espressif ESP32</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="../../../_sources/platforms/xtensa/esp32/index.rst.txt" rel="nofollow"> View page source</a> |
| </li> |
| </ul> |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <section id="espressif-esp32"> |
| <h1>Espressif ESP32<a class="headerlink" href="#espressif-esp32" title="Permalink to this heading"></a></h1> |
| <p>The ESP32 is a series of single and dual-core SoCs from Espressif |
| based on Harvard architecture Xtensa LX6 CPUs and with on-chip support |
| for Bluetooth and Wi-Fi.</p> |
| <p>All embedded memory, external memory and peripherals are located on the |
| data bus and/or the instruction bus of these CPUs. With some minor |
| exceptions, the address mapping of two CPUs is symmetric, meaning they |
| use the same addresses to access the same memory. Multiple peripherals in |
| the system can access embedded memory via DMA.</p> |
| <p>On dual-core SoCs, the two CPUs are typically named “PRO_CPU” and “APP_CPU” |
| (for “protocol” and “application”), however for most purposes the |
| two CPUs are interchangeable.</p> |
| <section id="toolchain"> |
| <h2>Toolchain<a class="headerlink" href="#toolchain" title="Permalink to this heading"></a></h2> |
| <p>You can use the prebuilt <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html#xtensa-esp32-elf">toolchain</a> |
| for Xtensa architecture and <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html#openocd-esp32">OpenOCD</a> |
| for ESP32 by Espressif.</p> |
| <p>For flashing firmware, you will need to install <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code> by running:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pip install esptool |
| </pre></div> |
| </div> |
| <section id="building-from-source"> |
| <h3>Building from source<a class="headerlink" href="#building-from-source" title="Permalink to this heading"></a></h3> |
| <p>You can also build the toolchain yourself. The steps to |
| build the toolchain with crosstool-NG on Linux are as follows</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/espressif/crosstool-NG.git |
| <span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span>crosstool-NG |
| <span class="gp">$ </span>git<span class="w"> </span>checkout<span class="w"> </span>esp-2021r1 |
| <span class="gp">$ </span>git<span class="w"> </span>submodule<span class="w"> </span>update<span class="w"> </span>--init |
| |
| <span class="gp">$ </span>./bootstrap<span class="w"> </span><span class="o">&&</span><span class="w"> </span>./configure<span class="w"> </span>--enable-local<span class="w"> </span><span class="o">&&</span><span class="w"> </span>make |
| |
| <span class="gp">$ </span>./ct-ng<span class="w"> </span>xtensa-esp32-elf |
| <span class="gp">$ </span>./ct-ng<span class="w"> </span>build |
| |
| <span class="gp">$ </span>chmod<span class="w"> </span>-R<span class="w"> </span>u+w<span class="w"> </span>builds/xtensa-esp32-elf |
| |
| <span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"crosstool-NG/builds/xtensa-esp32-elf/bin:</span><span class="nv">$PATH</span><span class="s2">"</span> |
| </pre></div> |
| </div> |
| <p>These steps are given in the setup guide in |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html">ESP-IDF documentation</a>.</p> |
| </section> |
| </section> |
| <section id="flashing"> |
| <h2>Flashing<a class="headerlink" href="#flashing" title="Permalink to this heading"></a></h2> |
| <p>Firmware for ESP32 is flashed via the USB/UART interface using the <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code> tool. |
| It’s a two step process where the first converts the ELF file into a ESP32-compatible binary |
| and the second flashes it to the board. These steps are included into the build system and you can |
| flash your NuttX firmware simply by running:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make flash ESPTOOL_PORT=<port> |
| </pre></div> |
| </div> |
| <p>where <code class="docutils literal notranslate"><span class="pre"><port></span></code> is typically <code class="docutils literal notranslate"><span class="pre">/dev/ttyUSB0</span></code> or similar. You can change the baudrate by passing <code class="docutils literal notranslate"><span class="pre">ESPTOOL_BAUD</span></code>.</p> |
| <section id="bootloader-and-partitions"> |
| <h3>Bootloader and partitions<a class="headerlink" href="#bootloader-and-partitions" title="Permalink to this heading"></a></h3> |
| <p>ESP32 requires a bootloader to be flashed as well as a set of FLASH partitions. This is only needed the first time |
| (or any time you which to modify either of these). An easy way is to use prebuilt binaries for NuttX <a class="reference external" href="https://github.com/espressif/esp-nuttx-bootloader">from here</a>. In there you will find instructions to rebuild these if necessary. |
| Once you downloaded both binaries, you can flash them by adding an <code class="docutils literal notranslate"><span class="pre">ESPTOOL_BINDIR</span></code> parameter, pointing to the directory where these binaries were downloaded:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>flash<span class="w"> </span><span class="nv">ESPTOOL_PORT</span><span class="o">=</span><port><span class="w"> </span><span class="nv">ESPTOOL_BINDIR</span><span class="o">=</span><dir> |
| </pre></div> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>It is recommended that if this is the first time you are using the board with NuttX that you perform a complete |
| SPI FLASH erase.</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>esptool.py<span class="w"> </span>erase_flash |
| </pre></div> |
| </div> |
| </div> |
| </section> |
| </section> |
| <section id="peripheral-support"> |
| <h2>Peripheral Support<a class="headerlink" href="#peripheral-support" title="Permalink to this heading"></a></h2> |
| <p>The following list indicates the state of peripherals’ support in NuttX:</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Peripheral</p></th> |
| <th class="head"><p>Support</p></th> |
| <th class="head"><p>NOTES</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>GPIO</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>UART</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>SPI</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>I2C</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>DMA</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Wifi</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Ethernet</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>SPIFLASH</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>SPIRAM</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Timers</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Watchdog</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>RTC</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>RNG</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>AES</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>eFuse</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>ADC</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Bluetooth</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>SDIO</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>SD/MMC</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>I2S</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>LED_PWM</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>RMT</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>MCPWM</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Pulse_CNT</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>SHA</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>RSA</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>CAN/TWAI</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| </section> |
| <section id="memory-map"> |
| <h2>Memory Map<a class="headerlink" href="#memory-map" title="Permalink to this heading"></a></h2> |
| <section id="address-mapping"> |
| <h3>Address Mapping<a class="headerlink" href="#address-mapping" title="Permalink to this heading"></a></h3> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>BUS TYPE</p></th> |
| <th class="head"><p>START</p></th> |
| <th class="head"><p>LAST</p></th> |
| <th class="head"><p>DESCRIPTION</p></th> |
| <th class="head"><p>NOTES</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>Data</p></td> |
| <td><p>0x3F400000</p></td> |
| <td><p>0x3F7FFFFF</p></td> |
| <td><p>External Memory</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Data</p></td> |
| <td><p>0x3F800000 |
| 0x3FC00000</p></td> |
| <td><p>0x3FBFFFFF |
| 0x3FEFFFFF</p></td> |
| <td><p>External Memory</p></td> |
| <td><p>Reserved</p></td> |
| </tr> |
| <tr class="row-even"><td><p>Data</p></td> |
| <td><p>0x3FF00000</p></td> |
| <td><p>0x3FF7FFFF</p></td> |
| <td><p>Peripheral</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Data</p></td> |
| <td><p>0x3FF80000</p></td> |
| <td><p>0x3FFFFFFF</p></td> |
| <td><p>Embedded Memory</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Instruction</p></td> |
| <td><p>0x40000000</p></td> |
| <td><p>0x400C1FFF</p></td> |
| <td><p>Embedded Memory</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Instruction</p></td> |
| <td><p>0x400C2000</p></td> |
| <td><p>0x40BFFFFF</p></td> |
| <td><p>External Memory</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>.</p></td> |
| <td><p>0x40C00000</p></td> |
| <td><p>0x4FFFFFFF</p></td> |
| <td></td> |
| <td><p>Reserved</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Data / Instruction</p></td> |
| <td><p>0x50000000</p></td> |
| <td><p>0x50001FFF</p></td> |
| <td><p>Embedded Memory</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>.</p></td> |
| <td><p>0x50002000</p></td> |
| <td><p>0xFFFFFFFF</p></td> |
| <td></td> |
| <td><p>Reserved</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </section> |
| <section id="embedded-memory"> |
| <h3>Embedded Memory<a class="headerlink" href="#embedded-memory" title="Permalink to this heading"></a></h3> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>BUS TYPE</p></th> |
| <th class="head"><p>START</p></th> |
| <th class="head"><p>LAST</p></th> |
| <th class="head"><p>DESCRIPTION</p></th> |
| <th class="head"><p>NOTES</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>Data</p></td> |
| <td><p>0x3ff80000</p></td> |
| <td><p>0x3ff81fff</p></td> |
| <td><p>RTC FAST Memory</p></td> |
| <td><p>PRO_CPU Only</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>.</p></td> |
| <td><p>0x3ff82000</p></td> |
| <td><p>0x3ff8ffff</p></td> |
| <td></td> |
| <td><p>Reserved</p></td> |
| </tr> |
| <tr class="row-even"><td><p>Data</p></td> |
| <td><p>0x3ff90000</p></td> |
| <td><p>0x3ff9ffff</p></td> |
| <td><p>Internal ROM 1</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>.</p></td> |
| <td><p>0x3ffa0000</p></td> |
| <td><p>0x3ffadfff</p></td> |
| <td></td> |
| <td><p>Reserved</p></td> |
| </tr> |
| <tr class="row-even"><td><p>Data</p></td> |
| <td><p>0x3ffae000</p></td> |
| <td><p>0x3ffdffff</p></td> |
| <td><p>Internal SRAM 2</p></td> |
| <td><p>DMA</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Data</p></td> |
| <td><p>0x3ffe0000</p></td> |
| <td><p>0x3fffffff</p></td> |
| <td><p>Internal SRAM 1</p></td> |
| <td><p>DMA</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </section> |
| <section id="boundary-address-embedded"> |
| <h3>Boundary Address (Embedded)<a class="headerlink" href="#boundary-address-embedded" title="Permalink to this heading"></a></h3> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>BUS TYPE</p></th> |
| <th class="head"><p>START</p></th> |
| <th class="head"><p>LAST</p></th> |
| <th class="head"><p>DESCRIPTION</p></th> |
| <th class="head"><p>NOTES</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>Instruction</p></td> |
| <td><p>0x40000000</p></td> |
| <td><p>0x40007fff</p></td> |
| <td><p>Internal ROM 0</p></td> |
| <td><p>Remap</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Instruction</p></td> |
| <td><p>0x40008000</p></td> |
| <td><p>0x4005ffff</p></td> |
| <td><p>Internal ROM 0</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>.</p></td> |
| <td><p>0x40060000</p></td> |
| <td><p>0x4006ffff</p></td> |
| <td></td> |
| <td><p>Reserved</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Instruction</p></td> |
| <td><p>0x40070000</p></td> |
| <td><p>0x4007ffff</p></td> |
| <td><p>Internal SRAM 0</p></td> |
| <td><p>Cache</p></td> |
| </tr> |
| <tr class="row-even"><td><p>Instruction</p></td> |
| <td><p>0x40080000</p></td> |
| <td><p>0x4009ffff</p></td> |
| <td><p>Internal SRAM 0</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Instruction</p></td> |
| <td><p>0x400a0000</p></td> |
| <td><p>0x400affff</p></td> |
| <td><p>Internal SRAM 1</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Instruction</p></td> |
| <td><p>0x400b0000</p></td> |
| <td><p>0x400b7FFF</p></td> |
| <td><p>Internal SRAM 1</p></td> |
| <td><p>Remap</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Instruction</p></td> |
| <td><p>0x400b8000</p></td> |
| <td><p>0x400bffff</p></td> |
| <td><p>Internal SRAM 1</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Instruction</p></td> |
| <td><p>0x400c0000</p></td> |
| <td><p>0x400c1FFF</p></td> |
| <td><p>RTC FAST Memory</p></td> |
| <td><p>PRO_CPU Only</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Data / Instruction</p></td> |
| <td><p>0x50000000</p></td> |
| <td><p>0x50001fff</p></td> |
| <td><p>RTC SLOW Memory</p></td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table> |
| </section> |
| <section id="external-memory"> |
| <h3>External Memory<a class="headerlink" href="#external-memory" title="Permalink to this heading"></a></h3> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>BUS TYPE</p></th> |
| <th class="head"><p>START</p></th> |
| <th class="head"><p>LAST</p></th> |
| <th class="head"><p>DESCRIPTION</p></th> |
| <th class="head"><p>NOTES</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>Data</p></td> |
| <td><p>0x3f400000</p></td> |
| <td><p>0x3f7fffff</p></td> |
| <td><p>External Flash</p></td> |
| <td><p>Read</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>Data</p></td> |
| <td><p>0x3f800000</p></td> |
| <td><p>0x3fbfffff</p></td> |
| <td><p>External SRAM</p></td> |
| <td><p>Read and Write</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </section> |
| <section id="boundary-address-external"> |
| <h3>Boundary Address (External)<a class="headerlink" href="#boundary-address-external" title="Permalink to this heading"></a></h3> |
| <p>Instruction 0x400c2000 0x40bfffff 11512 KB External Flash Read</p> |
| </section> |
| <section id="linker-segments"> |
| <h3>Linker Segments<a class="headerlink" href="#linker-segments" title="Permalink to this heading"></a></h3> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>DESCRIPTION</p></th> |
| <th class="head"><p>START</p></th> |
| <th class="head"><p>END</p></th> |
| <th class="head"><p>ATTR</p></th> |
| <th class="head"><p>LINKER SEGMENT NAME</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><dl class="simple"> |
| <dt>FLASH mapped data:</dt><dd><ul class="simple"> |
| <li><p>.rodata</p></li> |
| <li><p>Constructors |
| /destructors</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </td> |
| <td><p>0x3f400010</p></td> |
| <td><p>0x3fc00010</p></td> |
| <td><p>R</p></td> |
| <td><p>drom0_0_seg</p></td> |
| </tr> |
| <tr class="row-odd"><td><dl class="simple"> |
| <dt>COMMON data RAM:</dt><dd><ul class="simple"> |
| <li><p>.bss/.data</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </td> |
| <td><p>0x3ffb0000</p></td> |
| <td><p>0x40000000</p></td> |
| <td><p>RW</p></td> |
| <td><p>dram0_0_seg (NOTE 1,2,3)</p></td> |
| </tr> |
| <tr class="row-even"><td><dl class="simple"> |
| <dt>IRAM for PRO cpu:</dt><dd><ul class="simple"> |
| <li><p>Interrupt Vectors</p></li> |
| <li><p>Low level |
| handlers</p></li> |
| <li><p>Xtensa/Espressif |
| libraries</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </td> |
| <td><p>0x40080000</p></td> |
| <td><p>0x400a0000</p></td> |
| <td><p>RX</p></td> |
| <td><p>iram0_0_seg</p></td> |
| </tr> |
| <tr class="row-odd"><td><dl class="simple"> |
| <dt>RTC fast memory:</dt><dd><ul class="simple"> |
| <li><p>.rtc.text |
| (unused?)</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </td> |
| <td><p>0x400c0000</p></td> |
| <td><p>0x400c2000</p></td> |
| <td><p>RWX</p></td> |
| <td><p>rtc_iram_seg (PRO_CPU only)</p></td> |
| </tr> |
| <tr class="row-even"><td><dl class="simple"> |
| <dt>FLASH:</dt><dd><ul class="simple"> |
| <li><p>.text</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </td> |
| <td><p>0x400d0018</p></td> |
| <td><p>0x40400018</p></td> |
| <td><p>RX</p></td> |
| <td><p>iram0_2_seg (actually FLASH)</p></td> |
| </tr> |
| <tr class="row-odd"><td><dl class="simple"> |
| <dt>RTC slow memory:</dt><dd><ul class="simple"> |
| <li><p>.rtc.data/rodata |
| (unused?)</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </td> |
| <td><p>0x50000000</p></td> |
| <td><p>0x50001000</p></td> |
| <td><p>RW</p></td> |
| <td><p>rtc_slow_seg (NOTE 4)</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <ol class="arabic simple"> |
| <li><p>Linker script will reserve space at the beginning of the segment |
| for BT and at the end for trace memory.</p></li> |
| <li><p>Heap ends at the top of dram_0_seg.</p></li> |
| <li><p>Parts of this region is reserved for the ROM bootloader.</p></li> |
| <li><p>Linker script will reserve space at the beginning of the segment |
| for co-processor reserve memory and at the end for ULP coprocessor |
| reserve memory.</p></li> |
| </ol> |
| </div> |
| </section> |
| </section> |
| <section id="bit-timers"> |
| <h2>64-bit Timers<a class="headerlink" href="#bit-timers" title="Permalink to this heading"></a></h2> |
| <p>ESP32 has 4 generic timers of 64 bits (2 from Group 0 and 2 from Group 1). They’re |
| accessible as character drivers, the configuration along with a guidance on how |
| to run the example and the description of the application level interface |
| can be found <a class="reference internal" href="../../../components/drivers/character/timer.html"><span class="doc">here</span></a>.</p> |
| </section> |
| <section id="watchdog-timers"> |
| <h2>Watchdog Timers<a class="headerlink" href="#watchdog-timers" title="Permalink to this heading"></a></h2> |
| <p>ESP32 has 3 WDTs. 2 MWDTS from the Timers Module and 1 RWDT from the RTC Module |
| (Currently not supported yet). They’re accessible as character drivers, |
| The configuration along with a guidance on how to run the example and the description |
| of the application level interface can be found |
| <a class="reference internal" href="../../../components/drivers/character/watchdog.html"><span class="doc">here</span></a>.</p> |
| </section> |
| <section id="smp"> |
| <h2>SMP<a class="headerlink" href="#smp" title="Permalink to this heading"></a></h2> |
| <p>The ESP32 has 2 CPUs. Support is included for testing an SMP configuration. |
| That configuration is still not yet ready for usage but can be enabled with |
| the following configuration settings, |
| in <span class="menuselection">RTOS Features ‣ Tasks and Scheduling</span>, with:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CONFIG_SPINLOCK=y |
| CONFIG_SMP=y |
| CONFIG_SMP_NCPUS=2 |
| </pre></div> |
| </div> |
| <p>Debug Tip: During debug session, OpenOCD may mysteriously switch from one |
| CPU to another. This behavior can be eliminated by uncommenting one of the |
| following in <code class="docutils literal notranslate"><span class="pre">scripts/esp32.cfg</span></code>:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Only configure the PRO CPU |
| #set ESP32_ONLYCPU 1 |
| # Only configure the APP CPU |
| #set ESP32_ONLYCPU 2 |
| </pre></div> |
| </div> |
| </section> |
| <section id="wi-fi"> |
| <h2>Wi-Fi<a class="headerlink" href="#wi-fi" title="Permalink to this heading"></a></h2> |
| <p>A standard network interface will be configured and can be initialized such as:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>nsh> ifup wlan0 |
| nsh> wapi psk wlan0 mypasswd 3 |
| nsh> wapi essid wlan0 myssid 1 |
| nsh> renew wlan0 |
| </pre></div> |
| </div> |
| <p>In this case a connection to AP with SSID <code class="docutils literal notranslate"><span class="pre">myssid</span></code> is done, using <code class="docutils literal notranslate"><span class="pre">mypasswd</span></code> as |
| password. IP address is obtained via DHCP using <code class="docutils literal notranslate"><span class="pre">renew</span></code> command. You can check |
| the result by running <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> afterwards.</p> |
| <div class="admonition tip"> |
| <p class="admonition-title">Tip</p> |
| <p>Boards usually expose a <code class="docutils literal notranslate"><span class="pre">wapi</span></code> defconfig which enables Wi-Fi</p> |
| </div> |
| </section> |
| <section id="wi-fi-softap"> |
| <h2>Wi-Fi SoftAP<a class="headerlink" href="#wi-fi-softap" title="Permalink to this heading"></a></h2> |
| <p>It is possible to use ESP32 as an Access Point (SoftAP). Actually there are some |
| boards config examples called sta_softap which enables this support</p> |
| <p>If you are using this board config profile you can run these commands to be able |
| to connect your smartphone or laptop to your board:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>nsh> ifup wlan1 |
| nsh> dhcpd_start wlan1 |
| nsh> wapi psk wlan1 mypasswd 3 |
| nsh> wapi essid wlan1 nuttxap 1 |
| </pre></div> |
| </div> |
| <p>In this case, you are creating the access point <code class="docutils literal notranslate"><span class="pre">nuttxapp</span></code> in your board and to |
| connect to it on your smartphone you will be required to type the password <code class="docutils literal notranslate"><span class="pre">mypasswd</span></code> |
| using WPA2. |
| The <code class="docutils literal notranslate"><span class="pre">dhcpd_start</span></code> is necessary to let your board to associate an IP to your smartphone.</p> |
| </section> |
| <section id="bluetooth"> |
| <h2>Bluetooth<a class="headerlink" href="#bluetooth" title="Permalink to this heading"></a></h2> |
| <p>These are the steps to test Bluetooth Low Energy (BLE) scan on ESP32 (i.e. Devkit board). |
| First configure to use the BLE board profile:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make distclean |
| $ ./tools/configure.sh esp32-devkitc:ble |
| $ make flash ESPTOOL_PORT=/dev/ttyUSB0 |
| </pre></div> |
| </div> |
| <p>Enter in the NSH shell using your preferred serial console tool and run the scan command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>NuttShell (NSH) NuttX-10.2.0 |
| nsh> ifconfig |
| bnep0 Link encap:UNSPEC at DOWN |
| inet addr:0.0.0.0 DRaddr:0.0.0.0 Mask:0.0.0.0 |
| |
| wlan0 Link encap:Ethernet HWaddr ac:67:b2:53:8b:ec at UP |
| inet addr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 |
| |
| nsh> bt bnep0 scan start |
| nsh> bt bnep0 scan stop |
| nsh> bt bnep0 scan get |
| Scan result: |
| 1. addr: 63:14:2f:b9:9f:83 type: 1 |
| rssi: -90 |
| response type: 3 |
| advertiser data: 1e ff 06 00 01 09 20 02 7c 33 a3 a7 cd c9 44 5b |
| 2. addr: 52:ca:05:b5:ad:77 type: 1 |
| rssi: -82 |
| response type: 3 |
| advertiser data: 1e ff 06 00 01 09 20 02 03 d1 21 57 bf 19 b3 7a |
| 3. addr: 46:8e:b2:cd:94:27 type: 1 |
| rssi: -92 |
| response type: 2 |
| advertiser data: 02 01 1a 09 ff c4 00 10 33 14 12 16 80 02 0a d4 |
| 4. addr: 46:8e:b2:cd:94:27 type: 1 |
| rssi: -92 |
| response type: 4 |
| advertiser data: 18 09 5b 4c 47 5d 20 77 65 62 4f 53 20 54 56 20 |
| 5. addr: 63:14:2f:b9:9f:83 type: 1 |
| rssi: -80 |
| response type: 3 |
| advertiser data: 1e ff 06 00 01 09 20 02 7c 33 a3 a7 cd c9 44 5b |
| nsh> |
| </pre></div> |
| </div> |
| </section> |
| <section id="i2s"> |
| <h2>I2S<a class="headerlink" href="#i2s" title="Permalink to this heading"></a></h2> |
| <p>The I2S peripheral is accessible using either the generic I2S audio driver or a specific |
| audio codec driver. Also, it’s possible to use the I2S character driver to bypass the |
| audio subsystem and develop specific usages of the I2S peripheral.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>Note that the bit-width and sample rate can be modified “on-the-go” when using |
| audio-related drivers. That is not the case for the I2S character device driver and |
| such parameters are set on compile time through <cite>make menuconfig</cite>.</p> |
| </div> |
| <p>Please check for usage examples using the <a class="reference internal" href="boards/esp32-devkitc/index.html"><span class="doc">ESP32 DevKitC</span></a>.</p> |
| </section> |
| <section id="using-qemu"> |
| <h2>Using QEMU<a class="headerlink" href="#using-qemu" title="Permalink to this heading"></a></h2> |
| <p>First follow the instructions <a class="reference external" href="https://github.com/espressif/qemu/wiki">here</a> to build QEMU.</p> |
| <p>Enable the <code class="docutils literal notranslate"><span class="pre">ESP32_QEMU_IMAGE</span></code> config found in <span class="menuselection">Board Selection ‣ ESP32 binary image for QEMU</span>.</p> |
| <p>Download the bootloader and the partition table from <a class="reference external" href="https://github.com/espressif/esp-nuttx-bootloader/releases">https://github.com/espressif/esp-nuttx-bootloader/releases</a> |
| and place them in a directory, say <code class="docutils literal notranslate"><span class="pre">../esp-bins</span></code>.</p> |
| <p>Build and generate the QEMU image:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make ESPTOOL_BINDIR=../esp-bins |
| </pre></div> |
| </div> |
| <p>A QEMU-compatible <code class="docutils literal notranslate"><span class="pre">nuttx.merged.bin</span></code> binary image will be created. It can be run as:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ qemu-system-xtensa -nographic -machine esp32 -drive file=nuttx.merged.bin,if=mtd,format=raw |
| </pre></div> |
| </div> |
| </section> |
| <section id="secure-boot-and-flash-encryption"> |
| <h2>Secure Boot and Flash Encryption<a class="headerlink" href="#secure-boot-and-flash-encryption" title="Permalink to this heading"></a></h2> |
| <section id="secure-boot"> |
| <h3>Secure Boot<a class="headerlink" href="#secure-boot" title="Permalink to this heading"></a></h3> |
| <p>Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that |
| each piece of software that is being booted is signed. On an ESP32, these pieces of software include |
| the second stage bootloader and each application binary. Note that the first stage bootloader does not |
| require signing as it is ROM code thus cannot be changed. This is achieved using specific hardware in |
| conjunction with MCUboot (read more about MCUboot <a class="reference external" href="https://docs.mcuboot.com/">here</a>).</p> |
| <p>The Secure Boot process on the ESP32 involves the following steps performed:</p> |
| <ol class="arabic simple"> |
| <li><p>The first stage bootloader verifies the second stage bootloader’s RSA-PSS signature. If the verification is successful, |
| the first stage bootloader loads and executes the second stage bootloader.</p></li> |
| <li><p>When the second stage bootloader loads a particular application image, the application’s signature (RSA, ECDSA or ED25519) is verified |
| by MCUboot. |
| If the verification is successful, the application image is executed.</p></li> |
| </ol> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only boot an |
| application firmware image if it has a verified digital signature. There are implications for reflashing |
| updated images once Secure Boot is enabled. You can find more information about the ESP32’s Secure boot |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html">here</a>.</p> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>As the bootloader image is built on top of the Hardware Abstraction Layer component |
| of <a class="reference external" href="https://github.com/espressif/esp-idf">ESP-IDF</a>, the |
| <a class="reference external" href="https://docs.mcuboot.com/readme-espressif.html">API port by Espressif</a> will be used |
| by MCUboot rather than the original NuttX port.</p> |
| </div> |
| </section> |
| <section id="flash-encryption"> |
| <h3>Flash Encryption<a class="headerlink" href="#flash-encryption" title="Permalink to this heading"></a></h3> |
| <p>Flash encryption is intended for encrypting the contents of the ESP32’s off-chip flash memory. Once this feature is enabled, |
| firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout |
| of flash will not be sufficient to recover most flash contents.</p> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>After enabling Flash Encryption, an encryption key is generated internally by the device and |
| cannot be accessed by the user for re-encrypting data and re-flashing the system, hence it will be permanently encrypted. |
| Re-flashing an encrypted system is complicated and not always possible. You can find more information about the ESP32’s Flash Encryption |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html">here</a>.</p> |
| </div> |
| </section> |
| <section id="prerequisites"> |
| <h3>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h3> |
| <p>First of all, we need to install <code class="docutils literal notranslate"><span class="pre">imgtool</span></code> (a MCUboot utility application to manipulate binary |
| images) and <code class="docutils literal notranslate"><span class="pre">esptool</span></code> (the ESP32 toolkit):</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pip install imgtool esptool |
| </pre></div> |
| </div> |
| <p>We also need to make sure that the python modules are added to <code class="docutils literal notranslate"><span class="pre">PATH</span></code>:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc |
| </pre></div> |
| </div> |
| <p>Now, we will create a folder to store the generated keys (such as <code class="docutils literal notranslate"><span class="pre">~/signing_keys</span></code>):</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ mkdir ~/signing_keys && cd ~/signing_keys |
| </pre></div> |
| </div> |
| <p>With all set up, we can now generate keys to sign the bootloader and application binary images, |
| respectively, of the compiled project:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem |
| $ imgtool keygen --key app_signing_key.pem --type rsa-3072 |
| </pre></div> |
| </div> |
| <div class="admonition important"> |
| <p class="admonition-title">Important</p> |
| <p>The contents of the key files must be stored securely and kept secret.</p> |
| </div> |
| </section> |
| <section id="enabling-secure-boot-and-flash-encryption"> |
| <h3>Enabling Secure Boot and Flash Encryption<a class="headerlink" href="#enabling-secure-boot-and-flash-encryption" title="Permalink to this heading"></a></h3> |
| <p>To enable Secure Boot for the current project, go to the project’s NuttX directory, execute <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">menuconfig</span></code> and the following steps:</p> |
| <blockquote> |
| <div><ol class="arabic simple"> |
| <li><p>Enable experimental features in <span class="menuselection">Build Setup ‣ Show experimental options</span>;</p></li> |
| <li><p>Enable MCUboot in <span class="menuselection">Application Configuration ‣ Bootloader Utilities ‣ MCUboot</span>;</p></li> |
| <li><p>Change image type to <code class="docutils literal notranslate"><span class="pre">MCUboot-bootable</span> <span class="pre">format</span></code> in <span class="menuselection">System Type ‣ Application Image Configuration ‣ Application Image Format</span>;</p></li> |
| <li><p>Enable building MCUboot from the source code by selecting <code class="docutils literal notranslate"><span class="pre">Build</span> <span class="pre">binaries</span> <span class="pre">from</span> <span class="pre">source</span></code>; |
| in <span class="menuselection">System Type ‣ Application Image Configuration ‣ Source for bootloader binaries</span>;</p></li> |
| <li><p>Enable Secure Boot in <span class="menuselection">System Type ‣ Application Image Configuration ‣ Enable hardware Secure Boot in bootloader</span>;</p></li> |
| <li><p>If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in |
| <span class="menuselection">System Type ‣ Application Image Configuration ‣ Enable Flash Encryption on boot</span>.</p></li> |
| </ol> |
| </div></blockquote> |
| <p>Now you can design an update and confirm agent to your application. Check the <a class="reference external" href="https://docs.mcuboot.com/design.html">MCUboot design guide</a> and the |
| <a class="reference external" href="https://docs.mcuboot.com/readme-espressif.html">MCUboot Espressif port documentation</a> for |
| more information on how to apply MCUboot. Also check some <a class="reference external" href="https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-nuttx.md">notes about the NuttX MCUboot port</a>, |
| the <a class="reference external" href="https://github.com/mcu-tools/mcuboot/blob/main/docs/PORTING.md">MCUboot porting guide</a> and some |
| <a class="reference external" href="https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot">examples of MCUboot applied in Nuttx applications</a>.</p> |
| <p>After you developed an application which implements all desired functions, you need to flash it into the primary image slot |
| of the device (it will automatically be in the confirmed state, you can learn more about image |
| confirmation <a class="reference external" href="https://docs.mcuboot.com/design.html#image-swapping">here</a>). |
| To flash to the primary image slot, select <code class="docutils literal notranslate"><span class="pre">Application</span> <span class="pre">image</span> <span class="pre">primary</span> <span class="pre">slot</span></code> in |
| <span class="menuselection">System Type ‣ Application Image Configuration ‣ Target slot for image flashing</span> |
| and compile it using <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-j</span> <span class="pre">ESPSEC_KEYDIR=~/signing_keys</span></code>.</p> |
| <p>When creating update images, make sure to change <span class="menuselection">System Type ‣ Application Image Configuration ‣ Target slot for image flashing</span> |
| to <code class="docutils literal notranslate"><span class="pre">Application</span> <span class="pre">image</span> <span class="pre">secondary</span> <span class="pre">slot</span></code>.</p> |
| <div class="admonition important"> |
| <p class="admonition-title">Important</p> |
| <p>When deploying your application, make sure to disable UART Download Mode by selecting <code class="docutils literal notranslate"><span class="pre">Permanently</span> <span class="pre">disabled</span></code> in |
| <span class="menuselection">System Type ‣ Application Image Configuration ‣ UART ROM download mode</span> |
| and change usage mode to <code class="docutils literal notranslate"><span class="pre">Release</span></code> in <cite>System Type –> Application Image Configuration –> Enable usage mode</cite>. |
| <strong>After disabling UART Download Mode you will not be able to flash other images through UART.</strong></p> |
| </div> |
| </section> |
| </section> |
| <section id="things-to-do"> |
| <h2>Things to Do<a class="headerlink" href="#things-to-do" title="Permalink to this heading"></a></h2> |
| <ol class="arabic"> |
| <li><p>Lazy co-processor save logic supported by Xtensa. That logic works like this:</p> |
| <ol class="loweralpha simple"> |
| <li><p>CPENABLE is set to zero on each context switch, disabling all co- |
| processors.</p></li> |
| <li><p>If/when the task attempts to use the disabled co-processor, an |
| exception occurs</p></li> |
| <li><p>The co-processor exception handler re-enables the co-processor.</p></li> |
| </ol> |
| <p>Instead, the NuttX logic saves and restores CPENABLE on each context |
| switch. This has disadvantages in that (1) co-processor context will |
| be saved and restored even if the co-processor was never used, and (2) |
| tasks must explicitly enable and disable co-processors.</p> |
| </li> |
| <li><p>Currently the Xtensa port copies register state save information from |
| the stack into the TCB. A more efficient alternative would be to just |
| save a pointer to a register state save area in the TCB. This would |
| add some complexity to signal handling and also to up_initialstate(). |
| But the performance improvement might be worth the effort.</p></li> |
| <li><p>See SMP-related issues above</p></li> |
| </ol> |
| </section> |
| <section id="supported-boards"> |
| <h2>Supported Boards<a class="headerlink" href="#supported-boards" title="Permalink to this heading"></a></h2> |
| <div class="toctree-wrapper compound"> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="boards/esp32-devkitc/index.html">ESP32 DevKitC</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="boards/esp32-lyrat/index.html">ESP32-LyraT V4.3</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="boards/esp32-wrover-kit/index.html">ESP-WROVER-KIT</a></li> |
| </ul> |
| </div> |
| </section> |
| </section> |
| |
| |
| </div> |
| </div> |
| <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> |
| <a href="../index.html" class="btn btn-neutral float-left" title="Xtensa" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="boards/esp32-devkitc/index.html" class="btn btn-neutral float-right" title="ESP32 DevKitC" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> |
| </div> |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p>© Copyright 2020, The Apache Software Foundation.</p> |
| </div> |
| |
| |
| |
| </footer> |
| </div> |
| </div> |
| </section> |
| </div> |
| <script> |
| jQuery(function () { |
| SphinxRtdTheme.Navigation.enable(true); |
| }); |
| </script> |
| |
| </body> |
| </html> |
