No work for me to do there then…

#!/bin/bash
HOST=$1

got=`ifconfig eth1 | egrep -o "inet addr:152.78.[0-9]{1,3}\\.[0-9]{1,3}"`
got+=`ifconfig eth0 | egrep -o "inet addr:152.78.[0-9]{1,3}\\.[0-9]{1,3}"`

if [[ "$got" == "" ]]
then
    ssh uglogin.ecs.soton.ac.uk nc $HOST 22
else
    nc $HOST 22
fi

About 10 builds and 20 reboots later, I found the commit in which the problem was happening, and then read some stuff about USB etc (the LWN device drivers book proved invaluable yet again) and subsequently generated a patch. I’ve sent it to (what I think are) the right places.

If you can’t wait for the next kernel release (if it passes review…), then you can rebuild the ti_usb_3410_5052 module by downloading this tarball, untarring it and then running “make” in the resulting directory, and then “make install” as root. You will need enough of your kernel’s sources hanging around to do this. In Fedora, these are provided in the kernel-devel package.

Update (5th April ’08): The patch has made its way into Linus’s tree, so I think it’ll be in 2.6.25.

I clicked “Yes” (I’d click “always”, but this was on a Live CD so it wouldn’t really have meaning), and then it popped up with:

Pretty cool. It didn’t ask me for any of my details, which I think is cool. Going to kerneloops.org reveals that it exists to track which crash signatures occur the most.

I had a quick search for audio converters for GNOME, and found AudioFormat and audio-convert-mod. audio-convert-mod is in the Fedora repos, so I used that. It was surprisingly enjoyable. It automatically detected the encoders and decoders that were available on my system:

The program takes the form of a wizard, which first asks for the files to convert, then the format to convert to, and the destination directory. Then it converts them. That’s it, no hassle.

R.

#!/bin/bash                                                                     

KEY=`cat ~/.ssh/id_rsa.pub`

ssh $1 bash <<EOF
mkdir -p ~/.ssh
chmod u=rwx,g=,o= ~/.ssh
echo $KEY >> ~/.ssh/authorized_keys
chmod u=rw,g=,o= ~/.ssh/authorized_keys
EOF

It can be run like this:

% ./sendkey remoteusername@remotehost

15/02/2007 Update: I fixed the script so that it made the .ssh directory first… kind of important.

29/02/2007 Update: Klaus pointed out that it might be useful to write how to generate one’s ssh keys:

/usr/bin/ssh-keygen -t rsa -f ~/.ssh/id_rsa -N ''

KERNEL=="i2c-[0-9]*", GROUP="i2c"

(You can stick that in a file in /etc/udev/rules.d if you’re using Fedora).

It uses features of the dynamic linker (the thing that’s resposible for loading the shared libraries that a program needs during execution – see man ld.so) to interpose a monitoring function between a call to a library function and the actual library function. When read(), write() or open() are called, an event is logged.

You can get iomon by checking it out like so:

git clone http://xgoat.com/proj/fiu/iomon/iomon.git/

You can build it by just running “make”:

% cd iomon
% make

You might need to install the glib 2.0 headers (in Fedora, they’re in the glib2-devel package).

Example Usage

I thought it might be useful to demonstrate how to use it with an example. After building iomon, build the following C program (also available here) using gcc:

#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>

int main( int argc, char** argv )
{
        int f, g;

        umask( 000 );
        f = open("test-file1", O_RDWR | O_CREAT);
        g = open("test-file2", O_RDWR | O_CREAT);

        write(f, "test", 4);
        write(g, "second file", 11);

        return 0;
}

This is the program that we’re going to monitor. As you can probably see, the program just opens a file called “test-file1″ and another called “test-file2″. It then writes “test” and “second file” to the first and second file respectively. Not really a very useful program, but it will suffice for this demo.

The next thing to do is set the LD_PRELOAD environment variable to contain iomon.so. The dynamic linker needs to be able to find the shared object file, and so the easiest thing to do is to put the full path into LD_PRELOAD:

% cd iomon
% export LD_PRELOAD=`pwd`/iomon.so

Now every time that you run a program in this shell, iomon.so will be loaded first. At the moment iomon will default to dumping all the read, write and open calls to standard output in raw format. I suggest that you don’t run anything in this mode… iomon is configured through the IOMON environment variable. This takes a list of arguments just like any command line program:

% IOMON="--help" cat /dev/null
Usage:
  iomon [OPTION...] 

