Llosa de Viango Tollos – tollosI2C.c

Introduction

Features

Getting started

Download


Libraries

  Tollos libraries

  Device libraries

    boards

    microcontrollers

    peripherals


Background

  Sample application

  Troubleshooting

tollosI2C.c – I2C bus functions for Tollos

Functions to read and write data from I2C bus devices, in I2C master mode (the microcontroller is the Master):

  • Get functions to read one or more bytes from registers (using the convention that a data byte is first written to identify the register), or to read one byte directly
  • Put functions to write one or more bytes to registers (using the convention that a data byte is first written to identify the register), or to write one byte directly
  • a PutGet function to write an arbitrary number of data bytes followed by a read of an arbitrary number of bytes (this is the ‘low level’ I/O supported by I2C)
  • a test/debug function to scan an I2C channel for devices.

Where these functions take a ‘device’ parameter, this is the i2c channel number (bus interface, 0, 1, 2, etc.) combined with the 7-bit I2C physical address by shifting the channel number left 16 bits and ORing it with the 7-bit device physical address. The 16-bit shift allows for 10-bit I2C device addresses; however the latter are not yet supported.
Functions
 i2cGetByte   read a byte from a device
 i2cGetReg   read a byte from a register in device
 i2cGetRegs   read bytes from registers in device
 i2cPutByte   write a byte to a device
 i2cPutGet   general I2C low-level O/I function
 i2cPutReg   write a byte to a register in device
 i2cPutRegs   write bytes to registers in device
 i2cScan   scan I2C channel for devices

i2cGetByte – read a byte from a device

int i2cGetByte(uint device, byte *get);

device – channel and 7-bit physical address of the device

get – place to store the byte read

returns 0 if OK, negative if an error occurred

i2cGetReg – read a byte from a register in device

int i2cGetReg(uint device, byte reg, byte *get);

device – channel and 7-bit physical address of the device

reg – register (start address) to be read

get – place to store the byte read

returns 0 if OK, negative if an error occurred

i2cGetRegs – read bytes from registers in device

int i2cGetRegs(uint device, byte reg, byte *get, uint len);

device – channel and 7-bit physical address of the device

reg – register (start address) to be read

get – place to store the bytes read

len – number of bytes to be read

returns 0 if OK, negative if an error occurred

i2cPutByte – write a byte to a device

int i2cPutByte(uint device, byte put);

device – channel and 7-bit physical address of the device

put – byte to be written

returns 0 if OK, negative if an error occurred

i2cPutGet – general I2C low-level O/I function

int i2cPutGet(uint device, byte *put, uint putlen, byte *get, uint getlen);

device – channel and physical address of device (channel shifted left 16 bits and ORed with 7-bit or 10-bit I2C physical address); currently only 7-bit addresses are supported

put – start of byte(s) to write

putlen – count of byte(s) to write [may be 0]

get – start of byte(s) to read

getlen – count of byte(s) to read [may be 0]

returns 0 if OK, negative if an error occurred

put is ignored if putlen is 0 (NULL recommended). get is ignored if getlen is 0 (NULL recommended).

This function effects a lower-level I2C bus operation. First, putlen bytes are written to the device. Next, the device is addressed with a request to read, and getlen bytes are read.

For many devices the first data byte written to the device is a register address, and then a continuing write writes to that register and a read reads from that register.

i2cPutReg – write a byte to a register in device

int i2cPutReg(uint device, byte reg, byte put);

device – channel and 7-bit physical address of the device

reg – register (start address) to be written

put – byte to be written

returns 0 if OK, negative if an error occurred

i2cPutRegs – write bytes to registers in device

int i2cPutRegs(uint device, byte reg, byte *put, uint len);

device – channel and 7-bit physical address of the device

reg – register (start address) to be written

put – address of bytes to be written

len – number of bytes to be written

returns 0 if OK, negative if an error occurred

i2cScan – scan I2C channel for devices

int i2cScan(uint device1, uint device2);

device1 – device address of first device to scan

device2 – device address of last device to scan [>= device1]

returns count of devices found, or −1 if an error

Both device addresses must be in the same channel (i.e., their most significant 16 bits are identical).

This scan reads ‘register 0x00’ at each device address in the requested range, and reports (using debugf) any device that responds to that read.

By convention, many devices return a ‘who am I’ value for a read from register 0x00, however – because a read of a register is itself a convention (write register then read a byte) – the results of this scan should be interpreted carefully.

Tollos and these web pages were written by Mike Cowlishaw; Please send me any corrections, suggestions, etc.
All content © Mike Cowlishaw, 2010–2012, except where marked otherwise. All rights reserved. The pages here are for non-commercial use only (see the separate licence for Tollos source code). Privacy policy: the Speleotrove website records no personal information and sets no ‘cookies’. However, statistics, etc. might be recorded by the web hosting service.

This page was last updated on 2011-11-18 by c2wiki.