/mdk

A bare metal SDK for the ESP32 & ESP32C3

Primary LanguageCMIT LicenseMIT

A baremetal, single header ESP32/ESP32C3 SDK

A bare metal, single header make-based SDK for the ESP32/ESP32C3 chips. Written from scratch using datasheets ( ESP32 C3 TRM, ESP32 TRM). It is completely independent from the ESP-IDF and does not use any ESP-IDF tools or files. MDK implements its own flashing utility esputil, which is developed in a separate repo. Esputil is written in C, with no dependencies on python or anything else, working on Mac, Linux, and Windows as a static, singe no-dependencies executable.

A screenshot below demonstrates a examples/ws2812 RGB LED firmware flashed on a ESP32-C3-DevKitM-1 board. It takes < 2 seconds for a full firmware rebuild and flash:

Currently, "esp32c3" and "esp32" architectures are supported. MDK file structure is as follows:

  • $(ARCH)/link.ld - a linker script file. ARCH is esp32 or esp32c3
  • $(ARCH)/boot.c - a startup code
  • $(ARCH)/mdk.h - a single header that implements MDK API
  • $(ARCH)/build.mk - a helper Makefile for building projects

Environment setup

  1. Use Linux or MacOS. Install Docker
  2. Execute the following shell commands (or add them to your ~/.profile):
$ export MDK=/path/to/mdk     # Points to MDK directory
$ export ARCH=esp32c3         # Valid choices: esp32 esp32c3
$ export PORT=/dev/ttyUSB0    # Serial port for flashing

Verify setup by building and flashing a blinky example firmware. From repository root, execute:

$ make -C examples/blinky clean build flash monitor

Firmware Makefile

Firmware Makefile should look like this (see examples/blinky/Makefile):

SOURCES = main.c another_file.c

EXTRA_CFLAGS ?=
EXTRA_LINKFLAGS ?=

include $(MDK)/$(ARCH)/build.mk

Environment reference

  • Environment / Makefile variables:
    • ARCH - Architecture. Possible values: esp32c3, esp32
    • TOOLCHAIN - Crosscompiler prefix. riscv64-unknown-elf or xtensa-esp32-elf
    • PORT - Serial port for flashing. Default: /dev/ttyUSB0
    • FLASH_PARAMS - Flash parameters, see below. Default: empty
    • FLASH_SPI - Flash SPI settings, see below. Default: empty
    • EXTRA_CFLAGS - Extra compiler flags. Default: empty
    • EXTRA_LINKFLAGS - Extra linker flags. Default: empty
  • Makefile targets:
    • make clean - Clean up build artifacts
    • make build - Build firmware in a project directory
    • make flash - Flash firmware. Needs PORT variable set
    • make monitor - Run serial monitor. Needs PORT variable set
  • Board defaults: - overridable by e.g. EXTRA_CFLAGS="-DLED1=3"
    • LED1 - User LED pin. Default: 2
    • BTN1 - User button pin. Default: 9

API reference

Currently, a limited API is implemented. The plan is to implement WiFi/BLE primitives in order to integrate cesanta/mongoose networking library. Unfortunately radio registers are not documented by Espressif - please contact us if you have more information on that.

  • GPIO
    • void gpio_output(int pin); - set pin mode to OUTPUT
    • void gpio_input(int pin); - set pin mode to INPUT
    • void gpio_write(int pin, bool value); - set pin to low (false) or high
    • void gpio_toggle(int pin); - toggle pin value
    • bool gpio_read(int pin); - read pin value
  • SPI
    • struct spi { int miso, mosi, clk, cs; }; - an SPI descriptor
    • bool spi_init(struct spi *spi); - initialise SPI
    • void spi_begin(struct spi *spi, int cs); - start SPI transaction
    • void spi_end(struct spi *spi, int cs); - end SPI transaction
    • uin8_t spi_txn(struct spi *spi, uint8_t); - do SPI transaction: write one byte, read response
  • UART
    • void uart_init(int no, int tx, int rx, int baud); - initialise UART
    • bool uart_read(int no, uint8_t *c); - read byte. Return true on success
    • void uart_write(int no, uint8_t c); - write byte. Block if FIFO is full
  • Misc
    • void wdt_disable(void); - disable watchdog
    • uint64_t uptime_us(void); - return uptime in microseconds
    • void delay_us(unsigned long us); - block for "us" microseconds
    • void delay_ms(unsigned long ms); - block for "ms" milliseconds
    • void spin(unsigned long count); - execute "count" no-op instructions

Toolchain Docker images

By default, docker is used for builds. For ARCH=esp32, the espressif/idf image is used. For ARCH=esp32c3, the mdashnet/riscv image is used, which is built using the following Dockerfile:

FROM alpine:edge
RUN apk add --update build-base gcc-riscv-none-elf newlib-riscv-none-elf && rm -rf /var/cache/apk/*