Adding Encoders

Encoders can be added to the Raspberry Pi to provide zynthian with an interface designed to drive the Graphical User Interface, and act as parameter controllers for any device managed by the zynthian. This is one of the zynthians key features and allows control of almost any parameter of the Audio engines that it manages.

There are a number of ways of implementing the basic zynthian encoder interface, and these have developed alongside the project. The techniques used in the early Version One days have been supplanted by more recent design and a software environment has been constructed that allows these differing approaches to be integrated with no difference between the implementations.

This is drawn form a couple of threads ...https://discourse.zynthian.org/t/encoders-directly-to-the-gpio-of-the-pi-4/4728/84 and is a work in progress nag wyleu on the forum if it seems incomplete or missing detail .

1 But what is an encoder?

An Encoder

It's a rotating control designed to provide similar functionality to a control known as a potentiometer which most people meet as a volume control. A way of easily controlling some parameter within an electronic device.Which is why the zynthian likes them so much.

There are some important characteristics it possesses, which make it highly suitable for the zynthian interface.

It is endless.

You can keep turning it forever in either direction, you will never hit a physical endstop.

But you can hit a software one.

This means the software completely controls the actual position both at the limits, you can't turn volume up more than maximum and less than silent, but you can also change to a new setting, for instance when a snapshot or sub-snapshot is loaded. If you were using a synth with potentiometers you would have to adjust each control to match the position the software would like the control to be in. There are mechanisms for this, but they involve concepts like hook or absolute which aren't very intuitive.

The Nord Modular, above, used 18 potentiometers (pots) which whilst very flexible as a machine could really be used as a patch machine. It tried various approaches but still struggled under the limitations.

The Nord Modular G2, replacement machine used Encoders, but dressed them up with the screen printing to look like Potentiometers. But you also got indiidual displays to identify the function of the encoder.

So the encoder is a much more suitable device for something like the zynth, as it can quickly and seamlessly move between patches and the control interface doesn't need to be changed from one to another. The push switch allows the navigation between parameter pages provides the other needed mechanical deice.

Offering 4 controls and a useful GUI aids this process.

A zynthian parameter page

Zynthian v5

The zynthian simply controls the Linux audio subsystem, (Jack) and it then uses the MIDI standard provided by almost all Linux audio devices to control those engines. This is very helpful because a cleverly defined GUI (and it is one) can by easy selection of different pages present virtually any audio control in the same manner. The four Encoders provide 4 parameters per page, all of which respond. This is exactly what a performing interface requires. It provides as much control as 4 encoders can when behaving like 4 volume controls. It is highly responsive. Allowing for subtle and careful parameter control. Bending a synth filter for example. But it is important to recognize that the audio Engine involved may not be prepared for such fast change. Altering a time constant in a looper over a wide range will probably have irritating sonic sound effects, as such things occur and the Engine simply can't keep up.. That's down to the Engine. zynth just delivers the information you tell it to the parameter it has selected in the GUI.

But You might well want more than 4 parameters and some of the engines provide an incredible number. Well this is where the other element of the humble Encode comes into play. The press switch component.

By pressing down on the top of an encoder a completely separate switch can be operated without any alteration of the rotating component (hopefully). This used to select the page of parameter you are to use, which is demonstrated by a grey screen activated by a short push of the encoder. This is a basic Zynthian function and it is used to indicate selection in the zynthian world. It is also why the zynth interface cannot be completely implemented into an encoder only environment. For instance rotary encoders on keyboard controllers and the like... You need the associated press witches to drive it successfully. No doubt something could be arranged but it gets pretty contrived, pretty quickly.

2 Soldering?

One thing to notice about an encoder is that you have to solder it to something.

This could be a Printed Circuit Board (PCB) or insulated wires but you will almost undoubtedly have to solder.

You will need

1. A soldering iron
   1. They have USB powered one's nowadays.
2. A soldering iron stand
   1. A crisis you can recognise once it is already a problem.
3. Solder
   1. Thin as you feel comfortable with.
4. Flux
   1. A necessity with modern Lead free solders
   2. It allows contaminates at the melted metal boundary to be extracted in what is basically a soap.
5. Good Illumination
   1. You always want to be able to see what you are doing
6. Three hands
   1. Holding the Solder
   2. Holding the Soldering Iron
   3. Holding the thing, that could well get quite hot.
7. A third hand.
   1. A stand that can grab the device as you solder it. IF you intend going near a solderable Pi connector with a soldering iron these are very useful to have.

