Linduino  1.3.0
Linear Technology Arduino-Compatible Demonstration Board
LT_I2C.h
Go to the documentation of this file.
1 
2 /*!
3 LT_I2C: Routines to communicate with ATmega328P's hardware I2C port.
4 
5 
6 Copyright 2018(c) Analog Devices, Inc.
7 
8 All rights reserved.
9 
10 Redistribution and use in source and binary forms, with or without
11 modification, are permitted provided that the following conditions are met:
12  - Redistributions of source code must retain the above copyright
13  notice, this list of conditions and the following disclaimer.
14  - Redistributions in binary form must reproduce the above copyright
15  notice, this list of conditions and the following disclaimer in
16  the documentation and/or other materials provided with the
17  distribution.
18  - Neither the name of Analog Devices, Inc. nor the names of its
19  contributors may be used to endorse or promote products derived
20  from this software without specific prior written permission.
21  - The use of this software may or may not infringe the patent rights
22  of one or more patent holders. This license does not release you
23  from the requirement that you obtain separate licenses from these
24  patent holders to use this software.
25  - Use of the software either in source or binary form, must be run
26  on or directly connected to an Analog Devices Inc. component.
27 
28 THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
29 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
30 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
31 IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
32 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
33 LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR
34 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
35 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
36 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
37 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 */
39 
40 /*! @file
41  @ingroup LT_I2C
42  Library Header File for LT_I2C: Routines to communicate with ATmega328P's hardware I2C port.
43 */
44 
45 #ifndef LT_I2C_H
46 #define LT_I2C_H
47 
48 #include <stdint.h>
49 //#include <Wire.h>
50 
51 //! @name HARDWARE I2C PRESCALER VALUES
52 //! @{
53 #define HARDWARE_I2C_PRESCALER_1 0
54 #define HARDWARE_I2C_PRESCALER_4 1
55 #define HARDWARE_I2C_PRESCALER_16 2
56 #define HARDWARE_I2C_PRESCALER_64 3
57 //! @}
58 
59 //! @name I2C READ and WRITE BITS
60 //! @{
61 //! Eighth bit (LSB) of I2C address indicates a "read" or "write".
62 //! (The first seven bits are the 7-bit I2C address.)
63 #define I2C_READ_BIT 0x01
64 #define I2C_WRITE_BIT 0x00
65 //! @}
66 
67 //! @name STATUS BITS
68 //! @{
69 #define STATUS_START 0x08
70 #define STATUS_REPEATED_START 0x10
71 #define STATUS_ADDRESS_WRITE_ACK 0x18
72 #define STATUS_ADDRESS_WRITE_NACK 0x20
73 #define STATUS_WRITE_ACK 0x28
74 #define STATUS_WRITE_NACK 0x30
75 #define STATUS_ARBITRATION_LOST 0x38
76 #define STATUS_ADDRESS_READ_ACK 0x40
77 #define STATUS_ADDRESS_READ_NACK 0x48
78 #define STATUS_READ_ACK 0x50
79 #define STATUS_READ_NACK 0x58
80 //! @}
81 
82 //! @name TIMEOUT AND DELAY IN US
83 //! @{
84 #define HW_I2C_DELAY 1
85 #define HW_I2C_TIMEOUT 20000
86 //! @}
87 
88 //! @name ACK OR NACK PARAMETER PASSED TO I2C_READ
89 //! @{
90 #define WITH_ACK 0 //!< Use with i2c_read(WITH_ACK) to read with an acknowledge
91 #define WITH_NACK 1 //!< Use with i2c_read(WITH_NACK) to read without an acknowledge. Normally used after the last byte of a multi-byte read.
92 //! @}
93 
94 //! @name OPTIONAL I2C Address MACRO
95 //! @{
96 #define I2C_8ADDR(address) (address >> 1) //!< Use to convert an 8-bit I2C address to 7 bits.
97 //! @}
98 
99 //! Read a byte, store in "value".
100 //! @return 0 on success, 1 on failure
101 int8_t i2c_read_byte(uint8_t address, //!< 7-bit I2C address
102  uint8_t *value //!< Byte to be read
103  );
104 
105 //! Write "value" byte to device at "address"
106 //! @return 0 on success, 1 on failure
107 int8_t i2c_write_byte(uint8_t address, //!< 7-bit I2C address
108  uint8_t value //!< Byte to be written
109  );
110 
111 //! Read a byte of data at register specified by "command", store in "value"
112 //! @return 0 on success, 1 on failure
113 int8_t i2c_read_byte_data(uint8_t address, //!< 7-bit I2C address
114  uint8_t command, //!< Command byte
115  uint8_t *value //!< Byte to be read
116  );
117 
118 //! Write a byte of data to register specified by "command"
119 //! @return 0 on success, 1 on failure
120 int8_t i2c_write_byte_data(uint8_t address, //!< 7-bit I2C address
121  uint8_t command, //!< Command byte
122  uint8_t value //!< Byte to be written
123  );
124 
125 //! Read a 16-bit word of data from register specified by "command"
126 //! @return 0 on success, 1 on failure
127 int8_t i2c_read_word_data(uint8_t address, //!< 7-bit I2C address
128  uint8_t command, //!< Command byte
129  uint16_t *value //!< Word to be read
130  );
131 
132 //! Write a 16-bit word of data to register specified by "command"
133 //! @return 0 on success, 1 on failure
134 int8_t i2c_write_word_data(uint8_t address, //!< 7-bit I2C address
135  uint8_t command, //!< Command byte
136  uint16_t value //!< Word to be written
137  );
138 
139 //! Read a block of data, starting at register specified by "command" and ending at (command + length - 1)
140 //! @return 0 on success, 1 on failure
141 int8_t i2c_read_block_data(uint8_t address, //!< 7-bit I2C address
142  uint8_t command, //!< Command byte
143  uint8_t length, //!< Length of array
144  uint8_t *values //!< Byte array to be read
145  );
146 
147 //! Read a block of data, no command byte, reads length number of bytes and stores it in values.
148 //! @return 0 on success, 1 on failure
149 int8_t i2c_read_block_data(uint8_t address, //!< 7-bit I2C address
150  uint8_t length, //!< Length of array
151  uint8_t *values //!< Byte array to be read
152  );
153 
154 
155 //! Write a block of data, starting at register specified by "command" and ending at (command + length - 1)
156 //! @return 0 on success, 1 on failure
157 int8_t i2c_write_block_data(uint8_t address, //!< 7-bit I2C address
158  uint8_t command, //!< Command byte
159  uint8_t length, //!< Length of array
160  uint8_t *values //!< Byte array to be written
161  );
162 
163 //! Write a two command bytes, then receive a block of data
164 //! @return 0 on success, 1 on failure
165 int8_t i2c_two_byte_command_read_block(uint8_t address, //!< 7-bit I2C address
166  uint16_t command, //!< Command word
167  uint8_t length, //!< Length of array
168  uint8_t *values //!< Byte array to be read
169  );
170 
171 //! Initializes Linduino I2C port.
172 //! Before communicating to the I2C port through the QuikEval connector, you must also run
173 //! quikeval_I2C_connect to connect the I2C port to the QuikEval connector through the
174 //! QuikEval MUX (and disconnect SPI).
175 void quikeval_I2C_init(void);
176 
177 //! Switch MUX to connect I2C pins to QuikEval connector.
178 //! This will disconnect SPI pins.
179 void quikeval_I2C_connect(void);
180 
181 //! i2c_enable or quikeval_I2C_init must be called before using any of the other I2C routines.
182 void i2c_enable(void);
183 
184 //! Write start bit to the hardware I2C port
185 //! @return 0 if successful, 1 if not successful
186 int8_t i2c_start();
187 
188 //! Write a repeat start bit to the hardware I2C port
189 //! @return 0 if successful, 1 if not successful
190 int8_t i2c_repeated_start();
191 
192 //! Write stop bit to the hardware I2C port
193 void i2c_stop();
194 
195 //! Send a data byte to hardware I2C port
196 //! @return 0 if successful, 1 if not successful
197 int8_t i2c_write(uint8_t data //!< byte that will be written to hardware I2C port.
198  );
199 
200 //! Read a data byte from the hardware I2C port.
201 //! If ack is 0 then an acknowledge (ACK) is generated, else a NACK is generated.
202 //! @return the data byte read.
203 uint8_t i2c_read(int8_t ack //!< If ACK is 0 then an acknowledge is generated, else a NACK is generated.
204  );
205 
206 //! Poll the I2C port and look for an acknowledge
207 //! @return Returns 0 if successful, 1 if not successful
208 int8_t i2c_poll(uint8_t i2c_address //!< i2c_address is the address of the slave being polled.
209  );
210 
211 
212 // //! Read a byte, store in "value".
213 // //! @return -1 if failed or value if it succeeds
214 // int32_t i2c_read_byte(uint8_t address, //!< 7-bit I2C address
215 // uint8_t *value //!< Byte to be read
216 // );
217 //
218 // //! Write "value" byte to device at "address"
219 // //! @return -1 if failed or 0 if it succeeds
220 // int32_t i2c_write_byte(uint8_t address, //!< 7-bit I2C address
221 // uint8_t value //!< Byte to be written
222 // );
223 //
224 // //! Read a byte of data at register specified by "command", store in "value"
225 // //! @return -1 if failed or value if it succeeds
226 // int32_t i2c_read_byte_data(uint8_t address, //!< 7-bit I2C address
227 // uint8_t command, //!< Command byte
228 // uint8_t *value //!< Byte to be read
229 // );
230 //
231 // //! Write a byte of data to register specified by "command"
232 // //! @return -1 if failed or 0 if it succeeds
233 // int32_t i2c_write_byte_data(uint8_t address, //!< 7-bit I2C address
234 // uint8_t command, //!< Command byte
235 // uint8_t value //!< Byte to be written
236 // );
237 //
238 // //! Read a 16-bit word of data from register specified by "command"
239 // //! @return -1 if failed or value if it succeeds
240 // int32_t i2c_read_word_data(uint8_t address, //!< 7-bit I2C address
241 // uint8_t command, //!< Command byte
242 // uint16_t *value //!< Word to be read
243 // );
244 //
245 // //! Write a 16-bit word of data to register specified by "command"
246 // //! @return -1 if failed or 0 if it succeeds
247 // int32_t i2c_write_word_data(uint8_t address, //!< 7-bit I2C address
248 // uint8_t command, //!< Command byte
249 // uint16_t value //!< Word to be written
250 // );
251 //
252 //
253 // //! Read a block of data, starting at register specified by "command" and ending at (command + length - 1)
254 // //! @return Byte count
255 // int32_t i2c_read_block_data(uint8_t address, //!< 7-bit I2C address
256 // uint8_t command, //!< Command byte
257 // uint8_t length, //!< Length of array
258 // uint8_t *values //!< Byte array to be read
259 // );
260 //
261 // //! Write a block of data, starting at register specified by "command" and ending at (command + length - 1)
262 // //! @return Byte count
263 // int32_t i2c_write_block_data(uint8_t address, //!< 7-bit I2C address
264 // uint8_t command, //!< Command byte
265 // uint8_t length, //!< Length of array
266 // uint8_t *values //!< Byte array to be written
267 // );
268 //
269 // //! Write a two command bytes, then receive a block of data
270 // //! @return Byte count
271 // int32_t i2c_two_byte_command_read_block(uint8_t address, //!< 7-bit I2C address
272 // uint16_t command, //!< Command word
273 // uint8_t length, //!< Length of array
274 // uint8_t *values //!< Byte array to be read
275 // );
276 //
277 // //! Initializes Linduino I2C port.
278 // //! Before communicating to the I2C port through the QuikEval connector, you must also run
279 // //! quikeval_I2C_connect to connect the I2C port to the QuikEval connector through the
280 // //! QuikEval MUX (and disconnect SPI).
281 // void quikeval_I2C_init(void);
282 //
283 // //! Switch MUX to connect I2C pins to QuikEval connector
284 // //! This will disconnect SPI pins.
285 // void quikeval_I2C_connect(void);
286 //
287 // //! Setup and enable the hardware I2C interface.
288 // //! Must be called before using any of the other routines.
289 // // 100kHz example:
290 // // uint8 bit_rate = 18;
291 // // hw_i2c_enable(bit_rate, HARDWARE_I2C_PRESCALER_4);
292 // void i2c_enable(uint8_t bit_rate, //!< I2C Bit Rate
293 // uint8_t prescaler //!< I2C prescaler
294 // );
295 
296 
297 // LT I2C functions to emulate Linux SMBus functions for E-Z porting. There does not appear to be
298 // a single source of the "correct" way to implement these functions.
299 
300 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
301 //// From http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/i2c/dev-interface
302 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
303 //// You can do plain I2C transactions by using read(2) and write(2) calls.
304 //// You do not need to pass the address byte; instead, set it through
305 //// ioctl I2C_SLAVE before you try to access the device.
306 ////
307 //// You can do SMBus level transactions (see documentation file smbus-protocol
308 //// for details) through the following functions:
309 //// __s32 i2c_smbus_write_quick(int file, __u8 value);
310 //// __s32 i2c_smbus_read_byte(int file);
311 //// __s32 i2c_smbus_write_byte(int file, __u8 value);
312 //// __s32 i2c_smbus_read_byte_data(int file, __u8 command);
313 //// __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
314 //// __s32 i2c_smbus_read_word_data(int file, __u8 command);
315 //// __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
316 //// __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
317 //// __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
318 //// __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
319 //// // __u8 *values);
320 //// All these transactions return -1 on failure; you can read errno to see
321 //// what happened. The 'write' transactions return 0 on success; the
322 //// 'read' transactions return the read value, except for read_block, which
323 //// returns the number of values read. The block buffers need not be longer
324 //// than 32 bytes.
325 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
326 
327 
328 /*
329 
330 // Begin "LT-ified" versions of these functions:
331 
332 // Original Linux prototype: __s32 i2c_smbus_write_quick(int file, __u8 value);
333 // Write a single bit in the R/W bit of the address. Note - we are using 8-bit addresses,
334 // we should probably AND with 0xFE before appending the "value" bit. Also, should we obligate the user
335 // to send a value with a "1" in the LSB, or any nonzero value to assert a 1?
336 int8_t LT_i2c_write_quick(uint8_t address, uint8_t value);
337 
338 // Original Linux prototype: __s32 i2c_smbus_read_byte(int file);
339 // Read a byte, store in "value".
340 int8_t LT_i2c_read_byte(uint8_t address, uint8_t *value);
341 
342 // Original Linux prototype: __s32 i2c_smbus_write_byte(int file, __u8 value);
343 // Write "value" byte to device at "address"
344 int8_t LT_i2c_write_byte(uint8_t address, uint8_t value);
345 
346 // Original Linux prototype: __s32 i2c_smbus_read_byte_data(int file, __u8 command);
347 // Read a byte of data at register specified by "command", store in "value"
348 int8_t LT_i2c_read_byte_data(uint8_t address, uint8_t command, uint8_t *value);
349 
350 // Original Linux prototype: __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
351 // Write a byte of data to register specified by "command"
352 int8_t LT_i2c_write_byte_data(uint8_t address, uint8_t command, uint8_t value);
353 
354 // Original Linux prototype: __s32 i2c_smbus_read_word_data(int file, __u8 command);
355 // Read a 16-bit word of data from register specified by "command"
356 int8_t LT_i2c_read_word_data(uint8_t address, uint8_t command, uint16_t *value);
357 
358 // Original Linux prototype: __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
359 // Write a 16-bit word of data to register specified by "command"
360 int8_t LT_i2c_write_word_data(uint8_t address, uint8_t command, uint16_t value);
361 
362 // Original Linux prototype: __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
363 int8_t LT_i2c_process_call(uint8_t address, uint8_t command, uint16_t value);
364 
365 // For block read / write, this explains the lack of length parameter in some versions:
366 // "Until kernel 2.6.22, the length is hard coded to 32 bytes. If you
367 // ask for less than 32 bytes, your code will only work with kernels
368 // 2.6.23 and later."
369 
370 // Original Linux prototype: __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
371 // Read a block of data, starting at register specified by "command" and ending at (command + length - 1)
372 int8_t LT_i2c_read_block_data(uint8_t address, uint8_t command, uint8_t length, uint8_t *values);
373 
374 // Original Linux prototype: __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, __u8 *values);
375 // Write a block of data, starting at register specified by "command" and ending at (command + length - 1)
376 int8_t LT_i2c_write_block_data(uint8_t address, uint8_t command, uint8_t length, uint8_t *values);
377 
378 // Proposed additional function to handle cases like the LTC2495 / 97 / 99 family, which require
379 // a 16-bit command, and can return either 3 or 4 bytes of data.
380 // Write a two command bytes, then receive a block of data
381 int8_t LT_i2c_two_byte_command_read_block(uint8_t address, uint16_t command, uint8_t length, uint8_t *values);
382 
383 */
384 
385 #endif // LT_I2C_H
int8_t i2c_read_byte(uint8_t address, uint8_t *value)
Read a byte, store in "value".
Definition: LT_I2C.cpp:93
uint8_t i2c_address
int8_t i2c_write_block_data(uint8_t address, uint8_t command, uint8_t length, uint8_t *values)
Write a block of data, starting at register specified by "command" and ending at (command + length - ...
Definition: LT_I2C.cpp:321
int8_t i2c_write_byte(uint8_t address, uint8_t value)
Write "value" byte to device at "address".
Definition: LT_I2C.cpp:109
static uint8_t address
Definition: DC2091A.ino:83
union LT_union_int32_4bytes data
Definition: DC2094A.ino:138
int8_t i2c_read_block_data(uint8_t address, uint8_t command, uint8_t length, uint8_t *values)
Read a block of data, starting at register specified by "command" and ending at (command + length - 1...
Definition: LT_I2C.cpp:244
int8_t i2c_write(uint8_t data)
Send a data byte to hardware I2C port.
Definition: LT_I2C.cpp:470
int8_t i2c_read_byte_data(uint8_t address, uint8_t command, uint8_t *value)
Read a byte of data at register specified by "command", store in "value".
Definition: LT_I2C.cpp:124
int8_t i2c_write_word_data(uint8_t address, uint8_t command, uint16_t value)
Write a 16-bit word of data to register specified by "command".
Definition: LT_I2C.cpp:216
int8_t i2c_poll(uint8_t i2c_address)
Poll the I2C port and look for an acknowledge.
Definition: LT_I2C.cpp:526
int8_t i2c_two_byte_command_read_block(uint8_t address, uint16_t command, uint8_t length, uint8_t *values)
Write a two command bytes, then receive a block of data.
Definition: LT_I2C.cpp:345
void quikeval_I2C_connect(void)
Switch MUX to connect I2C pins to QuikEval connector.
Definition: LT_I2C.cpp:401
void i2c_enable(void)
i2c_enable or quikeval_I2C_init must be called before using any of the other I2C routines.
Definition: LT_I2C.cpp:414
int8_t i2c_write_byte_data(uint8_t address, uint8_t command, uint8_t value)
Write a byte of data to register specified by "command".
Definition: LT_I2C.cpp:155
int8_t i2c_read_word_data(uint8_t address, uint8_t command, uint16_t *value)
Read a 16-bit word of data from register specified by "command".
Definition: LT_I2C.cpp:172
uint8_t i2c_read(int8_t ack)
Read a data byte from the hardware I2C port.
Definition: LT_I2C.cpp:491
void quikeval_I2C_init(void)
Initializes Linduino I2C port.
Definition: LT_I2C.cpp:394
void i2c_stop()
Write stop bit to the hardware I2C port.
Definition: LT_I2C.cpp:462
int8_t i2c_repeated_start()
Write a repeat start bit to the hardware I2C port.
Definition: LT_I2C.cpp:444
int8_t i2c_start()
Write start bit to the hardware I2C port.
Definition: LT_I2C.cpp:425
static uint8_t values[4]
Definition: DC2218A.ino:117