Adding Encoders

From ZynthianWiki
Jump to navigation Jump to search

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.

Nord-modular

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.

Nord-modular-G2

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.

The Zynthian -prototype
A zynthian parameter page


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. The molten metal makes an excellent electrical bond with the surface of the wire or copper trace on a PCB. 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.

3 How does the zynthian understand the encoders?

Code, obviously. 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 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.2 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.2.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.5 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....

Zynthian-v3
Zynthian-v4




3.2.6 MCP23017 INT-A Pin

3.2.7 MCP23017 INT-B Pin

3.2.8 Zynaptik Config

3.2.9 ADS1115 I2C Address

3.2.10 MCP4728 I2C Address

4 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 below.

Zynthian-amp3-open


5 Encoders connected using a MCP23017 chip

As an interface grows ( when 4 user definable switches were added to V3 (?) 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.

Zynaptik-3.jpg


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 109
Pin 2 GPB1 110
Pin 3 GPB2 111
Pin 4 GPB3 112
Pin 5 GPB4 113
Pin 6 GPB5 114
Pin 7 GPB6 115
Pin 8 GPB7 116
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 101
Pin 22 GPA1 102
Pin 23 GPA2 103
Pin 24 GPA3 104
Pin 25 GPA4 105
Pin 26 GPA5 106
Pin 27 GPA6 107
Pin 28 GPA7 108



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


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


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

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

5.3.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).

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 - 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 GPIO 27 FAN Control 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 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 - - Pin 36
Pin 37 - - Pin 38
Pin39 0v Ground - Pin 40
5.3.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 (EEPROM SDA) GPIO 1 (EEPROM SCL) 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
5.3.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.

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

GPIO-Working.png



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

6 Other nefarious methods

Other methods can be accomodated using the zynthian's inbuilt Control Device interface.