How to get started building I2C-based drivers

[kasperl]

Get started building an I2C-based driver

To show how to get started building drivers for I2C-connected peripherals, let's build a driver for the SparkFun Qwiic Joystick. We connect the joystick to the ESP32 with a Qwiic cable and a simple I2C setup — here using pin 21 for SDA (blue) and pin 22 for SCL (yellow).

The datasheet for the joystick shows the important registers like the default address and the button position:

The code required to start interacting with the SparkFun Joystick is less than 30 lines of Toit code:

import gpio
import i2c
import serial

main:
  bus := i2c.Bus
      --sda=gpio.Pin 21
      --scl=gpio.Pin 22
  device := bus.device SparkFunJoystick.I2C_ADDRESS
  joystick := SparkFunJoystick device
  joystick.on

  while true:
    print "Pressed: $joystick.pressed"
    sleep --ms=250

class SparkFunJoystick:
  static I2C_ADDRESS ::= 0x20

  static REG_DEFAULT_ADDRESS_ ::= 0x00
  static REG_BUTTON_POSITION_ ::= 0x07

  registers_/serial.Registers

  constructor device/serial.Device:
    registers_ = device.registers

  on:
    reg := registers_.read_u8 REG_DEFAULT_ADDRESS_
    if reg != I2C_ADDRESS: throw "INVALID_CHIP"

  pressed -> bool:
    return (registers_.read_u8 REG_BUTTON_POSITION_) == 0

You can read more about the driver and how to expand it do deal with more of the joystick functionality in here.

[justind000]

Writing drivers for various devices will need a read and write that doesn't send the register address with every transaction.

Some devices require more register-pointer management. You can see one example of this in Sparkfun's AS7341X driver. There are others that will require this method. The SHT30 series of temperature/humidity sensors is one, they don't make use of registers, as can be seen here. It accepts 16 bit commands then a request will send the measurements

The AS7341X device requires a <start><write register pointer><stop><request> be sent. It looks like Toit is currently using commands like this, <start><write register pointer><START><request>.

If I'm following the code correctly, it appears that passing a -1 for the register address skips sending it, however at another point in the code, it will throw an exception when it sees -1.

[andersjohnsen]

As you point out, 8-bit register devices are fairly common but far from covers all use cases. You can thus do most[1] operations directly on the device itself. So instead of using the registers abstraction (device.registers) you can use device.read and device.write directly.

Let's take the example of a 16-bit register device, as you mention. To write a 1-byte value to a 16-bit register we simply do:

device := i2c.device I2C_ADDRESS
device.write #[cmd >> 8, cmd, value]

And to read from the same register, we first write the command and then issue the read.

device := i2c.device I2C_ADDRESS
device.write #[cmd >> 8, cmd]
value := device.read 1

If you take a look at the Toit SHT31-D driver, that's exactly how it's accomplished here: https://github.com/harshkc03/sht31-d_driver/blob/main/src/driver.toit#L126

I hope this helps. And if you indeed finds limitations that can't be worked around, let us know and we'll find a way to make it work :)

[1] We currently don't support multiple start/stop in one I2C sequence. It would make sense to find a way to introduce this, if really needed.

[lask]

I may be missing the point here, but how does that ensure the correct sequence of starts and stops as in the AS7341X example?

[andersjohnsen]

This will ensure the correct sequence of events, but add a timing gap between the intermediate stop/start. However, as I understand these devices (and the I2C spec in general), this is allowed.

[justind000]

Using device.read/write was what I was thinking, just didn't see it. I put together a quick bh1750 (ambient light sensor) using them.

@lask I haven't followed the call stack, but I am assuming that each plain read/write will come with the correct start/stop conditions. I haven't connected a LA to the lines to ensure, but from my bh1750 test just now, it appears to be working as expected (by me anyway).