Building a Zynthian Box using an official Kit v3

1 Introduction

This tutorial is mainly intended for those who are building a Zynthian Box using one of the official kits, that i offer here:

Zynthian Shop

Specifically, these instructions are for assembling kit v3 (version 3), those kits using the Zynaptik circuit and the ZynScreen v1.4 display.

2 Bill of Materials

• Zynthian Basic Kit v3 (4 x controller v3 + zynaptic circuit + ribbon bus cable)
• ZynScreen v1.4 (3.5" touch-display + controller driver)
• Raspberry Pi 3
• HifiBerry DAC+ADC souncard
• Case kit v3, including nuts, bolts and connectors
• Power adapter for Raspberry Pi (5.1v 2.4A with microUSB connector)
• 16GB SD Card (a good one, please!)

3 Some definitions

3.1 Zynthian

It's an open project with the goal of creating an Open Synth Platform based in Free Software and Open Hardware Specifications & Designs (when available). It's a community-driven project. If you are here, probably you already know all this ;-)

3.2 Zynthian Software

The Zynthian Software stack consist of:

+ GNU Linux Operating System: Raspbian Jessie (Minibian is used in the most recent SD images)
+ Jack Audio Daemon
+ A collection of standalone Synth Engines & LV2 Plugins (see Supported Synth Engines & Plugins)
+ MOD-HOST + MOD-UI software, from ModDevices (github repositories)
+ Zynthian User Interface (github repository)
+ Zynthian Webconf Tool (github repository)

All the software used by Zynthian is Free Software (free as in freedom, not as in free beer) and it's covered by the GPL license or similar. If you don't know what i'm talking about, please, take a look to this:

What is Free Software?

The easiest way of getting the software is downloading the last official SD image from here:

Download Zynthian "Aruk RC-3" SD-image

It's a 16GB compressed image file (plenty of soundfonts) compiled for Raspberry Pi 3.

These SD card images include all the Zynthian software, properly configured for working with the official kits. Completely ready to use. Plug and play!

After downloading the SD-image, you have to write it to a SDcard. You need a SD card with a minimum size of 16GB, although you can use a bigger one if you want.

If you don't know how to do it, you can use Etcher (free software works on Mac, Windows or Linux) to flash the image onto the SDcard. Or do it manually! There is a really good manual for this at this link.

Finally, if you like, you can build your own SD image following these instructions:

Building the SD Image using the Setup Script

3.3 Zynthian Box

A Zynthian Box is a hardware device, a small digital computer designed to run the Zynthian Software. Currently it's based in the Raspberry Pi platform, but it could be easily adapted to other computer platforms.

This is a sketch with the main blocks of the official Zynthian Box:

In the project's repositories you will find all the electric schemes, PCB specifications, Herber files, etc. to build your own Zynthian Box from scratch:

- Zynthian Hardware Repository
- Zynthian Case Repository

The official version is the canonical reference. Of course, you don't have to build the official version. You can build your customized Zynthian Box modifying and improving what you want. If you do so, some feedback would be very appreciated ;-)

3.4 Zynthian Bundle All Kit v3

A Zynthian Kit is a set of specific and generic electronic parts. This tutorial refers to the official Zynthian Bundle All Kit v3, that is composed of these specific parts:

+ 4 x Controller Modules + Wiring 
+ 1 x Zynaptik Module: MIDI Ports + extended I/O
+ 1 x ZynScreen 3.5': Touch-Display + Controllers circuit
+ 1 x Main ribbon bus cable

these generic parts:

+ 1 x Raspberry Pi 3
+ 1 x Hifiberry DAC+ADC

and the aluminium case:

+ 1 x Zynthian Aluminium Case
+ 1 x Connectors
+ 1 x Bolts & Nuts

4 Assembling your Zynthian Box

4.1 Prerequisites

Assembling your Zynthian Kit V3 is not difficult at all: you need your attention, a screwdriver and an adjustable wrench. The kit v3 is a pre-built kit and you don't need to solder anything, just screwdrive the bolts and plug the wires.

Read the instructions and observe the detailed photos carefully. If you get in trouble you can ask the community:

https://discourse.zynthian.org

WARNING!!

Please, handle electronic parts with care, specially the display, as it's easy to damage.

4.2 Secure the Jack connectors

Insert every connector from the inner-side of the case and the ring washers and nuts from the outer-side. The ring-washers will avoid damaging the case surface when you tighten the nuts. A wrench or pair of pliers can be useful for tightening the nuts.

4.3 Secure the MIDI connectors

Just insert every connector with the JST-wire from the outer-side of the case and the nut from the inner-side. A wrench or pair of pliers can be useful for tightening the nuts.

