Building a custom Zynthian - Revision history

Hannesmenzel: Formatting

2025-09-03T23:13:48Z

Formatting

Hannesmenzel: Added final pictures

2025-09-03T22:58:33Z

Added final pictures

Hannesmenzel: /* Parts used */

2025-09-03T22:45:53Z

Parts used

Hannesmenzel: /* Int-A and B pins */

2025-09-03T22:24:44Z

Int-A and B pins

Hannesmenzel: GPIO stuff added

2025-09-03T22:10:45Z

GPIO stuff added

Hannesmenzel: Add display setup

2025-09-03T21:33:50Z

Add display setup

Hannesmenzel at 21:28, 3 September 2025

2025-09-03T21:28:12Z

Hannesmenzel at 21:04, 3 September 2025

2025-09-03T21:04:24Z

Hannesmenzel: /* Wiring */

2025-09-03T20:58:56Z

Wiring

Hannesmenzel: Added wiring section

2025-09-03T20:48:28Z

Added wiring section

@@ Line 1: / Line 1: @@
 This is the documentation of my first custom zynthian build. It is work in progress and will be expanded over time. I really got much help of others in the forum, [https://discourse.zynthian.org/t/adding-encoders-to-a-home-built-zynthian/10631 this thread] can also be seen as part of the documentation.
 =The plan=
 After initially only wanting to get into this project by connecting a bare PI to a HDMI display and an external USB audio interface I considered building a custom Zynthian with a nice case and at least four encoders and stereo input and output connectors. You can read below how that succeeded (it miraculously did).
 =Parts used=
 ==Parts used in this build==
@@ Line 28: / Line 33: @@
 ==Building step by step==
 If you, like me, build the custom Zynthian step by step, you can do so. If you don't feel like investing in a DAC and a headphone amp you can use your USB Audio interface. If you chose to use the Zynthian with touch display input only for the parameter control, you can delay the whole encoder circuit build.
 =Planning=
@@ Line 50: / Line 57: @@
 The [https://www.hifiberry.com/docs/hardware/gpio-usage-of-hifiberry-boards/ HifiBerry Documentation] is pretty clear about what to use and what not. In out case with the DAC2 ADC Pro is says: ''"Do not use more than a few mA from the 3.3V line. If your circuit requires 3.3V, use the 5V power rail of the Raspberry Pi with an additional voltage regulator. Pin 27 and 28 are always reserved for an ID EEPROM on the Raspberry Pi. Independently which card you use, these pins are always reserved and should never be used to connect external components. [...] GPIO2-3 (pins 3 and 5) are used by our products for configuration. If you are experienced with I2C, you might add other slave devices. If you a a novice, we don’t recommend this at all. GPIOs 18-21 (pins 12, 35, 38 and 40) are used for the sound interface. You can’t use them for any other purpose."'' So there you go.
 ===Zynthian MIDI===
 ===Other purposes===
@@ Line 64: / Line 69: @@
 * A HAT mounted onto the PI will raise heat considerably, because the air from the cooler cannot move so well. I had to raise the audio hat with a 9mm 40 pin header to not conflict with the cooler anyway.
 With all these things in mind: My Zynthian never exceeds 60°C CPU temperature.
 =Soldering and assembling=
 ==Audio inputs and outputs==
@@ Line 84: / Line 91: @@
 Except for the DSP header which is used in this case as the extended PI GPIOs nothing more needs to be connected right now.
 ===Connecting the headphone amp===
@@ Line 99: / Line 105: @@
 PrototypingBoard.jpg|Picture 1: Unsuccessful attempt to put the schematic to the prototyping board
 </gallery>
 ===Soldering to a permaboard===
@@ Line 151: / Line 156: @@
 I happened to have ordered encoders mounted on a PCB, don't ask why. This includes 10kOhm pull-up resistors (don't ask why). The two options were to desolder these resistors, cut their lines or just power the encoders. I chose the latter option. Without connecting them to 5V they actually worked, but very clumsy, unreliable and sometimes triggering other actions than intended.
 =Setup=
 The software sided setup of your hardware is typically done in [[Web_Configuration_User_Guide|Webconf]]. You may also feel like editing the file /zynthian/config/zynthian_envars.sh which is basically edited when you do changes in Webconf. The code snippets below are taken from that file for better readability. You may find the according Webconf page and settings very quickly. If you find a "\n" in these snippets, this expands to an EOL (line break).
 ==Wiring setup==
@@ Line 168: / Line 176: @@
   export ZYNTHIAN_WIRING_MCP23017_INTA_PIN="27"
   export ZYNTHIAN_WIRING_MCP23017_INTB_PIN="25"
 ===Wiring layout===
 We use MCP23017_ENCODERS_V5TOUCH because we have physical encoders, but no physical buttons, why we are using the virtual V5-onscreen buttons.
 ===Encoders===
@@ Line 180: / Line 186: @@
 The bunch of 20 "-1" in the switches field represent the virtual buttons you'll use if you use the touch or virtual V5-buttons setup. If you don't have 20 physical buttons connected to match the V5 layout, just type it in like that.
 ===MCP Adress===
@@ Line 190: / Line 195: @@
      ...
   +++ > 0x27
 ===Int-A and B pins===
@@ Line 196: / Line 200: @@
 To make things easier here: if you, like me, chose to use psysical pin 36 and 37, also chose that in the webconf menu.
 ==Audio setup==
@@ Line 223: / Line 228: @@
   export FRAMEBUFFER="/dev/fb0"
   export DISPLAY_KERNEL_OPTIONS=""
 =Building a case=
 =Final state=
@@ Line 235: / Line 243: @@
 FinalBack.jpg|Final view from the back
 </gallery>

← Older revision		Revision as of 22:58, 3 September 2025
Line 226:		Line 226:

	=Building a case=		=Building a case=
		+
		+	=Final state=
		+
		+	Here is how it looks right now:
		+	<gallery>
		+	FinalTop.jpg\|Final view from the top
		+	FinalFront.jpg\|Final view from the front
		+	FinalBack.jpg\|Final view from the back
		+	</gallery>
		+

	=Further plans=		=Further plans=

@@ Line 5: / Line 5: @@
 =Parts used=
-Parts used in this build are the following (will be specified in steps):
 * Raspberry PI5 8GB with official active cooler, official power supply and a fast SD card
 * 8 inch Waveshare HDMI capacitive touch display
@@ Line 16: / Line 17: @@
 * Many little parts: DIY flat cables for display connection, Dupont cables, pin headers, permaboards and the lot
 If you, like me, build the custom Zynthian step by step, you can do so. If you don't feel like investing in a DAC and a headphone amp you can use your USB Audio interface. If you chose to use the Zynthian with touch display input only for the parameter control, you can delay the whole encoder circuit build.

@@ Line 182: / Line 182: @@
 ===Int-A and B pins===
-We connected the IA and IB pins of the MCP to physical pins 36 and 37. If you look them up in the webconf menu, you can chose for example "WPi GPIO 27 (Pin 36)", where pin 36 is the physical pin 36 (if you count on the hardware), and WPi GPIO 27 is the "WiringPi" number (not the GPIO 27). Check the pinout overview linked above: You'll see that this Pin is actually GPIO 16.
+We connected the IA and IB pins of the MCP to physical pins 36 and 37. If you look them up in the webconf menu, you can chose for example "WPi GPIO 27 (Pin 36)", where pin 36 is the physical pin 36 (if you count on the hardware), and WPi GPIO 27 is the "WiringPi" number (not the GPIO 27). Check the pinout overview linked above: You'll see that this Pin is actually GPIO 16. So why is the setup file storing it as "27" and "25"? It uses the WiringPi naming convention (see issue above).
 To make things easier here: if you, like me, chose to use psysical pin 36 and 37, also chose that in the webconf menu.
 ==Audio setup==

← Older revision		Revision as of 22:10, 3 September 2025
Line 23:		Line 23:

	==GPIO accessability==		==GPIO accessability==
		+
		+	If you mount an audio DAC on top of your PI, it acquires all of your 40 PI GPIOs, even if it doesn't use it. If you have an audio DAC with 40 pin outs like this one has, you can consider them being duplicates of the 40 PI GPIOs. In some cases you do not have the pins but only 40 holes where you have to solder an adequate 40 pin header to.


	==GPIO usage==		==GPIO usage==
		+
		+	We try to figure out which GPIOs not to use for our encoder wirings and other endeavours. Things to consider:
		+
		+	* When reading documentations about that matter, here's one thing to always keep in mind. Pins are labeled differently, referring to things like [https://pinout.xyz/ "(physical) pin", "GPIO", "WiringPi No." and other obscurities].
		+	* Things that might conflict with your plans might be (not exclusively): GPIOs your DAC relies on, GPIOs your MIDI IN/OUT might rely on, GPIOs that have special purposes in this context (SCL, SDA, EEPROM, ...).
		+	* When using an MCP23017 GPIO extender like in this project, you only need to find 2 unused GPIOs from your PI. The Webconf wiring setup's dropdown menu when chosing the pins for Int-A and Int-B gives you a hint what you might want to consider (Again, see the above mention naming convention problem). We'll use Pin 36; 37 for that matter (More on that later).
		+
		+
		+	===DAC===
		+
		+	The [https://www.hifiberry.com/docs/hardware/gpio-usage-of-hifiberry-boards/ HifiBerry Documentation] is pretty clear about what to use and what not. In out case with the DAC2 ADC Pro is says: ''"Do not use more than a few mA from the 3.3V line. If your circuit requires 3.3V, use the 5V power rail of the Raspberry Pi with an additional voltage regulator. Pin 27 and 28 are always reserved for an ID EEPROM on the Raspberry Pi. Independently which card you use, these pins are always reserved and should never be used to connect external components. [...] GPIO2-3 (pins 3 and 5) are used by our products for configuration. If you are experienced with I2C, you might add other slave devices. If you a a novice, we don’t recommend this at all. GPIOs 18-21 (pins 12, 35, 38 and 40) are used for the sound interface. You can’t use them for any other purpose."'' So there you go.
		+
		+
		+	===Zynthian MIDI===
		+
		+
		+	===Other purposes===

@@ Line 2: / Line 2: @@
 =The plan=
-After initially only wanting to get into this project by connecting a bare PI to a HDMI display and an external USB audio interface I considered building a custom Zynthian with a nice case and at least four encoders and stereo input and output connectors. You can read below how that succeeded.
+After initially only wanting to get into this project by connecting a bare PI to a HDMI display and an external USB audio interface I considered building a custom Zynthian with a nice case and at least four encoders and stereo input and output connectors. You can read below how that succeeded (it miraculously did).
 =Parts used=
 Parts used in this build are the following (will be specified in steps):
 * Raspberry PI5 8GB with official active cooler, official power supply and a fast SD card
 * HifiBerry DAC2 ADC Pro audio HAT
 * MCP23017 GPIO Extender
 * 4 rotary encoders
 * 8x 10nF ceramic capacitors for encoder movement debouncing
 * 4x 47nF ceramic capacitors for encoder button debouncing
 * Many little parts: DIY flat cables for display connection, Dupont cables, pin headers, permaboards and the lot
 =Planning=
 I'll act here like I had the final device already in mind when I started out. The truth is, that the design changed over the process of building oftentimes, but I don't want to bore anybody with that.
 ==GPIO accessability==
 ==GPIO usage==
 ==Cooling==
-The PI has the official active cooler mounted. In the beginning when only the PI was mounted on the display in fresh air, it got ridiculously low CPU temperature values. Things to consider:
+In this case the PI has the official active cooler mounted. In the beginning when only the PI was mounted on the display in fresh air, it got ridiculously low CPU temperature values. Things to consider:
 * Many people here swear by passive cooling connected to a metal case, because cooling works good and it has no noise. I couldn't do that, because a wooden case can't distribute heat.
 * The PI living in a case forces you to think about air ventilation within the case.
 * A HAT mounted onto the PI will raise heat considerably, because the air from the cooler cannot move so well. I had to raise the audio hat with a 9mm 40 pin header to not conflict with the cooler anyway.
 With all these things in mind: My Zynthian never exceeds 60°C CPU temperature.
 =Soldering and assembling=
 ==Audio inputs and outputs==
 ===Mouting the audio HAT===
 I chose the HifiBerry DAC2 ADC Pro, because I wanted these input connectors to use the Zynthian as an effect unit. The Board fits easily onto your PI, but if you use the official active cooler like me, you need to raise the height with some 40 pin extenders (9mm in my case).
 With this specific board you have the 40-pin DSP header on top, others may only have holes where you might need to solder a 40-pin header on top. The convenient thing is that these only copy the PI's GPIOs, so you can use it for your connections. You only have to consider which GPIOs not to use (see section "GPIO usage").
 ===Connecting the input and output jacks===
 The connectors with HifiBerry DACs are [https://www.hifiberry.com/docs/data-sheets/datasheet-dac2-adc-pro/ quite well documented].
@@ Line 42: / Line 54: @@
 Except for the DSP header which is used in this case as the extended PI GPIOs nothing more needs to be connected right now.
 ===Connecting the headphone amp===
 This will be added later. For now you can read this [https://discourse.zynthian.org/t/adding-a-high-quality-headphone-output/205 forum thread].
 ==Encoder circuit==
 ===Assembling on a prototyping board===
 First things first: This did not work for me. I put everything like I planned to do it in the correct manner, but the MCP wasn't recognized. You may succeed in prototyping with jumper cables and little parts, but putting a 26 pin MCP with two 13 pin headers on a prototyping board loosely (Picture 1) will likely not work.
 <gallery>
@@ Line 56: / Line 72: @@
 ===Soldering to a permaboard===
 So I went all in and soldered everything together.
@@ Line 106: / Line 123: @@
 =Setup=
 ==Wiring==

← Older revision		Revision as of 21:04, 3 September 2025
Line 143:		Line 143:

	To make things easier here: if you, like me, chose to use psysical pin 36 and 37, also chose that in the webconf menu.		To make things easier here: if you, like me, chose to use psysical pin 36 and 37, also chose that in the webconf menu.
		+
		+	==Audio==
		+
		+	My working setup:
		+
		+	#Audio Config
		+	export SOUNDCARD_NAME="HifiBerry DAC+ ADC PRO"
		+	export SOUNDCARD_CONFIG="dtoverlay=hifiberry-dacplusadcpro\nforce_eeprom_read=0"
		+	export SOUNDCARD_MIXER="Digital_0,PGA_Gain_Left,Digital_1,PGA_Gain_Right,ADC_Left_Input,ADC_Right_Input"
		+	export JACKD_OPTIONS="-P 70 -s -S -d alsa -d hw:sndrpihifiberry -r 48000 -p 128 -n 2 -o 2 -i 2 -X raw"
		+
		+	In the SOUNDCARD_CONFIG we chose the suitable dtoverlay for the DAC (see their instructions) and force_eeprom_read=0 because Hifiberry recommends that for PI5.
		+
		+	In the JACKD_OPTIONS you might see where I changed the sample rate to 48000Hz and the buffer size to 128 samples.

	=Building a case=		=Building a case=