No Hardware Build

1 Building a Zynthian With Just a Raspberry Pi

So you've heard a bit about Zynthian and you want to dip your toe in the water? This guide describes how to build a Zynthian with just a Raspberry Pi and no other hardware (aka No Box Build). While the full kit available in the store will always provide the best experience of Zynthian, this guide allows you to test Zynthian before purchasing a kit.

The guide aims to serve two scenarios:

You wish to setup Zynthian similar to a regular pc with a monitor, keyboard & mouse

You want to go further and create a no screen (headless) setup and connect and control Zynthian remotely via another computer, a tablet, a smartphone or a midi controller.

Once setup you are free to customise your Zynthian build with additions such as a touchscreen, rotary encoders, USB audio interface with multi-IO etc. etc.

1.1 Requirements

At a minimum you will need:

Raspberry Pi 3, 4 or 5 (5 recommended)

Good quality power supply for the Raspberry Pi (the official Raspberry Pi PSU is recommended)

32GB (or larger) MicroSD card

MicroSD card adapter, e.g. USB

Personal computer

HDMI monitor

Micro HDMI to standard HDMI cable (standard HDMI for Pi 3)

USB computer keyboard

USB computer mouse

Headphones or audio cable to connect to sound system with stereo 3.5mm plug

Optional but highly recommended is a suitable audio hat for your Raspberry Pi or USB audio interface (may require a bit more configuration and testing). For more information about hardware see here. (Required for Pi 5 which has no audio output)

To setup remote access, update your Zynthian and enable a headless (no screen) setup:

Wired connection from the Raspberry Pi to your personal computer

1.2 Get the firmware

Zynthian is based on a standard Debian OS with modifications to provide the rich set of functionality.

Download the latest stable Zynthian firmware image from https://os.zynthian.org/zynthianos-last-stable.zip to the personal computer

Install an image writing software, e.g. Raspberry Pi Imager

Insert the microSD card into the adaptor and plug the adaptor into the personal computer

Use the image writing software to write the image to the microSD card - note that Raspberry Pi Imager (and some other software) will use the downloaded zip so don't unzip it manually

Eject the microSD card

2 Interfacing with Zynthian via Screen, Headless or Both

At this point you are free to choose which way to interact with your device. It's recommended to use a screen with keyboard & mouse as it is simple and not subject to potential networking headaches. Alternatively, it is possible to immediately boot and connect to Zynthian remotely (headless setup). If you're game then you can skip plugging in the peripherals as you follow these steps.

2.1 First Boot

The first boot of ZynthianOS takes some time so be patient. Consequent boots are faster.

Insert the microSD card into the Raspberry Pi

Connect the Raspberry Pi to the computer keyboard, mouse and HDMI monitor

Connnect the headphones or sound system to the Raspberry Pi 3.5mm audio output or connect the USB soundcard / hat

Connect power to the Raspberry Pi

ZynthianOS starts and should display a message that it is performing some initialisation which may take a few minutes - be patient and wait for this to complete

Zynthian reboots and displays the user interface on the HDMI monitor

If you just want to start playing, you're ready to start using your Zynthian setup, plugin a USB midi device and get going! See #Post-Installation Steps for more on further configuration or if you see an error message. However, it's recommended to follow the next few steps to get network connectivity sorted.

2.1.1 Network Connection

The simplest way is to directly connect an ethernet cable from the Raspberry Pi to the computer.

Alternatively, connect the two devices to an Ethernet switch.

2.1.2 Connect via Web Browser

Now it's time to connect to Zynthian's built-in web interface (known as WebConf). Open your web browser of choice then:

Go to http://zynthian.local to access the Zynthian WebConf Tool

password = opensynth

If this fails, first find the IP address of the Raspberry Pi, then type the IP address on the web browser to access the Zynthian WebConf Tool.

There maybe tools available on your OS to activate the mDNS (aka bonjour) mechanism to allow using the name which is a much more flexible option.

2.1.3 Troubleshooting

Some suggestions if you cannot enter to the Zynthian WebConf Tools:

Before anything else: you must identify the correct IP address of your Raspberry Pi on your network!

Wait a little bit more (booting is reasonably quick but first boot takes time)