4.4 Mount the MIDI activity LEDS

Insert the 3 LEDS in the case holes, leaving the short lead at left. Don't push the LED's head! Instead push the black plastic holder around the LED. Sometimes is hard to push ...

When it's done, you have to plug the LED wires into the 2 spare "DUPONT" connectors from the MIDI harness (green & yellow wires). Polarity is important, so don't cross the wires:

* JST Green wire (1) => LED's Anode (LED's long lead)
* JST Yellow wire (2) => LED's Cathode (LED's short lead)

As the LED's leads are too long, you would like to cut them a little bit (7-8 mm is a good length), but remember where the "short" lead is located!!

Note:

If you don’t connect the status LEDs, the MIDI-OUT and MIDI-THRU won’t work unless you short jumpers JP1 & JP2 in the zynaptik board.

4.5 Assemble the Main Computing Block

The main computing block is composed by the RBPi and the HifiBerry soundcard, and should be assembled using the next set of separator & bolts:

For easier assembling, you should follow the next steps:

1. Fix the 2x4 separators to the RBPi. The bigger one must be on top and the smaller one on bottom.
2. Insert the Hifiberry soundcard in the RBPi. 
3. Screwdrive the 4 bolts on top of the HifiBerry.

4.6 Secure the Main Computing Block

After assembling the main computing block, you should secure it to the case. Use 4 black M2.5 bolts (see photo above).

4.7 Secure the Zynaptik module

Secure the Zynaptik module to the case using 4 x separators and 8 x M2.5 bolts. I recommend to start fixing the separators to the case.

As you can see, the zynaptik circuit has some extra circuitry that is not soldered on it by default. Don't worry about it because it's not needed at all for building a fully functional standard Zynthian Box.

4.8 Secure the Display

WARNING!!

Please, handle electronic parts with care, specially the display, as it's easy to damage.

For fixing the display to the case cover, you have to use this set:

It's composed of 4 bolts, 4 nuts and 4 nylon separators. Before securing the screen, don't forget to remove the protective plastic sheet. For tightening the bolts you could use a 2mm Allen key while hold the nut with your fingers.

4.9 Secure the Controllers

Plug a wire on every controller.

Fix the 4 controller modules to the case cover using the 4 nuts and washers attached to every rotary encoder.

4.10 Insert the knobs

You should insert the knobs into the encoders before closing the case. This will avoid forcing the encoders too much as otherwise, you could break them. Follow these simple steps and you wouldn't have any problem:

* moisten with water or saliva the encoder stem and the knob hole
* press the encoder PCB with the finger from the rear side while pushing the knob from the front side until is completely inserted

4.11 Stick the rubber feet

5 Connecting everything

The Zynthian Kit 3 is designed to use JST connectors that can't be plugged reversed, so connecting everything is really straight-forward:

• Connect the Main Ribbon Bus cable to the RBPi's 40-pin header and also to the Zynaptik module. The red wire is pin 1, so if you are looking at the case from the front side, it should be at right.

• Connect the 4 controller cables to the 4 controller connectors on the ZynScreen (CTRL1, CTRL2, CTRL3, CTRL4)

• Connect the 3 cables from the MIDI connectors to the MIDI-IN, MIDI-OUT and MIDI-THRU connectors on the Zynaptik module.

Note:

If you don’t connect the status LEDs, the MIDI-OUT and MIDI-THRU won’t work unless you short jumpers JP1 & JP2 in the zynaptik board.

• Connect the audio output jack connectors to the audio-output header on the Hifiberry soundcard:

The black wire on the "R" pin, white on the "L" one and red on "GND" (middle).

Note:

Some kits have flipped the red and white wires. This is not a problem. Simply look at the black wire.

• Connect the balanced audio input jack connector to the audio-input header on the Hifiberry soundcard:

The black wire should be connected to pin 3, red wire to pin 2 and white wire to pin 1. Looking at the first photo, numbering is left to right.

Note:

Some kits have flipped the red and white wires. This is not a problem. Simply look at the black wire.

5.1 Connect the Display

And finally, connect the ribbon's 26-pin connector to the display's connector. Put attention to the orientation. The red wire should be the pin 1 that as marked in the display's PCB surface.

At this point, your Zynthian Box should look something like this:

6 Testing your Zynthian Box

And that's all. Your Zynthian Box is almost ready to boot. I recommend that you double-check everything before trying to boot.

6.1 Double-check part's assembling and wiring

It's easy to make a mistake while assembling the parts or connecting the wires. Some errors can be dangerous for the electronic components (short-circuits, some specific bad-wiring combinations) so it's better to be sure that everything is correctly assembled and connected.

