Difference between revisions of "Beginners Headless Zynthian Tutorial"

Latest revision as of 06:26, 15 July 2023

1 Introduction

A headless Zynthian is a Raspberry Pi with ZynthianOS without the screen, the buttons and the knobs. Here's a simple as possible step by step beginners tutorial to setup a headless Zynthian.

Zynthian can be 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. However, if you want to try Zynthian before you purchase a Zynthian Kit or experiment with another type of configuration, a headless setup allows this.

2 Hardware

Raspberry Pi (Pi4 recommended)
SD card (class 10)
Power supply (take the official one)
(optionnal but recommended for the best audo experience) an I2S DAC (sound card) (recommended sound cards)

3 ZynthianOS

Download the last stable Zynthian OS image
Download Etcher
Burn the ZynthianOS image on an SD card

4 Network Connection

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.

5 Web Browser

You will need a web browser but not all are working well for that purpose.

Google Chrome is reported to works well

6 First Boot

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.

There are tools available to activate the bonjour mechanism to allow using the name which is a much more flexible option.

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.

7 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

8 Update ZynthianOS

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

Software / Update 
System / Reboot

9 Configure the hardware

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

10 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"

11 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

12 OPTIONAL STEPS

12.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.

12.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

12.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.

@@ Line 2: / Line 2: @@
 === Introduction ===
-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 [https://en.wikipedia.org/wiki/Headless_computer without the screen], the buttons and the knobs. 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.
+Zynthian can be controlled remotely via another computer, a tablet, a smartphone or a midi controller.
-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.
+However, if you want to try Zynthian before you purchase a Zynthian Kit or experiment with another type of configuration, a headless setup allows this.
 === Hardware ===
-# Raspberry Pi (Pi4 recommanded)
+# Raspberry Pi (Pi4 recommended)
 # SD card (class 10)
 # Power supply (take the official one)
-# I2S DAC (sound card) ([https://wiki.zynthian.org/index.php/Unofficial_hardware recommanded sound cards])
+# (optionnal but recommended for the best audo experience) an I2S DAC (sound card) ([https://wiki.zynthian.org/index.php/Unofficial_hardware recommended sound cards])
 === ZynthianOS ===
@@ Line 20: / Line 19: @@
 # Burn the ZynthianOS image on an SD card
-=== Network Connexion ===
+=== Network Connection ===
 * 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.
@@ Line 34: / Line 33: @@
 # Open your web browser
 * On MacOS, go to http://zynthian.local to access the Zynthian WebConf Tool
-* On Windows, first [https://wiki.zynthian.org/index.php/Finding_your_IP_address find the IP address of the Raspberry Pi], then type the IP address on the web browser to access the Zynthian WebConf Tool
+ password = raspberry
+* On Windows, first [https://wiki.zynthian.org/index.php/Finding_your_IP_address 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.
 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.
@@ Line 41: / Line 42: @@
 * 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
+  [http://zynthian.local/sys-wifi System / WIFI] / Add Network
   Mode = ON
 === Update ZynthianOS ===
 Now that you are connected to the Internet, you can update Zynthian OS via the WebConf:
-  Software / Update
+  [http://zynthian.local/sw-update Software / Update ]
-  System / Reboot
+  [http://zynthian.local/sys-reboot System / Reboot]
 === Configure the hardware ===
 Configure your hardware setup via the WebConf:
-  Hardware / Kit / Custom
+  [http://zynthian.local/hw-kit Hardware / Kit] / Custom
-  Hardware / Audio / ''Select your soundcard on the list''
+  [http://zynthian.local/hw-audio Hardware / Audio] / ''Select your soundcard on the list'' or choose RBPiHeadphones
-   Hardware / Display / Generic HDMI Display
+   [http://zynthian.local/hw-display Hardware / Display] / Generic HDMI Display
-  Hardware / Wiring / DUMMIES
+  [http://zynthian.local/hw-wiring Hardware / Wiring] / DUMMIES
-  System / Reboot
+  [http://zynthian.local System/sys-reboot / Reboot]
-=== Install VNC Server on the Raspberry Pi ===
+=== 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.
-To install VNC (or other softwares) on the Raspberry Pi, you need an access to the terminal:
+With your browser pointing to http://zynthian.local, navigate to Interface => UI Options scroll at the bottom and check "Enable VNC server"
-* Option 1 : via the WebConf terminal
- System / Terminal
-* Option 2 : via SSH (that's mean via another terminal)
-- On MacOS, open the MacOS Terminal and type:
- 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 [https://www.putty.org/ PuTTy] and do the same that for MacOS.
-* When you are on the Raspberry Pi terminal, run the following commands:
- sudo apt update
- 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 ===
@@ Line 101: / Line 78: @@
 For a better use, configure Zynthian UI for headless use in the WebConf:
-  Interface / UI options
+  [http://zynthian.local/ui-options Interface / UI options ]
   Advanced view : ON
   Enable Touch Widgets: ON
@@ Line 108: / Line 85: @@
 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
+  [http://zynthian.local/sys-wifi System / WIFI] / Hotspot
 == OPTIONAL STEPS ==
+=== 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 [[Zynthian_UI_Users_Guide#CUIA: Callable UI Actions | CUIA: Callable UI Actions]] for info about keyboard shortcuts and MIDI controls.
 === Accessing the Native GUI ===
-If you want to access from your computer to the Graphical User Interface of softwares like Pure data that run on the Raspberry Pi, you need to install an X11 server on your computer:
+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: [https://www.xquartz.org/ Xquartz]
 * On Windows: [https://sourceforge.net/projects/xming/ Xming]
@@ Line 119: / Line 101: @@
 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: ZynAddSubFX, Aeolus and Pianoteq) and thehe Pure Data GUI should appears on your computer screen.
+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 :
+ [http://zynthian.local:8888 Software / MOD-UI]
 === Accessing the ZynthianOS Folders ===
@@ Line 131: / Line 116: @@
   User : root
   Password : raspberry
-. If, for exemple, you want to access to the Pure Data externals folders for manually installing externals that aren’t available via another way, simpli use it as a normal finder, go to:
+. 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.