You are joining two clean metal surfaces with a metal that melts at a considerably lower temperature. It is a purely surface effect for the wires being joined. They do not melt, only the solder does. The molten metal makes an excellent electrical bond with the surface of the wire or copper trace on a PCB when in solidifies, and if done properly protects the join from the air, preventing galvanic issues . However the emphasis is very much on the word clean. Hence the flux. So you apply the flux to all metal parts that are involved in the process. It will heat up as soon as the iron is near and boil off anything on the metal surface that could hinder the joint. It also ensures the solder, when molten, doesn't adhere to the rubbish that the boiling flux removes. All essential when making a reliable, sustainable electrical connection. Soldering has stood the test of time. You can make some fairly ropey connections, but they are surprisingly resilient. Flexible wires will often fail before the solder joint.

Remember Electrons can't see they only go where the voltages tell them. A Multimeter is the sure fire way of telling if metal thingie one is connected to metal thingie two. A Magnifying glass also helps if you are trying to see quite where the tiny bit of solder has bridged between two tracks on a piece of stripboard.

2.1 A Multimeter ?

Yes, the essential first purchase after the soldering iron. At minimum it will measure three things

2.1.1 Voltage

The potential difference in Volts between two points. Selected with a V Dc or Dc Volts setting on the control knob. A battery is an obvious example. You will see them with voltages from half a volt up to 20 Volts and more. The meter will show you the voltage. Reerse the leads notice the display now shows -20Volts. You are measuring the difference between two voltages, even if one of them os at 0V and attached to all the metal around you. Volts are always about differences.

2.1.2 Current

No of electrons flowing per second

It might be tempting to simply put the meter when set to amps across the battery we measured in Volts, but this is not a good idea. A current measurement is measuring how many electrons are flowing. And if we do this with a voltage we have just measured are then we are effectively connecting the two voltages together and as much electricity as can will flow. A SHORT CIRCUIT! Since our the electronic we have constructed does not behave like a short circuit (Hopefully!) then there must be something limiting the current. V= IR, Resistance ! The Next measurement .

So in small electrical circuits we tend not to measure too much current, because it normally involves breaking a wire to perform the measurement. Measuring current consumption of a Pi can be an indicator of problems but ensuring a reliable way of actually making the measurement with a Pi & a Multimeter can get rather involved. Best measured on a Bench Power Supply. The net purchase. . . But I digress, The Pi acts as a resistance and using the two equations of electricity

V=IR Voltage (Volts) = Current(Amps) * Resistance (Ohms)

&

W=VI Power (Watts) = Voltage (Volts) * Current (Amps)

Looking at the Zynth here I'm dring it from a 12V power supply into a hifiberry Power Amp Card.

My Bench top power supply shows a voltage of 12.27 Volts, 0.460 Amps and 5.656 Watts

The Maths checks out (fairly closely to an engineering accuracy)

12.27 * 0.460 = 5.6442

So it's right to about two decimal places 9 this is a whole area in itself...)

So we know the Pi is consuming 5.6 Watts of power.

And here's the clever bit. A Pi runs from 5V so we can calculate the Current flowing into the Pi by playing with the same equation again.

W = IV 5.64 Watts = Current * 5 Volts

So the current = 5.64/5 = 1.128 Amps

2.1.3 Resistance

Resistance is an electrical concept that simply relates current and voltage. It can have very low values 0,.001 ohms(Ω) is the resistance involved in semiconductors and we can also deal with Megaohms, the resistors used in Power Distibution. This is a incredible range of values, but for most electronic use the values are from a few Ω to 10 or so Megaohms, since these are the values resistors can be bought in.

Your meter will measure a resistor in a similar fashion to how you use a multimeter to Voltage. You set the meter to Ohms(Ω) and place the two wires on the ends of the resistor. and the meter display will show the resistance. But there is something subtly different here. To perform this measurement there must be a voltage across the multimeter wires and the meter is actually measuring the current flowing and calculating the resistance to display. So there is actually a voltage across the multimeter when set to Ω. Indeed I use it to test LED's a working as it's only 1 or 2 volts. But it isn't a proper power supply. If you measure a Pi this way you may get a reading, but don't expect that to tell you how much current the Pi will use. There are semiconductors(lots of them) in the Pi and these do not present accurate resistance readings in such cases . .

And then we come to

2.1.4 Continuity

Resistance's rougher cousin.

Frequently, for instance when soldering, you aren't worried as to what the resistance is you simply want to know that electricity has gone where you hoped it would go. And you don't want to be distracted by having to look at the meter screen, you want a noise that indicates when the two leads are directly shorted to each other.

