aboutsummaryrefslogtreecommitdiff
path: root/lib/i2c_master.h
blob: f4e4933385d124c18e42071a2a64a2989cfc91c9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
/* This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
/** library to communicate using I2C as master (API)
 *  @file i2c_master.h
 *  @author King Kévin <kingkevin@cuvoodoo.info>
 *  @date 2017-2018
 *  @note peripherals used: I2C
 */
#pragma once

/** I2C return codes */
enum i2c_master_rc {
	I2C_MASTER_RC_NONE = 0, /**< no error */
	I2C_MASTER_RC_START_STOP_IN_PROGESS, /**< a start or stop condition is already in progress */
	I2C_MASTER_RC_NOT_MASTER, /**< not in master mode */
	I2C_MASTER_RC_NOT_TRANSMIT, /**< not in transmit mode */
	I2C_MASTER_RC_NOT_RECEIVE, /**< not in receive mode */
	I2C_MASTER_RC_NOT_READY, /**< slave is not read (previous operations has been nacked) */
	I2C_MASTER_RC_NAK, /**< not acknowledge received */
	I2C_MASTER_RC_BUS_ERROR, /**< an error on the I2C bus occurred */
};

/** setup I2C peripheral
 *  @param[in] i2c I2C base address
 *  @param[in] frequency frequency to use in kHz (1-400)
 *  @note Standard mode (Sm) is used for frequencies up to 100 kHz, and Fast mode (Fm) is used for frequencies up to 400 kHz
 */
void i2c_master_setup(uint32_t i2c, uint16_t frequency);
/** release I2C peripheral
 *  @param[in] i2c I2C base address
 */
void i2c_master_release(uint32_t i2c);
/** reset I2C peripheral, fixing any locked state
 *  @warning the I2C peripheral needs to be re-setup
 *  @note to be used after failed start or stop, and bus error
 *  @param[in] i2c I2C base address
 */
void i2c_master_reset(uint32_t i2c);
/** check if SDA and SCL signals are high
 *  @param[in] i2c I2C base address
 *  @return SDA and SCL signals are high
 */
bool i2c_master_check_signals(uint32_t i2c);
/** send start condition
 *  @param[in] i2c I2C base address
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_start(uint32_t i2c);
/** select I2C slave device
 *  @warning a start condition should be sent before this operation
 *  @param[in] i2c I2C base address
 *  @param[in] slave I2C address of slave device to select
 *  @param[in] address_10bit if the I2C slave address is 10 bits wide
 *  @param[in] write this transaction will be followed by a read (false) or write (true) operation
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_select_slave(uint32_t i2c, uint16_t slave, bool address_10bit, bool write);
/** read data over I2C
 *  @warning the slave device must be selected before this operation
 *  @param[in] i2c I2C base address
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_read(uint32_t i2c, uint8_t* data, size_t data_size);
/** write data over I2C
 *  @warning the slave device must be selected before this operation
 *  @param[in] i2c I2C base address
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_write(uint32_t i2c, const uint8_t* data, size_t data_size);
/** sent stop condition
 *  @param[in] i2c I2C base address
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_stop(uint32_t i2c);
/** read data from slave device
 *  @warning the slave device must be selected before this operation
 *  @param[in] i2c I2C base address
 *  @param[in] slave I2C address of slave device to select
 *  @param[in] address_10bit if the I2C slave address is 10 bits wide
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_slave_read(uint32_t i2c, uint16_t slave, bool address_10bit, uint8_t* data, size_t data_size);
/** write data to slave device
 *  @warning the slave device must be selected before this operation
 *  @param[in] i2c I2C base address
 *  @param[in] slave I2C address of slave device to select
 *  @param[in] address_10bit if the I2C slave address is 10 bits wide
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_slave_write(uint32_t i2c, uint16_t slave, bool address_10bit, const uint8_t* data, size_t data_size);
/** read data at specific address from an I2C memory slave
 *  @param[in] i2c I2C base address
 *  @param[in] slave I2C address of slave device to select
 *  @param[in] address_10bit if the I2C slave address is 10 bits wide
 *  @param[in] address memory address of slave to read from
 *  @param[in] address_size address size in bytes
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_address_read(uint32_t i2c, uint16_t slave, bool address_10bit, const uint8_t* address, size_t address_size, uint8_t* data, size_t data_size);
/** write data at specific address on an I2C memory slave
 *  @param[in] i2c I2C base address
 *  @param[in] slave I2C address of slave device to select
 *  @param[in] address_10bit if the I2C slave address is 10 bits wide
 *  @param[in] address memory address of slave to write to
 *  @param[in] address_size address size in bytes
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_address_write(uint32_t i2c, uint16_t slave, bool address_10bit, const uint8_t* address, size_t address_size, const uint8_t* data, size_t data_size);