i2c  1.4.2
RoadNarrows Robotics I2C Package
Classes | Macros | Typedefs | Functions
i2c.h File Reference

Low-level I2C communication level. More...

#include "rnr/rnrconfig.h"
#include "rnr/i2c-dev.h"

Go to the source code of this file.

Classes

struct  i2c_struct
 I2C Bus Handle Type. More...
 

Macros

#define I2C_ADDR_NONE   ((i2c_addr_t)(-1))
 no I2C address selected
 

Typedefs

typedef ushort_t i2c_addr_t
 I2C Device Address Type.
 
typedef struct i2c_struct i2c_t
 I2C Bus Handle Type.
 

Functions

int i2c_open (i2c_t *i2c, const char *device)
 Open the host I2C Bus device. More...
 
void i2c_close (i2c_t *i2c)
 Closes an I2C Bus. More...
 
int i2c_read (i2c_t *i2c, i2c_addr_t addr, byte_t *buf, uint_t len)
 Read from an I2C device. More...
 
int i2c_write (i2c_t *i2c, i2c_addr_t addr, const byte_t *buf, uint_t len)
 Write to an I2C device. More...
 
int i2c_transfer (i2c_t *i2c, i2c_addr_t addr, const byte_t *write_buf, uint_t write_len, byte_t *read_buf, uint_t read_len)
 Perform a transfer with an I2C device. More...
 
int i2c_exists (i2c_t *i2c, i2c_addr_t addr)
 Test the existance of a device at the given address on the given I2C Bus. More...
 
int i2c_scan (i2c_t *i2c, int(*callback)(i2c_t *i2c, i2c_addr_t addr, void *context), void *context)
 Scans the given I2C Bus to find all connected devices. More...
 

Detailed Description

Low-level I2C communication level.

LastChangedDate
2016-01-28 14:19:12 -0700 (Thu, 28 Jan 2016)
Rev
4278

This file has been modified from the original i2ccom.h source (see below).

Author
Robin Knight (robin.nosp@m..kni.nosp@m.ght@r.nosp@m.oadn.nosp@m.arrow.nosp@m.s.co.nosp@m.m)
Copyright
© 2007-2017. RoadNarrows LLC.
http://www.roadnarrows.com
All Rights Reserved
Original Header:
See "Original Source Header EULA" in source file.

Definition in file i2c.h.

Function Documentation

void i2c_close ( i2c_t *  i2c)

Closes an I2C Bus.

Parameters
[in,out]i2cPointer to I2C Bus handle.

Definition at line 137 of file i2ccom.c.

References i2c_struct::addr, i2c_struct::fd, and I2C_ADDR_NONE.

Referenced by execQuit(), and i2ccore_close().

138 {
139  if( i2c->fd >= 0 )
140  {
141  close(i2c->fd);
142  i2c->fd = -1;
143  i2c->addr = (ushort_t)I2C_ADDR_NONE;
144  }
145 }
i2c_struct::addr
i2c_addr_t addr
address of the currently selected attached I2C device
Definition: i2c.h:82
i2c_struct::fd
int fd
opened file descriptor of the I2C bus device
Definition: i2c.h:81
I2C_ADDR_NONE
#define I2C_ADDR_NONE
no I2C address selected
Definition: i2c.h:74
int i2c_exists ( i2c_t *  i2c,
i2c_addr_t  addr 
)

Test the existance of a device at the given address on the given I2C Bus.

Parameters
[in]i2cPointer to I2C Bus handle.
addrI2C device's 7/10-bit address.
Returns
Returns 1 if the device is present. Else returns 0.

Definition at line 199 of file i2ccom.c.

References i2c_msg_struct::addr, i2c_msg_struct::buf, i2c_struct::fd, i2c_msg_struct::flags, I2C_M_NOFLAGS, I2C_RDWR, i2c_msg_struct::len, i2c_rdwr_ioctl_data_struct::msgs, and i2c_rdwr_ioctl_data_struct::nmsgs.

Referenced by execCheck(), i2c_scan(), and i2ccore_check().

200 {
201  i2c_msg_t msg;
202  i2c_rdwr_ioctl_data_t msgset;
203  int rc;
204 
205  msg.addr = addr;
206  msg.flags = I2C_M_NOFLAGS;
207  msg.buf = NULL;
208  msg.len = 0;
209 
210  msgset.msgs = &msg;
211  msgset.nmsgs = 1;
212 
213  rc = ioctl(i2c->fd, I2C_RDWR, &msgset);
214 
215  // answer from an I2C device
216  return rc == 1? 1: 0;
217 }
i2c_rdwr_ioctl_data_struct::msgs
i2c_msg_t * msgs
pointers to i2c_msgs
Definition: i2c-dev.h:252
i2c_msg_struct::len
short len
message length (bytes)
Definition: i2c-dev.h:129
i2c_struct::fd
int fd
opened file descriptor of the I2C bus device
Definition: i2c.h:81
i2c_msg_struct::addr
ushort_t addr
7/10-bit slave address 0xxx xxxx
Definition: i2c-dev.h:127
i2c_rdwr_ioctl_data_struct::nmsgs
int nmsgs
number of i2c_msgs
Definition: i2c-dev.h:253
i2c_rdwr_ioctl_data_struct
I2C SMBus IOCTL Multi-Message Structure.
Definition: i2c-dev.h:250
i2c_msg_struct::flags
ushort_t flags
flags
Definition: i2c-dev.h:128
i2c_msg_struct::buf
char * buf
pointer to message data
Definition: i2c-dev.h:130
I2C_RDWR
#define I2C_RDWR
combined R/W transfer (one stop only)
Definition: i2c-dev.h:229
I2C_M_NOFLAGS
#define I2C_M_NOFLAGS
no/clear flags
Definition: i2c-dev.h:111
i2c_msg_struct
I2C Message Stucture.
Definition: i2c-dev.h:125
int i2c_open ( i2c_t *  i2c,
const char *  device 
)

