| <!-- |
| 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.19: https://docutils.sourceforge.io/" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>Espressif ESP32-C3 — NuttX latest documentation</title> |
| <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css" /> |
| <link rel="stylesheet" type="text/css" href="../../../_static/copybutton.css" /> |
| <link rel="stylesheet" type="text/css" href="../../../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" /> |
| <link rel="stylesheet" type="text/css" href="../../../_static/custom.css" /> |
| |
| |
| <link rel="shortcut icon" href="../../../_static/favicon.ico"/> |
| <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/clipboard.min.js"></script> |
| <script src="../../../_static/copybutton.js"></script> |
| <script src="../../../_static/design-tabs.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-C3 DevKit" href="boards/esp32c3-generic/index.html" /> |
| <link rel="prev" title="ESP32-C3 DevKit" href="../esp32c3-legacy/boards/esp32c3-devkit/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> |
| |
| <option value="../../../../12.6.0" >12.6.0</option> |
| |
| <option value="../../../../12.7.0" >12.7.0</option> |
| |
| <option value="../../../../12.8.0" >12.8.0</option> |
| |
| <option value="../../../../12.9.0" >12.9.0</option> |
| |
| <option value="../../../../12.10.0" >12.10.0</option> |
| |
| <option value="../../../../12.11.0" >12.11.0</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="../../arm64/index.html">ARM64</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../avr/index.html">Microchip AVR</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../ceva/index.html">CEVA</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../hc/index.html">HC</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../mips/index.html">MIPS</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../misco/index.html">Misoc</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../or1k/index.html">OpenRISC</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../renesas/index.html">Renesas</a></li> |
| <li class="toctree-l2 current"><a class="reference internal" href="../index.html">RISC-V</a><ul class="current"> |
| <li class="toctree-l3"><a class="reference internal" href="../bl602/index.html">Bouffalo Lab BL602</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../bl808/index.html">Bouffalo Lab BL808</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../c906/index.html">THEAD C906</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../eic7700x/index.html">ESWIN EIC7700X</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../esp32c3-legacy/index.html">Espressif ESP32-C3 (Legacy)</a></li> |
| <li class="toctree-l3 current"><a class="current reference internal" href="#">Espressif ESP32-C3</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#esp32-c3-toolchain">ESP32-C3 Toolchain</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#installing">Installing</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#building-and-flashing-nuttx">Building and flashing NuttX</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#installing-esptool">Installing esptool</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#bootloader-and-partitions">Bootloader and partitions</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#building-and-flashing">Building and Flashing</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#flashing-nsh-example">Flashing NSH Example</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#debugging">Debugging</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#debugging-with-openocd-and-gdb">Debugging with <code class="docutils literal notranslate"><span class="pre">openocd</span></code> and <code class="docutils literal notranslate"><span class="pre">gdb</span></code></a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#stack-dump-and-backtrace-dump">Stack Dump and Backtrace Dump</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l4"><a class="reference internal" href="#peripheral-support">Peripheral Support</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#analog-to-digital-converter-adc">Analog-to-digital converter (ADC)</a></li> |
| </ul> |
| </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="#id1">Managing esptool on virtual environment</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="#using-pipx-recommended">Using pipx (recommended)</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="#using-venv-alternative">Using venv (alternative)</a></li> |
| </ul> |
| </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/esp32c3-generic/index.html">ESP32-C3 DevKit</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="boards/esp32c3-xiao/index.html">Seeed Studio XIAO ESP32C3</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="../esp32c6/index.html">Espressif ESP32-C6</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../esp32h2/index.html">Espressif ESP32-H2</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../fe310/index.html">SiFive FE310</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../hpm6000/index.html">Hpmicro HPM6000</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../hpm6750/index.html">Hpmicro HPM6750</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../jh7110/index.html">StarFive JH7110</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../k210/index.html">Kendryte K210</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../k230/index.html">Kendryte K230</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../litex/index.html">Enjoy Digital LiteX FPGA’s</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../mpfs/index.html">Microchip PolarFire® SoC FPGA’s (MPFS)</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../qemu-rv/index.html">QEMU Generic RV32/RV64</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../rv32m1/index.html">NXP RV32M1</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="../sg2000/index.html">SOPHGO SG2000</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../../sim/index.html">Simulators</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../sim/network_linux.html">Network Support on Linux</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../sim/network_vpnkit.html">Network support with VPNKit</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../sparc/index.html">SPARC</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../tricore/index.html">TriCore</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../x86/index.html">Intel 80x86</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../x86_64/index.html">Intel 80x86_64</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../xtensa/index.html">Xtensa</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../z16/index.html">Z16</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../../z80/index.html">Z80</a></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="../../../implementation/index.html">Implementation Details</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="../../../debugging/index.html">Debugging</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> |
| <li class="toctree-l1"><a class="reference internal" href="../../../logos/index.html">NuttX Logos</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../../_tags/tagsindex.html">Tags</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">RISC-V</a></li> |
| <li class="breadcrumb-item active">Espressif ESP32-C3</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="https://github.com/apache/nuttx/blob/master/Documentation/platforms/risc-v/esp32c3/index.rst" class="fa fa-github"> Edit on GitHub</a> |
| </li> |
| </ul> |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <section id="espressif-esp32-c3"> |
| <span id="esp32c3"></span><h1>Espressif ESP32-C3<a class="headerlink" href="#espressif-esp32-c3" title="Permalink to this heading"></a></h1> |
| <p>The ESP32-C3 is an ultra-low-power and highly integrated SoC with a RISC-V |
| core and supports 2.4 GHz Wi-Fi and Bluetooth Low Energy.</p> |
| <ul class="simple"> |
| <li><p>Address Space |
| - 800 KB of internal memory address space accessed from the instruction bus |
| - 560 KB of internal memory address space accessed from the data bus |
| - 1016 KB of peripheral address space |
| - 8 MB of external memory virtual address space accessed from the instruction bus |
| - 8 MB of external memory virtual address space accessed from the data bus |
| - 480 KB of internal DMA address space</p></li> |
| <li><p>Internal Memory |
| - 384 KB ROM |
| - 400 KB SRAM (16 KB can be configured as Cache) |
| - 8 KB of SRAM in RTC</p></li> |
| <li><p>External Memory |
| - Up to 16 MB of external flash</p></li> |
| <li><p>Peripherals |
| - 35 peripherals</p></li> |
| <li><p>GDMA |
| - 7 modules are capable of DMA operations.</p></li> |
| </ul> |
| <section id="esp32-c3-toolchain"> |
| <h2>ESP32-C3 Toolchain<a class="headerlink" href="#esp32-c3-toolchain" title="Permalink to this heading"></a></h2> |
| <p>A generic RISC-V toolchain can be used to build ESP32-C3 projects. It’s recommended to use the same |
| toolchain used by NuttX CI. Please refer to the Docker |
| <a class="reference external" href="https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile">container</a> and |
| check for the current compiler version being used. For instance:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>############################################################################### |
| # Build image for tool required by RISCV builds |
| ############################################################################### |
| FROM nuttx-toolchain-base AS nuttx-toolchain-riscv |
| # Download the latest RISCV GCC toolchain prebuilt by xPack |
| RUN mkdir riscv-none-elf-gcc && \ |
| curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ |
| | tar -C riscv-none-elf-gcc --strip-components 1 -xz |
| </pre></div> |
| </div> |
| <p>It uses the xPack’s prebuilt toolchain based on GCC 13.2.0-2.</p> |
| <section id="installing"> |
| <h3>Installing<a class="headerlink" href="#installing" title="Permalink to this heading"></a></h3> |
| <p>First, create a directory to hold the toolchain:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mkdir<span class="w"> </span>-p<span class="w"> </span>/path/to/your/toolchain/riscv-none-elf-gcc |
| </pre></div> |
| </div> |
| <p>Download and extract toolchain:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>curl<span class="w"> </span>-s<span class="w"> </span>-L<span class="w"> </span><span class="s2">"https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz"</span><span class="w"> </span><span class="se">\</span> |
| <span class="p">|</span><span class="w"> </span>tar<span class="w"> </span>-C<span class="w"> </span>/path/to/your/toolchain/riscv-none-elf-gcc<span class="w"> </span>--strip-components<span class="w"> </span><span class="m">1</span><span class="w"> </span>-xz |
| </pre></div> |
| </div> |
| <p>Add the toolchain to your <cite>PATH</cite>:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">echo</span><span class="w"> </span><span class="s2">"export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:</span><span class="nv">$PATH</span><span class="s2">"</span><span class="w"> </span>>><span class="w"> </span>~/.bashrc |
| </pre></div> |
| </div> |
| <p>You can edit your shell’s rc files if you don’t use bash.</p> |
| </section> |
| </section> |
| <section id="building-and-flashing-nuttx"> |
| <h2>Building and flashing NuttX<a class="headerlink" href="#building-and-flashing-nuttx" title="Permalink to this heading"></a></h2> |
| <section id="installing-esptool"> |
| <h3>Installing esptool<a class="headerlink" href="#installing-esptool" title="Permalink to this heading"></a></h3> |
| <p>Make sure that <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code> is installed and up-to-date. |
| This tool is used to convert the ELF to a compatible ESP32-C3 image and to flash the image into the board.</p> |
| <p>It can be installed with: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">esptool>=4.8.1</span></code>.</p> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>Installing <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code> may required a Python virtual environment on newer systems. |
| This will be the case if the <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> command throws an error such as: |
| <code class="docutils literal notranslate"><span class="pre">error:</span> <span class="pre">externally-managed-environment</span></code>.</p> |
| <p>If you are not familiar with virtual environments, refer to <a class="reference internal" href="#managing-esptool-on-virtual-environment">Managing esptool on virtual environment</a> for instructions on how to install <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code>.</p> |
| </div> |
| </section> |
| <section id="bootloader-and-partitions"> |
| <h3>Bootloader and partitions<a class="headerlink" href="#bootloader-and-partitions" title="Permalink to this heading"></a></h3> |
| <p>NuttX can boot the ESP32-C3 directly using the so-called “Simple Boot”. |
| An externally-built 2nd stage bootloader is not required in this case as all |
| functions required to boot the device are built within NuttX. Simple boot does not |
| require any specific configuration (it is selectable by default if no other |
| 2nd stage bootloader is used).</p> |
| <p>If other features, like <a class="reference internal" href="#secure-boot-and-flash-encryption">Secure Boot and Flash Encryption</a>, are required, an |
| externally-built 2nd stage bootloader is needed. The bootloader is built using |
| the <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">bootloader</span></code> command. This command generates the firmware in the |
| <code class="docutils literal notranslate"><span class="pre">nuttx</span></code> folder. The <code class="docutils literal notranslate"><span class="pre">ESPTOOL_BINDIR</span></code> is used in the <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">flash</span></code> command |
| to specify the path to the bootloader. For compatibility among other SoCs and |
| future options of 2nd stage bootloaders, the commands <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">bootloader</span></code> and |
| the <code class="docutils literal notranslate"><span class="pre">ESPTOOL_BINDIR</span></code> option (for the <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">flash</span></code>) can be used even if no |
| externally-built 2nd stage bootloader is being built (they will be ignored if |
| Simple Boot is used, for instance):</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make bootloader |
| </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 to |
| perform a complete SPI FLASH erase.</p> |
| <blockquote> |
| <div><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></blockquote> |
| </div> |
| </section> |
| <section id="building-and-flashing"> |
| <h3>Building and Flashing<a class="headerlink" href="#building-and-flashing" title="Permalink to this heading"></a></h3> |
| <p>This is a two-step process where the first step converts the ELF file into an ESP32-C3 compatible binary |
| and the second step flashes it to the board. These steps are included in the build system and it is |
| possible to build and flash the NuttX firmware simply by running:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=./ |
| </pre></div> |
| </div> |
| <p>where:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">ESPTOOL_PORT</span></code> is typically <code class="docutils literal notranslate"><span class="pre">/dev/ttyUSB0</span></code> or similar.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">ESPTOOL_BINDIR=./</span></code> is the path of the externally-built 2nd stage bootloader and the partition table (if applicable): when built using the <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">bootloader</span></code>, these files are placed into <code class="docutils literal notranslate"><span class="pre">nuttx</span></code> folder.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">ESPTOOL_BAUD</span></code> is able to change the flash baud rate if desired.</p></li> |
| </ul> |
| </section> |
| <section id="flashing-nsh-example"> |
| <h3>Flashing NSH Example<a class="headerlink" href="#flashing-nsh-example" title="Permalink to this heading"></a></h3> |
| <p>This example shows how to build and flash the <code class="docutils literal notranslate"><span class="pre">nsh</span></code> defconfig for the ESP32-C3-DevKitC-02 board:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ cd nuttx |
| $ make distclean |
| $ ./tools/configure.sh esp32c3-generic:nsh |
| $ make -j$(nproc) |
| </pre></div> |
| </div> |
| <p>When the build is complete, the firmware can be flashed to the board using the command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make -j$(nproc) flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=./ |
| </pre></div> |
| </div> |
| <p>where <code class="docutils literal notranslate"><span class="pre"><port></span></code> is the serial port where the board is connected:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make flash ESPTOOL_PORT=/dev/ttyUSB0 ESPTOOL_BINDIR=./ |
| CP: nuttx.hex |
| MKIMAGE: NuttX binary |
| esptool.py -c esp32c3 elf2image --ram-only-header -fs 4MB -fm dio -ff 80m -o nuttx.bin nuttx |
| esptool.py v4.8.1 |
| Creating esp32c3 image... |
| Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended. |
| Merged 1 ELF section |
| Successfully created esp32c3 image. |
| Generated: nuttx.bin |
| esptool.py -c esp32c3 -p /dev/ttyUSB0 -b 921600 write_flash -fs 4MB -fm dio -ff 80m 0x0000 nuttx.bin |
| esptool.py v4.8.1 |
| Serial port /dev/ttyUSB0 |
| Connecting.... |
| Chip is ESP32-C3 (QFN32) (revision v0.4) |
| [...] |
| Flash will be erased from 0x00000000 to 0x0003afff... |
| Compressed 240768 bytes to 104282... |
| Wrote 240768 bytes (104282 compressed) at 0x00000000 in 3.4 seconds (effective 568.4 kbit/s)... |
| Hash of data verified. |
| |
| Leaving... |
| Hard resetting via RTS pin... |
| </pre></div> |
| </div> |
| <p>Now opening the serial port with a terminal emulator should show the NuttX console:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ picocom -b 115200 /dev/ttyUSB0 |
| NuttShell (NSH) NuttX-12.8.0 |
| nsh> uname -a |
| NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 19:58:56 risc-v esp32c3-generic |
| </pre></div> |
| </div> |
| </section> |
| </section> |
| <section id="debugging"> |
| <h2>Debugging<a class="headerlink" href="#debugging" title="Permalink to this heading"></a></h2> |
| <p>This section describes debugging techniques for the ESP32-C3.</p> |
| <section id="debugging-with-openocd-and-gdb"> |
| <h3>Debugging with <code class="docutils literal notranslate"><span class="pre">openocd</span></code> and <code class="docutils literal notranslate"><span class="pre">gdb</span></code><a class="headerlink" href="#debugging-with-openocd-and-gdb" title="Permalink to this heading"></a></h3> |
| <p>Espressif uses a specific version of OpenOCD to support ESP32-C3: <a class="reference external" href="https://github.com/espressif/">openocd-esp32</a>.</p> |
| <p>Please check <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd">Building OpenOCD from Sources</a> |
| for more information on how to build OpenOCD for ESP32-C3.</p> |
| <p>ESP32-C3 has a built-in JTAG circuitry and can be debugged without any additional chip. |
| Only an USB cable connected to the D+/D- pins is necessary:</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>ESP32-C3 Pin</p></th> |
| <th class="head"><p>USB Signal</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>GPIO18</p></td> |
| <td><p>D-</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>GPIO19</p></td> |
| <td><p>D+</p></td> |
| </tr> |
| <tr class="row-even"><td><p>5V</p></td> |
| <td><p>V_BUS</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>GND</p></td> |
| <td><p>Ground</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>One must configure the USB drivers to enable JTAG communication. Please check |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html#configure-usb-drivers">Configure USB Drivers</a> |
| for more information.</p> |
| </div> |
| <p>OpenOCD can then be used:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>openocd -s <tcl_scripts_path> -c 'set ESP_RTOS hwthread' -f board/esp32c3-builtin.cfg -c 'init; reset halt; esp appimage_offset 0x0' |
| </pre></div> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">appimage_offset</span></code> should be set to <code class="docutils literal notranslate"><span class="pre">0x0</span></code> when <code class="docutils literal notranslate"><span class="pre">Simple</span> <span class="pre">Boot</span></code> is used. For MCUboot, this value should be set to |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_ESPRESSIF_OTA_PRIMARY_SLOT_OFFSET</span></code> value (<code class="docutils literal notranslate"><span class="pre">0x10000</span></code> by default).</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">-s</span> <span class="pre"><tcl_scripts_path></span></code> defines the path to the OpenOCD scripts. Usually set to <cite>tcl</cite> if running openocd from its source directory. |
| It can be omitted if <cite>openocd-esp32</cite> were installed in the system with <cite>sudo make install</cite>.</p></li> |
| </ul> |
| </div> |
| <p>If you want to debug with an external JTAG adapter it can |
| be connected as follows:</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>ESP32-C6 Pin</p></th> |
| <th class="head"><p>JTAG Signal</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>GPIO4</p></td> |
| <td><p>TMS</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>GPIO5</p></td> |
| <td><p>TDI</p></td> |
| </tr> |
| <tr class="row-even"><td><p>GPIO6</p></td> |
| <td><p>TCK</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>GPIO7</p></td> |
| <td><p>TDO</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <p>Furthermore, an efuse needs to be burnt to be able to debug:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>espefuse.py -p <port> burn_efuse DIS_USB_JTAG |
| </pre></div> |
| </div> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>Burning eFuses is an irreversible operation, so please |
| consider the above option before starting the process.</p> |
| </div> |
| <p>OpenOCD can then be used:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-ftdi.cfg |
| </pre></div> |
| </div> |
| <p>Once OpenOCD is running, you can use GDB to connect to it and debug your application:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>riscv-none-elf-gdb -x gdbinit nuttx |
| </pre></div> |
| </div> |
| <p>whereas the content of the <code class="docutils literal notranslate"><span class="pre">gdbinit</span></code> file is:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>target remote :3333 |
| set remote hardware-watchpoint-limit 2 |
| mon reset halt |
| flushregs |
| monitor reset halt |
| thb nsh_main |
| c |
| </pre></div> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p><code class="docutils literal notranslate"><span class="pre">nuttx</span></code> is the ELF file generated by the build process. Please note that <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_SYMBOLS</span></code> must be enabled in the <code class="docutils literal notranslate"><span class="pre">menuconfig</span></code>.</p> |
| </div> |
| <p>Please refer to <a class="reference internal" href="../../../quickstart/debugging.html"><span class="doc">Debugging</span></a> for more information about debugging techniques.</p> |
| </section> |
| <section id="stack-dump-and-backtrace-dump"> |
| <h3>Stack Dump and Backtrace Dump<a class="headerlink" href="#stack-dump-and-backtrace-dump" title="Permalink to this heading"></a></h3> |
| <p>NuttX has a feature to dump the stack of a task and to dump the backtrace of it (and of all |
| the other tasks). This feature is useful to debug the system when it is not behaving as expected, |
| especially when it is crashing.</p> |
| <p>In order to enable this feature, the following options must be enabled in the NuttX configuration: |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_BACKTRACE</span></code>, <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_SYMBOLS</span></code> and, optionally, <code class="docutils literal notranslate"><span class="pre">CONFIG_ALLSYMS</span></code>.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>The first two options enable the backtrace dump. The third option enables the backtrace dump |
| with the associated symbols, but increases the size of the generated NuttX binary.</p> |
| </div> |
| <p>Espressif also provides a tool to translate the backtrace dump into a human-readable format. |
| This tool is called <code class="docutils literal notranslate"><span class="pre">btdecode.sh</span></code> and is available at <code class="docutils literal notranslate"><span class="pre">tools/espressif/btdecode.sh</span></code> of NuttX |
| repository.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>This tool is not necessary if <code class="docutils literal notranslate"><span class="pre">CONFIG_ALLSYMS</span></code> is enabled. In this case, the backtrace dump |
| contains the function names.</p> |
| </div> |
| <section id="example-crash-dump"> |
| <h4>Example - Crash Dump<a class="headerlink" href="#example-crash-dump" title="Permalink to this heading"></a></h4> |
| <p>A typical crash dump, caused by an illegal load with <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_BACKTRACE</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_SYMBOLS</span></code> enabled, is shown below:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>riscv_exception: EXCEPTION: Store/AMO access fault. MCAUSE: 00000007, EPC: 42012df2, MT0 |
| riscv_exception: PANIC!!! Exception = 00000007 |
| _assert: Current Version: NuttX 10.4.0 2ae3246e40-dirty Sep 19 2024 14:34:41 risc-v |
| _assert: Assertion failed panic: at file: :0 task: backtrace process: backtrace 0x42012dac |
| up_dump_register: EPC: 42012df2 |
| up_dump_register: A0: 0000005a A1: 3fc88a54 A2: 00000001 A3: 00000088 |
| up_dump_register: A4: 00007fff A5: 00000001 A6: 00000000 A7: 00000000 |
| up_dump_register: T0: 00000000 T1: 00000000 T2: ffffffff T3: 00000000 |
| up_dump_register: T4: 00000000 T5: 00000000 T6: 00000000 |
| up_dump_register: S0: 3fc87b16 S1: 3fc87b00 S2: 00000000 S3: 00000000 |
| up_dump_register: S4: 00000000 S5: 00000000 S6: 00000000 S7: 00000000 |
| up_dump_register: S8: 00000000 S9: 00000000 S10: 00000000 S11: 00000000 |
| up_dump_register: SP: 3fc88ab0 FP: 3fc87b16 TP: 00000000 RA: 42012df2 |
| dump_stack: User Stack: |
| dump_stack: base: 0x3fc87b20 |
| dump_stack: size: 00004048 |
| dump_stack: sp: 0x3fc88ab0 |
| stack_dump: 0x3fc88a90: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00001800 |
| stack_dump: 0x3fc88ab0: 00000000 3fc87718 42012dac 42006dd0 00000000 00000000 3fc87b00 00000002 |
| stack_dump: 0x3fc88ad0: 00000000 00000000 00000000 42004d4c 00000000 00000000 00000000 00000000 |
| stack_dump: 0x3fc88af0: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 |
| sched_dumpstack: backtrace| 2: 0x42012df2 |
| dump_tasks: PID GROUP PRI POLICY TYPE NPX STATE EVENT SIGMASK STACKBASE STACKSIZE COMMAND |
| dump_tasks: ---- --- --- -------- ------- --- ------- ---------- ---------------- 0x3fc845e0 1536 irq |
| dump_task: 0 0 0 FIFO Kthread - Ready 0000000000000000 0x3fc85d18 2032 Idle_Task |
| dump_task: 1 1 100 RR Task - Waiting Semaphore 0000000000000000 0x3fc86c30 2000 nsh_main |
| dump_task: 2 2 255 RR Task - Running 0000000000000000 0x3fc87b20 4048 backtrace task |
| sched_dumpstack: backtrace| 0: 0x42008420 |
| sched_dumpstack: backtrace| 1: 0x420089a8 |
| sched_dumpstack: backtrace| 2: 0x42012df2 |
| </pre></div> |
| </div> |
| <p>The lines starting with <code class="docutils literal notranslate"><span class="pre">sched_dumpstack</span></code> show the backtrace of the tasks. By checking it, it is |
| possible to track the root cause of the crash. Saving this output to a file and using the <code class="docutils literal notranslate"><span class="pre">btdecode.sh</span></code>:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>./tools/btdecode.sh esp32c3 /tmp/backtrace.txt |
| Backtrace for task 2: |
| 0x42012df2: assert_on_task at backtrace_main.c:158 |
| (inlined by) backtrace_main at backtrace_main.c:194 |
| |
| Backtrace dump for all tasks: |
| |
| Backtrace for task 2: |
| 0x42012df2: assert_on_task at backtrace_main.c:158 |
| (inlined by) backtrace_main at backtrace_main.c:194 |
| |
| Backtrace for task 1: |
| 0x420089a8: sys_call2 at syscall.h:227 |
| (inlined by) up_switch_context at riscv_switchcontext.c:95 |
| |
| Backtrace for task 0: |
| 0x42008420: up_idle at esp_idle.c:74 |
| </pre></div> |
| </div> |
| <p>The above output shows the backtrace of the tasks. By checking it, it is possible to track the |
| functions that were being executed when the crash occurred.</p> |
| </section> |
| </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>ADC</p></td> |
| <td><p>Yes</p></td> |
| <td><p>Oneshot</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>AES</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>CAN/TWAI</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>DMA</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>DS</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>eFuse</p></td> |
| <td><p>Yes</p></td> |
| <td><p>Also virtual mode supported</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>GPIO</p></td> |
| <td><p>Yes</p></td> |
| <td><p>Dedicated GPIO supported</p></td> |
| </tr> |
| <tr class="row-even"><td><p>HMAC</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>I2C</p></td> |
| <td><p>Yes</p></td> |
| <td><p>Master and Slave mode supported</p></td> |
| </tr> |
| <tr class="row-even"><td><p>I2S</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>LED/PWM</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>RMT</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>RNG</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>RSA</p></td> |
| <td><p>No</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>SHA</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>SPI</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>SPIFLASH</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>SPIRAM</p></td> |
| <td><p>No</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Timers</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>USB Serial</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>Watchdog</p></td> |
| <td><p>Yes</p></td> |
| <td><p>XTWDT supported</p></td> |
| </tr> |
| <tr class="row-even"><td><p>Wi-Fi</p></td> |
| <td><p>Yes</p></td> |
| <td><p>WPA3-SAE supported</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <section id="analog-to-digital-converter-adc"> |
| <h3>Analog-to-digital converter (ADC)<a class="headerlink" href="#analog-to-digital-converter-adc" title="Permalink to this heading"></a></h3> |
| <p>Two ADC units are available for the ESP32-C3:</p> |
| <ul class="simple"> |
| <li><p>ADC1 with 5 channels.</p></li> |
| <li><p>ADC2 with 1 channel and internal voltage reading. <strong>This unit is not implemented.</strong></p></li> |
| </ul> |
| <p>Those units are independent and can be used simultaneously. During bringup, GPIOs for selected channels are |
| configured automatically to be used as ADC inputs. |
| If available, ADC calibration is automatically applied (see |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/v5.1/esp32c3/api-reference/peripherals/adc_calibration.html">this page</a> for more details). |
| Otherwise, a simple conversion is applied based on the attenuation and resolution.</p> |
| <p>The ADC unit is accessible using the ADC character driver, which returns data for the enabled channels.</p> |
| <p>The ADC1 unit can be enabled in the menu <span class="menuselection">System Type ‣ Peripheral Support ‣ Analog-to-digital converter (ADC)</span>.</p> |
| <p>Then, it can be customized in the menu <span class="menuselection">System Type ‣ ADC Configuration</span>, which includes operating mode, gain and channels.</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Channel</p></th> |
| <th class="head"><p>ADC1 GPIO</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>0</p></td> |
| <td><p>0</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>1</p></td> |
| <td><p>1</p></td> |
| </tr> |
| <tr class="row-even"><td><p>2</p></td> |
| <td><p>2</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>3</p></td> |
| <td><p>3</p></td> |
| </tr> |
| <tr class="row-even"><td><p>4</p></td> |
| <td><p>4</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>Maximum measurable voltage may saturate around 2900 mV.</p> |
| </div> |
| </section> |
| </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-C3, 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-C3 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-C3’s Secure boot |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/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-C3’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-C3’s Flash Encryption |
| <a class="reference external" href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/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> (the MCUboot utility application to manipulate binary |
| images):</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pip install imgtool |
| </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="id1"> |
| <h2><span class="target" id="managing-esptool-on-virtual-environment">Managing esptool on virtual environment</span><a class="headerlink" href="#id1" title="Permalink to this heading"></a></h2> |
| <p>This section describes how to install <code class="docutils literal notranslate"><span class="pre">esptool</span></code>, <code class="docutils literal notranslate"><span class="pre">imgtool</span></code> or any other Python packages in a |
| proper environment.</p> |
| <p>Normally, a Linux-based OS would already have Python 3 installed by default. Up to a few years ago, |
| you could simply call <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> to install packages globally. However, this is no longer recommended |
| as it can lead to conflicts between packages and versions. The recommended way to install Python packages |
| is to use a virtual environment.</p> |
| <p>A virtual environment is a self-contained directory that contains a Python installation for a particular |
| version of Python, plus a number of additional packages. You can create a virtual environment for each |
| project you are working on, and install the required packages in that environment.</p> |
| <p>Two alternatives are explained below, you can select any one of those.</p> |
| <section id="using-pipx-recommended"> |
| <h3>Using pipx (recommended)<a class="headerlink" href="#using-pipx-recommended" title="Permalink to this heading"></a></h3> |
| <p><code class="docutils literal notranslate"><span class="pre">pipx</span></code> is a tool that makes it easy to install Python packages in a virtual environment. To install |
| <code class="docutils literal notranslate"><span class="pre">pipx</span></code>, you can run the following command (using apt as example):</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ apt install pipx |
| </pre></div> |
| </div> |
| <p>Once you have installed <code class="docutils literal notranslate"><span class="pre">pipx</span></code>, you can use it to install Python packages in a virtual environment. For |
| example, to install the <code class="docutils literal notranslate"><span class="pre">esptool</span></code> package, you can run the following command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pipx install esptool |
| </pre></div> |
| </div> |
| <p>This will create a new virtual environment in the <code class="docutils literal notranslate"><span class="pre">~/.local/pipx/venvs</span></code> directory, which contains the |
| <code class="docutils literal notranslate"><span class="pre">esptool</span></code> package. You can now use the <code class="docutils literal notranslate"><span class="pre">esptool</span></code> command as normal, and so will the build system.</p> |
| <p>Make sure to run <code class="docutils literal notranslate"><span class="pre">pipx</span> <span class="pre">ensurepath</span></code> to add the <code class="docutils literal notranslate"><span class="pre">~/.local/bin</span></code> directory to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>. This will |
| allow you to run the <code class="docutils literal notranslate"><span class="pre">esptool</span></code> command from any directory.</p> |
| </section> |
| <section id="using-venv-alternative"> |
| <h3>Using venv (alternative)<a class="headerlink" href="#using-venv-alternative" title="Permalink to this heading"></a></h3> |
| <p>To create a virtual environment, you can use the <code class="docutils literal notranslate"><span class="pre">venv</span></code> module, which is included in the Python standard |
| library. To create a virtual environment, you can run the following command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ python3 -m venv myenv |
| </pre></div> |
| </div> |
| <p>This will create a new directory called <code class="docutils literal notranslate"><span class="pre">myenv</span></code> in the current directory, which contains a Python |
| installation and a copy of the Python standard library. To activate the virtual environment, you can run |
| the following command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ source myenv/bin/activate |
| </pre></div> |
| </div> |
| <p>This will change your shell prompt to indicate that you are now working in the virtual environment. You can |
| now install packages using <code class="docutils literal notranslate"><span class="pre">pip</span></code>. For example, to install the <code class="docutils literal notranslate"><span class="pre">esptool</span></code> package, you can run the following |
| command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pip install esptool |
| </pre></div> |
| </div> |
| <p>This will install the <code class="docutils literal notranslate"><span class="pre">esptool</span></code> package in the virtual environment. You can now use the <code class="docutils literal notranslate"><span class="pre">esptool</span></code> command as |
| normal. When you are finished working in the virtual environment, you can deactivate it by running the following |
| command:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ deactivate |
| </pre></div> |
| </div> |
| <p>This will return your shell prompt to its normal state. You can reactivate the virtual environment at any time by |
| running the <code class="docutils literal notranslate"><span class="pre">source</span> <span class="pre">myenv/bin/activate</span></code> command again. You can also delete the virtual environment by deleting |
| the directory that contains it.</p> |
| </section> |
| </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/esp32c3-generic/index.html">ESP32-C3 DevKit</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="boards/esp32c3-xiao/index.html">Seeed Studio XIAO ESP32C3</a></li> |
| </ul> |
| </div> |
| </section> |
| </section> |
| |
| |
| </div> |
| </div> |
| <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> |
| <a href="../esp32c3-legacy/boards/esp32c3-devkit/index.html" class="btn btn-neutral float-left" title="ESP32-C3 DevKit" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="boards/esp32c3-generic/index.html" class="btn btn-neutral float-right" title="ESP32-C3 DevKit" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> |
| </div> |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p>© Copyright 2023, The Apache Software Foundation.</p> |
| </div> |
| |
| |
| |
| </footer> |
| </div> |
| </div> |
| </section> |
| </div> |
| <script> |
| jQuery(function () { |
| SphinxRtdTheme.Navigation.enable(true); |
| }); |
| </script> |
| |
| </body> |
| </html> |