Continuity.

It beeps when the leads are shorted. The meter displays something but I don't think anybody ever reads it. This is the mode to use to check soldering.

It checks that things that should be connected are. It checks that things that shouldn't be connected aren't.

2.1.5 Other things the Meter will measure

Some amazing facilities nowadays. Capacitance, Transistor Performance, Temperature

Very useful devices.

3 How does the zynthian understand the encoders?

Zynthian Code, obviously.

The Raspberry Pi waits to hear of a change in the encoder settings by monitoring the pins themselves, if they are directly connected to the GPIO pins or by monitoring the pins connected to the chip (MCP23017) that does this operation on behalf of the Pi over a specific connection type (I2C)

But there is a flexibility built into the system that allows it to interpret digital signals from devices connected to encoders and use that information to control the Graphical User Interface (GUI). THis is achieved using the zynthian webconf maintenance which is a web server internal to the zynthian that presents extended information for configuration and also for moving files of various sorts into and out of the zynthian's file system.

Zynthian Webconf

It also allows some quite detailed configuration of encoders in the wiring section.

Zynthian 23017 wiring

Now, obviously if you are using the zynaptik-3 then you merely have to select the appropriate configuration option in Wiring Layout and it should all just work, but if you are here you are probably rolling your own device. So you should select Custom. AS this makes no assumptions about your configuration and allows you to define your own configuration that you can save under it's own name. One of the most telling realisations one makes if you are doing this for the first time is that the details you can spend a couple of weekends puzzling over like which wire goes to which pin instantly gets forgotten as soon as it all works, and when revisited, needs to be completely worked out from first principles because you didn't make a record and you have rebuilt your zynthian from a clean software image. Do the housekeeping!

Makes notes!!

3.1 What do the numbers in the boxes mean?

It depends. The zynthian distinguishes between the various ways it can examine pins by adding 100 to the number. Connected straight to the Raspberry Pi GPIO pins are in the range 0 - 99 whilst devices using the I2C connection and an MCP23017 start at 100 and go up from there. In the first case you are specifically identifying the Pi GPIO pins connected to the encoders, in the second you are identifying the pins on the MCP23017 chip that are connected to the encoders and also describing how the I2C bus is connected to the Pi.

3.1.1 Raspberry Pi GPIO Pins

This was the original way the pins where connected to the encoders and it is still supported in the Zynthian. The Broadcom Addresses are put into the appropriate box to link the encoder to the zynth.

There is a fairly involved explanation as to why the numbers end up they way they are and not simply the number of the pin on the Raspberry Pi connector. There are two ways of addressing GPIO pins on a Pi.

The Documentation illustrates the issue

RPi.GPIO supports referring to GPIO pins using either the physical pin numbers on the GPIO connector or using the BCM channel names from the Broadcom SOC that the pins are connected to. For example, pin 24 is BCM channel GPIO8. To use physical board pin numbers, call:

GPIO.setmode(GPIO.BOARD)

and to use the BCM channel numbers, use:

GPIO.setmode(GPIO.BCM)

Either method will work. The BOARD number scheme has the advantage that the library is aware of the Raspberry Pi model it is running on and will work correctly even if the Broadcom SOC channel names change in the future.

In the zynth we use GPIO.setmode(GPIO.BCM)

So you need to use GPIO references NOT Raspberry Pi Pin numbers.

3.1.2 I2C

Simply, a recognised and agreed way to connect electronic devices together with an agreed set of rules about behaviour and a mechanism for informing the community there is a message to be transferred. It is a standard supported by both the Raspberry Pi and a range of specific IC's that do various useful things.

3.1.3 MCP23017

A 28 pin chip that manages 16 Input Output Pins via an I2C connection. There are also two Interrupt lines that allow the MCP23017 to inform the Pi that a change has occurred.

3.1.3.1 Addressing

The Software itself needs to be informed of the correct pins to examine to see the behavior it is expecting. Encoder going up and down and switches being pressed, and obviously the machine has no way of telling which encoder is which. This is all identified in the webconf wiring section.

The order in the fields are Ch (Top Left) Back (Bottom Left) , Ls (Top Right) , Select (Bottom Right)

Ch (Top Left)	Back (Bottom Left)	Ls (Top Right)	Select (Bottom Right)

3.2 Encoder Pins

Each zynthian encoder is connected to a minimum of 4 wires.

3.2.1 A Ground Wire

