Beginners Headless Zynthian Tutorial
- 1 Introduction
- 2 Hardware
- 3 ZynthianOS
- 4 Network Connection
- 5 Web Browser
- 6 First Boot
- 7 Configure Internet
- 8 Update ZynthianOS
- 9 Configure the hardware
- 10 Install VNC Server on the Raspberry Pi
- 11 Install VNC Viewer in your Devices
- 12 OPTIONAL STEPS
Here's a simple as possible step by step beginners tutorial to setup a headless Zynthian.
A headless Zynthian is a Raspberry Pi with ZynthianOS without the screen, the buttons and the knobs. All is controlled remotely via another computer, a tablet, a smartphone or a midi controller. In most of the cases, the Zynthian Kit is the better way to use ZynthianOS. But sometimes, headless configuration could be interesting.
- Raspberry Pi (Pi4 recommanded)
- SD card (class 10)
- Power supply (take the official one)
- I2S DAC (sound card) (recommanded sound cards)
- The more simple way for making a network connexion is to directly connect an ethernet cable from the Raspberry Pi to the computer.
- Another way is to connect the two devices to an Ethernet switch.
You will need a web browser but not all are working well for that purpose.
- Google Chrome is reported to works well
- Put the SD on the raspberry
- Power on by plugin the power supply
- Wait a little bit
- Open your web browser
- 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
If you cannot enter to the Zynthian WebConf Tools, wait a little bit more. Then try to reboot by powering off. Then, try to burn another SD card.
- 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
Now that you are connected to the Internet, you can update Zynthian OS via the WebConf:
Configure the hardware
Configure your hardware setup via the WebConf:
Hardware / Kit / Custom Hardware / Audio / Select your soundcard on the list Hardware / Display / Generic HDMI Display Hardware / Wiring / DUMMIES
Install 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. To install VNC (or other softwares) on the Raspberry Pi, you need an access to the terminal:
- Option 1 : via the WebConf terminal
- Option 2 : via SSH (that's mean via another terminal)
- On MacOS, open the MacOS Terminal and type:
sudo ssh zynthian.local
It will first ask for your mac password and then the Zynthian password (raspberry). Then, if you see root@zynthian:~ you are on the Raspberry Pi terminal.
Note : On MacOS, if you need to re-burn your SD card and have the error message “Host key verification failed” when you try to connect via SSH, you need to erase the previous SSH information with the nano text editor in the ssh known_hosts by running this command:
sudo nano /var/root/.ssh/known_hosts
In nano, delete the zynthian line (control K), then write the file (control O + enter), then quit (control X).
- On Windows, download PuTTy and do the same that for MacOS.
- When you are on the Raspberry Pi terminal, run the following commands:
sudo apt install realvnc-vnc-server sudo raspi-config Interfacing Options / VNC / Yes
If you are using the WebConf terminal, note that it's normal that the apt update take a long time (and you see nothing, that is just a display bug). After the update, you should scroll down or launch a new WebConf terminal to install vnc.
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 : raspberry
You should now have the Zynthian UI working remotely.
For a better use, configure Zynthian UI for headless use in the WebConf:
Interface / UI options Advanced view : ON Enable Touch Widgets: ON Enable cursor: ON
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
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 the X11 server’s terminal (xterm) that run on your computer, send the command:
ssh -Y email@example.com
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 :
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:
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:
And upload your custom externals.