stm32f1/lib/i2c_master.h

/* 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 I²C as master (API)
 *  @file
 *  @author King Kévin <kingkevin@cuvoodoo.info>
 *  @date 2017-2019
 *  @note peripherals used: I²C
 */
#pragma once

/** I²C 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 I²C bus occurred */
};

/** setup I²C peripheral
 *  @param[in] i2c I²C 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 I²C peripheral
 *  @param[in] i2c I²C 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
 *  @return true if complete reset is successful, false if the lines could not be set
 */
bool i2c_master_reset(uint32_t i2c);
/** check if SDA and SCL signals are high
 *  @param[in] i2c I²C base address
 *  @return SDA and SCL signals are high
 */
bool i2c_master_check_signals(uint32_t i2c);
/** send start condition
 *  @param[in] i2c I²C base address
 *  @return I2C return code
 */
enum i2c_master_rc i2c_master_start(uint32_t i2c);
/** select I²C slave device
 *  @warning a start condition should be sent before this operation
 *  @param[in] i2c I²C base address
 *  @param[in] slave I²C address of slave device to select
 *  @param[in] address_10bit if the I²C slave address is 10 bits wide
 *  @param[in] write this transaction will be followed by a read (false) or write (true) operation
 *  @return I²C return code
 */
enum i2c_master_rc i2c_master_select_slave(uint32_t i2c, uint16_t slave, bool address_10bit, bool write);
/** read data over I²C
 *  @warning the slave device must be selected before this operation
 *  @param[in] i2c I²C base address
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @note the last read byte is NACKed, but the I²C peripheral will clock the read for at least 2 more bytes after the NACK
 *  @return I²C return code
 */
enum i2c_master_rc i2c_master_read(uint32_t i2c, uint8_t* data, size_t data_size);
/** write data over I²C
 *  @warning the slave device must be selected before this operation
 *  @param[in] i2c I²C base address
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return I²C 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 I²C base address
 *  @return I²C return code
 */
enum i2c_master_rc i2c_master_stop(uint32_t i2c);
/** read data from slave device
 *  @param[in] i2c I²C base address
 *  @param[in] slave I²C address of slave device to select
 *  @param[in] address_10bit if the I²C slave address is 10 bits wide
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return I²C 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
 *  @param[in] i2c I²C base address
 *  @param[in] slave I²C address of slave device to select
 *  @param[in] address_10bit if the I²C 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 I²C 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 I²C memory slave
 *  @param[in] i2c I²C base address
 *  @param[in] slave I²C address of slave device to select
 *  @param[in] address_10bit if the I²C 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 I²C 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 I²C memory slave
 *  @param[in] i2c I²C base address
 *  @param[in] slave I²C address of slave device to select
 *  @param[in] address_10bit if the I²C 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 I²C 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);