Put special attention to ribbon bus connection and verify that red wire is on pin 1 for every connector. Also put attention to audio jack connectors and check that they are correctly connected to the Hifiberry soundcard.

6.2 First Boot

When you are sure that everything is in its place, it's time to boot the machine, so:

1. Insert the SD-card with the zynthian image ready to run. If you don't have one yet, read this. You can insert the SD-card through the "window" on the bottom-side of the case. Also, if the case is still open, you can do it from the top.
2. Plug the mini-usb power connector. A good 5V micro-usb charger is recommended (> 2 Amp).

These are the stages that you should see while booting:

1. After 5-10 seconds, it will show the Zynthian splash screen
2. After 3-4 seconds, it will go black
3. If you are using a fresh zynthian image and it's the first boot, the stages 1 and 2 will be repeated
4. After 5-10 seconds, the zynthian UI will be shown

If you get the Zynthian UI, congratulations!!! You are really close to get it!!

If you don't get an error screen or a blank screen, bad luck! Probably you made some mistake during the mounting process. You have to locate and solve the problem(s).

If you are using the Aruk RC-3 SD image (you should!), you will note that the controllers are not working at all. This SD image is pre-configured for working with the kit v2, so you need to configure the software for working with the kit v3. The simplest way of doing it is using the webconf tool:

• Connect your zynthian to your local network using an ethernet cable (RJ-45).
• From your web browser, access the zynthian's webconf tool by typing "zynthian.local" in the address bar. If this doesn't work for you, you should try with the IP. You can get the IP of your zynthian by navigating to the Admin Menu and clicking "Network Info". You should do that by using the "touch" interface: Click the top bar with a stick (or your nail, if it's not too wide) until you are in the Admin Menu. Once you are there, go down and click "Network Info".
• Type the password (raspberry) for login into the webconf tool.
• Once you are logged in, you have to access Hardware->Kit and select "Kit V3".
• Save the changes and reboot your Zynthian.

6.3 Test the Controllers & UI

If you get into the Zynthian UI, then you should be in the 'Layer list' screen. Let's start testing that your controllers are working OK.

1. Rotate the SELECT controller up & down for selecting the different options in the Layers menu. 

2. Push SELECT to create a New 'Synth Layer'. You should get into the 'Engine Selection' screen.

If it doesn't works, try rotating/pushing the 'learn/snapshot' controller. Perhaps you have cross-wired the 3 & 4 controllers and in that case, you have to fix the wiring. If it doesn't work, try pushing the other two controllers and rotating the controllers. If something happens, most probably you have reversed the wiring order when connecting the controllers. Double-check the wiring again.

3. Rotate the SELECT controller to choose the engine you want to instance for the new layer. 

The selector must go down when rotating clockwise and go up when rotating counter-clockwise. If the rotation sense is reversed, you should check the wiring. Perhaps some harness is faulty. The wires color sequence should be: red, black, yellow, green.

4. Select the ZynAddSubFX engine, select channel #1, bank 'Collection' and preset 'Metal Drips'. 

You should get into the 'Instrument Control' screen.

5. Rotate every control to test that it works and that the rotation sense is correct. 

If some controller doesn't work correctly, check the wiring again. You could try to figure what is happening by analyzing the observed behaviour.

6. Push SELECT to move to the next controller screen. Bold push to select a controller screen from the list.

7. Push BACK. You should go back to the 'Preset Selection' screen. 

8. Push BACK again. You should go back to the 'Bank Selection' screen. 

9. Push LAYER again to return to the 'Layer Selection' screen. Try to create another layer following the same procedure.

10. Push 'SNAPSHOT' to get into the 'Snapshot' screen. Select 'New Snapshot' and your first snapshot will be stored.

If everything is working OK, then you should read the User's Guide and start enjoying your Zynthian Box, but before that ... why not enjoying a little bit? Connect your MIDI keyboard, your speakers and check this out:

Bank 'net-wisdom', Preset 'Vangelis Saw - C'

Keep pushing a single note (or a chord) and move the cutoff and resonance controllers. Enjoy! ;-)

6.4 Test the Audio Output

1. Connect the audio output (RCA or Jack connectors) to your amplifier or auto-amplified speakers.
2. Boot your Zynthian. You should be in the initial 'Layer Selection' screen.
3. Push BACK and you will get into the 'Admin' screen.
4. Select 'Audio Test' option and push 'SELECT'. You should hear the test audio-track: a nice afrocuban stuff ;-)
5. Push 'BACK' to stop the playing, and 'BACK' again to return to the "Layer Selection' screen.

