Using the I2C Protocol
The I2C protocol protocol allows for multiple (slave) devices to be controlled by one or more master devices using only two wires to transmit the data.
1 The I2C Protocol Explained
I2C is a serial communication protocol which means the data is transferred bit by bit which means the speed of communication is relatively slow, typically around 100 kbps in slom mode rising to up to 5Mbps in ultra-fast mode. The two pins are:
- SDA – Serial Data, the line that is used to send and receive the data.
- SCL – Serial Clock, the line used to carry the clock signal.
Each connected device is assigned a 7 bit address (27 unique addresses available) which is built into the hardware which means in normal circumstances only one device of each type can be connected in the same network although some devices allow the address to be changed to one of a fixed number of values. The address of a device should be found in its datasheet and some sites such as Adafruit publish a master list.
Each message sent through the I2C bus is preceeded by an address frame which tells the bus which device the data is for. This is read by all the devices and, if the address does not match, the data that follows is ignored. Once the address frame has been sent, this is followed by one or more 8 bit Data Frames, each followed by an ACK/NACK checksum bit to ensure the data was received correctly.
In this tutorial we will configure the I2C interface so that you can both send and receive data. By the end of section 3 section you should have a screen that displays the computer host name and ip address whenever you power it on. Section 4 shows how to capture data from an I2C enabled sensor. The materials assume you have already built a base server by following the instructions in the Getting Started tutorial. If you have not completed this do it now.
2 Enabling the I2C Interface
Out of the box the I2C interface is disabled by default. Out first step is therefore to enable this interface.
Start by running the raspi-config command. This time access the interface options and choose Enable/Disable automatic loading of I2C kernel module to enable I2C. After exiting the tool you need to reboot. We are now no longer logged in as root but rebooting requires root permissions. Since we are part of the sudoers group we can run a command with root privileges by prefixing it with the sudo keyword.
After enabling the interface exit the raspi-config tool, you will be asked to reboot the server and this will be needed to activate the I2C interface.
When it has rebooted, log in.
2.1 Fixing I2C Permissions
By default, the I2C bus is only accessible if you use root permissions. The problem is that we don't want to run all our python scripts as root! To fix this you need to edit the /lib/udev/rules.d/60-i2c-tools.rules file using the nano text editor.
sudo nano /lib/udev/rules.d/60-i2c-tools.rules
Notice that we have to edit the file with root privileges. The Raspberry Pi includes two I2C buses, labelled i2c-0 and i2c-1, We will be using bus 1. Replace the existing contents with the following:
KERNEL=="i2c-0" , GROUP="i2c", MODE="0660"
KERNEL=="i2c-[1-9]*", GROUP="i2c", MODE="0666"
This splits this so that the permissions are retained for interface 0 but every user can access all the others (bus 1).
2.2 Changing the I2C Baud Rate
By default the I2C bus runs at a slow 100Kb/s speed however the Raspberry Pi has a "fast mode" (400Kb/s) driver. To enable this we need to edit the /boot/config.txt file using root privileges:
sudo nano /boot/config.txt
modify the following line:
dtparam=i2c_arm=on,i2c_arm_baudrate=400000
Having made our changes we need to restart the server.
2.3 Scanning for I2C Devices
There is a command called i2cdetect which scans an I2C but looking for attached devices. We will be using I2C bus 1 so we run the following command:
$ sudo i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --
As you can see, no devices are detected. You should now move on to either section 2 where we configure a small OLED screen or section 3 where we configure a simple sensor and read in data from it.
3 Connecting an OLED Screen
Now lets check the I2C bus is configured correctly by wiring up a small OLED screen. You should find one in your electronics kit. Notice that it has 4 pins labelled GND, VCC, SCK, SDA. These need to be connected to the matching pins on the Raspberry Pi header. Below you can see the pins labelled. This labelling applies to both the RPi v2 and v3. If you look carefully at the diagram you can see that the pins connected to the I2C-1 bus are clearly labelled:
- Pin 6 is labelled
GND, this should be connected to theGNDpin on the screen. - Pin 4 is labelled
5V PWR, this should be connected to theVCCpin. - Pin 5 is labelled
I2C SCL, this should be connected to theSCKpin. - Pin 3 is labelled
I2C1 SDA, this should be connected to theSDApin.
If we run the i2cdetect command again we should see that the screen is detected and is using I2C address 0x3c.
$ sudo i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --
This demonstrates both that the i2c bus is configured correctly and that the screen is working.
3.1 Writing to the Screen
Finally we can create a simple python script to test out the screen. We first need to install a couple of packages and then some libraries. The first is the Adafruit SSD1306 library that is needed to control the screen.
sudo apt install -y python-pip python-imaging python-dev python-smbus
git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git
cd Adafruit_Python_SSD1306
sudo python setup.py install
The second is the GPIO library that needs to be installed using the pip package tool:
sudo pip install RPi.GPIO
Create a new script in your home directory on the Raspberry Pi and call it oled.py. Open it in the nano editor and paste in the contents of oled.py which you can find in the exercises/01_rpi/ directory, save and exit from nano.
At the moment the script is not executable so, before running it we need to set the execution flag on the file:
chmod +x oled.py
./oled.py
If you look at the screen you should see a message...
3.2 Running a Script at Boot
The final task in this section is to create a script that displays the hostname and ip address on the screen when the raspberry pi first boots. The first task is to create a script in the /bin/ directory.
sudo nano /bin/network.py
Copy in the contents of the network.py script, save and quit nano. Now you need to make the file executable.
sudo chmod +x /bin/network.py
If we want the script to run automatically we need to add it as a cron task. We do this by running the crontab -e command, this opens the crontab file. Add the following to the end:
@reboot python /bin/network.py &
This tells the crontab to run the script when the device boots. The & character runs the script in the background. Try rebooting the server, you should see the information displayed as soon as the reboot is complete.
4 Reading Data from a Sensor
Many common sensors make use of the I2C protocol which makes it very easy for us to add them to our
In this task you will be adding a TSL2561 light sensor that will allow you to measure the ambient temperature.