software and system v1
This commit is contained in:
395
1 software design/components/osal/i2c_wrapper/COMPONENT.md
Normal file
395
1 software design/components/osal/i2c_wrapper/COMPONENT.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# I2C Wrapper Component
|
||||
## OSAL Layer - ESP-IDF v5.4 Abstraction
|
||||
|
||||
**Component ID:** C-OSAL-I2C
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Location:** `osal/i2c_wrapper/`
|
||||
**ESP-IDF Service:** `driver/i2c_master.h`, `driver/i2c_slave.h`
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Overview
|
||||
|
||||
The I2C Wrapper provides a platform-independent interface for I2C bus operations, abstracting ESP-IDF v5.4 I2C master and slave drivers. This component enables sensor drivers and other components to access I2C devices without direct ESP-IDF dependencies.
|
||||
|
||||
**Primary Purpose:** Abstract I2C bus operations for application components.
|
||||
|
||||
---
|
||||
|
||||
## 2. Responsibilities
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- I2C bus initialization and configuration
|
||||
- I2C device registration and management
|
||||
- I2C read/write operations (master mode)
|
||||
- I2C bus error handling and recovery
|
||||
- I2C bus resource management
|
||||
- I2C timeout handling
|
||||
- I2C bus status monitoring
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- I2C slave mode (not required for sensor hub)
|
||||
- I2C protocol-level error recovery (handled by ESP-IDF)
|
||||
- I2C bus arbitration (handled by ESP-IDF)
|
||||
- Device-specific I2C protocols (handled by sensor drivers)
|
||||
|
||||
---
|
||||
|
||||
## 3. Provided Interfaces
|
||||
|
||||
### 3.1 Bus Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Initialize I2C bus
|
||||
* @param bus_num I2C bus number (0 or 1)
|
||||
* @param config Bus configuration (clock speed, SDA/SCL pins)
|
||||
* @return OSAL_OK on success, error code on failure
|
||||
*/
|
||||
osal_result_t osal_i2c_bus_init(i2c_bus_num_t bus_num, const osal_i2c_bus_config_t* config);
|
||||
|
||||
/**
|
||||
* @brief Deinitialize I2C bus
|
||||
* @param bus_num I2C bus number
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_bus_deinit(i2c_bus_num_t bus_num);
|
||||
|
||||
/**
|
||||
* @brief Check if I2C bus is initialized
|
||||
* @param bus_num I2C bus number
|
||||
* @return true if initialized, false otherwise
|
||||
*/
|
||||
bool osal_i2c_bus_is_initialized(i2c_bus_num_t bus_num);
|
||||
```
|
||||
|
||||
### 3.2 Device Management Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Register I2C device on bus
|
||||
* @param bus_num I2C bus number
|
||||
* @param device_addr I2C device address (7-bit)
|
||||
* @param device_handle Output device handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_device_register(i2c_bus_num_t bus_num, uint8_t device_addr,
|
||||
osal_i2c_device_handle_t* device_handle);
|
||||
|
||||
/**
|
||||
* @brief Unregister I2C device
|
||||
* @param device_handle Device handle
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_device_unregister(osal_i2c_device_handle_t device_handle);
|
||||
```
|
||||
|
||||
### 3.3 Data Transfer Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Write data to I2C device
|
||||
* @param device_handle Device handle
|
||||
* @param reg_addr Register address (optional, 0 if not used)
|
||||
* @param data Data buffer
|
||||
* @param data_len Data length in bytes
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_write(osal_i2c_device_handle_t device_handle, uint8_t reg_addr,
|
||||
const uint8_t* data, size_t data_len, uint32_t timeout_ms);
|
||||
|
||||
/**
|
||||
* @brief Read data from I2C device
|
||||
* @param device_handle Device handle
|
||||
* @param reg_addr Register address (optional, 0 if not used)
|
||||
* @param data Output data buffer
|
||||
* @param data_len Data length in bytes
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_read(osal_i2c_device_handle_t device_handle, uint8_t reg_addr,
|
||||
uint8_t* data, size_t data_len, uint32_t timeout_ms);
|
||||
|
||||
/**
|
||||
* @brief Write then read (combined transaction)
|
||||
* @param device_handle Device handle
|
||||
* @param write_data Write data buffer
|
||||
* @param write_len Write data length
|
||||
* @param read_data Read data buffer
|
||||
* @param read_len Read data length
|
||||
* @param timeout_ms Timeout in milliseconds
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_write_read(osal_i2c_device_handle_t device_handle,
|
||||
const uint8_t* write_data, size_t write_len,
|
||||
uint8_t* read_data, size_t read_len,
|
||||
uint32_t timeout_ms);
|
||||
```
|
||||
|
||||
### 3.4 Status and Diagnostics Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Get I2C bus status
|
||||
* @param bus_num I2C bus number
|
||||
* @param status Output status structure
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_get_bus_status(i2c_bus_num_t bus_num, osal_i2c_bus_status_t* status);
|
||||
|
||||
/**
|
||||
* @brief Reset I2C bus (recovery from error)
|
||||
* @param bus_num I2C bus number
|
||||
* @return OSAL_OK on success
|
||||
*/
|
||||
osal_result_t osal_i2c_bus_reset(i2c_bus_num_t bus_num);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Structures
|
||||
|
||||
### 4.1 Configuration Structures
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint32_t clock_speed_hz; // I2C clock speed (100kHz, 400kHz, 1MHz)
|
||||
gpio_num_t sda_pin; // SDA GPIO pin
|
||||
gpio_num_t scl_pin; // SCL GPIO pin
|
||||
bool sda_pullup_enable; // Enable SDA pull-up
|
||||
bool scl_pullup_enable; // Enable SCL pull-up
|
||||
uint32_t timeout_ms; // Default timeout
|
||||
} osal_i2c_bus_config_t;
|
||||
|
||||
typedef struct {
|
||||
bool is_initialized;
|
||||
uint32_t active_devices;
|
||||
uint32_t error_count;
|
||||
uint32_t transaction_count;
|
||||
} osal_i2c_bus_status_t;
|
||||
```
|
||||
|
||||
### 4.2 Handle Types
|
||||
|
||||
```c
|
||||
typedef void* osal_i2c_device_handle_t;
|
||||
typedef enum {
|
||||
I2C_BUS_0 = 0,
|
||||
I2C_BUS_1 = 1
|
||||
} i2c_bus_num_t;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Internal State Machine
|
||||
|
||||
```
|
||||
[UNINITIALIZED]
|
||||
↓ osal_i2c_bus_init()
|
||||
[INITIALIZED]
|
||||
↓ osal_i2c_device_register()
|
||||
[DEVICE_REGISTERED]
|
||||
↓ osal_i2c_write/read()
|
||||
[OPERATIONAL]
|
||||
↓ Error detected
|
||||
[ERROR_STATE]
|
||||
↓ osal_i2c_bus_reset()
|
||||
[INITIALIZED]
|
||||
↓ osal_i2c_bus_deinit()
|
||||
[UNINITIALIZED]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. ESP-IDF v5.4 Integration
|
||||
|
||||
### 6.1 ESP-IDF APIs Used
|
||||
|
||||
- `i2c_master_bus_config_t` - Bus configuration
|
||||
- `i2c_master_bus_handle_t` - Bus handle
|
||||
- `i2c_master_dev_handle_t` - Device handle
|
||||
- `i2c_master_bus_add_device()` - Device registration
|
||||
- `i2c_master_transmit_receive()` - Data transfer
|
||||
|
||||
### 6.2 ESP-IDF Error Mapping
|
||||
|
||||
| ESP-IDF Error | OSAL Error |
|
||||
|---------------|------------|
|
||||
| ESP_OK | OSAL_OK |
|
||||
| ESP_ERR_INVALID_ARG | OSAL_ERR_INVALID_ARG |
|
||||
| ESP_ERR_NO_MEM | OSAL_ERR_NO_MEM |
|
||||
| ESP_ERR_TIMEOUT | OSAL_ERR_TIMEOUT |
|
||||
| ESP_ERR_NOT_FOUND | OSAL_ERR_HW_FAILURE |
|
||||
|
||||
---
|
||||
|
||||
## 7. Error Handling
|
||||
|
||||
### 7.1 Error Detection
|
||||
|
||||
- I2C bus errors (NACK, arbitration loss)
|
||||
- Timeout errors
|
||||
- Invalid parameter errors
|
||||
- Resource exhaustion errors
|
||||
|
||||
### 7.2 Error Recovery
|
||||
|
||||
- Automatic bus reset on error
|
||||
- Retry mechanism (configurable)
|
||||
- Error reporting to Diagnostics Manager
|
||||
- Bus status monitoring
|
||||
|
||||
### 7.3 Diagnostic Events
|
||||
|
||||
- `DIAG-HW-I2C-0001`: I2C bus initialization failure
|
||||
- `DIAG-HW-I2C-0002`: I2C device registration failure
|
||||
- `DIAG-HW-I2C-0003`: I2C transaction timeout
|
||||
- `DIAG-HW-I2C-0004`: I2C bus error (NACK)
|
||||
- `DIAG-HW-I2C-0005`: I2C bus reset performed
|
||||
|
||||
---
|
||||
|
||||
## 8. Configuration Parameters
|
||||
|
||||
### 8.1 Build-time Configuration
|
||||
|
||||
- Maximum number of I2C buses: 2
|
||||
- Maximum devices per bus: 8
|
||||
- Default timeout: 1000ms
|
||||
- Retry count: 3
|
||||
|
||||
### 8.2 Runtime Configuration
|
||||
|
||||
- Clock speed (from Machine Constants)
|
||||
- GPIO pin assignments (from GPIO mapping)
|
||||
- Pull-up enable (from hardware design)
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependencies
|
||||
|
||||
### 9.1 OSAL Dependencies
|
||||
|
||||
- **OSAL-GPIO:** GPIO pin configuration
|
||||
|
||||
### 9.2 ESP-IDF Dependencies
|
||||
|
||||
- `driver/i2c_master.h`
|
||||
- `driver/gpio.h`
|
||||
- `esp_err.h`
|
||||
|
||||
### 9.3 Application Dependencies
|
||||
|
||||
- **Logger:** Error logging
|
||||
- **Diagnostics Manager:** Error reporting
|
||||
- **Time Utils:** Timeout handling
|
||||
|
||||
---
|
||||
|
||||
## 10. Thread Safety
|
||||
|
||||
### 10.1 Concurrent Access
|
||||
|
||||
- Bus operations are thread-safe
|
||||
- Device handles are thread-safe
|
||||
- Multiple devices on same bus can be accessed concurrently
|
||||
- Bus initialization/deinitialization requires synchronization
|
||||
|
||||
### 10.2 FreeRTOS Integration
|
||||
|
||||
- Uses FreeRTOS mutex for bus protection
|
||||
- Non-blocking operations preferred
|
||||
- Timeout handling uses FreeRTOS ticks
|
||||
|
||||
---
|
||||
|
||||
## 11. Performance Considerations
|
||||
|
||||
### 11.1 Timing Constraints
|
||||
|
||||
- I2C write operation: < 10ms (typical)
|
||||
- I2C read operation: < 10ms (typical)
|
||||
- Bus initialization: < 100ms
|
||||
- Device registration: < 10ms
|
||||
|
||||
### 11.2 Resource Usage
|
||||
|
||||
- Memory: ~2KB per bus (ESP-IDF overhead)
|
||||
- CPU: Minimal (hardware-assisted)
|
||||
- Interrupts: I2C interrupt handler
|
||||
|
||||
---
|
||||
|
||||
## 12. Testing Strategy
|
||||
|
||||
### 12.1 Unit Testing
|
||||
|
||||
- Mock ESP-IDF I2C functions
|
||||
- Test error handling paths
|
||||
- Test timeout handling
|
||||
- Test resource management
|
||||
|
||||
### 12.2 Integration Testing
|
||||
|
||||
- Test with real I2C devices
|
||||
- Test concurrent access
|
||||
- Test error recovery
|
||||
- Test bus reset functionality
|
||||
|
||||
### 12.3 Hardware Testing
|
||||
|
||||
- Test with actual sensors
|
||||
- Test I2C bus conflicts
|
||||
- Test pull-up resistor behavior
|
||||
- Test clock speed variations
|
||||
|
||||
---
|
||||
|
||||
## 13. Traceability
|
||||
|
||||
### 13.1 System Requirements
|
||||
|
||||
- **SR-HW-005:** System shall abstract all hardware interfaces through driver layers
|
||||
- **SR-SYS-015:** System shall ensure all shared I2C buses have appropriate physical pull-up resistors
|
||||
|
||||
### 13.2 Software Requirements
|
||||
|
||||
- **SWR-IF-002:** Software shall provide sensor interfaces supporting I2C protocol
|
||||
- **SWR-DESIGN-003:** Software shall access hardware only through driver and OSAL layers
|
||||
|
||||
### 13.3 Cross-Feature Constraints
|
||||
|
||||
- **CFC-ARCH-01:** Application logic shall not access hardware directly
|
||||
|
||||
---
|
||||
|
||||
## 14. Implementation Notes
|
||||
|
||||
### 14.1 ESP-IDF v5.4 Specifics
|
||||
|
||||
- Uses new I2C master driver API (not legacy)
|
||||
- Supports I2C_NUM_0 and I2C_NUM_1
|
||||
- Clock speed: 100kHz, 400kHz, 1MHz supported
|
||||
- Requires proper GPIO configuration
|
||||
|
||||
### 14.2 GPIO Requirements
|
||||
|
||||
- SDA and SCL pins must be configured via GPIO mapping
|
||||
- Physical pull-up resistors required (2.2kΩ - 4.7kΩ)
|
||||
- Software pull-ups can be enabled as backup
|
||||
|
||||
### 14.3 Known Limitations
|
||||
|
||||
- Maximum 8 devices per bus (ESP-IDF limitation)
|
||||
- Clock stretching not fully supported in all modes
|
||||
- Bus sharing requires careful synchronization
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
**Approval Required:** Software Architect
|
||||
Reference in New Issue
Block a user