Appendix C: I2C Devices

The I2C standards only specify how data is sent from device to device. It does not specify the layout of the registers of a device. LEGO, however, has guidelines for 3rd party manufactures so that they can provide sensors with a (fairly) uniform register layout.

We call sensors that were designed following LEGO’s guidelines NXT/I2C sensors. This common register layout lets us autodetect the type of sensor and proves access to the sensor via the lego-sensor class.

We refer to sensors that do not conform to LEGO’s specifications as Other/I2C sensors. There are so many types of I2C chips in the wild that are already supported on Linux that we do not attempt to autodetect them. To use them, we just need to find a compatible driver and manually load it.

This page discusses both types of I2C sensors.

Addressing

I2C uses a 7-bit addressing scheme (there is also 10-bit addressing but it is not implemented in the ev3dev I2C driver). When sending an address over the bus, the address is shifted to the left 1 bit and the least significant bit is used to indicate read or write.

Note

The I2C address that is used in ev3dev is different from the other EV3/NXT programming languages/environments. This means the address in your sensors’ documentation is probably not the address that you need for ev3dev! In ev3dev (and Linux in general), we used the unshifted 7-bit address.

I2C addresses 0x01 through 0x07 (unshifted) are reserved for special use by the I2C specifications. However, these addresses are used by some sensors anyway (most notably the NXT Ultrasonic sensor). The ev3dev kernel has been patched to allow these to work, but some userspace tools will not work with devices at these addresses. For example, we distribute a patched version of the i2c-tools package to work around this.

There is a table of I2C addresses at the end of the page.

Using NXT/I2C Sensors

See the page on the lego-sensor class for general usage. This page only covers the I2C specifics.

Polling

When we say “polled”, we just mean that the EV3 brick initiates a read command to read data from the sensor. The data that is read depends on the current mode that is selected. You can change the polling rate using the poll_ms attribute (of the lego-sensor device). You can also disable polling by setting poll_ms to 0. When polling is disabled, you can initiate a data read by setting the mode again. By default, NXT/I2C sensors are polled every 100 milliseconds. The default value can be changed via a module parameter.

Direct Reading and Writing of the Sensor

Warning

Be very careful when reading from or writing to your sensors. It is theoretically possible to break them if you read or write to the wrong register.

In most cases, setting the mode of a sensor will write the proper data if necessary, so you don’t actually need to write data using this method. However, it is possible to write arbitrary data to I2C sensors using the direct attribute. Use seek to specify the register to read or write from and always specify the number of bytes to read or write.

Example: Reading the white calibration data from the mindsensors.com Light Sensor Array. This reads 8 bytes from register 0x5A.

$ hd -s $(( 0x5A )) -n 8 direct

Example: Sending a “calibrate white” command to the mindsensor.com Light Sensor Array. This just writes the ascii character W to register 0x41.

$ echo -e -n "W" | dd bs=1 of=direct seek=$(( 0x41 ))

Manually Loading Devices

If you have autodetection disabled (e.g. using the other-i2c mode of a port) or if you have managed to change the I2C address of your sensor to something other than the default or you are using something that is not even a LEGO compatible sensor, you will have to manually load a device in order to be able to use your sensor. We just have to tell the I2C adapter which driver to use and the address of the device.

The I2C adapter device nodes are at /sys/bus/i2c/devices/i2c-N where N is the number of the input port plus 2. To load a device, we write to the new_device attribute. NOTE: These nodes only exist when you have an I2C sensor plugged into an input port or the port was manually set to an I2C mode.

Example:

# echo nxt-i2c-sensor 0x0B > /sys/bus/i2c/devices/i2c-5/new_device

Using Other/I2C Sensors

As we already discussed, Other/I2C sensors generally have an existing Linux driver that you can use. This means that each sensor will work a bit differently. You can load a device just like for manually loading an NXT/I2C device, except we use a different driver name. You can find the names of drivers here.

Example: Using the mindsensors.com Realtime Clock Sensor on input port 2.

$ echo ds1307 0x68 > /sys/bus/i2c/devices/i2c-4/new_device
$ dmesg | tail
...
i2c-legoev3 i2c-legoev3.4: registered on input port 2
i2c i2c-4: new_device: Instantiated device ds1307 at 0x68
rtc-ds1307 4-0068: SET TIME!
rtc-ds1307 4-0068: rtc core: registered ds1307 as rtc1
rtc-ds1307 4-0068: 56 bytes nvram
$ cd /sys/class/rtc
$ ls
rtc0    rtc1
$ cd rtc1
$ ls
date  device   max_user_freq  since_epoch  time
dev   hctosys  name           subsystem    uevent

