02 Using the I2C Protocol.md

# Using the I2C Protocol

In this tutorial we will configure the I2C interface so that you can attach sensors that make use of it. By the end of this section you should have a screen that displays the computer host name and ip address whenever you power it on. We will also explore 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.

## 1 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.

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

### 1.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.

### 1.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.

## 2 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.

### 2.4 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...

### 2.5 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.

## 3 Reading Data from a Sensor

In this task you will be adding a GY-61 ADXL335 / 345 Module which can be used to measure the angle of the raspberry pi.

- TC74 temperature sensor
- VEML6070 UV light sensor
- TSL2561 light sensor
- 4 channel ADC
- BMP280 temperature/humidity (also SPI)
- HMC5883L Compass