RIoT Core: Working with I2C

RIoT provides actors built on top of Pi4J’s capabilities which allow access to I2C devices.

To communicate with an I2C device, RIoT will need you to specify which I2C bus to use, which address the device uses on that bus, and what the protocol between the Raspberry Pi and the I2C device is:

The bus number used by the Paspberry Pi is typically 1. Other devices may have more busses, typically numbered starting with 0.
I2C devices normally have one preset address, or will allow you to switch between a few preset addresses by setting some of its pins high or low (to do this, connect them to VCC or GND).
The protocol is either raw if the RIoT application wishes to directly read and write bytes to rthe device, or special class than encapsulates a particular protocol (more on these later).

‘Raw’ access to the I2C bus

To access an I2C bus directly, use I2C’s rawDevice() method, specify the bus and address, and finish with asFlow (for an Akka Streaming component) or asProps (to use a regular Akka Actor):

Props props = I2C.rawDevice().onBus(1).at(0x23).asProps();
ActorRef rawDevice = system.actorOf(props);
rawDevice.tell(RawI2CProtocol.Command.write(0x14, (byte) 0x86), self());

The underlying actor will accept 2 commands: RawI2CProtocol.Command.write(...) and RawI2CProtocol.Command.read(...). It will reply with a RawI2CProtocol.Result message, which will be empty for a write operation, or will contain the result of the Read operation.

The actor will reply to the sender of a RawI2CProtocol.Command with the RawI2CProtocol.Result. Similarly, a Flow component will recieve RawI2CProtocol.Command messages, and will emit RawI2CProtocol.Result messages in return.

Accessing an I2C device

In RIoT, a ‘protocol class’ encapsulates the specific protocol for a device, defining the commands that can be issued to it, and describing how these commands are implemented (by reading and writing through the bus to the device).

On the caller side, this class need only be instantiated (possibly passing some additional settings specific to the device) and passed to the I2C object through the device(...) method. Typically, this class will also define constants containing the default addresses the device uses, and the commands it will accept from the caller:

Props props = I2C.device(BMA280.class)
                 .onBus(1)
                 .at(BMA280Constants.DEFAULT_ADDRESS)
                 .asProps();
           

ActorRef bma280 = system.actorOf(props);
bma280.tell(BMA280.Command.SELFTEST, self());

The Actor will respond to a Command object sent by the caller with a Response. The format of both Command and Response will typically be defined within the Protocol class.

Similarly, Akka Streams components can be built using the asFlow(...) method. The Flow component will accept the Commands messages defined in the protocol class, and emit a Response message in return:

Flow<BMA280.Command, BMA280.Results, NotUsed> bma280 = 
     I2C.device(BMA280.class)
        .onBus(1)
		.at(BMA280Constants.DEFAULT_ADDRESS)
		.asFlow(system);

// Send a READ command every 500 millis...
Source<BMA280.Command, ?> timerSource = Source
        .tick(Duration.ZERO, Duration.ofSeconds(1), BMA280.Command.READ);

// ...then print out the measurement to the console
timerSource.via(bma280).to(logSink).run(mat);

Implementing an I2C protocol

Interacting with an I2C device is done through a series of read and write operations. In RIoT, this is encapsulated in a Protocol class, which describes how this interaction happens at startup, shutdown, or in response to messages:

public interface I2CProtocol<I, O> extends Protocol<I, O> {

	void init(I2CDevice dev) throws IOException;

	O exec(I2CDevice dev, I message) throws IOException;

	void shutdown(I2CDevice dev) throws IOException;

}

The Protocol class should specify the type of message it will accept (the generic type I above), and the type it will send as a response (O).

Often, protocol classes will be able to execute more than just one operation. In this case, possible strategies are specifying a superclass as the type, or an enum:

public class BMA280 implements I2CProtocol<BMA280.Command, BMA280.Results> {
   ...
   
   // Use an enum for the commands
	public static enum Command {
		READ, CALIBRATE, SELFTEST
	}

   // Use a superclass for the results
	public static class Results {
	}
	
	// Some commands will return this subclass
	public static class Measurement extends Results {
		//...
	}
	
	public void init(I2CDevice dev) throws IOException {
		//...
	}

	public Results exec(I2CDevice dev, Command command) throws IOException {
		switch (command) {
		case SELFTEST:
         //...
         return new Results();
		case CALIBRATE:
         //... 
         return new Results();
       case READ:
		default:
		  /...
		  return new Measurements(...);
	}

	@Override
	public void shutdown(I2CDevice dev) throws IOException {
		//...
	}

Parameters that are used in configuring the I2C device can be passed to the constructor of the Protocol class, and kept in member variables, so that they are available when the init() method is called. Instead of constructing Streams components and Actors usiong a class name, they are then constructed using an instance of the protocol class:

// Configure a BMA280 device 
BMA280 bma280config = new BMA280( 
		BMA280Constants.AccelerometerScale.AFS_2G, 
		BMA280Constants.Bandwidth.BW_500Hz, 
		BMA280Constants.PowerMode.normal_Mode, 
		BMA280Constants.SleepDuration.sleep100ms);

Flow<BMA280.Command, BMA280.Results, NotUsed> bma280 = 
     I2C.device(bma280config) //instead of 'BMA280.class'
        .onBus(1)
		.at(BMA280Constants.DEFAULT_ADDRESS)
		.asFlow(system);

The Protocol Descriptor

In addition, each Protocol requires a ProtocolDescriptor object, returned by the getDescriptor method:

public interface Protocol<I, O> {

	ProtocolDescriptor<I, O> getDescriptor();

}

This contains the class name of the input and output message, and the maximal time that can elapse between a command message is received, and a response is sent:


@Override
public ProtocolDescriptor<Command, Results> getDescriptor() {

	return new ProtocolDescriptor<Command, Results>(
	        Command.class, 
	        Results.class, 
	        Timeout.apply(1, TimeUnit.SECONDS));
	
}

This class can be expanded in future relase to contain more metadata about the protocol.

Documentation

‘Raw’ access to the I2C bus

Accessing an I2C device

Implementing an I2C protocol

The Protocol Descriptor