A user's guide to i2c

ansible
teletype

#1

A user’s guide to i2c modules/devices

Prepared by @okyeron, @scanner_darkly and @justmat

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-master, multi-slave, 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.

Questions:

  • 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 is the only firmware right now that can be switched between leader/follower at any time.

  • Can a device be a leader AND a follower?
    The specification does allow this but this is currently not supported by any of the devices within the monome ecosystem (Polyearthsea can switch between being a leader and a follower but doesn’t support being both at the same time).

  • 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
monome white whale
monome meadowphysics
monome earthsea
monome ansible
bpcmusic telexo
bpcmusic telexi
orthogonal devices er-301
mannequins just friends
mannequins w/
sssrlabs matrixarchate
16n faderbank

confirmed planned:

crow

possibly:

intellijel tetrapad
xor electronics nerdseq

what firmwares support i2c

as leader:

teletype

as follower:

white whale
orca
kria
meadowphysics
earthsea
ansible (all apps, can also be used as a teletype expander with up to 4 devices)
telex txo (up to 8 devices)
telex txi (up to 8 devices)
just friends
w/
er-301 (up to 3 devices)
matrixarchate (up to 3 devices)

as either leader or follower:

polyearthsea (can switch dynamically)
16n faderbank (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.

examples:

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.

do I need a powered busboard?

Some i2c devices provide power/voltage (and pull-up resistors) to the i2c bus and others do not. Teletype is the only monome module that directly provides power to the i2c bus. So if you’re using other modules aside from Teletype, then you will need an external power source to make the i2c bus work.

To make this easier for users, “powered busboard” expanders have been made to help - which also provide additional i2c connectors. These busboards take power from the eurorack rack power supply and add 3.3v to the i2c bus.

The Teletype busboard attaches directly to the back of the TT module. Other variations attach to anisible or can sit in the back of your case (tt-busboard-jr).

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.

Busboards:

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!

cables

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

DIY i2c cables
Source for TT I2C Cable?
I2c cable purchase advice
I2c cable newbie question

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:
https://monome.org/docs/modular/iiheader/

A more complex arrangement is show here:
https://www.instagram.com/p/Bs7BbAvhOTg/

connection tips

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

Reference links:

I2C questions / discussions
Teletype I2C protocol (development)
https://forum.orthogonaldevices.com/t/nerdseq-i2c-er-301/2260/30 (ER-301/NerdSeq)
Telex: Teletype expanders (Telex)


Polyphonic earthsea for trilogy/ansible and er-301/just friends/txo
16n Faderbank: build help, dev suggestions
#2

if your question is not covered by the above or if anything is not clear/accurate please post here and we’ll update it - the guide is a work in progress!


TT-Busboard-Jr (a small powered i2c busboard)
#3

Fantastic layout of this information. Couple things:

  • it’s mentioned that black PCBs teletypes can use a busboard as a splitter, just don’t power it. That is slightly confusing to me as I’m not sure how you’d do that with a backpack.
  • I believe the er-301 revision that doesn’t require the mod also flips the scl/sda to the standard layout—at least I’ve been using that and it seems to work fine hah

#4

I believe this would be possible with a non-backpack busboard like my tt-busboard-jr and the ii busboard listed above or the skinny one @bpcmusic mentions here:


#5

or just use it separately without attaching it to teletype, just make sure there is no chance something might touch the exposed pins!

good to know, i’ve asked on o|d forum and we’ll update the guide once i get confirmation.


#6

Thanks for this! This is a guide whose time has come.

For the sake of completeness, is it worth noting which followers support polling or sending values back to the leader when requested?

Ansible and TELEXi do, ER-301 and TELEXo do not. I’m not sure about the others.


#7

Had a question concerning my current setup and was wondering how to connect as well as what to cover and leave covered?

I want to be able to use WW and Ansible both with JF if possible?

I have a jr I2c board from Denki as well as a dual i2c cable and singles

I’m thinking

Denki board -> WW, Ansible,JF

But not sure of combination of cables and what to leave covered and or where to plug in on the module


#8

you connect SDA to SDA, SCL to SCL and GND to GND on each module and the board. you can daisy chain devices (which is preferable) or you could connect each module to the busboard.

the guide has detailed information on how to connect, can you post what’s not clear specifically so we can adjust the guide?


#9

I guess what I’m asking here is if I wanted to connect the bus board to all of my modules like I said above

• Do I cover the unused jacks? If so with what?
• Does it matter the order if I wanted the whale and ansible to be both leaders?

Busboard w/single i2c> WW w/single i2c> Ansible w/single i2c> JF (daisy chained?) so both could control JF, if possible?

Or Busboard w/dual i2 > WW,Ansible > w/single i2c to JF

Also what other options other than polyes would this offer me?


#10

all SDAs (on ww, jf, ansible, busboard) have to be connected together, all SCL have to be connected together and all GND have to be connected together. how they are connected doesn’t really matter. some modules have double set of pins so you can use that to daisy chain. if yours don’t then just connect however possible.

yes, you would want to cover unused pins with something like a tape, or make sure nothing touches them accidentally - this is really the same logic you would apply to any electric part or module.

multiple leaders set up is covered in the guide.

as for configurations, in the case of ww/ansible/jf you can only use polyearthsea as it’s the only firmware that works as a leader on a module that is not teletype or 16n faderbank (at least right now). so it would be either ww running polyes controlling jf, or ansible running polyes controlling jf.


#12

here’s one a possible example…

Busboard --- double cable --- ansible
                         |
                          --- white whale

         --- single cable -- just friends

         --- unconnected 
            (use the header connector thing that was 
            over the pins when it shipped to you to 
            protect the pins or leave them uncovered)

They don’t really need to be in any particular order. They just need to be attaached to the i2c bus via the busboard.

Does that help?


#13

This definitely helps thanks for this!


#14

Just wanted to say thanks to @okyeron, @scanner_darkly and @justmat for putting this together. Thanks!!!


#15

Just a couple questions I hope someone can clarify.

16nfaderbank:
So currently the only way to connect the 16n i2c trs cable to Teletype is the Telexb module?
Is this the same way you would connect the 16n to Er-301?

Example setup:
Teletype backpack -> er301
Teletype backpack -> telexb -> 16n
Teletype backpack -> ansible

With this setup I would be able to use teletype as leader to read the faders on 16n and then control both the er-301 and anisble with an appropriate script?

follow up question:
Since the telexb is powered and has multiple connections, is the teletype backpack necessary? Would teletype still be leader if all the i2c device plug directly to telexb?


#16

Yes.

Yes, the i2c network doesn’t care about the configuration, so long as all SDA, SDL, and GND are connected.

No, the TT backpack isn’t necessary. You could connect everything to the TXb, provided the TXb is powered.


#17

Thanks man! Everything I wanted to know! Now if only I could get my hands on a TXb
@bpcmusic do you have timeframe of when Telexb will become available?


#18

Sales open up tomorrow!


#19

Oh damn! Just in time! That’s two for two @Justmat
I really appreciate the helpful reply’s!
Cheers


#20

Was it ever determined if the Slashes board would work as a powered bus? Can I damage anything by trying it?


#22

from the slashes page you linked to:

Additionally, it’s recommended you install a few components to provide pull-up resistance for the i2c connection. Indeed this is necessary if you only plan to use W/-to-W/ communication. If you already have a powered Teletype busboard providing the i2c connection to slashes, then pull-up components are not necessary. Otherwise, you should install them. NB: Any values between 2k2 and 4k99 are suitable for the pull-up resistors.

So yes - in theory it should work as a powered busboard if you populate the 3.3v regulator and the pulls-ups.