How to write a driver

We are using the SparkFun Qwiic Joystick as an example of how to write a driver - in the Toit language - for a sensor. The SparkFun Qwiic Joystick is a 2-axis joystick with a single button. Using a Qwiic connector, it's very simple to get the joystick connected.

This guide will walk you through the steps of identifying how the sensor communicates and how to write a fully working driver for it.

Approach

The Joystick features an ATtiny85 microcontroller with a custom firmware. As described in the Hookup Guide, the firmware exposes several registers. With that in mind, we're going to do the following steps:

Connect the Joystick to an I²C bus, configuring the I²C device.
Use the Registers abstraction to communicate with the chip.
Validate connectivity to the device.
Read out Axis and Button values.

I2C setup

We use a simple I²C setup, currently using pin 21 for SDA (blue) and pin 22 for SCL (yellow).

import gpio
import serial.protocols.i2c as i2c

main:
  bus := i2c.Bus
    --sda=gpio.Pin 21
    --scl=gpio.Pin 22

Driver skeleton

As all I²C/SPI drivers that work using registers, the driver starts with the following skeleton.

import serial

class SparkFunJoystick:
  static I2C_ADDRESS ::= 0x20

  registers_/serial.Registers

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

  on:

  off:

The hookup guide has a table of I²C registers available in the custom firmware. At address 0x00 is the slave address assigned to the device (hard-coded to 0x20).

Validate connectivity

By reading the I2C_ADDRESS register, we can confirm the connectivity to the device is functional.

class SparkFunJoystick:
  static REG_DEFAULT_ADDRESS_ ::= 0x00

  // ...

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

With this added, we can validate the setup:

main:
  // ...

  device := bus.device SparkFunJoystick.I2C_ADDRESS

  joystick := SparkFunJoystick device

  joystick.on
  print "SparkFunJoystick"

Running the code should print out the string SparkFunJoystick to the terminal. If not, the I²C bus is not configured to match the wiring.

If the Joystick is connected without the full breakout board from SparkFun, I²C pull-up resistors may be needed.

Read out data

We're going to expand the driver with 3 new methods:

class SparkFunJoystick:

  // ...

  /**
  Returns the horizontal value in the range [-1..1].
  */
  horizontal -> float:
    // ...

  /**
  Returns the vertical value in the range [-1..1].
  */
  vertical -> float:
    // ...

  /**
  Returns true if the button is pressed.
  */
  pressed -> bool:
    // ...

Both the horizontal and vertical values are formatted the same way; 2 bytes in big endian order (MSB first). We want to transform this value to a float in the range [-1..1]. Let's create a helper function to perform this step:

The last 6 bits of the result are unused, but to keep the code simple we treat the result as an 16-bit unsigned integer.

import binary
import serial

class SparkFunJoystick:

  // ...

  read_position_ reg/int -> float:
    value := registers_.read_u16_be reg
    // Move from uint16 range to int16 range.
    value -= binary.INT16_MAX
    // Perform floating-point division to get to [-1..1] range.
    return value.to_float / binary.INT16_MAX

With that in place, we can now finish the horizontal and vertical methods:

  // Continuing class SparkFunJoystick:
  static REG_HORIZONTAL_POSITION_ ::= 0x03 // (to 0x04)
  static REG_VERTICAL_POSITION_ ::= 0x05 // (to 0x06)

  // ...

  horizontal -> float:
    return read_position_ REG_HORIZONTAL_POSITION_

  vertical -> float:
    return read_position_ REG_VERTICAL_POSITION_

Lastly, we need to implement the pressed method. We're simply going to read out the 1-byte register value and check for 0, with 0 meaning pressed.

  // Continuing class SparkFunJoystick:
  static REG_BUTTON_POSITION_ ::= 0x07
  // ...

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

Let's try it out:

main:
  // ...

  joystick.on
  while true:
    print "$joystick.horizontal - $joystick.vertical (pressed: $joystick.pressed)"
    sleep --ms=250

This code will run until aborted (Ctrl-C).

As the joystick is moved around, it's possible to get an I²C error if the I²C bus is accidentally short-circuited by the fingers.

To improve responsibility, the sensor should be read at a higher frequency. However no printing should be done at higher frequencies to avoid logging data building up.

Full code

The driver

driver.toit

import binary
import serial

class SparkFunJoystick:
  static I2C_ADDRESS ::= 0x20

  static REG_DEFAULT_ADDRESS_::= 0x00
  static REG_HORIZONTAL_POSITION_ ::= 0x03 // (to 0x04)
  static REG_VERTICAL_POSITION_::= 0x05 // (to 0x06)
  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"

  off:

  /**
  Returns the horizontal value in the range [-1..1].
  */
  horizontal -> float:
    return read_position_ REG_HORIZONTAL_POSITION_

  /**
  Returns the vertical value in the range [-1..1].
  */
  vertical -> float:
    return read_position_ REG_VERTICAL_POSITION_

  /**
  Returns true if the button is pressed.
  */
  pressed -> bool:
    return (registers_.read_u8 REG_BUTTON_POSITION_) == 0

  read_position_ reg/int -> float:
    value := registers_.read_u16_be reg
    // Move from uint16 range to int16 range.
    value -= binary.INT16_MAX
    // Perform floating-point division to get to [-1..1] range.
    return value.to_float / binary.INT16_MAX

The Toit application running on your device

main.toit

import gpio
import serial.protocols.i2c as i2c

import .driver

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 "$joystick.horizontal - $joystick.vertical "
        + "(pressed: $joystick.pressed)"
    sleep --ms=250