Introduction to the device-to-device bus
The Inter-Integrated Circuit (I2C) bus is a chip-level serial communications mechanism that operates over just two wires. Some developers pronounce the bus’ name eye-two-see, others eye-squared-see, but both refer to the same thing. Devised by Philips in the early 1980s, I²C was established to standardize communications between the company’s chips, but it has since become a de facto standard supported by many microcontroller devices from Arduino boards to the Raspberry Pi and, of course, imps.
I²C itself comprises two wires. One I²C line transmits data, the other the clock signals that synchronize the conversation between devices. The data line is called ‘SDA’, the clock line ‘SCL’.
Typically, both SDA and SCL are each connected to a 3.3 or 5V power line through a single ‘pull-up’ resistor, one on each line. This is necessary because devices’ SDA and SCL connections are ‘open drain’ lines: they can force the voltage on the line to 0V, or ‘low’, but can’t raise it to 3.3V, or ‘high’. High and low are the electrical representations of the 1s and 0s that are the fundamental components of digital information. Adding these two resistors — and the bus needs only two, no matter how many devices are connected to it — ensures the voltage rises back to 3.3V without a short circuit.
I²C insists devices have open drain lines to ensure no component-harming high currents are able to flow when two devices try and signal simultaneously.
In most cases, you will be expected to add these resistors yourself, but some devices, typically those that operate at 3.3V, include them in order to be compatible with devices supplying 5V. Remember, you only need a pair of pull-up resistors per bus, so it may be necessary to remove pull-up resistors attached to other devices on the bus. Though the imp has internal pull-up resistors of its own, these are too weak to be useful for I²C and so they are automatically disabled when its pins are set to handle I²C signals.
The I²C bus separates devices into ‘masters’ and ‘slaves’. Only one device can send out timing pulses on the SCL line at a time, and that’s the one chosen to be the master device. All the others synchronize their timings to the master, and are thus considered slaves. The master — typically the imp — and its slaves can all transmit and receive data, but only the master can tell the slave when to transmit data back.
In order for one I²C device to communicate with another on a one-to-one basis, both devices need to be uniquely identifiable. This identity is the device’s I²C address. I²C addresses are usually 7-bit numbers, so a bus can comprise up to 127 devices in all. A byte comprises eight bits, of course, and so the extra bit is used to indicate whether the signal is being sent by the master to the slave — a ‘write’ — or in the other direction — a ‘read’. This eighth bit is actually bit zero in the address byte sent out onto the bus. The 7-bit address is placed in bits one through seven of the address byte.
In keeping with this format, the imp API takes an I²C addresses as an 8-bit value. Device suppliers usually give their products’ addresses as a 7-bit number, so it’s necessary to convert the address from seven bits to eight. This is a achieved with Squirrel’s << operator, which moves a number’s individual bit values to the left:
If we start with the value 0x47 (71 in decimal), A is its binary representation. Applying Squirrel’s shifts the component bits one step to the left, as in B. Now the value is 0x8E (142)
This process is the equivalent of multiplying by two. In code, this process looks like this:
local sevenBitAddress = 0x39; local eightBitAddress = sevenBitAddress << 1;
Squirrel automatically sets bit zero to the correct I²C-defined value: 0 for a write operation, 1 for a read. Now you’re ready to use one of the imp’s i2c methods to write data to the bus:
The 7-bit address of the device to which you want your imp to communicate with will be supplied by the component’s manufacturer and listed on the device’s datasheet. It may not be fixed, but selected from a range of addresses according to the voltage applied to another of the devices pins. For example, a TAOS TSL2561 light sensor has three possible addresses: 0x29, 0x49 or 0x39, depending on whether its ADDR pin is fixed at 0V, 3.3V or ‘floating’ between the two. We say the value is floating because it has not been actively selected to operate at a specific voltage; it could be anything from 0 to 3.3V inclusive.
The I²C bus’ master uses a device’s 7-bit address to signal the component it wants to talk to. In fact, the signalling is more complex than that, but fortunately all the details are handled by the imp so that you need only supply the address as an 8-bit value.
If you’re writing to the device, you also need to supply the data to write, which often include register values which instruct the device what to do with the data. The imp API documentation refers to these registers as sub-addresses:
local integerValue = 0xFFEA; local dataString = format("%i", integerValue);
Reading information from a device may require a command to tell the device which data to fetch. Telling the imp to read data from the I²C bus also involves providing a third parameter, the number of bytes you expect to receive:
i2c.read(eightBitAddress, controlDataString, numberOfBytesToRead);
Behind these operations are the I²C’s electrical signals, applied to the SDA line synchronized with the timing pulses applied to the SCL line. Writing to the bus involves a start marker: dropping SDA to 0V while SCL is 3.3V. Changing the SDA voltage when the SCL’s voltage is high defines start and stop markers. If the SDA voltage doesn’t change while SCL is high, I²C devices know that data, rather than markers, is being sent.
SDA now goes high or low to send out each bit of the address byte: the 7-bit device address followed by the read/write bit. The byte’s bits are sent out left-most bit — the ‘most significant bit’ — first, with SDA going high if the bit’s value is 1 or low if it is zero. The slave will now pull SDA low to signal acknowledgement of receipt of the data, and then out goes eight bits of control information or data, followed by more data if necessary. There is an single-pulse ‘ack’ acknowledgement pause on SDA between every eight bits sent, timed to a ninth SCL pulse. If the slave doesn’t acknowledge receipt this way, the master will detect that SDA has remained high and will signal an error.
When data flows from the slave to the master, the master likewise acknowledges the receipt of eight bits by pulling SDA low on the ninth SCL pulse unless this is the final byte of a batch, in which case the master does not pull SDA low — it makes a ‘nak’ signal, or ‘no acknowledgement’ — in order to let the slave know it has finished.
When we’re done, SDA goes high as a stop marker.
The start of transmission is indicated by SDA dropping from High to Low voltage (the rectangle on the left),
stop by the reverse (the right rectangle). SCL must be High when this takes place
The standard clock speed for I²C communications is 100kHz — 100,000 SCL pulses per second. It’s possible to go faster, up to 400kHz. Some devices may not be able to support this speed; check the datasheet that accompanies the device you want to connect to your imp. However, many slow devices use a technique called ‘clock stretching’ to force faster devices to work to their speed. Essentially, they hold SCL low while they are fetching the data you want them to send to the imp. The master detects this, releases the SCL line and waits until SCL goes high again before continuing. The imp supports devices that make use of this technique.
However, you may need to lower the I²C speed yourself if the electrical characteristics of your set-up slow down the speed of the transition between 0V and 3.3V, called the ‘rise time’. This is often caused by long wires, which increase the capacitance of the circuit. In order for the devices to successfully detect the transmission of each bit, the bus needs to run more slowly. Data corruption or unexpected results are the clues you should look out for. Reduce the I²C bus speed until the data is being successfully read.
The imp API currently provides four pre-defined clock values: 10, 50 100 and 400kHz. They are selected by passing a constant to the I²C configuration method as a parameter:
where the value of speedConstant is one of
The i2c object in the example lines of code given above is not provided directly by the imp, but chosen by you according to which of your chosen imp’s pins you’ll be using for I²C communications. Each type of imp has multiple I²C buses, all made available at start-up. Check out the pin mux for the type of imp you are using to see which I²C objects are available to you. Here, we’ll assume you are using an imp001. The imp001’s two I²C buses are on pins 1 and 2, and pins 8 and 9, respectively instanced as properties i2c12 and i2c89 of the hardware object when the imp starts up. Pins 1 and 8 are assigned to SCL, 2 and 9 to SDA.
It is commonplace to reference your choice with a global variable:
i2c <- hardware.i2c12; i2c.configure(CLOCK_SPEED_100_KHZ);
The following code works with the TAOS TSL2561 visible and infrared light sensor, a 3.3V device that uses I²C to communicate with its host microcontroller. The chip’s datasheet can be downloaded from the Adafruit website. Adafruit sells the chip on a low-cost breakout board which includes suitable pull-up resistors on the power pin, VCC. This means it’s ready to connect directly to an imp’s I²C pins.
Adafruit’s TSL2561 breakout board
Note After this article was written, Adafruit updated its TSL2561 sensor board. The new version works with the current code.
Here is the code, for the agent and then the device:
The agent code responds to an incoming HTTP request by notifying the device that it requires a reading. For simplicity, the reading is simply displayed in the log.
The device code reads the sensor and calculates a lux value according to the math set down in the TSL2561 datasheet. The first part of the program sets up constants for the TSL2561’s key registers and settings, including its I²C address options. Other constants are used in the luminosity conversion process.
Wiring up the imp
At the program start point, the code aliases one of the imp’s I²C pin set as a global variable, configures the bus speed to 100kHz and then shifts the TSL2561’s I²C address one bit to the left so it’s ready to be used with the imp I²C functions. It then sets up the sensor. Just to check this has worked, we read the control register: the return value should be 3 if the TSL2561 has just started up, or 51 if the device has already been switched on.
Next, the code sets the sensor’s ADC resolution through the TSL2561’s timing register, and then sets the signal gain to high.
Finally, we tell the imp how to respond to
"sense" notifications from the agent. This calls a function which reads the TSL2561’s two light sensors, digital values for which are stored in the chip’s four 8-bit ADC registers. The first two give a 16-bit combined optical and Infra-Red reading, the second pair a 16-bit IR-only value. The functions readSensorAdc0() and readSensorAdc1() convert the individual register values into 16-bit numbers by multiplying the most-significant byte by 256 and adding the value of the least-significant byte. The multiplication is performed by the shifting the eight-bit number’s bits left eight places with Squirrel’s << operator.
The code then provides both of these readings to a third function to calculate a final luminosity, ‘lux’ value.