iomon

Help Options:
  -?, --help         Show help options

Application Options:
  -f, --file         File to monitor access to.
  -l, --log          Log file
  -t, --text-log     Log in text, instead of binary
  --times            Include times in the log

There’s some helpful information on how to use it. I’ll explain the arguments in a little more detail:

• -f FILE, --file FILE
  Instead of logging all file access, just log access to FILE. iomon will monitor calls to open() to get the file descriptor assigned to FILE, and will only log calls to read() and write() that use that file descriptor. At the moment, iomon only supports one file descriptor per file (patches welcome!).
• -l FILE, --log FILE
  Send log output to FILE, rather than standard output.
• -t --text-log
  This makes the log human-readable. All data is converted into readable hex strings before writing to the log file.
• --times
  Prepend every log event with a timestamp. The timestamps are relative to the first interposed function call. Only implemented for text-based output (--text-log)

Right! Now we can run the test program:

% IOMON="-t --times -f test-file2" ./test
0.000016 open: 74 65 73 74 2D 66 69 6C 65 32
0.000138 write: 73 65 63 6F 6E 64 20 66 69 6C 65

And there we see the call to open for test-file2, followed by the filename in hex. Then there’s the data sent to it through write() also in hex. The logged call to open() happened 16μs after the first call to open(), and the write() call we were interested in happened 122μs later.

Hopefully I’ll be writing about why I needed this utility later.

The Basics

Linux has an i2c subsystem. This provides methods for interacting with I²C clients connected to the same bus as the machine running Linux. As far as I know, Linux can only be a master at the moment. If you’ve got an I²C client that needs to interact with your Linux system then you’ve got two options. The first is to write a driver as a Linux kernel module. This is (surprisingly) straightforward but isn’t what I’m going to focus on here. The second method is to use the “i2c-dev” kernel module. This lets you interact with your devices from userspace and is what I’ll be covering here. If you want to write a kernel driver, then there are good sources of information for this lurking around the place – also have a look in Documentation/i2c/writing-clients in the Linux source.

Preparing your system

The first thing to do is to make sure that the kernel that you’re going to be running this program under has the “I2C device interface” driver either compiled in or as a module. The Linux build config option for this is CONFIG_I2C_CHARDEV. The second thing that you need to make sure you have is the i2c-dev.h header file from the lm-sensors project. For some reason, it took me a whlie to realise that this header file needed to come from there. Download their tarball and find the header somewhere in there. This header file contains some inline functions that wrap around the ioctls of the /dev/i2c-N device files that the i2c-dev kernel driver creates.

When one has both the i2c-dev module and the kernel module for the I2C adapter loaded, a device file called /dev/i2c-0 (or /dev/i2c-1, /dev/i2c-2 etc.) will be created. It’s important to note that it will only be created if you’re running udev. You might need to run:

% mknod /dev/i2c-0 c 89 0

Which will create the device file.

Opening the device

In your program, you’ll need to open the device file for the i2c adapter:

        int fd;
        fd = open( "/dev/i2c-0", O_RDWR );

After checking for opening errors, the next stage is to set the address of the I2C slave that we want to communicate with:

#define ADDRESS 0x38

...

        if( ioctl( fd, I2C_SLAVE, ADDRESS ) < 0 )
        {
                fprintf( stderr, "Failed to set slave address: %m\n" );
                return 2;
        }

To get that I2C_SLAVE constant you'll need to include the i2c-dev.h file I wrote about above.

Operations

So now that we've set the address, then only thing that remains is to actually interact with the device. There are two ways of doing this:

1. Using read() and write(). Every time you do one of these an entire I2C transaction takes place (i.e. start bit, address, data, stop).
2. Using the wrapper functions that i2c-dev.h provides.

The read() and write() method is fairly straightforward so I won't go over it here. i2c-dev.h provides many functions to do various i2c transactions. I'll go over them in a moment - first I'll provide an example of how to write a single byte to the I2C client:

    if( i2c_smbus_write_byte( fd, 0xAA ) < 0 )
        fprintf( stderr, "Failed to write 0xAA to I2C device: %m\n" );

This example writes the byte 0xAA to whatever address was configured using the I2C_SLAVE ioctl. All of the functions in i2c-dev.h will return a number less than 0 upon failure. errno will get set accordingly.

SMBus functions

SMBus is a protocol that defines a set of ways for using an I²C bus. i2c-dev.h provides a function for each of these operations. The best place to read about these is in the SMBus spec in section 5.5 "Bus Protocols" - it has nice pictures.

