Robot Control Library
i2c.h
Go to the documentation of this file.
1 /**
2  * <rc/i2c.h>
3  *
4  * @brief C interface for the the Linux I2C driver
5  *
6  * Developed and tested on the BeagleBone Black but should work fine on any
7  * Linux system.
8  *
9  * @author James Strawson
10  *
11  * @date 1/19/2018
12  *
13  * @addtogroup I2C
14  * @ingroup IO
15  * @{
16  */
17 
18 
19 #ifndef RC_I2C_H
20 #define RC_I2C_H
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 #include <stddef.h>
27 #include <stdint.h>
28 
29 /**
30  * @brief Maximum I2C bus identifier. Default is 5 for a total of 6 busses.
31  * This can be increased by the user for special cases.
32  */
33 #define I2C_MAX_BUS 5
34 
35 /**
36  * @brief size of i2c buffer in bytes for writing to registers. Only
37  * increase if you know what you are doing.
38  */
39 #define I2C_BUFFER_SIZE 128
40 
41 /**
42  * @brief Initializes a bus and sets it to talk to a particular device
43  * address.
44  *
45  * @param[in] bus The bus
46  * @param[in] devAddr The device address
47  *
48  * @return 0 on success or -1 on failure
49  */
50 int rc_i2c_init(int bus, uint8_t devAddr);
51 
52 /**
53  * @brief Closes an I2C bus
54  *
55  * @param[in] bus The bus
56  *
57  * @return 0 on success or -1 on failure
58  */
59 int rc_i2c_close(int bus);
60 
61 /**
62  * @brief Changes the device address the bus is configured to talk to.
63  *
64  * Actually changing the device address in the I2C driver requires a
65  * system call and is relatively slow. This function records which
66  * device address the bus is set to and will only make the system
67  * call if the requested address is different than the set address.
68  * This makes it safe to call this function repeatedly with no
69  * performance penalty.
70  *
71  * @param[in] bus The bus
72  * @param[in] devAddr The new device address
73  *
74  * @return { description_of_the_return_value }
75  */
76 int rc_i2c_set_device_address(int bus, uint8_t devAddr);
77 
78 /**
79  * @brief Reads a single byte from a device register.
80  *
81  * This sends the device address and register address to be read
82  * from before reading the response, works for most i2c devices.
83  *
84  * @param[in] bus The bus
85  * @param[in] regAddr The register address
86  * @param[out] data The data pointer to write response to.
87  *
88  * @return 0 on success or -1 on failure
89  */
90 int rc_i2c_read_byte(int bus, uint8_t regAddr, uint8_t *data);
91 
92 /**
93  * @brief Reads multiple bytes from a device register.
94  *
95  * This sends the device address and register address to be read
96  * from before reading the response, works for most i2c devices.
97  *
98  * @param[in] bus The bus
99  * @param[in] regAddr The register address
100  * @param[in] count number of bytes to read
101  * @param[out] data The data pointer to write response to.
102  *
103  * @return returns number of bytes read or -1 on failure
104  */
105 int rc_i2c_read_bytes(int bus, uint8_t regAddr, size_t count, uint8_t *data);
106 
107 /**
108  * @brief Reads a single word (16 bits) from a device register.
109  *
110  * This sends the device address and register address to be read
111  * from before reading the response, works for most i2c devices.
112  *
113  * @param[in] bus The bus
114  * @param[in] regAddr The register address
115  * @param[out] data The data pointer to write response to.
116  *
117  * @return 0 on success or -1 on failure
118  */
119 int rc_i2c_read_word(int bus, uint8_t regAddr, uint16_t *data);
120 
121 /**
122  * @brief Reads multiple words (16 bytes each) from a device register.
123  *
124  * This sends the device address and register address to be read
125  * from before reading the response, works for most i2c devices.
126  *
127  * @param[in] bus The bus
128  * @param[in] regAddr The register address
129  * @param[in] count Number of 16-bit words to read, NOT number of bytes to read
130  * @param[out] data The data pointer to write response to.
131  *
132  * @return 0 on success or -1 on failure
133  */
134 int rc_i2c_read_words(int bus, uint8_t regAddr, size_t count, uint16_t* data);
135 
136 
137 /**
138  * @brief Writes a single byte to a specified register address.
139  *
140  * This sends the device address and register address followed by
141  * the actual data to be written. Works for most i2c devices.
142  *
143  * @param[in] bus The bus
144  * @param[in] regAddr The register address
145  * @param[in] data Single byte to be writen
146  *
147  * @return 0 on success or -1 on failure
148  */
149 int rc_i2c_write_byte(int bus, uint8_t regAddr, uint8_t data);
150 
151 /**
152  * @brief Writes multiple bytes to a specified register address.
153  *
154  * This sends the device address and register address followed by
155  * the actual data to be written. Works for most i2c devices.
156  *
157  * @param[in] bus The bus
158  * @param[in] regAddr The register address to write to
159  * @param[in] count The number of bytes to write
160  * @param data pointer to user's data to be writen
161  *
162  * @return 0 on success or -1 on failure
163  */
164 int rc_i2c_write_bytes(int bus, uint8_t regAddr, size_t count, uint8_t* data);
165 
166 
167 /**
168  * @brief Writes a single word (16 bits) to a specified register address.
169  *
170  * This sends the device address and register address followed by
171  * the actual data to be written. Works for most i2c devices.
172  *
173  * @param[in] bus The bus
174  * @param[in] regAddr The register address to write to
175  * @param[in] data 16-bit word to be written
176  *
177  * @return 0 on success or -1 on failure
178  */
179 int rc_i2c_write_word(int bus, uint8_t regAddr, uint16_t data);
180 
181 /**
182  * @brief Writes multiple words (16 bits each) to a specified register
183  * address.
184  *
185  * This sends the device address and register address followed by
186  * the actual data to be written. Works for most i2c devices.
187  *
188  * @param[in] bus The bus
189  * @param[in] regAddr The register address
190  * @param[in] count Number of 16-bit words to write, NOT number of bytes
191  * @param[in] data The data
192  *
193  * @return 0 on success or -1 on failure
194  */
195 int rc_i2c_write_words(int bus, uint8_t regAddr, size_t count, uint16_t* data);
196 
197 
198 
199 /**
200  * @brief Sends exactly user-defined data without prepending a register
201  * address.
202  *
203  * Instead of automatically sending a device address before the data
204  * which is typical for reading/writing registers, the
205  * rc_i2c_send_bytes function send only the data given by the data
206  * argument. This is useful for more complicated IO such as
207  * uploading firmware to a device.
208  *
209  * @param[in] bus The bus
210  * @param[in] count Number of bytes to send
211  * @param[in] data The data
212  *
213  * @return 0 on success or -1 on failure
214  */
215 int rc_i2c_send_bytes(int bus, size_t count, uint8_t* data);
216 
217 /**
218  * @brief Sends exactly user-defined data without prepending a register
219  * address.
220  *
221  * Instead of automatically sending a device address before the data
222  * which is typical for reading/writing registers, the
223  * rc_i2c_send_bytes function send only the data given by the data
224  * argument. This is useful for more complicated IO such as
225  * uploading firmware to a device.
226  *
227  * @param[in] bus The bus
228  * @param[in] data The data
229  *
230  * @return 0 on success or -1 on failure
231  */
232 int rc_i2c_send_byte(int bus, uint8_t data);
233 
234 /**
235  * @brief Locks the bus so other threads in the process know the bus is in
236  * use.
237  *
238  * Locking a bus is similar to locking a mutex, it is a way for
239  * threads to communicate within one process when sharing a bus.
240  * This, however, is not a hard lock in the sense that it does not
241  * block and does not stop any of the other functions in this API
242  * from being called. It only serves as a flag that can be checked
243  * between threads if the user chooses to do so. This is encouraged
244  * in multithraded applications to prevent timing-sensitive i2c
245  * communication from being interrupted but is not enforced.
246  *
247  * All read/write functions in this API will lock the bus during the
248  * transaction and return the lockstate to what it was at the
249  * beginning of the transaction. Ideally the user should lock the
250  * bus themselves before a sequence of transactions and unlock it
251  * afterwards.
252  *
253  * @param[in] bus The bus ID
254  *
255  * @return Returns the lock state (0 or 1) when this function is called, or -1 on
256  * error.
257  */
258 int rc_i2c_lock_bus(int bus);
259 
260 /**
261  * @brief Unlocks a bus to indicate to other threads in the process that
262  * the bus is now free.
263  *
264  * see rc_i2c_lock_bus for further description.
265  *
266  * @param[in] bus The bus ID
267  *
268  * @return Returns the lock state (0 or 1) when this function is called, or -1 on
269  * error.
270  */
271 int rc_i2c_unlock_bus(int bus);
272 
273 /**
274  * @brief Fetches the current lock state of the bus.
275  *
276  * @param[in] bus The bus ID
277  *
278  * @return Returns 0 if unlocked, 1 if locked, or -1 on error.
279  */
280 int rc_i2c_get_lock(int bus);
281 
282 /**
283  * @brief Gets file descriptor.
284  *
285  *
286  * @param[in] bus The bus
287  *
288  * @return returns file descriptor of the specified bus or -1 on failure
289  */
290 int rc_i2c_get_fd(int bus);
291 
292 
293 
294 
295 #ifdef RC_AUTOPILOT_EXT
296 /**
297  * @brief Reads multiple bytes from a device register.
298  *
299  * This sends the device address and register address to be read
300  * from before reading the response, works for most i2c devices.
301  *
302  * @param[in] bus The bus
303  * @param[in] regAddr The register address
304  * @param[in] length number of bytes to read. It can be larger than 255 as MPU9250 FIFO size is 512 bytes.
305  * @param[out] data The data pointer to write response to.
306  *
307  * @return returns number of bytes read or -1 on failure
308  */
309 int rc_i2c_read_data(int bus, uint8_t regAddr, size_t length, uint8_t *data);
310 #endif // RC_AUTOPILOT_EXT
311 
312 
313 
314 
315 #ifdef __cplusplus
316 }
317 #endif
318 
319 #endif // RC_I2C_H
320 
321 ///@} end group IO
int rc_i2c_write_word(int bus, uint8_t regAddr, uint16_t data)
Writes a single word (16 bits) to a specified register address.
int rc_i2c_read_byte(int bus, uint8_t regAddr, uint8_t *data)
Reads a single byte from a device register.
int rc_i2c_send_byte(int bus, uint8_t data)
Sends exactly user-defined data without prepending a register address.
int rc_i2c_close(int bus)
Closes an I2C bus.
int rc_i2c_set_device_address(int bus, uint8_t devAddr)
Changes the device address the bus is configured to talk to.
int rc_i2c_get_fd(int bus)
Gets file descriptor.
int rc_i2c_unlock_bus(int bus)
Unlocks a bus to indicate to other threads in the process that the bus is now free.
int rc_i2c_init(int bus, uint8_t devAddr)
Initializes a bus and sets it to talk to a particular device address.
int rc_i2c_lock_bus(int bus)
Locks the bus so other threads in the process know the bus is in use.
int rc_i2c_write_byte(int bus, uint8_t regAddr, uint8_t data)
Writes a single byte to a specified register address.
int rc_i2c_write_words(int bus, uint8_t regAddr, size_t count, uint16_t *data)
Writes multiple words (16 bits each) to a specified register address.
int rc_i2c_read_bytes(int bus, uint8_t regAddr, size_t count, uint8_t *data)
Reads multiple bytes from a device register.
int rc_i2c_read_words(int bus, uint8_t regAddr, size_t count, uint16_t *data)
Reads multiple words (16 bytes each) from a device register.
int rc_i2c_write_bytes(int bus, uint8_t regAddr, size_t count, uint8_t *data)
Writes multiple bytes to a specified register address.
int rc_i2c_read_word(int bus, uint8_t regAddr, uint16_t *data)
Reads a single word (16 bits) from a device register.
int rc_i2c_get_lock(int bus)
Fetches the current lock state of the bus.
int rc_i2c_send_bytes(int bus, size_t count, uint8_t *data)
Sends exactly user-defined data without prepending a register address.