A wire connected to Ground or 0 Volts of the system. This is what the other encoder wires connect to to inform the MC23017 that the pin is set logic low and should be interpreted as such.Do not worry that there is no logic high connection, this is indicated by an open circuit and by the clever use of Pull Up Resistors the open circuit connection can be interpreted as a logic High. If you have an encoder with a +V connection there are separate notes on how to address this as it is a little more complicated.

So the encoder pins and the push down switch connect to 0V when operated.

3.2.2 Encoders A-pins

Encoders work by connecting and disconnecting two slightly out of phase switches as the shaft is turned. By examination of the relationship between when the switches open an close one can interpret the amount of turning that has been done and also the direction it was turned. All the information required to adjust a zynthian parameter.

This is the one of the Two pins of the encoder. If the encoder appears to go the wrong way you can either

1/ Swap the wires on the encoders (Open case, turn on soldering iron, find solder, find flux, etc. . . )

2/ Change the numbers in the webconf.

This is the flexibility on offer but obviously with such flexibility you have to be very specific. It is unlikely you will get it right first time because you have the possibilities of getting both the hardware wiring AND the configuration wrong and this can be very frustrating

Make Notes!!

3.2.3 Encoders B-pins

Simply the other pin on the end of the encoder. See Encoders A-pins

3.2.4 Encoders Switches Pins

The Push function that connects the identified pin to the zynth and operates a function in the GUI via the short, bold and long press's.

3.2.4.1 But what is all this fuss about capacitors?

One of the first things that most people delving in to controlling computers with switches is that computers of any kind and a Pi is no exception, do things very fast. So fast in fact that what may seem like an emphatic switch contact to us slow humans is actually a succession of switch bounces as the contacts meet and the computer is fast enough to detect these rapid ons and offs and if this isn't addressed interpret them as not one switch closing once but the same switch bouncing and appearing to open and close several times. This is particularly iritating in the world of encoders where the simple process of turning the encoder would become difficult to operate reliably.

There are various answers to this problem. Firstly a hardware solution. Add capacitors across the switch contact as close to the switch themselves as you can.

Add software to de-bounce the switches. Possible for the Pi doing GPIO but not so easy for an MCP23107. So capacitors are recommended to be fitted to address switch bounce.

From our leader...

These capacitors are not “critical” but “convenient”. They debounce the encoder/switch signal and avoid that software debouncing algorithm consumes “high priority” CPU cycles (ISR). I recommend to use some kind of hardware debouncing circuitry with the encoders and switches, but you can ignore my recommendation and your Zynthian probably will work without problems :wink:

And further...

The debouncing circuit in the kit’s PCb consist of 3 capacitor from the 3 signal encoder pins to ground. For the switch pin 100nF and for the 2 encoder pins, 10nF.

3.2.4.2 But what are the extra Switches s1-s4?

Because there are only 12 pins needed for the Encoders and the MCP23017 has 16 pins, there are four pins un-allocated. These 4 spare pins were set aside for 4 momentary push buttons, which could be allocated to almost any function with the configuration sections.

These are the S1 to S4 buttons that appeared with the V4 version for zynthian. These are only configurable for the MCP23017 equipped Encoder interfaces

Zynthian S1-S4 Switch config

These Extra switches are configured at the bottom of the V4 wiring page....

The move to the MCP23017 for the encoders on the zynth freed up some work that the Pi was having to do and also provided more Input pins for control and involved less wiring inside the box.

...

3.2.5 MCP23017 INT-A Pin

To reduce the effort of the Pi the MCP23017 sends an Interrupt to the Pi when something changes on it's input pins. I.E and encoder has started to turn or the Switch has been pressed or released.

3.2.6 MCP23017 INT-B Pin

To reduce the effort of the Pi the MCP23017 sends an Interrupt to the Pi when something changes on it's input pins. I.E and encoder has started to turn or the Switch has been pressed or released.

3.2.8 ADS1115 I2C Address

The I2C bus allows many devices to be connected to it and communicate. One of these devices is the ADS1115 which is a four input Analog To Digital Converter ( AtoD) which means that external voltages can be monitored and the values used to control a Zynthian parameter. A foot pedal opening and closing the filter on a synth to provide A Wah Wah effect.

3.2.9 MCP4728 I2C Address

The I2C bus allows many devices to be connected to it and communicate. One of these devices is the MCP4728 chip which is a four channel Digital to Analog Converter ( DtoA) which means that control voltages can be generated and controlled by a zynthian parameter or the sequencer and the values used to control an external voltage controlled device. So a zynthian connected foot pedal opening and closing the filter on a separate Eurorack synth via the control voltage input to provide A Wah Wah effect.

