2025-04-02 v1.1

对之前遗留下来的乱码用 utf-8 重新编写
增加了标准的函数&文件注释

README.md

@@ -1 +1,8 @@
 # 基于 STM32 标准库的软件 I2C
+
+## 待办
+
+- 重构代码，解耦各个模块之间的联系，便于移植
+- 将原本在函数内部的 IO 配置通过回调函数引出函数
+- 重新编写延时部分，将延时方式转为回调 1us 心跳函数
+

i2c.c

@@ -1,11 +1,13 @@
 #include "i2c.h"
 
-// 初始化软件 I2C
+/*
+ * @brief 	初始化 I2C 对应的引脚和定时器
+ * @param	void
+ *
+ * @return 	void
+*/
 void i2cInit(void){
-	/* 初始化需要操作的 I2C IO */
 	GPIO_InitTypeDef GPIO_InitStruct;
-	
-	// enable gpiob for rcc_ahb1
 	I2C_RCC_CLOCK_CMD;
 	
 	GPIO_InitStruct.GPIO_Mode	= GPIO_Mode_OUT;
@@ -16,7 +18,6 @@ void i2cInit(void){
 	GPIO_InitStruct.GPIO_Pin = I2C_SCL_PIN | I2C_SDA_PIN;
 	GPIO_Init(I2C_GROUP,&GPIO_InitStruct);
 	
-	// 初始化 I2C 引脚为高电平
 	GPIO_SetBits(I2C_GROUP, I2C_SCL_PIN);
 	GPIO_SetBits(I2C_GROUP, I2C_SDA_PIN);
 	
@@ -32,20 +33,26 @@ void i2cInit(void){
 	TIM_TimeBaseInit(TIM2, &TIM_TimeBaseStructure);
 
 	TIM_Cmd(TIM2, ENABLE);
-	
-	// 初始化完毕后等待 1ms 可酌情删除
-	//i2cDelay_us(1000);
 }
 
-/* us 级延时 */
+/*
+ * @brief 	延时函数
+ * @param	uint32_t us	延时时长 us
+ *
+ * @return 	void
+*/
 void i2cDelay_us(uint32_t us){
 	TIM_SetCounter(TIM2, 0);
 	// wait counter to target
 	while(TIM_GetCounter(TIM2) < us);
 }
 
-/* 基本控制函数 */
+/*
-// 总线电平控制
+ * @brief 	软件 i2c 引脚操纵函数
+ * @param	uint8_t BitValue 0->低电平/1->高电平
+ *
+ * @return 	void
+*/
 void i2cCon_SCL(uint8_t BitValue){
 	GPIO_WriteBit(I2C_GROUP, I2C_SCL_PIN, (BitAction)(BitValue));
 	i2cDelay_us(i2cSpeedDelay);
@@ -55,15 +62,24 @@ void i2cCon_SDA(uint8_t BitValue){
 	i2cDelay_us(i2cSpeedDelay);
 }
 
-// 读取 SDA 数据
+/*
+ * @brief 	从 i2c SDA 引脚上读取一个 bit 电平
+ * @param	void
+ *
+ * @return 	uint8_t	总线电平状态
+*/
 uint8_t i2cReceive_SDA(void){
 	uint8_t bitValue = GPIO_ReadInputDataBit(I2C_GROUP, I2C_SDA_PIN);
 	i2cDelay_us(i2cSpeedDelay);
 	return bitValue;
 }
 
-/* 基本时序单元 */
+/*
-// 开始信号和结束信号
+ * @brief 	发送起始&终止信号
+ * @param	void
+ *
+ * @return 	void
+*/
 void i2cSignal_Start(void){
 	i2cCon_SDA(1);
 	i2cCon_SCL(1);
@@ -76,8 +92,12 @@ void i2cSignal_Stop(void){
 	i2cCon_SDA(1);
 }
 
-/* 数据收发 */
+/*
-// 发送一个字节
+ * @brief 	发送一个 byte 数据
+ * @param	uint8_t byte	需要发送的数据
+ *
+ * @return 	void
+*/
 void i2cSend_Byte(uint8_t byte){
 	for(int i = 0; i < 8; i++){
 		i2cCon_SDA(!!(byte & (0x80 >> i)));
@@ -85,7 +105,13 @@ void i2cSend_Byte(uint8_t byte){
 		i2cCon_SCL(0);
 	}
 }
-// 接收一个字节
+
+/*
+ * @brief 	接收一个 byte 数据
+ * @param	void
+ *
+ * @return 	uint8_t	接收到的数据
+*/
 uint8_t i2cReceive_Byte(void){
 	uint8_t rByte = 0x00;
 	i2cCon_SDA(1);
@@ -103,12 +129,24 @@ uint8_t i2cReceive_Byte(void){
 	return rByte;
 }
 
-/* 应答位操作 */
+/*
+ * @brief 	发送应答信号
+ * @param	uint8_t ackBit	0->无应答/1->应答
+ *
+ * @return 	void
+*/
 void i2cSend_ACK(uint8_t ackBit){
 	i2cCon_SDA(ackBit);
 	i2cCon_SCL(1);
 	i2cCon_SCL(0);
 }
+
+/*
+ * @brief 	接收应答信号
+ * @param	void
+ *
+ * @return 	uint8_t	是否有应答
+*/
 uint8_t i2cReceive_ACK(void){
 	i2cCon_SDA(1);
 	i2cCon_SCL(1);

i2c.h

@@ -1,21 +1,18 @@
 /*
- *	软件 I2C 库，基于 TIM 定时器的软件 I2C 实现
+ * Copyright (C) 2025 JRNitre nichinichisou67@outlook.com
+ * @file 	i2c.h
+ * @brief	基于 STM32 标准库的软件 i2c 驱动库
  * 
- *	[ DATE ]
+ * @author 	JRNitre
- *	CreateDate		: 2025-03-31
+ * @email	nichinichisou67@outlook.com
- *	LasetModified	: 2025-03-31
+ * @version	v1.0
- *	
+ * @date	2025-03-31
- *	[ COPYRIGHT ]
+ * @license	LGPL 3.0
- *	@ 2025 MAShiroSoftware by JRNitre
- *	
- *	[ VERSION ]
- *	Version			: v1.0
- *
- *	[ ILLUSTRATE ]
- *	当前库编写于 STM32F401CCU6 截至 v1.0 版本还并未对其它平台进行验证
- *	该库基于 STM32 的定时器自带延时函数，在 84Mhz 频率下，采用了 5us 的延时 I2C 通讯速率为 100kb/s
 */
 
+//TODO 重构代码，对核心功能进行封装，方便移植
+//TODO 调整延时函数，使得可以灵活适应不同主频和延时方式
+
 #ifndef __I2C_H
 #define __I2C_H