356 lines
12 KiB
Markdown
356 lines
12 KiB
Markdown
# ML307 4G Module Driver
|
||
|
||
This directory contains the ML307 4G module driver implementation for ARCS SDK, refactored from the ESP32-based c_version implementation.
|
||
|
||
## Architecture Overview
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Application Layer │
|
||
│ (HTTP Client, MQTT Client, Custom Protocols, etc.) │
|
||
└───────────────────────┬─────────────────────────────────┘
|
||
│
|
||
┌───────────────────────▼─────────────────────────────────┐
|
||
│ ml307_wrapper.h/c │
|
||
│ High-level Modem Management & Network Operations │
|
||
│ - Module initialization & reboot │
|
||
│ - Network registration monitoring (+CREG URC) │
|
||
│ - PDP context management (+MIPCALL URC) │
|
||
│ - Connection factory (TCP/SSL) │
|
||
└───────────────────────┬─────────────────────────────────┘
|
||
│
|
||
┌───────────────────────▼─────────────────────────────────┐
|
||
│ ml307_tcp.h/c & ml307_udp.h/c │
|
||
│ TCP/SSL & UDP Connection Management │
|
||
│ - Connection lifecycle (connect/disconnect) │
|
||
│ - Data transmission with hex encoding │
|
||
│ - URC handling (MIPOPEN, MIPCLOSE, MIPSEND, MIPURC) │
|
||
│ - Stream & disconnect callbacks │
|
||
└───────────────────────┬─────────────────────────────────┘
|
||
│
|
||
┌───────────────────────▼─────────────────────────────────┐
|
||
│ at_uart.h/c │
|
||
│ AT Command Communication Layer │
|
||
│ - Command/response synchronization (EventGroups) │
|
||
│ - URC (Unsolicited Result Code) parsing │
|
||
│ - Argument parsing (string/int/double) │
|
||
│ - Dynamic buffer management │
|
||
└───────────────────────┬─────────────────────────────────┘
|
||
│
|
||
┌───────────────────────▼─────────────────────────────────┐
|
||
│ lisa_uart (ARCS SDK) │
|
||
│ Hardware UART Driver Interface │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## File Structure
|
||
|
||
### Core Implementation Files
|
||
|
||
| File | Description | Lines |
|
||
|------|-------------|-------|
|
||
| [at_uart.h](at_uart.h) | AT command interface definitions | ~150 |
|
||
| [at_uart.c](at_uart.c) | AT command implementation with URC parsing | ~820 |
|
||
| [ml307_tcp.h](ml307_tcp.h) | TCP/SSL connection interface | ~153 |
|
||
| [ml307_tcp.c](ml307_tcp.c) | TCP/SSL connection implementation | ~620 |
|
||
| [ml307_wrapper.h](ml307_wrapper.h) | High-level modem management interface | ~100 |
|
||
| [ml307_wrapper.c](ml307_wrapper.c) | Modem management implementation | ~388 |
|
||
|
||
### Documentation & Examples
|
||
|
||
| File | Description |
|
||
|------|-------------|
|
||
| [README.md](README.md) | This file - architecture overview |
|
||
| [at_uart_usage_example.md](at_uart_usage_example.md) | AT UART layer usage guide |
|
||
| [ml307_usage_example.md](ml307_usage_example.md) | Complete ML307 usage guide with examples |
|
||
| [ml307_example.c](ml307_example.c) | Compilable example code |
|
||
|
||
### Reference Implementation (ESP32-based)
|
||
|
||
| File | Description |
|
||
|------|-------------|
|
||
| [c_version/at_uart.h](c_version/at_uart.h) | Original ESP32 AT interface |
|
||
| [c_version/at_uart.c](c_version/at_uart.c) | Original ESP32 AT implementation |
|
||
| [c_version/ml307_tcp.c](c_version/ml307_tcp.c) | Original ESP32 TCP implementation |
|
||
| [c_version/ml307_at_modem.c](c_version/ml307_at_modem.c) | Original ESP32 modem management |
|
||
|
||
## Key Features
|
||
|
||
### AT UART Layer (at_uart.c)
|
||
|
||
- ✅ **Command/Response Synchronization**: EventGroup-based waiting mechanism
|
||
- ✅ **URC Parsing**: Automatic detection and callback dispatch for unsolicited messages
|
||
- ✅ **Argument Parsing**: Automatic type detection (string/int/double)
|
||
- ✅ **Dynamic Buffers**: Auto-growing receive/response buffers
|
||
- ✅ **Ping-Pong Buffers**: Dual circular buffers for continuous reception
|
||
- ✅ **Error Handling**: OK/ERROR/+CME ERROR parsing
|
||
- ✅ **Thread Safety**: Multiple mutexes for concurrent access
|
||
- ✅ **Debug Mode**: Optional AT command logging
|
||
|
||
### TCP Layer (ml307_tcp.c)
|
||
|
||
- ✅ **Connection Management**: TCP and SSL/TLS support
|
||
- ✅ **Hex Encoding**: Automatic encoding/decoding for binary data
|
||
- ✅ **Event-driven**: Connection, disconnection, data callbacks
|
||
- ✅ **Multiple Connections**: Support for 6 simultaneous connections (ID 0-5)
|
||
- ✅ **Large Data Transfer**: Automatic chunking (730 bytes per packet)
|
||
- ✅ **Error Reporting**: Last error code tracking
|
||
- ✅ **State Machine**: Proper connection state management
|
||
|
||
### Wrapper Layer (ml307_wrapper.c)
|
||
|
||
- ✅ **Auto-initialization**: Complete module setup sequence
|
||
- ✅ **Network Monitoring**: Real-time network status via URC
|
||
- ✅ **PDP Context**: Automatic IP address detection
|
||
- ✅ **Connection Factory**: Simplified TCP/SSL instance creation
|
||
- ✅ **Sleep Mode**: Power management support
|
||
- ✅ **Connection Reset**: Cleanup utility for all connections
|
||
- ✅ **Reboot Support**: Module reset capability
|
||
|
||
## Quick Start
|
||
|
||
### 1. Basic HTTP GET Request
|
||
|
||
```c
|
||
#include "ml307_wrapper.h"
|
||
#include "ml307_tcp.h"
|
||
|
||
// Initialize modem
|
||
ml307_wrapper_t *modem = ml307_wrapper_create();
|
||
|
||
// Wait for network
|
||
ml307_network_check(modem, 30000);
|
||
|
||
// Create TCP connection
|
||
ml307_tcp_t *tcp = ml307_wrapper_create_tcp(modem, 0);
|
||
|
||
// Connect to server
|
||
ml307_tcp_connect(tcp, "httpbin.org", 80);
|
||
|
||
// Send HTTP request
|
||
const char *request = "GET /get HTTP/1.1\r\nHost: httpbin.org\r\n\r\n";
|
||
ml307_tcp_send(tcp, request, strlen(request));
|
||
|
||
// Cleanup
|
||
ml307_tcp_disconnect(tcp);
|
||
ml307_tcp_destroy(tcp);
|
||
ml307_wrapper_destroy(modem);
|
||
```
|
||
|
||
See [ml307_usage_example.md](ml307_usage_example.md) for comprehensive examples.
|
||
|
||
### 2. With Data Callbacks
|
||
|
||
```c
|
||
void on_data(const char *data, size_t len, void *user_data) {
|
||
printf("Received: %.*s\n", (int)len, data);
|
||
}
|
||
|
||
void on_disconnect(void *user_data) {
|
||
printf("Connection closed\n");
|
||
}
|
||
|
||
// Register callbacks before connecting
|
||
ml307_tcp_on_stream(tcp, on_data, NULL);
|
||
ml307_tcp_on_disconnected(tcp, on_disconnect, NULL);
|
||
ml307_tcp_connect(tcp, "example.com", 80);
|
||
```
|
||
|
||
## Migration from c_version
|
||
|
||
### Key Changes
|
||
|
||
1. **Driver Interface**: ESP32 `Driver_UART.h` → ARCS `lisa_uart.h`
|
||
2. **FreeRTOS Headers**: `freertos/xxx.h` → `FreeRTOS.h`
|
||
3. **GPIO Interface**: ESP32 GPIO → ARCS GPIO (if used)
|
||
4. **Global Instance**: `at_uart_t *uart` parameter → Global singleton pattern
|
||
5. **Configuration**: Kconfig-based GPIO pins → Runtime configuration
|
||
|
||
### API Compatibility
|
||
|
||
Most APIs remain compatible:
|
||
|
||
```c
|
||
// ESP32 version
|
||
at_uart_send_command(uart, "AT", 1000, true);
|
||
|
||
// ARCS version (global instance)
|
||
at_uart_send_command("AT", 1000, true);
|
||
```
|
||
|
||
## Configuration
|
||
|
||
### UART Configuration (at_uart.c)
|
||
|
||
```c
|
||
#define AT_UART_DEVICE LISA_UART_0
|
||
#define AT_UART_BAUD_RATE 115200
|
||
#define AT_UART_RX_BUF_SIZE 1024
|
||
#define AT_UART_TX_BUF_SIZE 512
|
||
```
|
||
|
||
### TCP Timeouts (ml307_tcp.h)
|
||
|
||
```c
|
||
#define TCP_CONNECT_TIMEOUT_MS 10000 // 10 seconds
|
||
#define TCP_SEND_TIMEOUT_MS 5000 // 5 seconds
|
||
```
|
||
|
||
### Network Wait (ml307_wrapper.c)
|
||
|
||
```c
|
||
// Wait up to 30 seconds for network ready
|
||
ml307_network_check(modem, 30000);
|
||
```
|
||
|
||
## Debugging
|
||
|
||
### Enable AT Command Debug
|
||
|
||
```c
|
||
at_uart_set_debug(true);
|
||
```
|
||
|
||
This will log all AT commands and responses:
|
||
|
||
```
|
||
[AT_TX] AT+CREG?
|
||
[AT_RX] +CREG: 2,1,"1234","5678"
|
||
[AT_RX] OK
|
||
```
|
||
|
||
### Check Network Status
|
||
|
||
```c
|
||
network_status_t status = ml307_wrapper_get_network_status(modem);
|
||
bool ready = ml307_wrapper_is_network_ready(modem);
|
||
```
|
||
|
||
### Get Last Error
|
||
|
||
```c
|
||
int error = ml307_tcp_get_last_error(tcp);
|
||
printf("Error code: %d\n", error);
|
||
```
|
||
|
||
## Thread Safety
|
||
|
||
All modules are thread-safe:
|
||
|
||
- **at_uart**: Uses `cmd_mutex`, `tx_mutex`, `buffer_mutex`
|
||
- **ml307_tcp**: Uses `mutex` for instance data
|
||
- **ml307_wrapper**: Uses `event_group` for synchronization
|
||
|
||
Multiple tasks can safely:
|
||
- Send AT commands concurrently (serialized by mutex)
|
||
- Create multiple TCP connections (different IDs)
|
||
- Register callbacks from different tasks
|
||
|
||
## Limitations
|
||
|
||
1. **Maximum Connections**: 6 simultaneous TCP/SSL connections (ID 0-5)
|
||
2. **Maximum Packet Size**: 730 bytes per MIPSEND command
|
||
3. **Buffer Sizes**: RX buffer max 8192 bytes (configurable)
|
||
4. **URC Callbacks**: Executed in UART task context (keep handlers short)
|
||
5. **SSL/TLS**: Uses ML307 built-in SSL (limited configuration options)
|
||
|
||
## Troubleshooting
|
||
|
||
### Module Not Responding
|
||
|
||
```c
|
||
// Enable debug to see AT traffic
|
||
at_uart_set_debug(true);
|
||
|
||
// Try rebooting module
|
||
ml307_wrapper_reboot(modem);
|
||
vTaskDelay(pdMS_TO_TICKS(5000));
|
||
```
|
||
|
||
### Network Registration Fails
|
||
|
||
```c
|
||
// Check SIM card
|
||
at_uart_send_command("AT+CPIN?", 1000, true);
|
||
|
||
// Check signal strength
|
||
at_uart_send_command("AT+CSQ", 1000, true);
|
||
|
||
// Check operator
|
||
at_uart_send_command("AT+COPS?", 1000, true);
|
||
```
|
||
|
||
### TCP Connection Fails
|
||
|
||
- Ensure network is ready: `ml307_wrapper_is_network_ready()`
|
||
- Check connection ID (0-5)
|
||
- Verify server hostname and port
|
||
- Increase timeout if on slow network
|
||
|
||
### Data Not Received
|
||
|
||
- Register callbacks BEFORE connecting
|
||
- Check callback function is being called
|
||
- Enable debug mode to see URC messages
|
||
- Verify data format (hex encoded)
|
||
|
||
## Performance
|
||
|
||
### Typical Timing
|
||
|
||
- Module initialization: ~3-5 seconds
|
||
- Network registration: 5-30 seconds (depends on signal)
|
||
- TCP connection: 1-10 seconds
|
||
- Data send latency: ~100-500ms
|
||
- Data receive latency: ~100-500ms
|
||
|
||
### Memory Usage
|
||
|
||
- `at_uart`: ~8KB (buffers + instance)
|
||
- `ml307_tcp`: ~2KB per connection
|
||
- `ml307_wrapper`: ~1KB
|
||
- Total: ~11KB + (2KB × num_connections)
|
||
|
||
## Testing
|
||
|
||
See [ml307_example.c](ml307_example.c) for complete test examples:
|
||
|
||
```c
|
||
// Start all examples
|
||
ml307_start_examples();
|
||
```
|
||
|
||
This will run:
|
||
1. HTTP GET request
|
||
2. TCP echo client
|
||
3. HTTPS request with SSL
|
||
4. Network status monitoring
|
||
|
||
## References
|
||
|
||
- **ML307 AT Command Manual**: Official ML307 documentation
|
||
- **ARCS SDK Documentation**: lisa_uart driver reference
|
||
- **FreeRTOS API**: Task, EventGroup, Mutex APIs
|
||
- [at_uart_usage_example.md](at_uart_usage_example.md): Detailed AT layer guide
|
||
- [ml307_usage_example.md](ml307_usage_example.md): Complete usage guide
|
||
|
||
## License
|
||
|
||
This implementation is part of the ARCS SDK voice assistant project.
|
||
|
||
## Change Log
|
||
|
||
### Version 1.0 (2024-12)
|
||
|
||
- Initial implementation based on c_version
|
||
- Migrated from ESP32 to ARCS SDK
|
||
- Added comprehensive documentation
|
||
- Added example code
|
||
|
||
---
|
||
|
||
For detailed API documentation and usage examples, see:
|
||
- [at_uart_usage_example.md](at_uart_usage_example.md)
|
||
- [ml307_usage_example.md](ml307_usage_example.md)
|
||
- [ml307_example.c](ml307_example.c)
|