4 Which setting do I choose?

Start with custom.

And do not expect to just get it right first time. We frequently see people in pursuit of the official settings, expecting them to match and it all just works. However with the combination of hardware, often being attempted for the first time and the flexible configuration options the odds of you hitting it randomly are pretty small.

A methodical approach is what you should adopt.

First use the Select Encoder push switch. This is the most frequently used switch and attempt to just get it working. You can enter -1 ( 0 is actually a used value) into the webconf screen to get zynthian to ignore other pins. And purely concentrate on that one pin and switch. If using a MCP23017 be sure you have a recognised response from 12cdetect -y 1 whilst GPIO you will have to check rigourously. But don't attempt anything else, tempting as it might be to get anything else working.

Next add the Encoder pins for the SELECT encoder. After this you will have one encoder working and it will confirm if you have de-bounce issues or that it is going the correct way.

Then proceed to the other Encoders.

BACK is probably the next one to do Switch first encoder pins second.

If whilst doing GPIO connections you find a pin that obstinately refused to work then try a different pin. Raspberry Pi does occasional magic in this area and I've had pins that have worked perfectly in the past just stop working along with the attached encoder.

Remember

Make Notes!!

You will probably be revisiting all this for some reason, normally expansion, at some later date and it is frustrating to have to work it all out again from scratch.

5 Encoders connected using a MCP23017 chip