Now, I just need to figure out what to do with TWO realtime clocks!

Direct I2C Communication (Going Driverless)

You actually don’t need a driver to use your I2C sensors. Drivers do make it much safer and easier, but if you really want full control, it is yours for the taking. There are symlinks for each I2C adapter to make finding them easy.

$ ls /dev/i2c-in*
/dev/i2c-in2  /dev/i2c-in3

Note

The symlinks and the underlying I2C device are only present when an I2C sensor is plugged into a port. Also, if a driver is loaded for a particular I2C device, you will get an error that it is in use. You should disable probing in the nxt-i2c-sensor module (or blacklist the driver in /etc/modprobe.d).

You can use the i2c-tools package or an I2C library in your programming language of choice to communicate with I2C devices this way. You don’t want to do this if a device is already loaded so you will want to disable autodetection first if the sensor is the autodetected type. Beware that many sensors, including the NXT Ultrasonic Sensor use an address of 0x01, which is illegal according to the I2C standards. i2c-tools and any library that does some error checking may prevent you from accessing the sensor. In ev3dev-jessie, the i2c-tools package has been patched to work around this.

Practical examples

Changing the Polling Rate

Using the NXT Ultrasonic Sensor:

$ cat poll_ms
100
$ while true; do cat value0; done
22
23
26
27
30
25
...
22
24
26
26
22
22
^C
$ echo 1000 > poll_ms
$ while true; do cat value0; done
22
22
22
22
22
22
22
25
25
25
25
25
25
25
25
...
^C
$ echo 0 > poll_ms
$ cat value0 # value0 will be last value measured before polling stopped
23
$ cat value0 # move the sensor and try again
23
$ cat mode
[NXT-US-CM] NXT-US-IN NXT-US-SI-CM NXT-US-SI-IN NXT-US-LIST
$ echo NXT-US-CM > mode # reads data
$ cat value0
29
$ cat value0 # move the sensor and try again
29

^C means you have to press CTRL+C to make the loop stop.

Sample /etc/modprobe.d/nxt-i2c-sensor.conf

# Module configuration for nxt-i2c-sensor

# Uncomment this line to disable polling
#options nxt-i2c-sensor default_poll_ms=0

# Uncomment this line to disable autodetection
#options nxt-i2c-sensor allow_autodetect=N

How to find the I2C adapter node without adding 2

$ IN2_I2C_ADAP=$(udevadm info -q path -n /dev/i2c-in2)"/../.."
$ echo $IN2_I2C_ADAP
/devices/platform/legoev3-ports/in2/in2:nxt-i2c-host/i2c-legoev3.4/i2c-4/i2c-dev/i2c-4/../..

Using i2c-tools

With the mindsensors.com Realtime Clock Sensor on input port 2:

& i2cdump 4 0x68
No size specified (using byte-data access)
WARNING! This program can confuse your I2C bus, cause data loss and worse!
I will probe file /dev/i2c-4, address 0x68, mode byte
Continue? [Y/n] y
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
00: 11 35 00 01 01 01 00 03 50 71 48 60 f5 01 6b 0c    ?5.???.?PqH`??k?
10: 78 e3 2d 4e 92 6e c7 69 25 61 6b 5b 04 34 15 05    x?-N?n?i%ak[?4??
20: cc 3e 4e 4b 41 8a 59 09 1b f3 1a 2a 7c 47 a7 90    ?>NKA?Y????*|G??
30: 20 6a 95 7a 3b da 5b de 73 31 a2 3a 6e 59 ed f8     j?z;?[?s1?:nY??
40: 11 35 00 01 01 01 00 03 50 71 48 60 f5 01 6b 0c    ?5.???.?PqH`??k?
50: 78 e3 2d 4e 92 6e c7 69 25 61 6b 5b 04 34 15 05    x?-N?n?i%ak[?4??
60: cc 3e 4e 4b 41 8a 59 09 1b f3 1a 2a 7c 47 a7 90    ?>NKA?Y????*|G??
70: 20 6a 95 7a 3b da 5b de 73 31 a2 3a 6e 59 ed f8     j?z;?[?s1?:nY??
80: 11 35 00 01 01 01 00 03 50 71 48 60 f5 01 6b 0c    ?5.???.?PqH`??k?
90: 78 e3 2d 4e 92 6e c7 69 25 61 6b 5b 04 34 15 05    x?-N?n?i%ak[?4??
a0: cc 3e 4e 4b 41 8a 59 09 1b f3 1a 2a 7c 47 a7 90    ?>NKA?Y????*|G??
b0: 20 6a 95 7a 3b da 5b de 73 31 a2 3a 6e 59 ed f8     j?z;?[?s1?:nY??
c0: 12 35 00 01 01 01 00 03 50 71 48 60 f5 01 6b 0c    ?5.???.?PqH`??k?
d0: 78 e3 2d 4e 92 6e c7 69 25 61 6b 5b 04 34 15 05    x?-N?n?i%ak[?4??
e0: cc 3e 4e 4b 41 8a 59 09 1b f3 1a 2a 7c 47 a7 90    ?>NKA?Y????*|G??
f0: 20 6a 95 7a 3b da 5b de 73 31 a2 3a 6e 59 ed f8     j?z;?[?s1?:nY??
$ i2cget -y 4 0x68 0x01 | sed s/0x// # read minutes
35
$ i2cset -y 4 0x68 0x08 0x46 0x72 0x65 0x65 0x20 0x72 0x61 0x6d 0x20 0x73 0x70 0x61 0x63 0x65 0x21 i
$ i2cdump -y -r 0x08-0x16 4 0x68
No size specified (using byte-data access)
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
00:                         46 72 65 65 20 72 61 6d            Free ram
10: 20 73 70 61 63 65 21                                space!

Useful Info

Table of I2C addresses
Shifted Address
(write/read)
Unshifted Address
(hex (dec))
Notes
0x00/0x01 0x00 (0) I2C spec: General call address / START byte
0x02/0x03 0x01 (1) LEGO NXT Ultrasonic and many 3rd party sensors
I2C spec: CBUS address
0x04/0x05 0x02 (2) LEGO Energy Storage
I2C spec: Reserved for different bus format
0x06/0x07 0x03 (3) mindsensors.com Motor Multiplexer
I2C spec: Reserved for future purposes
0x08/0x09 0x04 (4) I2C spec: Hs-mode master code
0x0A/0x0B 0x05 (5) I2C spec: Hs-mode master code
0x0C/0x0D 0x06 (6) I2C spec: Hs-mode master code
0x0E/0x0F 0x07 (7) I2C spec: Hs-mode master code
0x10/0x11 0x08 (8) Some HiTechnic sensors
0x12/0x13 0x09 (9)  
0x14/0x15 0x0A (10) mindsensors.com Light Sensor Array
0x16/0x17 0x0B (11)  
0x18/0x19 0x0C (12) mindsensors.com PPS58-Nx Pressure Sensor
0x1A/0x1B 0x0D (13)  
0x1C/0x1D 0x0E (14)  
0x1E/0x1F 0x0F (15)  
0x20/0x21 0x10 (16)  
0x22/0x23 0x11 (17) mindsensors.com AbsoluteIMU Accel/Compass/Gyro
0x24/0x25 0x12 (18)  
0x26/0x27 0x13 (19)  
0x28/0x29 0x14 (20)  
0x2A/0x2B 0x15 (21)  
0x2C/0x2D 0x16 (22)  
0x2E/0x2F 0x17 (23)  
0x30/0x31 0x18 (24) mindsensors.com GlideWheel-AS Angle Sensor
0x32/0x33 0x19 (25)  
0x34/0x35 0x1A (26)  
0x36/0x37 0x1B (27)  
0x38/0x39 0x1C (28)  
0x3A/0x3B 0x1D (29)  
0x3C/0x3D 0x1E (30)  
0x3E/0x3F 0x1F (31)  
0x40/0x41 0x20 (32)  
0x42/0x43 0x21 (33)  
0x44/0x45 0x22 (34)  
0x46/0x47 0x23 (35)  
0x48/0x49 0x24 (06)  
0x4A/0x4B 0x25 (37)  
0x4C/0x4D 0x26 (38)  
0x4E/0x4F 0x27 (39)  
0x50/0x51 0x28 (40)  
0x52/0x53 0x29 (41)  
0x54/0x55 0x2A (32)  
0x56/0x57 0x2B (43)  
0x58/0x59 0x2C (44)  
0x5A/0x5B 0x2D (45)  
0x5C/0x5D 0x2E (46)  
0x5E/0x5F 0x2F (47)  
0x60/0x61 0x30 (48)  
0x62/0x63 0x31 (49)  
0x64/0x65 0x32 (50)  
0x66/0x67 0x33 (51)  
0x68/0x69 0x34 (52)  
0x6A/0x6B 0x35 (53)  
0x6C/0x6D 0x36 (54)  
0x6E/0x6F 0x37 (55)  
0x70/0x71 0x38 (56) PCF8574 IC
0x72/0x73 0x39 (57)  
0x74/0x75 0x3A (58)  
0x76/0x77 0x3B (59)  
0x78/0x79 0x3C (60)  
0x7A/0x7B 0x3D (61)  
0x7C/0x7D 0x3E (62)  
0x7E/0x7F 0x3F (63)  
0x80/0x81 0x40 (64)  
0x82/0x83 0x41 (65)  
0x84/0x85 0x42 (66)  
0x86/0x87 0x43 (67)  
0x88/0x89 0x44 (68)  
0x8A/0x8B 0x45 (69)  
0x8C/0x8D 0x46 (70)  
0x8E/0x8F 0x47 (71)  
0x90/0x91 0x48 (72) PCF8591 IC
0x92/0x93 0x49 (73)  
0x94/0x95 0x4A (74)  
0x96/0x97 0x4B (75)  
0x98/0x99 0x4C (76) LEGO Temperature Sensor
0x9A/0x9B 0x4D (77)  
0x9C/0x9D 0x4E (78)  
0x9E/0x0F 0x4F (79)  
0xA0/0xA1 0x50 (80) mindsensors.com EV3 Sensor Multiplexer
0xA2/0xA3 0x51 (81) mindsensors.com EV3 Sensor Multiplexer
0xA4/0xA5 0x52 (82) mindsensors.com EV3 Sensor Multiplexer
0xA6/0xA7 0x53 (83)  
0xA8/0xA9 0x54 (84)  
0xAA/0xAB 0x55 (85)  
0xAC/0xAD 0x56 (87)  
0xAE/0xAF 0x57 (87)  
0xB0/0xB1 0x58 (88) mindsensors.com 8 Channel Servo Controller
0xB2/0xB3 0x59 (89)  
0xB4/0xB5 0x5A (90)  
0xB6/0xB7 0x5B (91)  
0xB8/0xB9 0x5C (92)  
0xBA/0xBB 0x5D (93)  
0xBC/0xBD 0x5E (94)  
0xBE/0xBF 0x5F (95)  
0xC0/0xC1 0x60 (96)  
0xC2/0xC3 0x61 (97)  
0xC4/0xC5 0x62 (98)  
0xC6/0xC7 0x63 (99)  
0xC8/0xC9 0x64 (100)  
0xCA/0xCB 0x65 (101)  
0xCC/0xCD 0x66 (102)  
0xCE/0xCF 0x67 (103)  
0xD0/0xD1 0x68 (104) mindsensors.com Realtime Clock
0xD2/0xD3 0x69 (105)  
0xD4/0xD5 0x6A (106)  
0xD6/0xD7 0x6B (107)  
0xD8/0xD9 0x6C (108)  
0xDA/0xDA 0x6D (109)  
0xDC/0xDD 0x6E (110)  
0xDE/0xDF 0x6F (111)  
0xE0/0xE1 0x70 (112)  
0xE2/0xE3 0x71 (113)  
0xE4/0xE5 0x72 (114)  
0xE6/0xE7 0x73 (115)  
0xE8/0xE9 0x74 (116)  
0xEA/0xEB 0x75 (117)  
0xEC/0xED 0x76 (118)  
0xEE/0xEF 0x77 (119)  
0xF0/0xF1 0x78 (120) I2C spec: 10-bit slave addressing
0xF2/0xF3 0x79 (121) I2C spec: 10-bit slave addressing
0xF4/0xF5 0x7A (122) I2C spec: 10-bit slave addressing
0xF6/0xF7 0x7B (123) I2C spec: 10-bit slave addressing
0xF8/0xF9 0x7C (124) I2C spec: Reserved for future purposes
0xFA/0xFB 0x7D (125) I2C spec: Reserved for future purposes
0xFC/0xFD 0x7E (126) I2C spec: Reserved for future purposes
0xFE/0xFF 0x7F (127) I2C spec: Reserved for future purposes