| <!-- |
| 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-C3 (Legacy) — 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/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/js/theme.js"></script> |
| <link rel="index" title="Index" href="../../../genindex.html" /> |
| <link rel="search" title="Search" href="../../../search.html" /> |
| <link rel="next" title="esp32c3-devkit-rust-1" href="boards/esp32c3-devkit-rust-1/index.html" /> |
| <link rel="prev" title="smartl-c906" href="../c906/boards/smartl-c906/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 current"><a class="current reference internal" href="#">Espressif ESP32-C3 (Legacy)</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="#second-stage-bootloader-and-partition-table">Second stage bootloader and partition table</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#building-and-flashing">Building and flashing</a></li> |
| <li class="toctree-l4"><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-l4"><a class="reference internal" href="#peripheral-support">Peripheral Support</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="#supported-boards">Supported Boards</a><ul> |
| <li class="toctree-l5"><a class="reference internal" href="boards/esp32c3-devkit-rust-1/index.html">esp32c3-devkit-rust-1</a></li> |
| <li class="toctree-l5"><a class="reference internal" href="boards/esp32c3-devkit/index.html">ESP32-C3 DevKit</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="../esp32c3/index.html">Espressif ESP32-C3</a></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="../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="../../../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> |
| </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 (Legacy)</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="../../../_sources/platforms/risc-v/esp32c3-legacy/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"> |
| |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>A new approach is being adopted for this chip and this implementation will be deprecated when the same support level is achieved. |
| For the new approach please check <a class="reference internal" href="../esp32c3/index.html#esp32c3"><span class="std std-ref">here</span></a>.</p> |
| </div> |
| <section id="espressif-esp32-c3-legacy"> |
| <h1>Espressif ESP32-C3 (Legacy)<a class="headerlink" href="#espressif-esp32-c3-legacy" 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/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.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 12.3.0.</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/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.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="second-stage-bootloader-and-partition-table"> |
| <h2>Second stage bootloader and partition table<a class="headerlink" href="#second-stage-bootloader-and-partition-table" title="Permalink to this heading"></a></h2> |
| <p>The NuttX port for now relies on IDF’s second stage bootloader to carry on some hardware |
| initializations. The binaries for the bootloader and the partition table can be found in |
| this repository: <a class="reference external" href="https://github.com/espressif/esp-nuttx-bootloader">https://github.com/espressif/esp-nuttx-bootloader</a> |
| That repository contains a dummy IDF project that’s used to build the bootloader and |
| partition table, these are then presented as Github assets and can be downloaded |
| from: <a class="reference external" href="https://github.com/espressif/esp-nuttx-bootloader/releases">https://github.com/espressif/esp-nuttx-bootloader/releases</a> |
| Download <code class="docutils literal notranslate"><span class="pre">bootloader-esp32c3.bin</span></code> and <code class="docutils literal notranslate"><span class="pre">partition-table-esp32c3.bin</span></code> and place them |
| in a folder, the path to this folder will be used later to program them. This |
| can be: <code class="docutils literal notranslate"><span class="pre">../esp-bins</span></code></p> |
| </section> |
| <section id="building-and-flashing"> |
| <h2>Building and flashing<a class="headerlink" href="#building-and-flashing" title="Permalink to this heading"></a></h2> |
| <p>First make sure that <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code> is installed. This tool is used to convert |
| the ELF to a compatible ESP32 image and to flash the image into the board. |
| 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.dev4</span></code>.</p> |
| <p>Configure the NuttX project: <code class="docutils literal notranslate"><span class="pre">./tools/configure.sh</span> <span class="pre">esp32c3-devkit:nsh</span></code> |
| Run <code class="docutils literal notranslate"><span class="pre">make</span></code> to build the project. Note that the conversion mentioned above is |
| included in the build process. |
| The <code class="docutils literal notranslate"><span class="pre">esptool.py</span></code> command to flash all the binaries is:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>esptool.py --chip esp32c3 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin |
| </pre></div> |
| </div> |
| <p>However, this is also included in the build process and we can build and flash with:</p> |
| <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins |
| </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 and <code class="docutils literal notranslate"><span class="pre">../esp-bins</span></code> is |
| the path to the folder containing the bootloader and the partition table |
| for the ESP32-C3 as explained above. |
| Note that this step is required only one time. Once the bootloader and partition |
| table are flashed, we don’t need to flash them again. So subsequent builds |
| would just require: <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">flash</span> <span class="pre">ESPTOOL_PORT=/dev/ttyUSBXX</span></code></p> |
| </section> |
| <section id="debugging-with-openocd-and-gdb"> |
| <h2>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></h2> |
| <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 -c 'set ESP_RTOS none' -f board/esp32c3-builtin.cfg |
| </pre></div> |
| </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 none' -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="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></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>Bluetooth</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-odd"><td><p>CDC Console</p></td> |
| <td><p>Yes</p></td> |
| <td><p>Rev.3</p></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>eFuse</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>GPIO</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>LED_PWM</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>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>SHA</p></td> |
| <td><p>Yes</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>Timers</p></td> |
| <td><p>Yes</p></td> |
| <td></td> |
| </tr> |
| <tr class="row-even"><td><p>Touch</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>Watchdog</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> |
| </tbody> |
| </table> |
| </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> (a MCUboot utility application to manipulate binary |
| images) and <code class="docutils literal notranslate"><span class="pre">esptool</span></code> (the ESP32-C3 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="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-devkit-rust-1/index.html">esp32c3-devkit-rust-1</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="boards/esp32c3-devkit/index.html">ESP32-C3 DevKit</a></li> |
| </ul> |
| </div> |
| </section> |
| </section> |
| |
| |
| </div> |
| </div> |
| <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> |
| <a href="../c906/boards/smartl-c906/index.html" class="btn btn-neutral float-left" title="smartl-c906" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="boards/esp32c3-devkit-rust-1/index.html" class="btn btn-neutral float-right" title="esp32c3-devkit-rust-1" 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> |