As an interface grows ( when 4 user definable switches were added to V4 we had already moved away from the direct encoder route in favour of a much more efficient way of reading encoders and switches, which passed off some of the effort to another piece of silicon. The MCP23017 16 port I2C multiplexer. This board meant the communication between the Raspberry Pi and this 20 pinned chip could be handled by only a few wires at the Pi end, and a standard form of communication called I2C.

The zynaptik-3 board from zynthian provides all the interfaces for encoders and the extra switches introduced, along with MIDI interfaces and Control voltage and digital ins and outs which represents the official implementation of this sort of approach.

But this isn't the only option there are several MCP23017 boards available, and you can make your own with stripboard. The zynthian will work with pretty much any of these boards as long a it presents enough Input pins to cover the encoders. Zynthian needs a minimum of 12 i/0 pins for encoders and their switches.

5.1 MCP23017 pins

The pins on the MCP23017board are connected to the pins on the encoder. Quite how they are presented is dependent on your board and what connectors it provides. A multi meter can be very useful for reassuring yourself that the actual pin on the IC is connected to the pin, whatever the labeling may say. People do make this sort of mistake and electrons don't read, they just follow electric fields .

MCP23017 Left Hand Pins

MCP23017 Pin	Function	Webconf Entry
Pin 1	GPBO	108
Pin 2	GPB1	109
Pin 3	GPB2	110
Pin 4	GPB3	111
Pin 5	GPB4	112
Pin 6	GPB5	113
Pin 7	GPB6	114
Pin 8	GPB7	115
Pin 9	Vdd +V Power
Pin 10	Vss 0V Power
Pin 11	Not Connected
Pin 12	I2C SCK Clock
Pin 13	I2C SDA Data
Pin 14	Not Connected

MCP23017 Pin out

MCP23017 Right Hand Pins

MCP23017 Pin	Function	Webconf Entry
Pin 15	A0 Address Pin	Set as part of Address
Pin 16	A1 Address Pin	Set as part of Address
Pin 17	A2 Address Pin	Set as Part of Address
Pin 18	Reset
Pin 19	INT B	Set as INT B
Pin 20	INT A	Set As INT A
Pin 21	GPA0	100
Pin 22	GPA1	101
Pin 23	GPA2	102
Pin 24	GPA3	103
Pin 25	GPA4	104
Pin 26	GPA5	105
Pin 27	GPA6	106
Pin 28	GPA7	107

5.2 How do I connect things at the Raspberry Pi End for an MCP23017?

The I2C connection requires only two wires 2nd the Raspberry Pi is specifically designed to accept an I2C connection on Pins 3 (SDA Data) & Pin 5 (SCL Clock).

Also Two Interrupt lines are also required and these can be any pin address in the webconf drop down. It defaults to

Raspberry Pi GPIO Pins

Odd Pins	Function	Function	Even Pins
Pin 1	3v3 Power	5v0 Power	Pin 2
Pin 3	I2C SDA Data Pin	5v0 Power	Pin 4
Pin 5	I2C SCL Clock Pin	0v Ground	Pin 6
Pin 7	-	-	Pin 8
Pin 9	0v Ground	-	Pin 10
Pin 11	-	-	Pin 12
Pin 13	-	0v Ground	Pin 14
Pin 15	-	-	Pin 16
Pin 17	3v3 Power	-	Pin 18
Pin 19	-	0v Ground	Pin 20
Pin 21	-	-	Pin 22
Pin 23	-	-	Pin 24
Pin 25	0v Ground	-	Pin 26
Pin 27	-	-	Pin 28
Pin 29	-	0v Ground	Pin 30
Pin 31	-	-	Pin 32
Pin 33	-	0v Ground	Pin 34
Pin 35	-	MCP23017 INT-A Pin	Pin 36
Pin 37	MCP23017 INT-B Pin	-	Pin 38
Pin39	0v Ground	-	Pin 40

5.2.1 MCP23017 I2C Address

This is where the I2C Address in defined. That is the specific I2C bus address that the MCP23017 will pay attention to, and until it is established that you are communicating with this, there is little point in attempting anything else. It proves that the MCP23017 and the Raspberry Pi are communicating correctly over the I2C bus. This can be checked by using a command line tool on the raspberry Pi which communicates with the I2C bus.

i2cdetect -y 1

ONce you have this then you can see that your MCP23017 is connected to Address A 0 . The default onfig. But you can change this if there is a conflict or your MCP23017 board has a different address set up. That's what the A0, A1 & A2 pins are for.

Conversely, if you don't see this, then you aren't ommunicating so you will need to investigate if there is something that is preventing the 12C bus working. It could be a short circuit or a broken wire or perhaps you have got the wires in the wrong order. By enlarge it's fairly forgiving and you probably haven't damaged anything, just . . .

Make Notes!!

6 Encoders directly connected to GPIO Pins

This is the original approach used from the start the Encoder were connected directly to GPIO pins on the Raspberry Pi. It is not considered as the recommended approach.

Please see the 23017 approach described above.

Zynthian-amp3-open

6.1 Connecting via the GPIO Pins.

The raspberry Pi has a 40 pin connector that provides access to a level of connection not generally available to the PC world. This allows Digital devices to be connected to a Raspberry Pi and the Pi can both receive and transmit information to these devices as digital Data. +3.3V or 0v in electrical terms.

This connector will probably exist as a standard for a considerable length of time, such is the electronic infrastructure that has grown around it. Indeed competitor boards, would dare use anything else so it's become ubiquitous, in a similar fashion to the IBM edge connectors carried on long after the company had stopped making PC's themselves.

Here's a site devoted to it.

Pi GPIO

6.1.1 Considerations

You will need to connect wires from the raspberry Pi pins to the encoders. Given it is recommended to connect capacitors across the encoder connections to reduce the bouncing that occurs when mechanical switches open and close and this is best done at the encoder end, some people construct daughter boards for each encoder with connections and sockets that are connected by Du Pont Wires with sockets on both ends. These socket based wires do work but they can easily be knocked off the pins if there is cable flexing, so it is probably better to get either a 40 pin ribbon cable or Pi ex pander board with solder pads to allow you to remove the device entirely from the Pi. This is important because you might want to transfer the Pi to do something else in later life, or more likely as you are constructing the enclosure you might well want to separate them for testing with a multi-meter, which is a tool that isn't exactly essential in these sorts of activities, but if you are new to soldering, is the authoritative way of checking that electrons actually do get from the point you believe they originate from to the place where they are going to make something happen.

6.1.2 Pins on the Pi

There are several different types of Pin presented on the Raspberry Pi 40 pin connector. The important thing to know is that there are two voltages present on a raspberry pi and genuine damage can be done to the device if this is ignored. One of the corner pins is +5Volts and this is the voltage supplied by the USB Power connector this MUST Not be connected to any of the other pins. they live off 3.3Volts and this should be honoured.

6.1.2.1 Power Supply

Raspberry Pi GPIO Pins

Odd Pins	Function	Function	Even Pins
Pin 1	3v3 Power	5v0 Power	Pin 2
Pin 3	-	5v0 Power	Pin 4
Pin 5	-	0v Ground	Pin 6
Pin 7	-	-	Pin 8
Pin 9	0v Ground	-	Pin 10
Pin 11	-	-	Pin 12
Pin 13	-	0v Ground	Pin 14
Pin 15	-	-	Pin 16
Pin 17	3v3 Power	-	Pin 18
Pin 19	-	0v Ground	Pin 20
Pin 21	-	-	Pin 22
Pin 23	-	-	Pin 24
Pin 25	0v Ground	-	Pin 26
Pin 27	-	-	Pin 28
Pin 29	-	0v Ground	Pin 30
Pin 31	-	-	Pin 32
Pin 33	-	0v Ground	Pin 34
Pin 35	-	-	Pin 36
Pin 37	-	-	Pin 38
Pin39	0v Ground	-	Pin 40

Do not take appreciable current from 3.3v Try not to run a light show for instance.

6.1.2.2 Pins not to use for GPIO

The EEPROM pins,GPIO 0 1 (Pi pins 27, 28) which are used by the Pi to recognize more complicated Devices connected to the Pi. It is strongly suggested these pins are not used. But they do work at a pinch.

And Pin 13 ( GPIO27) is used for a fan by the zynthian-pwm-fan controller. A wonderful addition that turns a mosquito buzzing always on fan into a cleverly managed fan, that just gets it right and only works hard when it has to. So if this is something you believe you need it is a good idea to leave this pin free, althou' you can configure it. Such is choice.

Be aware that the I2C pins (pins 3,5) are used for all kinds of expansions and also the correct way to do this sort of encoder addition ( 23017 uses this, and a couple of other pins).

If you have audio card then several other pins have will be used, and that is the sort of information to get from the data sheet for the card. For instance some cards use the I2C pins for parameter controls and then GPIO 18,19,20,21 ( Actual Pi Pins 12,35,38,40).

For the zynthian audio card pins to avoid are

12, 13, 15, 16, 18, 22, 35, 37, 38 & 40 which are the I2S (audio interface) pins on RPi5.

Depending on what you are trying to do other pins can be used, but it's wise to have an idea of what else was is used on your machine. If you want to try out the simplest config use an USB Audio connection and you shouldn't have to worry.

The following is an example that has worked, and below is another selection that has been proved.

It would be nice to give an emphatic set up and have that identified in the config files. If so we will maintain the information here.

Raspberry Pi GPIO Pins

Odd Pins	Function	Function	Even Pins
Pin 1	3v3 Power	5v0 Power	Pin 2
Pin 3	I2C SDA Data Pin	5v0 Power	Pin 4
Pin 5	I2C SCL Clock Pin	0v Ground	Pin 6
Pin 7	-	-	Pin 8
Pin 9	0v Ground	-	Pin 10
Pin 11	-	Zynthian Audio Card Pin	Pin 12
Pin 13	GPIO 27 FAN Control	0v Ground	Pin 14
Pin 15	Zynthian Audio Card Pin	Zynthian Audio Card Pin	Pin 16
Pin 17	3v3 Power	Zynthian Audio Card Pin	Pin 18
Pin 19	-	0v Ground	Pin 20
Pin 21	-	Zynthian Audio Card Pin	Pin 22
Pin 23	-	-	Pin 24
Pin 25	0v Ground	-	Pin 26
Pin 27	GPIO 0 (EEPROM SDA)	GPIO 0 (EEPROM SCL)	Pin 28
Pin 29	-	0v Ground	Pin 30
Pin 31	-	-	Pin 32
Pin 33	-	0v Ground	Pin 34
Pin 35	Zynthian Audio Card Pin	-	Pin 36
Pin 37	Zynthian Audio Card Pin	Zynthian Audio Card Pin	Pin 38
Pin39	0v Ground	Zynthian Audio Card Pin	Pin 40

6.1.2.3 General GPIO pins

The available GPIO pins that can be used.

Raspberry Pi GPIO Pins

Odd Pins	Function	Function	Even Pins
Pin 1	3v3 Power	5v0 Power	Pin 2
Pin 3	GPIO 2	5v0 Power	Pin 4
Pin 5	GPIO 3	0v Ground	Pin 6
Pin 7	GPIO 4	GPIO 14	Pin 8
Pin 9	0v Ground	GPIO 15	Pin 10
Pin 11	GPIO 17	GPIO 18	Pin 12
Pin 13	GPIO 27	0v Ground	Pin 14
Pin 15	GPIO 22	GPIO 23	Pin 16
Pin 17	3v3 Power	GPIO 24	Pin 18
Pin 19	GPIO 10	0v Ground	Pin 20
Pin 21	GPIO 9	GPIO 25	Pin 22
Pin 23	GPIO 11	GPIO 8	Pin 24
Pin 25	0v Ground	GPIO 7	Pin 26
Pin 27	GPIO 0	GPIO 1	Pin 28
Pin 29	GPIO 5	0v Ground	Pin 30
Pin 31	GPIO 6	GPIO 12	Pin 32
Pin 33	GPIO 13	0v Ground	Pin 34
Pin 35	GPIO 19	GPIO 16	Pin 36
Pin 37	GPIO 26	GPIO 20	Pin 38
Pin39	0v Ground	GPIO 21	Pin 40

6.1.2.4 Specialized GPIO Pins

Here is where it gets confusing. The Pin that is connected to the Pi edge connector is connected to a range of GPIO Pins that are not in any particular order, and these are subsequently wired to the pins on the BCM processor that does all this work and they have ANOTHER Mapping which the zynthian references. It's done that way to make it processor based not Pi based. There are two settings in software that works on the machine that decides which particular addressing mode is being used.

The appropriate pins for the Raspberry Pi pins are listed in the webconf columns.

6.1.2.5 Some settings that have been proved to work

A confirmed good configuration 17/02/2025

Pin allocation

Another set of setting that have worked.

So a V4 implementation (Two encoders either side of the touchscreen) would look something like this. . .

Make sure to select advanced in the top of the page to get the extended detail view, and select custom to get the basic view that allows configuration.

Zynthian-gpio-encoders-amp3-trimmed

The ordering of the Encoders in the Webconf above is

Raspberry Pi GPIO Pins

Encoder Pin	Odd Pins	Webconf	Function	Function	Webconf	Even Pins	Encoder Pin
-	Pin 1	-	3v3 Power	5v0 Power	-	Pin 2	-
-	Pin 3	8	GPIO 2 I2C SDA	5v0 Power	-	Pin 4	-
-	Pin 5	9	GPIO 3 I2C SCL	0v Ground	-	Pin 6	0V
Select B Pin	Pin 7	7	GPIO 4	GPIO 14	15	Pin 8	Select A Pin
-	Pin 9	-	0v Ground	GPIO 15	16	Pin 10	Back Switch
-	Pin 11	0	GPIO 17	GPIO 18	1	Pin 12	-
L/S Switch	Pin 13	2	GPIO 27 FAN Control	0v Ground	-	Pin 14	0V
L/S B Pin	Pin 15	3	GPIO 22	GPIO 23	4	Pin 16	L/S A Pin
-	Pin 17	-	3v3 Power	GPIO 24	5	Pin 18	-
-	Pin 19	12	GPIO 10	0v Ground	-	Pin 20	0V
-	Pin 21	13	GPIO 9	GPIO 25	6	Pin 22	-
-	Pin 23	14	GPIO 11	GPIO 8	10	Pin 24	-
0V	Pin 25	-	0v Ground	GPIO 7	11	Pin 26	-
-	Pin 27	30	GPIO 0 (EEPROM SDA)	GPIO 1 (EEPROM SCL)	31	Pin 28	-
Back B Pin	Pin 29	21	GPIO 5	0v Ground	-	Pin 30	0V
Select Switch	Pin 31	22	GPIO 6	GPIO 12	26	Pin 32	Back A pin
Channel Switch	Pin 33	23	GPIO 13	0v Ground	-	Pin 34	OV
-	Pin 35	24	GPIO 19	GPIO 16	27	Pin 36	Channel Pin B
Channel Pin A	Pin 37	25	GPIO 26	GPIO 20	28	Pin 38	-
OV	Pin39	-	0v Ground	GPIO 21	29	Pin 40	-

So the settings displayed below are

Raspberry Pi GPIO Pins

Label	Ch (Top Left)	Back (Bottom Left)	Ls (Top Right)	Select (Bottom Right)
A Pins	25	26	4	15
B PINS	27	21	3	7
SWITCH	23	16	2	22

6.1.2.6 Out in the wild

This has been working pretty hard doing audio at things.

It sat in a church for over a month playing sound effects, operated by little old ladies, Well turned on and off by them.

No reported problems. Homebuild is viable.

Zynthian-amp3rr

Zynthian-amp3-open

Just to prove it can be done on GPIO pins here it is in all it's glory. That's a hifiberry Amp on top of the Pi3 and it all fits in a case with a external 12- 18V supply powering it all. Which is sometimes a battery. The red heat shrink is evidence of a changing manifested on some Pi software update. ... and chains used to be called layers. . .

7 Other nefarious methods

Other methods can be accommodated

4 RGB i2c Encoders and A Blue Pill STM32

using the zynthian's inbuilt Control Device interface.