waveshare-esp32-s3-zero-keyboard/README.md

USB Keyboard with the Waveshare ESP32-S3-Zero

The keyboard.ino sketch registers the ESP32-S3-Zero as a USB HID keyboard. After an initial delay of two seconds, it types Hello Creat0r once every second. The keystrokes go to the currently focused window; open an empty text editor window to try it out.

Prerequisites

• arduino-cli and esptool available on your PATH
• Espressif's esp32:esp32 Arduino board package
• GNU Make for the Makefile commands
• A USB data cable and access to the board's serial port

The local development environment has Arduino CLI 1.5.1, the esp32:esp32 board package 3.3.12, and esptool 5.3.1 installed. The sketch uses the USB libraries included in the ESP32 board package; no additional Arduino libraries are required.

Run all commands below from the keyboard project directory.

Compile Manually

arduino-cli compile --fqbn "esp32:esp32:esp32s3:USBMode=default,CDCOnBoot=default,FlashSize=4M,PartitionScheme=default" --output-dir build .

The board configuration targets the ESP32-S3 with 4 MB of flash and the USB and partition settings shown above. Output files are saved in build/. The merged flash image build/keyboard.ino.merged.bin is used for flashing.

Flash Manually

Connect the board via USB and specify the appropriate port. The port used previously was /dev/ttyACM1:

esptool --chip esp32s3 --port /dev/ttyACM1 --baud 460800 write-flash 0x0 build/keyboard.ino.merged.bin

The merged image is written starting at address 0x0. If your device has a different name, adjust the value after --port.

Compile and Flash with Make

Compile only:

make compile

Compile and then flash:

make flash

Running make without a target is equivalent to make compile. The flash target runs compile first and only flashes if compilation succeeds.

You can override the port and baud rate when running Make:

make flash PORT=/dev/ttyACM0 BAUD=460800

The default values match the manual commands. You can also customize ARDUINO_CLI, ESPTOOL, FQBN, and BUILD_DIR using Make variables, for example: make compile BUILD_DIR=build-test.

Delete generated binaries and other build files:

make clean

This removes the entire build/ output directory. If you used a custom directory, specify the same value: make clean BUILD_DIR=build-test.