2 * Copyright Droids Corporation, Microb Technology, Eirbot (2007)
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 * Revision : $Id: i2c.h,v 1.1.2.9 2009-01-23 22:57:17 zer0 Exp $
22 /* Author Zer0, based on Tof old i2c module */
24 /** please read carefully !
27 * this implementation of the i2c interface is very specific this is a
28 * multi bus implementation. The multi bus operation is done by
29 * implementing software i2c modules (slave only)
34 * This module implements i2c using the hardware twi interface of AVR
35 * devices. It can operates in slave and/or master mode, depending on
36 * the initialisation parameter. This module is interrupt driven only.
38 * In master mode, buffer can be transmitted/received on demand (with
39 * start and stop conditions). In slave mode, operations are done
40 * asynchronously. Like some other modules in aversive, callback
41 * functions can be registered and are called on transmission or
44 * This module should support multimaster mode, send() or recv() depends
45 * on the address parameter.
51 #include <i2c_config.h>
55 #define I2C_ADD_GENCALL 0x00
57 /* this is not a valid address regarding the I2C protocol, but is used
58 * as a magic for addressing the master from the slave */
59 #define I2C_ADD_MASTER 0x80
65 typedef enum { I2C_MODE_UNINIT, /**< not initialized */
66 I2C_MODE_SLAVE, /**< Slave */
67 #ifdef CONFIG_MODULE_I2C_MASTER
68 I2C_MODE_MASTER, /**< Master */
70 #ifdef CONFIG_MODULE_I2C_MULTIMASTER
71 I2C_MODE_MULTIMASTER, /**< Master, but allow multimaster mode */
76 #define I2C_CTRL_GENERIC 0x00
77 /** Error code is returned instead of beeing sent as a callback. Note
78 * that the send_event callback is _not_ called if it is
79 * registered. This functions waits and only returns when the
80 * transmission is finished or if it failed. Note that there is no
81 * timeout, so it can loop forever... WARNING : irq MUST be
83 #define I2C_CTRL_SYNC 0x01
84 /** when the operation is finished as a master, don't release the bus
85 * (don't send any stop condition). You can send several commands
86 * without beeing interrupted by another master. To release it, send
87 * another command without this flag or just call
88 * i2c_release_bus(). This has no effect on a slave. */
89 #define I2C_CTRL_DONT_RELEASE_BUS 0x02
93 #define I2C_STATUS_READY 0x00
94 #define I2C_STATUS_MASTER_XMIT 0x01
95 #define I2C_STATUS_MASTER_RECV 0x02
96 #define I2C_STATUS_SLAVE_XMIT_WAIT 0x04
97 #define I2C_STATUS_SLAVE_XMIT 0x08
98 #define I2C_STATUS_SLAVE_RECV 0x10
99 #define I2C_STATUS_OP_FINISHED 0x20
100 #define I2C_STATUS_NEED_XMIT_EVT 0x40
101 #define I2C_STATUS_NEED_RECV_EVT 0x80
105 * mode is I2C_MODE_UNINIT, I2C_MODE_MASTER, I2C_MODE_MULTIMASTER or
106 * I2C_MODE_SLAVE. Parameter add is the address in slave mode, it is
108 * b7 : true if the uC can be addressed with GENCALL
109 * b0-6: slave address
111 void i2c_init(i2c_mode_t mode, uint8_t add);
115 * Register a function that is called when a buffer is received. The
116 * user application is always notified when data frame is received.
117 * Arguments of the callback are:
118 * - (recv_buf, n>0) if transmission succedded. The first parameter
119 * contains the address of the reception buffer and
120 * the second contains the number of received bytes.
121 * - (NULL, err<0) if the transmission failed (slave not answering
122 * or arbiteration lost). The first parameter is
123 * NULL and the second contains the error code.
125 void i2c_register_recv_event(void (*event)(uint8_t *, int8_t));
128 * Register a function that is called when a byte is received.
129 * Arguments of the callback are: (hwstatus, numbyte, byte). The user
130 * app can modify the g_size value, which is the number of bytes to be
131 * received in the frame: this can be done by calling
132 * i2c_set_recv_size().
134 void i2c_register_recv_byte_event(void (*event)(uint8_t, uint8_t, uint8_t));
138 * register a function that is called when a buffer is sent (or an
139 * error occured while sending) on the i2c bus. The event function is
140 * always called by software if the i2c_send() function returned 0.
141 * The parameter of the event function is the error code:
142 * - 0 if the number of transmitted bytes is equal to the size
143 * of the original send buffer, without NACK.
144 * - <0 if 0 byte has been transmitted (slave not answering or
146 * - Else, the number of transmitted bytes is given, including the
147 * one that was not acked.
149 void i2c_register_send_event(void (*event)(int8_t));
153 * Send a buffer. Return 0 if xmit starts correctly.
154 * On error, return < 0.
155 * - If mode is slave, dest_add should be I2C_ADD_MASTER, and transmission
156 * starts when the master transmits a clk.
157 * - If mode is master and if dest_add != I2C_ADD_MASTER, it will transmit
158 * a START condition if bus is available (the uc will act as a
160 * - If mode is master and if dest_add == I2C_ADD_MASTER, the uC will
161 * act as a slave, and data will be sent when the uC will be
163 * The transmission will be processed with these params until a
164 * i2c_flush() is called.
165 * The 'ctrl' parameter is composed by the flags I2C_CTRL_SYNC and
166 * I2C_CTRL_DONT_RELEASE_BUS
168 int8_t i2c_send(uint8_t dest_add, uint8_t *buf, uint8_t size, uint8_t ctrl);
171 * Resend the same buffer. This call is equivalent to i2c_send() with
172 * the same parameters as the last call. It safe to call it from the
173 * send_event, but else the send buffer may have been overwritten.
175 int8_t i2c_resend(void);
180 int8_t i2c_rerecv(void);
185 void i2c_release_bus(void);
188 * In slave mode, it returns error and is useless (all data is
189 * received trough the callback). In master mode, if dest_add is
190 * between 0 and 127, it will start to read the addressed slave. The
191 * size of the buffer to read must be specified. Return 0 on success.
192 * The 'ctrl' parameter is composed by the flags I2C_CTRL_SYNC and
193 * I2C_CTRL_DONT_RELEASE_BUS
195 int8_t i2c_recv(uint8_t dest_add, uint8_t size, uint8_t ctrl);
199 * Try to flush the current operation, before it is started. The
200 * i2c module is then tagged as ready. If it returns 0, the flush was
201 * a success, and i2c_send() can be called. Else, it means that
202 * a transmission was running.
204 int8_t i2c_flush(void);
207 * In MASTER RECEIVER mode, it is possible that the user application
208 * does not know the size of the buffer. You can adjust this size
209 * during transmission (generally the size can be specified at the
210 * beginning of received data, so the user app can be notified thanks
211 * to recv_byte_event(). Note that i2c_set_recv_size() function has to
212 * be used with careful, making sure you understand i2c protocol and
213 * this code. Return 0 on success. Note than in SLAVE RECEIVER mode,
214 * you don't have to use this function, because the master can end the
215 * transmission by sending a stop condition on the bus.
217 uint8_t i2c_set_recv_size(uint8_t size);
220 * return the current mode of the i2c module.
222 i2c_mode_t i2c_mode(void);
225 * return the status of the i2c module.
227 uint8_t i2c_status(void);
230 * Copy the received buffer in the buffer given as parameter. Return
231 * number of copied bytes or < 0 on error.
233 uint8_t i2c_get_recv_buffer(uint8_t *buf, uint8_t size);
236 * recover from error states
238 void i2c_reset(void);
242 * display debug infos
244 void i2c_debug(void);