02 Using the I2C Protocol.md

# 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:

1. **SDA** – Serial Data, the line that is used to send and receive the data.
2. **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](https://learn.adafruit.com/i2c-addresses/the-list) 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:

1. Pin 6 is labelled `GND`, this should be connected to the `GND` pin on the screen.
2. Pin 4 is labelled `5V PWR`, this should be connected to the `VCC` pin.
3. Pin 5 is labelled `I2C SCL`, this should be connected to the `SCK` pin.
4. Pin 3 is labelled `I2C1 SDA`, this should be connected to the `SDA` pin.

![Raspberry Pi 2 Pinout](exercises/.images/rp2_pinout.png)

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.

## References

- [Basics of the I2C Communication Protocol](http://www.circuitbasics.com/basics-of-the-i2c-communication-protocol/)