draft: Contributing to ESP-BSP #42
Conversation
There was a problem hiding this comment.
@georgik The article looks great! I left just a couple of suggestions.
One overall observation:
I see that this guide shows how to create a new BSP for a custom board. What seem to be missing is the final result of this exercise to make the example more relatable.
Should this guide also refer to an already implemented BSP as another example?
|
|
||
| ## Introduction | ||
|
|
||
| The ESP Board Support Package (ESP-BSP) is a powerful tool that simplifies the development of applications for various ESP32-based boards. If you're interested in creating and publishing a new BSP for a third-party board, this guide will walk you through the process, from setting up your development environment to submitting your BSP to the ESP Component Registry. For this guide, we'll use the ESP32-C3-DevKit-RUST-1 as our example board. |
There was a problem hiding this comment.
What is meant by a third-party board: a development board with an Espressfi SoC or module on it?
Suggest clarifying it here.
|
|
||
| Before you start, ensure you have the following: | ||
|
|
||
| - **ESP-IDF**: The official development framework for the ESP32, properly installed and sourced in your shell. |
There was a problem hiding this comment.
| - **ESP-IDF**: The official development framework for the ESP32, properly installed and sourced in your shell. | |
| - **ESP-IDF**: The official development framework for Espressif SoCs, properly installed and sourced in your shell. |
There was a problem hiding this comment.
This is kind of interesting question about the terminology. Community is using "ESP32", which kind of similar when people are using word google, to search for something. Espressif SoCs is quite impractical, yet I understand that it's "correct".
Also in case of search we will have more hits with ESP32, thatn Espressif SoC.
What about rephrashing this thing to framework for Espressif SoC (ESP32, ESP32-C3, ESP32-P4...)
|
|
||
| ## Developing a New BSP | ||
|
|
||
| In the following text we will describe a process how to create a new BSP for ESP32-C3-DevKit-RUST-1. |
There was a problem hiding this comment.
Suggest adding a link to the board name. Not sure if it is a correct link provided below, but this is the only one I found. The formatting on this linked page is off.
| In the following text we will describe a process how to create a new BSP for ESP32-C3-DevKit-RUST-1. | |
| In the following steps, we will describe a process how to create a new BSP for [ESP32-C3-DevKit-RUST-1](https://www.espressif.com/en/dev-board/esp32-c3-devkit-rust-1-en). |
| idf.py create-component esp32_c3_devkit_rust_1 | ||
| cd components/esp32_c3_devkit_rust_1 | ||
| ``` | ||
|
|
|
|
||
| Follow the conventions described in the [BSP development guide](https://github.com/espressif/esp-bsp/blob/master/BSP_development_guide.md). Ensure your BSP includes the following: | ||
|
|
||
| - **Public API Header**: Include a header file with the public API, e.g., `bsp/esp32_c3_devkit_rust_1.h`. |
There was a problem hiding this comment.
In the espressif / esp-bsp repo, I don't see .h files in the root of boards folders, for example bsp/esp-box-3.
Should we update the example path to the actual location of header files in the bsp directory?
| Follow the conventions described in the [BSP development guide](https://github.com/espressif/esp-bsp/blob/master/BSP_development_guide.md). Ensure your BSP includes the following: | ||
|
|
||
| - **Public API Header**: Include a header file with the public API, e.g., `bsp/esp32_c3_devkit_rust_1.h`. | ||
| - **Capabilities Macro**: Define the board's capabilities in the header file, similar to `SOC_CAPS_*` macros. |
There was a problem hiding this comment.
The guidelines in espressif / esp-bsp make it more clear what SOC_CAPS_* is.
The boards capabilities must be listed in its header file, similarly to SOC_CAPS_* macro used in esp-idf.
Suggest making it more clear what SOC_CAPS_* macros are here as well.
|
|
||
| - **Public API Header**: Include a header file with the public API, e.g., `bsp/esp32_c3_devkit_rust_1.h`. | ||
| - **Capabilities Macro**: Define the board's capabilities in the header file, similar to `SOC_CAPS_*` macros. | ||
| - **Initialization Functions**: Implement initialization functions for I2C, display, touch, etc. |
There was a problem hiding this comment.
With these three separate bullet points, it reads like there should be more than one header file created.
Is it correct that both Capabilities Macro and Initialization Functions should be added to the header file with the public API mentioned in the first bullet point?
If yes, suggest mentioning this header file in the introductory sentence to the bullet list and then list out Capabilities Macro and Initialization Functions as bullet points.
| #define BSP_CAPS_AUDIO_SPEAKER 0 | ||
| #define BSP_CAPS_AUDIO_MIC 0 | ||
| #define BSP_CAPS_SDCARD 0 | ||
| #define BSP_CAPS_IMU 1 |
There was a problem hiding this comment.
It might be good not to separate bullet points from the examples. Is it worth providing the examples of Capabilities Macros and initialization functions right after their respective bullet points?
|
The name |
The article explains how to contribute to ESP-BSP.