{"id":20169755,"url":"https://github.com/espzav/bsp-template-m5","last_synced_at":"2026-05-10T01:18:35.106Z","repository":{"id":166449871,"uuid":"629877299","full_name":"espzav/BSP-template-M5","owner":"espzav","description":"Espressif's BSP template for M5Stack Core 2 (Hackhathon)","archived":false,"fork":false,"pushed_at":"2023-12-13T10:12:38.000Z","size":98,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-13T15:24:46.839Z","etag":null,"topics":["esp-bsp","esp32"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/espzav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-19T07:55:11.000Z","updated_at":"2024-07-09T21:34:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"9bfa41ef-0417-4938-a596-e7f48a5ea84d","html_url":"https://github.com/espzav/BSP-template-M5","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espzav%2FBSP-template-M5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espzav%2FBSP-template-M5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espzav%2FBSP-template-M5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espzav%2FBSP-template-M5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/espzav","download_url":"https://codeload.github.com/espzav/BSP-template-M5/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241605820,"owners_count":19989612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp-bsp","esp32"],"created_at":"2024-11-14T01:13:39.432Z","updated_at":"2025-12-01T07:05:06.341Z","avatar_url":"https://github.com/espzav.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP BSP template M5Stack\n\nThis repository is a template for making ESP-BSP packages. It contains example for each part of BSP and one complex example for use all BSP parts.\n\n## Example of implementation some components in BSPs\n\n* I2C (esp-box)\n* SPI LCD (esp-box)\n* RGB LCD (esp32_s3_lcd_ev_board)\n* I2C LCD Touch (esp-box)\n* SPIFFS (esp-box)\n* SD Card (esp32_s3_korvo_2)\n* Buttons (esp32_s3_korvo_2, esp-box-lite)\n* LEDs (esp32_s3_korvo_2)\n* Audio (esp-box, esp-box-lite)\n* Camera (esp32_s3_korvo_2)\n* Battery (esp32_s3_korvo_2)\n* USB (esp32_s3_usb_otg)\n\n# Step-by-step guide\n\n|BSP API: | [I2C](#i2c) | [LCD display](#lcd_display) | [LCD Touch](#lcd_touch) | [SPIFFS](#spiffs) | [SD Card](#sd_card) | [Buttons](#buttons) | [LEDs](#leds) | [Audio](#audio) | [Camera](#camera) | [Battery](#battery) | [USB](#usb) |\n| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n\n## 1. Create folder\n\nCreate folder with name of the board in the root of [ESP-BSP](https://github.com/espressif/esp-bsp) repository.\n\n## 2. Copy template folder\n\nCopy all files and folders from template into new folder.\n\n## 3. Update file idf_component.yml\n\nEdit file `idf_component.yml` in BSP folder:\n* Put version to 1.0.0 (or lower for beta version)\n* Edit description, url, target and dependencies\n\n## 4. Update Kconfig\n\nEdit file `Kconfig` with settings some components. You can copy some settings from another BSPs.\n\n## 4. Update Readme file\n\nEdit file `README.md` in BSP folder:\n* Edit header\n* Put link to HW reference or another page about the board\n* Put image of the board\n* Write short description about the board and the features of this board\n\n## 5. Rename files\n\nRename main *.c file and header file of this BSP. \n* Rename `m5stack-core2.c` and `include\\bsp\\m5stack-core2.h`\n* Update `include\\bsp\\esp-bsp.h` with renamed header file\n* Update `CMakeLists.txt` \n\n\u003ca id=\"i2c\"\u003e\u003c/a\u003e\n## 6. I2C (mandatory)\n\nUpdate constants defined in BSP header - settings:\n* `BSP_I2C_NUM` (value: `0`/`1` - depends on ESP chip)\n\nUpdate constants defined in BSP header - I2C pins:\n* `BSP_I2C_SCL` (value: `GPIO_NUM_x`)\n* `BSP_I2C_SDA` (value: `GPIO_NUM_x`) \n\nFunctions, which **must** be defined in BSP `*.c` file:\n* `esp_err_t bsp_i2c_init(void);`\n* `esp_err_t bsp_i2c_deinit(void);`\n\n**Note:** When I2C is needed in some component, it should be initialized inside the component (call `bsp_i2c_init`). The function `bsp_i2c_init` should initialize I2C only once.\n\n\u003ca id=\"lcd_display\"\u003e\u003c/a\u003e\n## 7. Display (mandatory)\n\nDisplay functions are divided into two parts. The first part is only HW initialization (`include\\bsp\\display.h`) and second part is initialization of the LVG (BSP header). \n\nUpdate display constants defined in `display.h`:\n* `BSP_LCD_COLOR_FORMAT`    (values: `ESP_LCD_COLOR_FORMAT_RGB565`/`ESP_LCD_COLOR_FORMAT_RGB888`)\n* `BSP_LCD_BIGENDIAN`       (values: `0`/`1`)\n* `BSP_LCD_BITS_PER_PIXEL`  (values: `16`/`18`)\n* `BSP_LCD_COLOR_SPACE`     (values: `ESP_LCD_COLOR_SPACE_RGB`/`ESP_LCD_COLOR_SPACE_BGR`)\n\nUpdate display constants defined in BSP header - pins:\n* `BSP_LCD_DATA0`       (value: `GPIO_NUM_x`)\n* `BSP_LCD_PCLK`        (value: `GPIO_NUM_x`) \n* `BSP_LCD_CS`          (value: `GPIO_NUM_x`)\n* `BSP_LCD_DC`          (value: `GPIO_NUM_x`)\n* `BSP_LCD_RST`         (value: `GPIO_NUM_x`)\n* `BSP_LCD_BACKLIGHT`   (value: `GPIO_NUM_x`)\n\nUpdate display constants defined in BSP header - settings:\n* `BSP_LCD_H_RES`               (value: integer)\n* `BSP_LCD_V_RES`               (value: integer)\n* `BSP_LCD_PIXEL_CLOCK_HZ`      (value: integer)\n* `BSP_LCD_SPI_NUM`             (value: `0`/`1` - depends on ESP chip)\n* `BSP_LCD_DRAW_BUFF_SIZE`      (value `BSP_LCD_H_RES * x`)\n* `BSP_LCD_DRAW_BUFF_DOUBLE`    (value: `0`/`1`)\n\nFunctions, which **must** be defined in BSP `*.c` file:\n* `esp_err_t bsp_display_new(const bsp_display_config_t *config, esp_lcd_panel_handle_t *ret_panel, esp_lcd_panel_io_handle_t *ret_io);`\n* `lv_disp_t *bsp_display_start(void);`\n* `bool bsp_display_lock(uint32_t timeout_ms);`\n* `void bsp_display_unlock(void);`\n* `esp_err_t bsp_display_brightness_set(int brightness_percent);`\n* `esp_err_t bsp_display_backlight_on(void);`\n* `esp_err_t bsp_display_backlight_off(void);`\n* `void bsp_display_rotate(lv_disp_t *disp, lv_disp_rot_t rotation);`\n\n\u003ca id=\"lcd_touch\"\u003e\u003c/a\u003e\n## 8. LCD Touch (mandatory)\n\nLCD touch functions are divided into two parts. The first part is only HW initialization (`include\\bsp\\touch.h`) and second part is initialization of the LVG (BSP header).\n\nFunctions, which **must** be defined in BSP `*.c` file:\n* `esp_err_t bsp_touch_new(const bsp_touch_config_t *config, esp_lcd_touch_handle_t *ret_touch);`\n* `lv_indev_t *bsp_display_get_input_dev(void);`\n\n\u003ca id=\"spiffs\"\u003e\u003c/a\u003e\n## 9. SPI Flash File System (mandatory)\n\nThe SPIFFS is supported by all ESP chips internally. These functions are same for all BSPs.\n\nUpdate SPIFFS constants defined in BSP header - settings:\n* `BSP_MOUNT_POINT` (value: string)\n\nFunctions, which **must** be defined in BSP `*.c` file:\n* `esp_err_t bsp_spiffs_mount(void);`\n* `esp_err_t bsp_spiffs_unmount(void);`\n\n\u003ca id=\"sd_card\"\u003e\u003c/a\u003e\n## 10. SD Card (optional)\n\nUpdate SD card constants defined in BSP header - pins:\n* `BSP_SD_CLK` (value: `GPIO_NUM_x`)\n* `BSP_SD_CMD` (value: `GPIO_NUM_x`) \n* `BSP_SD_D0`  (value: `GPIO_NUM_x`) \n\nUpdate SD card constants defined in BSP header - settings:\n* `BSP_MOUNT_POINT` (value: string)\n\nFunctions, which **should** be defined in BSP `*.c` file:\n* `esp_err_t bsp_sdcard_mount(void);`\n* `esp_err_t bsp_sdcard_unmount(void);`\n\nand put the SD card handler into BSP header file as extern:\n```c\nextern sdmmc_card_t *bsp_sdcard;\n```\n\n\u003ca id=\"buttons\"\u003e\u003c/a\u003e\n## 11. Buttons (optional)\n\nButtons can be connected as GPIO pins, inside [button component](https://components.espressif.com/components/espressif/button), from LCD touch or IO expander. Recommended solution is using the button component for all buttons (GPIO, ADC, etc...). \n\nAdd buttons enum into BSP header:\n```c\ntypedef enum {\n    BSP_BUTTON_MAIN = 0,\n    BSP_BUTTON_xxx,\n    ...\n    BSP_BUTTON_NUM\n} bsp_button_t;\n```\n\nIf component buttons is used, create configuration structure in BSP *.c file:\n```c\nconst button_config_t bsp_button_config[BSP_BUTTON_NUM] = {\n    {\n        .type = BUTTON_TYPE_ADC,\n        .adc_button_config.adc_channel = ADC_CHANNEL_4, // ADC1 channel 4 is GPIO5\n        .adc_button_config.button_index = BSP_BUTTON_MAIN,\n        .adc_button_config.min = 2310, // middle is 2410mV\n        .adc_button_config.max = 2510\n    },\n    ...\n};\n```\n\nand put the configuration into BSP header file as extern:\n```c\nextern const button_config_t bsp_button_config[BSP_BUTTON_NUM];\n```\n\nFunctions, which **should** be defined in BSP `*.c` file (when not used button component):\n* `esp_err_t bsp_button_init(const bsp_button_t btn);`\n* `bool bsp_button_get(const bsp_button_t btn);`\n\n\u003ca id=\"leds\"\u003e\u003c/a\u003e\n## 12. LEDs (optional)\n\nLeds are usually controlled as GPIO or it can be controlled by IO expander.\n\nAdd LEDs enum into BSP header:\n```c\ntypedef enum bsp_led_t {\n    BSP_LED_BLUE,\n    BSP_LED_RED,\n} bsp_led_t;\n```\n\nFunctions, which **should** be defined in BSP `*.c` file:\n* `esp_err_t bsp_leds_init(void);`\n* `esp_err_t bsp_led_set(const bsp_led_t led_io, const bool on);`\n\n\u003ca id=\"audio\"\u003e\u003c/a\u003e\n## 13. Audio (optional)\n\nBSP audio functions are divided into two parts. The first part is initialization of the I2S (and I2C) for communication with codec chips and second part is initialization of the codec chips (for speaker and for microphone). For codec chips is usually used `esp_codec_dev` component. \n\nUpdate audio (I2S) constants defined in BSP header - pins:\n* `BSP_I2S_SCLK` (value: `GPIO_NUM_x`)\n* `BSP_I2S_MCLK` (value: `GPIO_NUM_x`) \n* `BSP_I2S_LCLK` (value: `GPIO_NUM_x`) \n* `BSP_I2S_DOUT` (value: `GPIO_NUM_x`) \n* `BSP_I2S_DSIN` (value: `GPIO_NUM_x`) \n* `BSP_POWER_AMP_IO`  (value: `GPIO_NUM_x`) \n\nUpdate audio configuration constants defined in BSP header - settings:\n```c\n#define BSP_I2S_GPIO_CFG       \\\n    {                          \\\n        .mclk = BSP_I2S_MCLK,  \\\n        .bclk = BSP_I2S_SCLK,  \\\n        .ws = BSP_I2S_LCLK,    \\\n        .dout = BSP_I2S_DOUT,  \\\n        .din = BSP_I2S_DSIN,   \\\n        .invert_flags = {      \\\n            .mclk_inv = false, \\\n            .bclk_inv = false, \\\n            .ws_inv = false,   \\\n        },                     \\\n    }\n\n#define BSP_I2S_DUPLEX_MONO_CFG(_sample_rate)                                                         \\\n{                                                                                                 \\\n    .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(_sample_rate),                                          \\\n    .slot_cfg = I2S_STD_PHILIP_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_MONO), \\\n    .gpio_cfg = BSP_I2S_GPIO_CFG,                                                                 \\\n}\n```\n\nFunctions, which **should** be defined in BSP `*.c` file:\n* `esp_err_t bsp_audio_init(const i2s_std_config_t *i2s_config, i2s_chan_handle_t *tx_channel, i2s_chan_handle_t *rx_channel);`\n* `esp_err_t bsp_audio_poweramp_enable(const bool enable);`\n* `esp_codec_dev_handle_t bsp_audio_codec_speaker_init(void)`\n* `esp_codec_dev_handle_t bsp_audio_codec_microphone_init(void);`\n\n\u003ca id=\"camera\"\u003e\u003c/a\u003e\n## 14. Camera (optional)\n\nUpdate camera constants defined in BSP header - pins:\n* `BSP_CAMERA_XCLK` (value: `GPIO_NUM_x`)\n* `BSP_CAMERA_PCLK` (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_VSYNC`(value: `GPIO_NUM_x`) \n* `BSP_CAMERA_HSYNC`(value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D0`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D1`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D2`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D3`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D4`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D5`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D6`   (value: `GPIO_NUM_x`) \n* `BSP_CAMERA_D7`   (value: `GPIO_NUM_x`) \n\nUpdate camera configuration constants defined in BSP header - settings:\n```c\n#define BSP_CAMERA_DEFAULT_CONFIG         \\\n    {                                     \\\n        .pin_pwdn = GPIO_NUM_NC,          \\\n        .pin_reset = GPIO_NUM_NC,         \\\n        .pin_xclk = BSP_CAMERA_XCLK,      \\\n        .pin_sccb_sda = GPIO_NUM_NC,      \\\n        .pin_sccb_scl = GPIO_NUM_NC,      \\\n        .pin_d7 = BSP_CAMERA_D7,          \\\n        .pin_d6 = BSP_CAMERA_D6,          \\\n        .pin_d5 = BSP_CAMERA_D5,          \\\n        .pin_d4 = BSP_CAMERA_D4,          \\\n        .pin_d3 = BSP_CAMERA_D3,          \\\n        .pin_d2 = BSP_CAMERA_D2,          \\\n        .pin_d1 = BSP_CAMERA_D1,          \\\n        .pin_d0 = BSP_CAMERA_D0,          \\\n        .pin_vsync = BSP_CAMERA_VSYNC,    \\\n        .pin_href = BSP_CAMERA_HSYNC,     \\\n        .pin_pclk = BSP_CAMERA_PCLK,      \\\n        .xclk_freq_hz = 16000000,         \\\n        .ledc_timer = LEDC_TIMER_0,       \\\n        .ledc_channel = LEDC_CHANNEL_0,   \\\n        .pixel_format = PIXFORMAT_RGB565, \\\n        .frame_size = FRAMESIZE_240X240,  \\\n        .jpeg_quality = 12,               \\\n        .fb_count = 2,                    \\\n        .fb_location = CAMERA_FB_IN_PSRAM,\\\n        .sccb_i2c_port = BSP_I2C_NUM,     \\\n    }\n```\n\n\u003ca id=\"battery\"\u003e\u003c/a\u003e\n## 15. Battery (optional)\n\nWhen the board is using ADC for measuring voltage of the batery, there should be added API inside BSP.\n\nUpdate constants defined in BSP header:\n* `BSP_BATTERY_VOLTAGE`     (value: `GPIO_NUM_x`)\n* `BSP_BATTERY_VOLTAGE_DIV` (value: integer)\n\nFunctions, which **should** be defined in BSP `*.c` file:\n* `esp_err_t bsp_voltage_init(void);`\n* `int bsp_voltage_battery_get(void);`\n\n\u003ca id=\"usb\"\u003e\u003c/a\u003e\n## 16. USB\n\nIf the board support USB connectiion, there should be defined USB pins.\n\nUpdate USB constants defined in BSP header - USB pins:\n* `BSP_USB_POS` (value: `USBPHY_DP_NUM`)\n* `BSP_USB_NEG` (value: `USBPHY_DM_NUM`) \n\n## SquareLine Template\n\nAfter the BSP is done, it should be added into SquareLine tepmplates in folder `esp-bsp\\SquareLine`. Follow [this](https://github.com/espressif/esp-bsp/blob/master/SquareLine/README.md) guide for add BSP into SquareLine as a template.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fespzav%2Fbsp-template-m5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fespzav%2Fbsp-template-m5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fespzav%2Fbsp-template-m5/lists"}