Docs

Getting Started

Most users can start with a release image. You do not need Git, Docker, or a compiler.

What you need

A Raspberry Pi 4.
A microSD card and a way to connect it to your computer.
A Raspberry Pi Codec Zero audio board.
A Raspberry Pi Touch Display 2.
The Ardor guitar input buffer board.
Guitar and audio cables, plus an amp or audio interface.
Four momentary footswitches and one rotary encoder for a full pedal build.

Read the Hardware guide before you wire the pedal. If you only want to try the software, start with the release image and connect the display, guitar, and audio output.

Prepare the guitar input

The Codec Zero needs a buffered guitar signal. Ardor includes a small input buffer in the buffer project. The project includes the KiCad schematic and PCB. Use the buffer between the guitar jack and the Codec Zero input.

Do not connect a passive guitar pickup directly to the Codec Zero. Connect the guitar to the buffer first, then connect the buffer output to the Codec Zero.

You can order a ready-built board from JLCPCB. The JLCPCB assembly service can use the order-ready files in the buffer production folder:

GERBER-buffer.zip: the PCB files.
BOM-buffer.csv: the parts list.
CPL-buffer.csv: the part placement list.

Start a PCB assembly order on JLCPCB.
Upload GERBER-buffer.zip for the PCB.
Upload the BOM and CPL files when JLCPCB asks for assembly files.
Choose SMD assembly and review the parts and placement.
Order the board after you check the connector and power requirements.

The production files cover the SMD parts. They do not include the guitar jack, output wiring, power wiring, or enclosure parts. Add wires or connectors to the labeled board points after the board arrives. Follow the schematic for the connections.

1. Download a ready-made image

Open the latest Ardor release on GitHub. Download these two files:

ardor-pedal-<version>.img.gz: the compressed disk image.
ardor-pedal-<version>.img.gz.sha256: the checksum for the image.

You do not need to open or edit the image. You will write it to the whole microSD card.

Writing an image erases the complete microSD card. Copy any important files from the card before you continue. Check the selected drive one more time before you click the Write button.

2. Unpack the image

The .gz ending means that the file is compressed. Unpack it before you use Raspberry Pi Imager.

Computer	Action
macOS	Double-click the `.img.gz` file in Finder. Finder creates an `.img` file.
Windows	Install 7-Zip. Right-click the file, choose 7-Zip, then choose Extract Here.
Linux	Double-click the file in your archive application and choose Extract.

3. Write the image to the card

Raspberry Pi Imager is the recommended tool. It works on macOS, Windows, and Linux.

Install and open Raspberry Pi Imager.
Choose Raspberry Pi, then choose Use custom.
Select the unpacked .img file.
Choose Storage, then select the microSD card.
Choose Next, then confirm that you want to erase the card.
Wait for Imager to write and verify the card.
Eject the card from your computer.

Remove other USB drives before you choose storage. Use the card size to identify the correct drive.

macOS: Open Imager from Applications. Allow access to removable storage if macOS asks.
Windows: Accept the administrator prompt. Close File Explorer windows that show the card.
Linux: Allow access to the removable drive if your desktop asks. Do not select your system drive.

You can also use balenaEtcher. Choose the unpacked image, choose the microSD card, and start the flash process.

4. Start the pedal

Insert the card into the Raspberry Pi.
Connect the Touch Display 2.
Connect your guitar to the mono input.
Connect the stereo output to an amp or audio interface.
Connect Ethernet for the first setup, then power on the pedal.

The pedal opens on the preset screen. Use the screen or a footswitch to choose a sound. Turn the encoder to set the master volume.

The release image does not contain Wi-Fi details. Use Ethernet for the first network setup. You can add Wi-Fi from the manager after the pedal starts.

5. Open the manager

The manager runs on the pedal. You do not need to install a desktop application. Find the pedal IP address in your router, then open this address in a browser:

http://<pedal-ip>:8080

If your network supports local device names, you can also try http://ardor-XXXXXXXX.local:8080. The display shows a one-time setup code. Enter the code in the browser and create a local username and password.

In the manager, open Settings, choose Wi-Fi, and save your network details. The pedal can disconnect while it reconnects to Wi-Fi. After the connection returns, you can remove Ethernet.

See Manager App to learn how to edit presets and add your own amp models and cabinet sounds.

Next steps

Learn the screen in UI & Controls. Then follow the signal in Signal Chain & Routing.

Advanced: check the download

The release includes a checksum file. Calculate the checksum for the downloaded .img.gz file and compare the result with the value in the .sha256 file.

macOS:   shasum -a 256 ardor-pedal-<version>.img.gz
Linux:   sha256sum ardor-pedal-<version>.img.gz
Windows: Get-FileHash .\ardor-pedal-<version>.img.gz -Algorithm SHA256

Advanced: flash from a command line

A command-line flash can erase the wrong drive. Use the graphical method above if you are not familiar with disk names. Replace every example value in angle brackets.

macOS

gzip -dk ardor-pedal-<version>.img.gz
diskutil list
diskutil unmountDisk /dev/diskN
sudo dd if=ardor-pedal-<version>.img of=/dev/rdiskN bs=4m
sync
diskutil eject /dev/diskN

Use the whole disk, such as /dev/diskN. Do not use a partition such as /dev/diskNs1.

Linux

gzip -dk ardor-pedal-<version>.img.gz
lsblk
sudo umount /dev/sdX1
sudo dd if=ardor-pedal-<version>.img of=/dev/sdX bs=4M status=progress conv=fsync
sync

Use the whole card, such as /dev/sdX. Do not use a partition such as /dev/sdX1.

Windows PowerShell

Raspberry Pi Imager also provides a command-line mode. The destination is the whole physical drive. Replace PhysicalDriveN with the number for your card.

rpi-imager.exe --cli --sha256 EXPECTED_SHA256 ardor-pedal-<version>.img.gz \\.\PhysicalDriveN

Check the drive number in Disk Management before you run the command. The graphical tool is safer if you are not sure.

Advanced: build Ardor from source

Most users do not need this. Use a release image unless you plan to change Ardor or help develop it. The source build needs Git, Docker, and build tools.

./scripts/build-image.sh

The script creates sdcard.img. You can write that file to a microSD card with the same tools described above.

Advanced: run the desktop simulator

Use the simulator if you want to explore the interface without a Raspberry Pi. This is a developer tool and needs a source checkout, CMake, and a C++ compiler.

cmake -S . -B build-sdl -DARDOR_UI_BACKEND=sdl -DCMAKE_BUILD_TYPE=Release
cmake --build build-sdl --target pedal-ui-sim -j
./build-sdl/pedal-ui-sim --data-root . --bank 0