Open the host I2C Bus device.

Parameters
[out]i2cPointer to I2C Bus handle.
Note: This descriptor must be allocated by the caller.
deviceA null-terminated string of the device name. If NULL, then the default '/dev/i2c/0' is used.
Returns
Returns 0 on success. Else errno is set appropriately and -1 is returned.

Definition at line 118 of file i2ccom.c.

References i2c_struct::addr, i2c_struct::fd, and I2C_ADDR_NONE.

Referenced by i2ccore_open(), and MainInit().

119 {
120  // no device selected
121  i2c->addr = (ushort_t)I2C_ADDR_NONE;
122 
123  // set hte default I2C bus device
124  if( device == NULL )
125  {
126  device = "/dev/i2c/0";
127  }
128 
129  if( (i2c->fd = open(device, O_RDWR)) < 0)
130  {
131  return i2c->fd;
132  }
133 
134  return 0;
135 }
i2c_struct::addr
i2c_addr_t addr
address of the currently selected attached I2C device
Definition: i2c.h:82
i2c_struct::fd
int fd
opened file descriptor of the I2C bus device
Definition: i2c.h:81
I2C_ADDR_NONE
#define I2C_ADDR_NONE
no I2C address selected
Definition: i2c.h:74
int i2c_read ( i2c_t *  i2c,
i2c_addr_t  addr,
byte_t *  buf,
uint_t  len 
)

Read from an I2C device.

The i2c_read() primitive reads data from a device at the given address on the given I2C Bus.

Parameters
[in,out]i2cPointer to I2C Bus handle.
addrI2C device's 7/10-bit address.
[out]bufPointer to the buffer that will receive the data bytes.
lenSize of the buffer in bytes.
Returns
On success, returns ≥ 0 number of bytes read.
Else errno is set appropriately and -1 is returned.

Definition at line 147 of file i2ccom.c.

References i2c_struct::fd, and i2c_select_device().

Referenced by execRead(), and i2ccore_read().

148 {
149  int rc;
150 
151  if( (rc = i2c_select_device(i2c , addr)) != -1 )
152  {
153  rc = (int)read(i2c->fd, buf, (size_t)len);
154  }
155 
156  return rc;
157 }
i2c_struct::fd
int fd
opened file descriptor of the I2C bus device
Definition: i2c.h:81
i2c_select_device
static int i2c_select_device(i2c_t *i2c, i2c_addr_t addr)
Selects the I2C device on a given I2C Bus.
Definition: i2ccom.c:97
int i2c_scan ( i2c_t *  i2c,
int(*)(i2c_t *i2c, i2c_addr_t addr, void *context)  callback,
void *  context 
)

Scans the given I2C Bus to find all connected devices.

For each device found, the provided callback function is called.

Parameters
[in]i2cPointer to I2C Bus handle.
callbackA callback function called when a device is found. If this callback function returns a value <0 the bus scan stops immedialety and the value is used as return value by i2c_scan().
contextA user defined value or a pointer passed to the callback function.
Returns
Returns the number of deviced found on success. Else errno is set appropriately and -1 is returned.

Definition at line 219 of file i2ccom.c.

References I2C_ADDR_DEV_HIGH, I2C_ADDR_DEV_LOW, and i2c_exists().

Referenced by execScan().

222 {
223  i2c_addr_t addr;
224  int nFound = 0;
225  int rc;
226 
227  //
228  // Scan the whole I<sup>2</sup>C Bus range.
229  //
230  for(addr=I2C_ADDR_DEV_LOW; addr<=I2C_ADDR_DEV_HIGH; ++addr)
231  {
232  if( i2c_exists(i2c, addr) )
233  {
234  ++nFound;
235 
236  if( callback != NULL )
237  {
238  if( (rc = callback(i2c, addr, context)) < 0 )
239  {
240  return rc;
241  }
242  }
243  }
244  }
245 
246  return nFound;
247 }
i2c_addr_t
ushort_t i2c_addr_t
I2C Device Address Type.
Definition: i2c.h:72
I2C_ADDR_DEV_HIGH
#define I2C_ADDR_DEV_HIGH
last available device address
Definition: i2c-dev.h:103
i2c_exists
int i2c_exists(i2c_t *i2c, i2c_addr_t addr)
Test the existance of a device at the given address on the given I2C Bus.
Definition: i2ccom.c:199
I2C_ADDR_DEV_LOW
#define I2C_ADDR_DEV_LOW
first available device address
Definition: i2c-dev.h:101
int i2c_transfer ( i2c_t *  i2c,
i2c_addr_t  addr,
const byte_t *  write_buf,
uint_t  write_len,
byte_t *  read_buf,
uint_t  read_len 
)

