1 files changed, 141 insertions, 0 deletions
diff --git a/drivers/i2c_master.h b/drivers/i2c_master.h
new file mode 100644
index 0000000000..dbe1cd42fa
--- /dev/null
+++ b/drivers/i2c_master.h
@@ -0,0 +1,141 @@
+// Copyright 2025 QMK
+// SPDX-License-Identifier: GPL-2.0-or-later
+#pragma once
+#include <stdint.h>
+/**
+ * \file
+ *
+ * \defgroup i2c_master I2C Master API
+ *
+ * \brief API to communicate with I2C devices.
+ * \{
+ */
+typedef int16_t i2c_status_t;
+#define I2C_STATUS_SUCCESS (0)
+#define I2C_STATUS_ERROR (-1)
+#define I2C_STATUS_TIMEOUT (-2)
+#define I2C_TIMEOUT_IMMEDIATE (0)
+#define I2C_TIMEOUT_INFINITE (0xFFFF)
+/**
+ * \brief Initialize the I2C driver. This function must be called only once, before any of the below functions can be called.
+ *
+ * This function is weakly defined, meaning it can be overridden if necessary for your particular use case.
+ */
+void i2c_init(void);
+/**
+ * \brief Send multiple bytes to the selected I2C device.
+ *
+ * \param address The 7-bit I2C address of the device.
+ * \param data A pointer to the data to transmit.
+ * \param length The number of bytes to write. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
+#if defined(__AVR__) || defined(__DOXYGEN__)
+/**
+ * \brief Send multiple bytes from PROGMEM to the selected I2C device.
+ *
+ * On ARM devices, this function is simply an alias for i2c_transmit(address, data, length, timeout).
+ *
+ * \param address The 7-bit I2C address of the device.
+ * \param data A pointer to the data to transmit.
+ * \param length The number of bytes to write. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_transmit_P(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
+#else
+#    define i2c_transmit_P(address, data, length, timeout) i2c_transmit(address, data, length, timeout)
+#endif
+/**
+ * \brief Receive multiple bytes from the selected I2C device.
+ *
+ * \param address The 7-bit I2C address of the device.
+ * \param data A pointer to a buffer to read into.
+ * \param length The number of bytes to read. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+/**
+ * \brief Write to a register with an 8-bit address on the I2C device.
+ *
+ * \param devaddr The 7-bit I2C address of the device.
+ * \param regaddr The register address to write to.
+ * \param data A pointer to the data to transmit.
+ * \param length The number of bytes to write. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
+/**
+ * \brief Write to a register with a 16-bit address (big endian) on the I2C device.
+ *
+ * \param devaddr The 7-bit I2C address of the device.
+ * \param regaddr The register address to write to.
+ * \param data A pointer to the data to transmit.
+ * \param length The number of bytes to write. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_write_register16(uint8_t devaddr, uint16_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
+/**
+ * \brief Read from a register with an 8-bit address on the I2C device.
+ *
+ * \param devaddr The 7-bit I2C address of the device.
+ * \param regaddr The register address to read from.
+ * \param data A pointer to a buffer to read into.
+ * \param length The number of bytes to read. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_read_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+/**
+ * \brief Read from a register with a 16-bit address (big endian) on the I2C device.
+ *
+ * \param devaddr The 7-bit I2C address of the device.
+ * \param regaddr The register address to read from.
+ * \param data A pointer to a buffer to read into.
+ * \param length The number of bytes to read. Take care not to overrun the length of `data`.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_read_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+/**
+ * \brief Ping the I2C bus for a specific address.
+ *
+ * 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).
+ *
+ * This function is weakly defined, meaning it can be overridden if necessary for your particular use case.
+ *
+ * \param address The 7-bit I2C address of the device.
+ * \param timeout The time in milliseconds to wait for a response from the target device.
+ *
+ * \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
+ */
+i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout);
+/** \} */

diff --git a/drivers/i2c_master.h b/drivers/i2c_master.h new file mode 100644 index 0000000000..dbe1cd42fa --- /dev/null +++ b/drivers/i2c_master.h
@@ -0,0 +1,141 @@
	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 Write to a register with an 8-bit address on the I2C device.
	77	*
	78	* \param devaddr The 7-bit I2C address of the device.
	79	* \param regaddr The register address to write to.
	80	* \param data A pointer to the data to transmit.
	81	* \param length The number of bytes to write. Take care not to overrun the length of `data`.
	82	* \param timeout The time in milliseconds to wait for a response from the target device.
	83	*
	84	* \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
	85	*/
	86	i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
	87
	88	/**
	89	* \brief Write to a register with a 16-bit address (big endian) on the I2C device.
	90	*
	91	* \param devaddr The 7-bit I2C address of the device.
	92	* \param regaddr The register address to write to.
	93	* \param data A pointer to the data to transmit.
	94	* \param length The number of bytes to write. Take care not to overrun the length of `data`.
	95	* \param timeout The time in milliseconds to wait for a response from the target device.
	96	*
	97	* \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
	98	*/
	99	i2c_status_t i2c_write_register16(uint8_t devaddr, uint16_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
	100
	101	/**
	102	* \brief Read from a register with an 8-bit address on the I2C device.
	103	*
	104	* \param devaddr The 7-bit I2C address of the device.
	105	* \param regaddr The register address to read from.
	106	* \param data A pointer to a buffer to read into.
	107	* \param length The number of bytes to read. Take care not to overrun the length of `data`.
	108	* \param timeout The time in milliseconds to wait for a response from the target device.
	109	*
	110	* \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
	111	*/
	112	i2c_status_t i2c_read_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
	113
	114	/**
	115	* \brief Read from a register with a 16-bit address (big endian) on the I2C device.
	116	*
	117	* \param devaddr The 7-bit I2C address of the device.
	118	* \param regaddr The register address to read from.
	119	* \param data A pointer to a buffer to read into.
	120	* \param length The number of bytes to read. Take care not to overrun the length of `data`.
	121	* \param timeout The time in milliseconds to wait for a response from the target device.
	122	*
	123	* \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
	124	*/
	125	i2c_status_t i2c_read_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
	126
	127	/**
	128	* \brief Ping the I2C bus for a specific address.
	129	*
	130	* 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).
	131	*
	132	* This function is weakly defined, meaning it can be overridden if necessary for your particular use case.
	133	*
	134	* \param address The 7-bit I2C address of the device.
	135	* \param timeout The time in milliseconds to wait for a response from the target device.
	136	*
	137	* \return `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
	138	*/
	139	i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout);
	140
	141	/** \} */