If you hear nothing, please, check the amplifier, speakers, cabling, gain, volume, etc. If nothing works, you have to locate and solve the problem(s).

6.5 Test the MIDI subsystem

1. Connect the audio output (RCA or Jack connector) to your amplifier or auto-amplified speakers.
2. Boot your Zynthian, select FluidSynth engine, channel #1 and 'TimGM6mb' bank. Select some instrument, like "Piano 1".
3. You could add more layers for completing the band ;-)
3. Push BACK, holding the switch pushed more than 2 seconds. You should get into the 'Admin' screen.
4. Select 'MIDI Test' option and push 'SELECT'. You should hear the test midi-track ('Take Five') interpreted by your Zynthian's band ;-)
5. Push 'BACK' to stop the playing

If you hear nothing, please, check the amplifier, speakers, cabling, gain, volume, etc. If nothing works, you have to locate and solve the problem(s).

6.6 Test the MIDI-USB inputs

1. Connect the audio output (RCA or Jack connector) to your amplifier or auto-amplified speakers.
2. Boot your Zynthian, select ZynAddSubFX, channel #1, bank and instrument
3. Connect a MIDI-USB keyboard to any USB port. The keyboard should be configured to use channel #1.
3. After 2-3 seconds , play something with your keyboard. A simple Chopin's Nocturni would be enough. You should hear your music. If you don't like it, probably you should take some piano lessons, same as me ;-)

If this doesn't work, you have to locate and solve the problem(s).

6.7 Test the MIDI-IN connector

1. Connect the audio output (RCA or Jack connector) to your amplifier or auto-amplified speakers.
2. Boot your Zynthian, select ZynAddSubFX, channel #1, bank and instrument.
3. Connect your keyboard's MIDI-OUT to the Zynthian's MIDI-IN using a MIDI cable.
3. After 2-3 seconds, play something with your keyboard. OK! A single melody can do the task. You should hear your song ;-)

If this doesn't work, you have to locate and solve the problem(s).

7 Final steps

Once everything is in its place and you have tested that it works, it's time to close the case ...

7.1 Close the case

Take your time to see how to bend and drive the cables to get a good fitting when closing the case. The ribbon bus cable is pre-bended for easing this process.

Finally, screw-drive the 8 sheet-threader bolts for securing the case, 4 each side.

8 Update your Zynthian Box

If you are using the official Zynthian SD Image, the first thing you should do after booting up your Zynthian Box and having the controllers working OK is update the software:

- connect your Zynthian Box to your router using an ethernet cable
- from the admin menu, click update software
- from the admin menu, click restart UI (or reboot)

The update process can take some time. Be patient. If you get some ERROR message while updating, please, ask in the forum. You can send a photo or description of the error message.

You can also update the software using the webconf tool, or from the command line.

9 Locating and Solving problems

In this section i will try to give you some tips for locating and solving the problems you may have.

For finding and solving problems, i really recommend to connect a HDMI display to the RBPi. It will give you accurate information during the booting sequence. Also, if you connect an USB keyboard, you could login into the system and get extra information, inspect the logs, etc.

9.1 The display don't show the zynthian splash screen on boot

In that case, probably the system is not booting correctly. You could try to connect a HDMI display and see if the system is booting. If you can't see the booting sequence, then you should re-burn your SD-card with the Zynthian image. Also, check that your image file is correct by using the SHA1 signature.

9.2 You get the zynthian error screen with the IP

Your hardware seems to be incorrectly configured. You should access the webconf tool and configure your hardware.

9.3 Your controllers doesn't work

You make a mistake while connecting the controllers or your hardware (wiring layout) is incorrectly configured. You should access the webconf tool and configure your hardware.

9.4 You can't solve the problem

If you can't find a solution for your problem, ask the community:

https://discourse.zynthian.org

Also, if you found a solution for a problem not described here, please send feedback to the community, or better, edit this wiki! ;-)

10 Technical Reference

Finally, i have included here some detailed schemes. People hacking the standard Zynthian design would find it very useful. Also, if you have some problem and need to "debug", you would find it useful too.

Error creating thumbnail: convert-im6.q16: unrecognized color `none;' @ warning/color.c/GetColorCompliance/1057. convert-im6.q16: non-conforming drawing primitive definition `fill' @ error/draw.c/RenderMVGContent/4404.

Error creating thumbnail: convert-im6.q16: unrecognized color `none;' @ warning/color.c/GetColorCompliance/1057. convert-im6.q16: non-conforming drawing primitive definition `fill' @ error/draw.c/RenderMVGContent/4404.

File:ZynScreen v1.3.svg

You can find all this info and much more in the project's Hardware Repository.