qmk_firmware

QMK firmware for my keyboards (Corne, Sweep Ferris) and trackball (Ploopy Adept)
Log | Files | Refs | Submodules | LICENSE

i2c_master.h (7265B)

      1 // Copyright 2025 QMK
      2 // SPDX-License-Identifier: GPL-2.0-or-later
      3 
      4 #pragma once
      5 
      6 #include <stdint.h>
      7 
      8 /**
      9  * \file
     10  *
     11  * \defgroup i2c_master I2C Master API
     12  *
     13  * \brief API to communicate with I2C devices.
     14  * \{
     15  */
     16 
     17 typedef int16_t i2c_status_t;
     18 
     19 #define I2C_STATUS_SUCCESS (0)
     20 #define I2C_STATUS_ERROR (-1)
     21 #define I2C_STATUS_TIMEOUT (-2)
     22 
     23 #define I2C_TIMEOUT_IMMEDIATE (0)
     24 #define I2C_TIMEOUT_INFINITE (0xFFFF)
     25 
     26 /**
     27  * \brief Initialize the I2C driver. This function must be called only once, before any of the below functions can be called.
     28  *
     29  * This function is weakly defined, meaning it can be overridden if necessary for your particular use case.
     30  */
     31 void i2c_init(void);
     32 
     33 /**
     34  * \brief Send multiple bytes to the selected I2C device.
     35  *
     36  * \param address The 7-bit I2C address of the device.
     37  * \param data A pointer to the data to transmit.
     38  * \param length The number of bytes to write. Take care not to overrun the length of `data`.
     39  * \param timeout The time in milliseconds to wait for a response from the target device.
     40  *
     41  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
     42  */
     43 i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
     44 
     45 #if defined(__AVR__) || defined(__DOXYGEN__)
     46 /**
     47  * \brief Send multiple bytes from PROGMEM to the selected I2C device.
     48  *
     49  * On ARM devices, this function is simply an alias for i2c_transmit(address, data, length, timeout).
     50  *
     51  * \param address The 7-bit I2C address of the device.
     52  * \param data A pointer to the data to transmit.
     53  * \param length The number of bytes to write. Take care not to overrun the length of `data`.
     54  * \param timeout The time in milliseconds to wait for a response from the target device.
     55  *
     56  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
     57  */
     58 i2c_status_t i2c_transmit_P(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
     59 #else
     60 #    define i2c_transmit_P(address, data, length, timeout) i2c_transmit(address, data, length, timeout)
     61 #endif
     62 
     63 /**
     64  * \brief Receive multiple bytes from the selected I2C device.
     65  *
     66  * \param address The 7-bit I2C address of the device.
     67  * \param data A pointer to a buffer to read into.
     68  * \param length The number of bytes to read. Take care not to overrun the length of `data`.
     69  * \param timeout The time in milliseconds to wait for a response from the target device.
     70  *
     71  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
     72  */
     73 i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
     74 
     75 /**
     76  * \brief Send multiple bytes and then receive multiple bytes from the selected I2C device.
     77  *
     78  * \param address The 7-bit I2C address of the device.
     79  * \param tx_data A pointer to the data to transmit.
     80  * \param tx_length The number of bytes to write. Take care not to overrun the length of `tx_data`.
     81  * \param rx_data A pointer to a buffer to read into.
     82  * \param rx_length The number of bytes to read. Take care not to overrun the length of `rx_data`.
     83  * \param timeout The time in milliseconds to wait for a response from the target device.
     84  *
     85  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
     86  */
     87 
     88 i2c_status_t i2c_transmit_and_receive(uint8_t address, const uint8_t* tx_data, uint16_t tx_length, uint8_t* rx_data, uint16_t rx_length, uint16_t timeout);
     89 
     90 /**
     91  * \brief Write to a register with an 8-bit address on the I2C device.
     92  *
     93  * \param devaddr The 7-bit I2C address of the device.
     94  * \param regaddr The register address to write to.
     95  * \param data A pointer to the data to transmit.
     96  * \param length The number of bytes to write. Take care not to overrun the length of `data`.
     97  * \param timeout The time in milliseconds to wait for a response from the target device.
     98  *
     99  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
    100  */
    101 i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
    102 
    103 /**
    104  * \brief Write to a register with a 16-bit address (big endian) on the I2C device.
    105  *
    106  * \param devaddr The 7-bit I2C address of the device.
    107  * \param regaddr The register address to write to.
    108  * \param data A pointer to the data to transmit.
    109  * \param length The number of bytes to write. Take care not to overrun the length of `data`.
    110  * \param timeout The time in milliseconds to wait for a response from the target device.
    111  *
    112  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
    113  */
    114 i2c_status_t i2c_write_register16(uint8_t devaddr, uint16_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
    115 
    116 /**
    117  * \brief Read from a register with an 8-bit address on the I2C device.
    118  *
    119  * \param devaddr The 7-bit I2C address of the device.
    120  * \param regaddr The register address to read from.
    121  * \param data A pointer to a buffer to read into.
    122  * \param length The number of bytes to read. Take care not to overrun the length of `data`.
    123  * \param timeout The time in milliseconds to wait for a response from the target device.
    124  *
    125  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
    126  */
    127 i2c_status_t i2c_read_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
    128 
    129 /**
    130  * \brief Read from a register with a 16-bit address (big endian) on the I2C device.
    131  *
    132  * \param devaddr The 7-bit I2C address of the device.
    133  * \param regaddr The register address to read from.
    134  * \param data A pointer to a buffer to read into.
    135  * \param length The number of bytes to read. Take care not to overrun the length of `data`.
    136  * \param timeout The time in milliseconds to wait for a response from the target device.
    137  *
    138  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
    139  */
    140 i2c_status_t i2c_read_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
    141 
    142 /**
    143  * \brief Ping the I2C bus for a specific address.
    144  *
    145  * On ChibiOS a "best effort" attempt is made by reading a single byte from register 0 at the given address. This should generally work except for I2C devices that do not not respond to a register 0 read request, which will result in a false negative result (unsuccessful response to ping attempt).
    146  *
    147  * This function is weakly defined, meaning it can be overridden if necessary for your particular use case.
    148  *
    149  * \param address The 7-bit I2C address of the device.
    150  * \param timeout The time in milliseconds to wait for a response from the target device.
    151  *
    152  * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
    153  */
    154 i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout);
    155 
    156 /** \} */