• i2c_smbus_write_quick( int file, __u8 value)
• i2c_smbus_read_byte(int file)
• i2c_smbus_write_byte(int file, __u8 value)
• i2c_smbus_read_byte_data(int file, __u8 command)
• i2c_smbus_write_byte_data(int file, __u8 command, __u8 value)
• i2c_smbus_read_word_data(int file, __u8 command)
• i2c_smbus_write_word_data(int file, __u8 command, __u16 value)
• i2c_smbus_process_call(int file, __u8 command, __u16 value)
• i2c_smbus_read_block_data(int file, __u8 command, __u8 *values)
• i2c_smbus_write_block_data(int file, __u8 command, __u8 length, __u8 *values)
• i2c_smbus_read_i2c_block_data(int file, __u8 command, __u8 *values)
• i2c_smbus_write_i2c_block_data(int file, __u8 command, __u8 length, __u8 *values)
• i2c_smbus_block_process_call(int file, __u8 command, __u8 length, __u8 *values)

Given the SMBus spec and the list of functions, it's quite easy to decide what each of them does. If you're in any doubt, then look for comments in i2c-dev.h around the function. Some of the functions above read data that's less than 32 bits in length yet return a 32 bit number. This is so that an error can be returned. If the returned value is 0 or above then just cast it into a type of the correct size.

Gotchas

During development, there were a few things that caught me out. I also introduced a couple of other people into using this interface and they got caught out by some things too. Hopefully I'll assist some others by listing those problems here.

The i2c-dev.h header file

The i2c-dev.h header file comes from the lm-sensors project. You'll need to grab this from their source.

I²C addresses are 7 bits wide

Apart from the rare 10-bit I²C addressing that some devices employ, all I²C addresses are 7 bits wide. Until I discovered the error of my ways, I would write addresses down as the 7-bit number shifted left by one bit to create an 8-bit word. Basically all I²C devices that do address encoding/detection (including the Linux Kernel) take the address as a 7-bit number.

So if your I2C address was all '1's, you would write it as 0x7F - not 0xFE.

Load the modules

There's almost always this short period just after I've booted a LInux device in which I'll try to use I² but nothing will work. Then I remember that I need to load the right modules - the one for the I²C controller itself and i2c-dev for the userspace interface. I know it's simple, but for some reason I always forget.

Use Checksums

Always use checksums. SMBus already defines a method of generating checksums. They're also supported by the Linux kernel. You can enable them using an ioctl:

if( ioctl( fd, I2C_PEC, 1) < 0)
{
fprintf( stderr, "Failed to enable PEC\n");
return -1;
}

Disable them by changing the argument to the ioctl to 0.

Block transfers

After painstakingly implementing SMBus block read/write on my I²C client, I discovered that the SMBus block transfers weren't supported by the I²C driver for my machine's adapter. So always check that the I²C driver supports the types of transfer that you want to do using the I2C_FUNCS ioctl.

The Linux kernel documentation

The documentation in the /Documentation/i2c directory of the Linux source is a good source of information about using I²C under Linux.

Examples

You want examples? Ok. My Student Robotics colleagues and I have been writing various test utilities that you might like to have a look at. I'm not guaranteeing that they work of course!

I hope this was helpful. I'd be most interested in hearing any feedback that you have.

i2c-tiny-usb:

I’ve just come across Till Harbaum’s i2c-tiny-usb design. Rather surprisingly this uses a relatively cheap ATtiny45 Atmel AVR and nothing else. It bitbangs the USB protocol. Apparently, this works rather well. What’s even more exciting, is that there’s a kernel driver available for the i2c-tiny-usb. This makes it behave as a proper Linux i2c bus device, so interacting with it from software couldn’t be simpler. This board can be an I2C master with clock speeds of up to 50KHz.

OSIF

The Open Source InterFace (OSIF) is part of the OpenServo project, and I believe was designed by Barry Carter. Carter took the i2c-tiny-usb design, and adapted it to use an AVR with more pins, and upped the maximum I2C clock speed to 400KHz. Furthermore, the board has support for serial (I think UART), 6 GPIO lines and an ADC channel. Barry Carter sells the OSIF for £20 a board.

Carter also provides a kernel driver for the OSIF as well :-D

I bought an OSIF earlier today. I like the way that the OSIF uses work from two previous open hardware projects to create and sell the results. More on how it goes when I get it…