Perform a transfer with an I2C device.

The i2c_transfer() primitive writes data to and then reads data from a device at the given address on the given I2C Bus. It is optimize to reduce start/stop sequences.

Note
Not all devices support the optimize tranfer. Use i2c_write() / i2c_read() as an alternate is these cases.
Parameters
[in]i2cPointer to I2C Bus handle.
addrI2C device's 7/10-bit address.
write_bufPointer to the buffer that contains the data to be written.
write_lenNumber of bytes to write. The data are in the write buffer.
[out]read_bufPointer to the buffer that will receive the data.
read_lenSize of the read buffer in bytes.
Returns
Returns ≥ 0 on success. Else errno is set appropriately and -1 is returned.

Definition at line 171 of file i2ccom.c.

References i2c_msg_struct::addr, i2c_msg_struct::buf, i2c_struct::fd, i2c_msg_struct::flags, I2C_M_NOFLAGS, I2C_M_RD, I2C_RDWR, i2c_msg_struct::len, i2c_rdwr_ioctl_data_struct::msgs, and i2c_rdwr_ioctl_data_struct::nmsgs.

Referenced by execTrans(), execTransaction(), and i2ccore_transfer().

174 {
175  i2c_msg_t msgs[2];
176  i2c_rdwr_ioctl_data_t msgset;
177  int rc;
178 
179  // write message
180  msgs[0].addr = addr;
181  msgs[0].flags = I2C_M_NOFLAGS;
182  msgs[0].buf = (char *)write_buf;
183  msgs[0].len = (short)write_len;
184 
185  // read message
186  msgs[1].addr = addr;
187  msgs[1].flags = I2C_M_RD;
188  msgs[1].buf = (char *)read_buf;
189  msgs[1].len = (short)read_len;
190 
191  msgset.msgs = msgs;
192  msgset.nmsgs = 2;
193 
194  rc = ioctl(i2c->fd , I2C_RDWR, &msgset);
195 
196  return rc;
197 }
i2c_rdwr_ioctl_data_struct::msgs
i2c_msg_t * msgs
pointers to i2c_msgs
Definition: i2c-dev.h:252
i2c_msg_struct::len
short len
message length (bytes)
Definition: i2c-dev.h:129
i2c_struct::fd
int fd
opened file descriptor of the I2C bus device
Definition: i2c.h:81
i2c_msg_struct::addr
ushort_t addr
7/10-bit slave address 0xxx xxxx
Definition: i2c-dev.h:127
i2c_rdwr_ioctl_data_struct::nmsgs
int nmsgs
number of i2c_msgs
Definition: i2c-dev.h:253
i2c_rdwr_ioctl_data_struct
I2C SMBus IOCTL Multi-Message Structure.
Definition: i2c-dev.h:250
I2C_M_RD
#define I2C_M_RD
read bit
Definition: i2c-dev.h:113
i2c_msg_struct::flags
ushort_t flags
flags
Definition: i2c-dev.h:128
i2c_msg_struct::buf
char * buf
pointer to message data
Definition: i2c-dev.h:130
I2C_RDWR
#define I2C_RDWR
combined R/W transfer (one stop only)
Definition: i2c-dev.h:229
I2C_M_NOFLAGS
#define I2C_M_NOFLAGS
no/clear flags
Definition: i2c-dev.h:111
i2c_msg_struct
I2C Message Stucture.
Definition: i2c-dev.h:125
int i2c_write ( i2c_t *  i2c,
i2c_addr_t  addr,
const byte_t *  buf,
uint_t  len 
)

Write to an I2C device.

The i2c_write() primitive writes data to a device at the given address on the given I2C Bus.

Parameters
[in,out]i2cPointer to I2C Bus handle.
addrI2C device's 7/10-bit address.
bufPointer to the buffer that will be written.
lenNumber of bytes to write.
Returns
On success, returns ≥ 0 number of bytes written.
Else errno is set appropriately and -1 is returned.

Definition at line 159 of file i2ccom.c.

References i2c_struct::fd, and i2c_select_device().

Referenced by execWrite(), and i2ccore_write().

160 {
161  int rc;
162 
163  if( (rc = i2c_select_device(i2c , addr)) != -1 )
164  {
165  rc = (int)write(i2c->fd , buf, (size_t)len);
166  }
167 
168  return rc;
169 }
i2c_struct::fd
int fd
opened file descriptor of the I2C bus device
Definition: i2c.h:81
i2c_select_device
static int i2c_select_device(i2c_t *i2c, i2c_addr_t addr)
Selects the I2C device on a given I2C Bus.
Definition: i2ccom.c:97