Try to reboot by powering off and back on again

2.1.4 Configure Internet

If you are connected via an ethernet switch, connect the switch to your Internet box

If you are directly connected via an ethernet cable, configure the Wifi on the WebConf page:

System / WIFI / Add Network Mode = ON

3 Post-Installation Steps

3.1 Configure Remote Access to Zynthian

3.1.1 Activate VNC Server on the Raspberry Pi

VNC allows you to remotely have the Raspberry Pi screen on your personal computer, your tablet or your smartphone. With your browser pointing to http://zynthian.local, navigate to Interface => UI Options scroll at the bottom and check "Enable VNC server"

3.1.2 Install VNC Viewer in your Devices

1. Download and install VNC viewer in your devices:

2. Connect to the Zynthian UI via VNC: You should be on the same network (ethernet cable and/or Wifi). Type the raspberry pi IP address (on Windows and android) or zynthian.local (on MacOS and iOS) in VNC Viewer. 

User name : root 
Password : opensynth

You should now have the Zynthian UI working remotely.

For a more comfortable experience with headless use, it is recommended to configure the following Zynthian UI settings in the WebConf:

Interface / UI options  
Advanced view : ON 
Enable Touch Widgets: ON 
Enable cursor: ON

3.1.3 Configuring a Wireless Hotspot Connection

On stage, you can disconnect the Zynthian from internet and configure it as a hotspot for connecting your devices to it. For this, go to the WebConf:

System / WIFI / Hotspot

3.2 Update ZynthianOS

Now that you are connected to the Internet, you can update Zynthian OS via the WebConf:

Software / Update 
System / Reboot

3.3 Configure the hardware

It's important to set things initially, particularly if you're using USB audio and trying to access Zynthian UI via VNC as incorrect settings can cause bootloops. Configure your hardware setup via the WebConf:

Hardware / Kit / Custom 
Hardware / Audio / Select your soundcard on the list or choose RBPiHeadphones
 Hardware / Display / Generic HDMI Display 
Hardware / Wiring / DUMMIES

  System/sys-reboot / Reboot

3.4 Finished!

You should now have a functional Zynthian that is network connected and up to date. Zynthian is designed to be controlled with rotary encoders and switches. It also has a touchscreen interface from which all functionality is accessible. A pointer device such as a mouse may be used to drive the interface. A cursor should show on the screen indicating the pointer position.

Look at the Zynthian UI Users Guide on the wiki to learn how to use Zynthian. Join the community in the Discourse forum for more current information on the status of the Zynthian project and to ask for help with troubleshooting. See below for some further optional setup/config steps.

Welcome and happy Zynthing...

4 Optional Steps

4.1 Controlling Headless Zynthian With A Computer Keyboard or MIDI Device

While a touch interface allows control for a headless Zynthian setup, adding a computer keyboard or MIDI keyboard or controller (such as a NanoKontrol) will allow a greater range of controls at your fingertips.

See CUIA: Callable UI Actions for info about keyboard shortcuts and MIDI controls.

4.2 Accessing the Native GUI

If you want to access from your computer to the Graphical User Interface of softwares like Pure data or Pianoteq that run on the Raspberry Pi, you need to install an X11 server on your computer:

On MacOS: Xquartz
On Windows: Xming

On the X11 server’s terminal (xterm) that run on your computer, send the command:

ssh -Y root@zynthian.local

On the Zythian UI, create a new Pure Data layer (or other engine with supported native GUI) and the Pure Data GUI should appears on your computer screen.

Note that you can access MOD-UI (the virtual pedal board) without X11. When you have created a MOD-UI layer, just go to the WebConf :

Software / MOD-UI

4.3 Accessing the ZynthianOS Folders

If you want to graphically access to the Zynthian OS files and folders (not recommended for beginners):

1. install an SFPT client on your computer:

On MacOS: Cyberduck
On Windows: PuTTy

2. Open an SFPT connection:

Server : zynthian.local (MacOS) or IP Address (Windows) 
User : root 
Password : raspberry

3. If, for exemple, you want to access to the Pure Data externals folders for manually installing externals that aren’t available via another way, simply use it as a normal finder and go to:

/usr/lib/pd/extra

And upload your custom externals.