first commit

README.md

@@ -0,0 +1,78 @@
+# 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
+
+```sh
+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`:
+
+```sh
+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:
+
+```sh
+make compile
+```
+
+Compile and then flash:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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`.