Your first firmware build

Your first custom instrument

This guide follows the public Fingersonic Guitar DevKit. Start with a known example, then change one thing at a time.

1. Get the kit

git clone https://github.com/lastness09/fingersonic-guitar-devkit.git
cd fingersonic-guitar-devkit

Keep the full repository together. It includes hardware documentation, public API examples, compilation partitions, a buildable reference, and recovery resources.

2. Set up Arduino CLI

Install Arduino CLI from the official Arduino instructions, then install the documented baseline:

arduino-cli core update-index --additional-urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core install esp32:esp32@3.3.2 --additional-urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli lib install "Adafruit MPR121@1.1.3" "Adafruit BusIO@1.17.4" "Adafruit GFX Library@1.12.6" "Adafruit ST7735 and ST7789 Library@1.11.0"

The initial board baseline is ESP32S3 Dev Module, CPU 240 MHz, Flash 16 MB, OPI PSRAM, and the supplied custom partitions.csv. Read the dependencies guide before changing versions.

3. Build the FM Studio reference

FM Studio main2 is a developer reference application with FM synthesis and a five-track groovebox. It is not official product firmware or an official recovery image.

cd examples/main2
arduino-cli compile --fqbn 'esp32:esp32:esp32s3:USBMode=default,CDCOnBoot=cdc,CPUFreq=240,FlashMode=qio,FlashSize=16M,PartitionScheme=custom,DebugLevel=none,PSRAM=opi,LoopCore=1,EventsCore=1' --build-path './build' .

On Windows PowerShell, the included ./build.ps1 performs the documented build and checks the application size. The application file is build/main2.ino.bin. It must be no larger than 2,097,152 bytes. Do not upload merged firmware, bootloader, partition, or App1 images.

See the complete FM Studio instructions for controls, architecture, and optional host tests.

4. Upload through the existing App1

Prepare the build and official recovery instructions while you still have Internet access. Charge your device before updating.

From a running FM Studio build, use SETTINGS → UPLOADER and confirm.
For recovery, disconnect charging and hold the encoder during a true cold start, as described in the recovery guide.
Join the device's Fingersonic Wi-Fi hotspot; the documented password is 88888888.
Use the FingersonicUploader guide or the documented HTTP interface:

curl --fail -F 'file=@./build/main2.ino.bin' http://192.168.4.1/upload

Wait for completion and restart. Keep the device powered throughout the upload. The local HTTP address above is the instrument's own Wi-Fi interface.

5. Make one change, then test

Read the hardware guide. Test inputs, power, audio, display, and recovery before adding more complex behavior. App0 can redefine controls and sound generation. Preserve the manufacturer-managed App1, bootloader, partition table, and system areas.

Complete the release checklist, then submit your firmware. Include the actual hardware target, toolchain, license, controls, installation and recovery instructions, known limitations, and the compiled App0 BIN. A GitHub source link is welcome; publishing your own source is optional.

Your release stays private until an administrator approves it. After publication, users can download the file, verify its SHA-256, share the page, and discuss the build with you.