Vhorde Developer Documentation

Welcome to the official documentation for Vhorde silicon and software. This guide covers everything needed to get a Vhorde board running, from flashing your first image to writing and deploying code, using either our native tooling or standard third-party tools you may already have installed.

1. Getting the OS Images

Before flashing anything, you need a Vhorde OS image file (.img or .iso, depending on board series).

Where to download

All official images are hosted at downloads.vhorde.com/images. Each release includes:

• The image file (compressed as .img.xz or .iso.gz)
• A SHA256SUMS file for verifying integrity
• Release notes covering kernel version, changes, and known issues

Verifying your download

Always verify the checksum before flashing. A corrupted image is one of the most common causes of a board that won't boot.

If the values don't match, re-download the image rather than attempting to flash it.

2. Flashing the Image

There are three supported ways to get an image onto your SD card or eMMC module. Use whichever fits your workflow; the CLI is a convenience layer, not a requirement.

Option A: vhorde-cli (recommended)

vhorde-cli handles decompression, checksum verification, and safe unmounting automatically. Run vhorde list-disks first to confirm the correct target device. Flashing to the wrong disk will overwrite it without warning.

Option B: Manual flashing with dd (Linux/macOS)

If you prefer not to install the CLI, you can flash any downloaded image directly:

Double-check the target device with diskutil list or lsblk before running dd. Writing to the wrong device can erase your host machine's own drive.

Option C: Third-party flashing tools

For a graphical alternative, any standard SD card flashing tool that accepts raw .img files will work with Vhorde images:

• Balena Etcher — cross-platform, drag-and-drop, built-in verification
• Raspberry Pi Imager — supports adding custom images via "Use Custom"
• Win32 Disk Imager — Windows only

Steps are the same across tools: select the downloaded .img file, select your target disk, and flash. No CLI installation needed.

3. OS Variations

Choose the image that matches your board series and use case. Each is tuned at the kernel level for our specific silicon architecture:

Not sure which board you have? Check the silkscreen label on the board itself, or run vhorde identify if you already have a working image booted.

4. First Boot

After flashing, insert the card into your board and power on. First boot typically takes 60-90 seconds longer than subsequent boots while the filesystem expands to fill the storage medium.

• Headless setup (vhorde-core): Connect via serial console (115200 baud) or SSH once the board obtains an IP address on your network. To enable SSH before first boot, place an empty file named ssh in the boot partition of the flashed card.
• Desktop setup (vhorde-xfce / vhorde-kde): Connect a display, keyboard, and mouse directly. The setup wizard will walk you through Wi-Fi, locale, and account configuration.

5. Development Environments

Vhorde IDE

Our native IDE, built specifically for Vhorde silicon. Includes integrated hardware debugging, an optimized C/C++ toolchain, and direct board flashing over USB.

Download IDE ↓
Supported platforms: macOS, Windows, Linux (x86_64 and ARM64)

Arduino IDE (via Vhorde Board Manager)

If you already work in the Arduino ecosystem, you can compile and flash directly from the standard Arduino IDE.

• Open Arduino IDE → Preferences
• Add the following URL to Additional Board Manager URLs: View JSON URL ↗
• Open Tools → Board → Boards Manager, search "Vhorde," and install
• Select your specific board under Tools → Board → Vhorde Boards

Command-line toolchain (no IDE)

For users who prefer building outside a GUI entirely, the Vhorde toolchain is also available as standalone compiler and flashing binaries via vhorde-cli:

6. GPIO & Pinout Reference

Vhorde boards use the standard Raspberry Pi 40-pin GPIO header layout, so existing Pi HATs, breakout boards, and GPIO libraries are compatible out of the box.

• Nano series (1GB / 2GB) — pin-compatible with Raspberry Pi Zero 2 W
• Titan and Nova series — pin-compatible with Raspberry Pi 5

If you've built for either of those boards before, your existing wiring, HATs, and pin references carry over directly.

40-Pin Header Layout (all series)

General Notes

• Logic level: 3.3V on all GPIO pins, consistent with the Pi Zero 2 W and Pi 5. Do not drive pins with 5V logic.
• I2C: pins 3 and 5 (GPIO2/GPIO3)
• SPI: pins 19, 21, 23, 24, 26
• UART: pins 8 and 10
• Hardware PWM: GPIO12, GPIO13, GPIO18, GPIO19

7. Troubleshooting

Board doesn't boot / no display output

• Re-verify the image checksum, re-flash if it doesn't match
• Confirm the image matches your exact board series (Nano/Titan/Nova images are not interchangeable)
• Try a different SD card, some cards are incompatible with the bootloader

Board boots but no network

• For vhorde-core, confirm the ssh file was placed correctly in the boot partition before first boot
• Check vhorde-xfce/vhorde-kde Wi-Fi settings via the desktop network manager

Flashing fails partway through

• Confirm you're not flashing to a mounted or in-use disk
• Try a lower baud/write speed with dd (bs=1m instead of bs=4m)

8. Where to Get Help

• GitHub Issues: for confirmed bugs
• Community forum: for setup questions and general discussion
• docs@vhorde.com: for documentation corrections