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:

1. You wish to setup Zynthian similar to a regular pc with a monitor, keyboard & mouse
2. 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
• 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. 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:

• On MacOS, go to http://zynthian.local to access the Zynthian WebConf Tool

password = raspberry

• On Windows, 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 are tools available to activate the 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:

• MacOS and Windows
• iOS
• Android

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 : raspberry

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.