# Maple Reference Documentation: i2c

### Note

The i2c interface is currently only available from the 'i2c' branch of libmaple in our github repositories.
i2c is a crude and easy-to-hack serial protocol that requires only two wires/channels for communication between many devices. Every message passed on the bus is between a Master (who initiates the message) and a Slave device. Slaves are addressed using 7-bit addresses (up to 127 unique devices); 10-bit addressing is possible but currently unimplemented. Every message consists of an arbitrary combination of 8-bit reads and writes as requested by the Master; higher level functionality, such as reading a particular register value, is achieved by writing to set the memory location then reading to pull out the data.

Note that the Master/Slave designation is on a message-by-message basis. The Maple can act as both a Master (messages initiated by user code) and Slave device (responding to requests via configurable interrupt handlers) at the same time.

- Hardware/Circuit Design
- Function Reference
- Recommended Reading

## Hardware/Circuit Design

The Maple has two i2c ports. Port 1 (i2c1) has SDA on header D9 and SCL on D5; Port 2 (i2c2) has SDA on D30 and SCL on D29.

The Maple reliably communicates with up to a 400kHz clock speed; this doesn't translate into a 400kbps data rate except in extreme cases because of addressing and protocol overhead. We have tested clock speeds up to a megahertz and have had mixed results; in theory it could be possible to achieve even higher rates but signal quality degrades rapidly and the bus becomes unreliable.

Proper wiring and pull-up resistor selection are essential when incorporating i2c into a circuit, especially with datarates above 100kHz. In the lab we usually use ~5k ohm resistors with Vcc (3.3v) as the high voltage and try to connect the pullup voltage as close to the SDA and SCL pins as possible. We recommend looking at the reference website listed below, starting with a slow clock rate (10kHz), and if possible using an oscilloscope to debug any issues.

## Function Reference

The function API for i2c is not finished! See the source code for now.

## SMBus

The stm32 microcontroller has hardware support for SMBus, we simply have not written software for it. The SMBAL line for i2c1 is on header D4 and for i2c2 is on D31.

## Recommended Reading

- i2c-bus.org
- Wikipedia Article on i2c
- Arduino i2c/TWI reference
- STMicro documentation for STM32F103RB microcontroller:
  - All
  - Datasheet (pdf)
  - Reference Manual (pdf)
  - Application Note on Advanced i2c Usage

### About this Document

A more recent version of this document may be available from the LeafLabs website. Our documentation is versioned on github; you can track changes to the master branch at this link.

This documentation is released under a Creative Commons Attribution-Share Alike 3.0 license.

Translations are welcomed; give us a ping to make sure we aren't in the process of revising or editing first.