A user’s guide to i2c modules/devices
A growing number of devices are making use of the i2c protocol, so here’s a simplified users guide to help monome/modular/music people navigate this sometimes confusing space.
Please add questions and comments and we can try to update the main post as needed.
what is i2c?
i2c is a communication protocol - it’s a way for devices to talk to each other, like MIDI or USB.
Some wikipedia for reference:
i2c “is a synchronous, multi-[leader], multi-[follower], packet switched, single-ended, serial computer bus invented in 1982.” “A particular strength of i2c is the capability of a microcontroller to control a network of device chips with just two general-purpose I/O pins and software.”
In the Monome/Teletype i2c ecosystem (where it’s sometimes also referred to as “ii”), i2c provides a convenient way to send commands/data between modules. In some situations reducing what could be many patch-cable connections down to a single i2c cable hidden behind the module. For example, the ER-301 can accept i2c commands on 100 different ports - so that’s 100 cv and 100 trigger controls over one cable!
how does it work?
To be really simplistic - the i2c bus consists of 3 lines - ground (GND), data (SDA) and clock (SCL). The data and clock lines are “pulled high*” via pull-up resistors. Communication happens by pulling the lines low*. What this means is that the i2c bus needs two things to operate: pull-up resistors and a power source. Teletype includes both, but depending on your set up, or if you don’t have a Teletype you might need some additional hardware - see the hardware section below for more details.
i2c specs define devices as either master or slave. However, since those terms are somewhat problematic, the Monome/Teletype i2c community uses the terms leader and follower are used instead.
leader / follower
A leader is a device that initiates communication. A follower is a device that only responds when it gets a request from a leader. Typically this means a device that controls other devices (such as Teletype) will be the leader, and the devices it controls will be followers. Every setup should have at least one leader.
A leader typically sends commands and data to followers, but in some cases it can also get data from followers. A communication in this case is still initiated by the leader asking a follower to send the data it needs. When the follower receives the request it will respond by sending the data.
How do you define which module is leader?
This is defined by the firmware. Most firmwares have a fixed role (Teletype is always a leader, for instance). Some firmwares have 2 different versions, one where it works as a leader and one where it works as a follower (16n faderbank). Polyearthsea, Ansible v3.0, Crow and others can be switched between leader/follower at any time.
Can a device be a leader AND a follower?
Yes. Crow is an example of such a device.
What happens if there are multiple leaders?
Typically there should only be one leader in any i2c setup. The specification supports multi leader setups, however it’s not currently officially supported by the monome ecosystem. In practice it should be okay to have multiple leaders as long as they don’t use i2c at the same time. There are even reports of some setups working with multiple leaders sending at the same time (even to the same follower!) but be aware that this might cause freezing which would require a power cycle (it should not cause any physical damage however).
Do I need to do anything to make a module a follower?
No! If it’s running a firmware that works as a follower that’s all you need. The only thing you might need to configure is the address. Note: Modules like the ER-301 may need some configuration to assign ports, etc.
How do followers know a leader is talking to them?
Each firmware uses its own address, so when Teletype sends a command to meadowphysics it will send it to the address assigned to meadowphysics firmware. These addresses are chosen by developers who make sure each firmware gets a unique address. What happens when there are multiple devices connected all running the same firmware? An example of that would be a setup with 4 Telexo modules for instance. In this scenario you can give each Telexo a unique address by setting jumpers on the back of the module.
What happens if you connect 2 devices running the same firmware that doesn’t support choosing a different address, like Just Friends or W/?
The chances are they will both respond.
what devices support i2c
monome teletype (leader) monome/whimsical raps crow (leader) monome white whale (depends on firmware) monome meadowphysics (depends on firmware) monome earthsea (depends on firmware) monome ansible (follower or leader) bpcmusic telexo (follower) bpcmusic telexi (follower) orthogonal devices er-301 (follower) mannequins just friends (follower) mannequins w/ (follower) sssrlabs matrixarchate (follower) 16n faderbank (follower or leader) addac 221 (follower) tesseract modular sweet sixteen (follower or leader) calsynth 16n faderbank (follower or leader) michigan synth works f8r (follower or leader) expert sleepers disting ex (follower)
intellijel tetrapad xor electronics nerdseq
what firmwares support i2c
as leader only:
as follower only:
white whale orca kria meadowphysics earthsea
as both leader and follower:
as either leader or follower:
ansible starting with 3.0 (can switch dynamically) polyearthsea (can switch dynamically) orca's heart (can switch dynamically) 16n faderbank and variations (2 different firmware versions)
what hardware do i need?
This depends on your specific setup. First of all, you will need a device/firmware that acts as a leader (see the list above), and one or more devices that will act as followers. Most of the listed devices already have i2c pins installed, but in some cases (early revisions of monome trilogy modules) you might need to solder them yourself. It’s easy to check - look for GND/SCL/SDA markings at the back of the module and see if there are pins next to them. Also, earlier revisions of er-301 require a manual mod - check here for more information.
In addition to a leader device and one or more follower devices you need something that will provide power and pull-up resistors for the i2c bus. Teletype provides both, but keep in mind that the earlier revisions (with green PCB) can only support 2-3 followers reliably, and if you get dropped connections or Teletype freezing when using i2c you might want to use a powered busboard.
If you have a later revision Teletype (black PCB) you should not need a powered busboard. With this version if you already have the busboad that attaches directly to the Teletype (aka Teletype backpack) you can still use it separately from Teletype (so that it’s not powered) as a splitter. If you do, make sure unused pins can’t accidentally touch other modules or the powerboard!
If your setup doesn’t involve a Teletype at all, you will need a powered busboard.
Finally, you will need some cables.
This is a lot of technical information, but what can you actually do with i2c? Here are some examples of typical setups:
- Teletype + monome trilogy: using Teletype for extra control of monome trilogy modules and features that are not available on standalone trilogy modules (such as external clocking for earthsea, for instance)
- Teletype + ansible: same as above, but also using ansible as 4 extra trigger and 4 extra CV outputs for Teletype
- Teletype + ER-301: sequencing and controlling ER-301 - not only you can avoid a cable mess but you can have control over a lot more parameters (up to 100 gate and 100 CV parameters)
- 16n faderbank + ER-301: using faderbank as an external controller for ER-301
- Teletype + TXi: having 4 extra knobs and 4 extra CV inputs for Teletype
- Teletype + TXo: having 4 extra gate and CV outputs, and being able to generate envelopes/LFOs from Teletype, and using TXo as 4 synth voices (with control over waveform/attack/decay/volume)
- Teletype + Just Friends: unlocking the ability to use Just Friends as a 6 voice synth
- polyearthsea on monome trilogy or ansible + ER-301 / TXo / Just Friends: being able to bypass the limited number of outputs on monome trilogy/ansible modules by directly controlling up to 8 voices on ER-301 / TXo / JF.
Some i2c devices provide power/voltage (and pull-up resistors) to the i2c bus and others do not. Teletype and crow are the only monome modules that directly provide power to the i2c bus. So if you’re using other modules aside from Teletype or crow, then you will need an external power source to make the i2c bus work. (crow’s pull-up feature is configurable in software - see crow docs for more info)
To make this easier for users, “powered busboard” expanders have been made to help - which also provide additional i2c connectors. These devices take power from the eurorack rack power supply and add 3.3v and pull-up resistors to the i2c bus. The TXb module is another i2c expander and is discussed in more detail below.
In some situations with many devices, a set of “pull-up” resistors are needed to help stabilize the i2c bus. Most of the powered busboards made by this community include 2.2K pull-ups. Unless you have a complicated setup, you probably won’t need to worry too much about this.
If you’re using Teletype with just one or two other modules, you probably do not need a powered busboard. A non-powered expander will do just fine.
- Teletype busboard
- ansible powered busboard
- ii busboard
- ii busboard (non-powered)
what is TXb?
TXb is a 2hp eurorack format powered busboard created by bpcmusic. It provides power and pull-up resistors for the i2c bus. Additionally, it serves as a minijack/i2c adapter - the main use case for this is to have the ability to connect 16n faderbank, but you could also use 2 TXb to connect i2c between different rows or cases (just remember to keep the distance short). You will need a standard 1/8" stereo minijack cable. Be extra careful to not accidentally plug a regular CV into an i2c input - doing so can damage your modules!
i2c cables are a simple 3-wire (or 6-wire) connector cable used to communicate between modules. There is no standard “i2c cable” per se, but you can make your own or get some from community members (see links below). Since there’s no standard marking for these cables, you will want to be consistent in how you decide to make connections (see below). For example - If you have colored cables, try to always use the same color (or certain colors) for ground (GND).
If you are using a TRS stereo minijack cable with a 16n faderbank or TXb module, the pin arrangement for the TRS cable with those devices is as follows:
sleeve - GND ring - SCL tip - SDA
how do i connect everything?
i2c is a bus and modules can be connected anywhere on the bus with i2c cables. Modules could be daisy-chained together (wired from module to module) or wired using single cables from a busboard to individual modules.
Most important thing is to make sure to always connect GND to GND, SCL to SCL and SDA to SDA!
Note that on early versions of the er-301 SCL and SDA are reversed, so double check you are connecting everything properly. (This applies to ER-301 with the older revision 7 hardware. This has been corrected on the newest er-301 modules.)
It’s best to keep connections short. On those modules where there are 2 pins for every line you can connect to either pin (or both). Such double pins are also convenient for daisy chaining devices - indeed, it’s recommended to daisy chain rather than use a star configuration where possible.
Monome has some instuctions on making connections (with a 6 pin ribbon cable) between Trilogy modules here:
A more complex arrangement is show here:
- Try to keep all connections as short as possible for improved reliability.
- Connect and disconnect devices only when they are powered down. If you use TXb or 16n, remember not to “hot plug” the i2c-minijack cable. (I2C just wasn’t designed to be as robust and hot-pluggable as MIDI or USB.)
- Be extremely careful not to connect regular CV, audio or MIDI cables to the I2C minijack. This could damage your devices.
- Sometimes device boot or power-up order will matter
- In practice, power your Leader device after your Follower devices.
I2C questions / discussions
Teletype I2C protocol (development)
Telex: Teletype expanders (Telex)