# yuantzg_dev

**Repository Path**: microchip-valley/yuantzg_dev

## Basic Information

- **Project Name**: yuantzg_dev
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-23
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32-S3 Vibration Monitoring System

A complete vibration monitoring solution for ESP32-S3 with WiFi connectivity and 4G module support.

## Features

### Core Functions
- **Vibration Sampling**: MAX11210 24-bit ADC with configurable sampling rate (default 100Hz)
- **Data Protocol**: Custom 424-byte binary protocol for vibration data transmission
- **4G Module Communication**: UART1 (GPIO36/37, 115200 baud) with custom protocol
- **WiFi Configuration**: AP+STA mode with web-based interface
- **Time Synchronization**: Unix timestamp synchronization via UART
- **LED Indicator**: Visual status indication (GPIO45)

### Data Transmission
- **Auto-upload**: Starts data collection automatically on boot
- **Time-synced timestamps**: Unix time (microseconds) after synchronization
- **Protocol format**: `AA 55 [CMD] [LEN_H] [LEN_L] [DATA] [CRC]`

## Hardware Requirements

- **MCU**: ESP32-S3 development board (16MB flash recommended)
- **ADC**: MAX11210 24-bit ADC for vibration sensor
- **4G Module**: UART communication (GPIO36/37)
- **LED**: Status indicator (GPIO45)
- **Buttons**:
  - RST button (hardware reset)
  - BOOT button (flash mode)
- **Indicators**:
  - Power LED (red) - always on when powered
  - Battery/Charging LED (green) - charging status
  - Status LED (green) - software controlled

## Pin Configuration

### MAX11210 ADC
| Pin | Function |
|-----|----------|
| GPIO8 | CS (Chip Select) |
| GPIO16 | CLK (SPI Clock) |
| GPIO17 | MISO (Master In Slave Out) |
| GPIO18 | MOSI (Master Out Slave In) |

### UART1 (4G Module)
| Pin | Function |
|-----|----------|
| GPIO36 | TX (Transmit to 4G module) |
| GPIO37 | RX (Receive from 4G module) |
| Baud | 115200 |

### LED Indicator
| Pin | Function |
|-----|----------|
| GPIO45 | Status LED (software controlled) |

## LED Status Indication

| LED State | System Status |
|-----------|---------------|
| **Slow blink (1Hz)** | Time not synchronized, device running |
| **Solid on** | Time synchronized, system ready |
| **Quick flash (50ms)** | Data transmitting |

## Software Requirements

- **ESP-IDF**: v5.5.2
- **Python**: 3.8+
- **CMake**: 3.16+
- **Compiler**: Xtensa ESP32-S3 GCC

## Installation

### 1. Set up ESP-IDF environment

```cmd
cd C:\Espressif\frameworks\esp-idf-v5.5.2
export.bat
```

### 2. Build and Flash

```bash
# Set target to ESP32-S3
idf.py set-target esp32s3

# Build the project
idf.py build

# Flash to device (replace COM6 with your port)
idf.py -p COM6 flash monitor
```

For faster flashing:
```bash
idf.py -p COM6 -b 921600 flash monitor
```

## Usage

### 1. Power On

1. Connect device to power supply
2. Status LED starts blinking slowly (time not synced)
3. Device sends SN (serial number) via UART

### 2. Time Synchronization

The device waits for time synchronization command from the 4G module (上位机):

**Command Format**:
```
AA 55 06 00 04 [TIMESTAMP_32BIT_LITTLE_ENDIAN] [CRC]
```

**Example**:
```
AA 55 06 00 04 4D A2 93 69 F5
```

After successful time sync:
- Status LED becomes solid on
- Device starts uploading vibration data every second

### 3. Data Upload

Device automatically uploads vibration data after time synchronization:

**Data Format** (424 bytes):
- Header: 24 bytes (device ID, timestamp, sample count, reserved)
- Data: 400 bytes (100 samples × 4 bytes)
- CRC: 4 bytes

### 4. WiFi Configuration (Optional)

Device also provides WiFi AP for web-based configuration:

1. Connect to AP: `ESP32-Config_XXXXXX`
2. Open browser: `http://192.168.4.1`
3. Configure WiFi credentials
4. Device auto-connects on next boot

## UART Protocol

### Frame Format

```
+--------+--------+--------+--------+--------+-----+--------+
|  HEAD1 |  HEAD2 |   CMD  |  LEN_H |  LEN_L | ... |   CRC  |
+--------+--------+--------+--------+--------+-----+--------+
|  0xAA  |  0x55  | 1 byte | 1 byte | 1 byte | ... | 1 byte |
+--------+--------+--------+--------+--------+-----+--------+
```

### Commands

| Command | Code | Direction | Description |
|---------|------|-----------|-------------|
| START_COLLECTION | 0x01 | DTU → Device | Start data collection |
| STOP_COLLECTION | 0x02 | DTU → Device | Stop data collection |
| DATA_REPORT | 0x03 | Device → DTU | Vibration data (424 bytes) |
| STATUS_QUERY | 0x04 | DTU → Device | Query device status |
| SN_REPORT | 0x05 | Device → DTU | Serial number report |
| TIME_SYNC | 0x06 | DTU → Device | Time synchronization |

### CRC Calculation

CRC-8 checksum calculated from command byte to the end of data field:
```c
uint8_t crc = (cmd + len_h + len_l + data[0] + ... + data[n-1]) & 0xFF;
```

For detailed protocol specification, see `doc/uart_protocol_for_device.md`.

## Project Structure

```
esp32-s3-bp/
├── CMakeLists.txt              # Root project configuration
├── sdkconfig                   # ESP-IDF configuration
├── main/
│   ├── CMakeLists.txt          # Main component configuration
│   ├── main.c                  # Application entry point
│   ├── max11210.c/h            # MAX11210 ADC driver
│   ├── vibration_sampler.c/h   # Vibration sampling task
│   ├── vibration_protocol.c/h  # Data packaging protocol
│   ├── uart_driver.c/h         # UART driver (4G module)
│   ├── led_indicator.c/h       # LED control
│   ├── wifi_manager.c/h        # WiFi management
│   ├── web_server.c/h          # Web server
│   ├── storage.c/h             # NVS storage
│   └── app_mqtt.c/h            # MQTT client
├── doc/
│   ├── uart_protocol_for_device.md    # UART protocol specification
│   └── 振动数据传输协议全链路解析.md  # Protocol documentation (Chinese)
└── BUILD_GUIDE.md              # Build instructions
```

## Configuration

### Sampling Configuration

Edit `main/main.c` (line ~188):
```c
vibration_sampler_config_t sampler_config = {
    .sample_rate_hz = 100,      // Sampling frequency
    .buffer_size = 1000,        // Circular buffer size (samples)
    .filter_alpha = 0.065f,     // IIR filter coefficient (5Hz cutoff)
};
```

### UART Configuration

Edit `main/uart_driver.h` (line ~9):
```c
#define UART_DRIVER_UART_NUM      UART_NUM_1
#define UART_DRIVER_TX_PIN        36
#define UART_DRIVER_RX_PIN        37
#define UART_DRIVER_BAUD_RATE     115200
```

### Timezone

Default timezone: CST-8 (Beijing Time, UTC+8)

## Serial Output

Expected serial output on successful startup:

```
I (1234) MAIN: ESP32-S3 WiFi Configuration Server starting...
I (1256) STORAGE: NVS initialized
I (1278) WIFI_MANAGER: WiFi AP+STA initialized. AP SSID: ESP32-Config_A1B2C3
I (1290) MAIN: MAX11210 configured: PGA×4
I (1310) MAIN: Initializing vibration protocol...
I (1320) MAIN: Initializing vibration sampler...
I (1330) MAIN: Initializing UART driver...
I (1340) LED_INDICATOR: LED indicator initialized (GPIO45, slow blink mode)
I (1350) UART_DRIVER: UART driver initialized successfully
I (1360) UART_DRIVER: Device SN: aabbccddeeff
I (1370) MAIN: ESP32-S3 WiFi Configuration Server Ready!
```

## Troubleshooting

### LED blinking slowly (time not synced)
- Check if 4G module is sending time sync command
- Verify UART connection (GPIO36/37)
- Check serial monitor for UART errors

### No data upload
- Verify time synchronization completed
- Check if 4G module is sending START_COLLECTION command
- LED should be solid on if time synced

### ADC readings all zeros
- Check SPI connections (CS=8, CLK=16, MISO=17, MOSI=18)
- Try setting `MAX11210_SWAP_MISO_MOSI=1` in max11210.h
- Verify sensor power supply

### Stack overflow error
- Stack size already increased to 8192 bytes
- If still occurs, check for memory leaks or infinite loops

### WiFi AP not found
- Wait ~10 seconds after power-on
- Check serial monitor for WiFi initialization errors
- Ensure 2.4GHz network (5GHz not supported)

## API Endpoints

### HTTP API (WiFi Web Interface)

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/` | Serve HTML configuration page |
| GET | `/api/scan` | Scan nearby WiFi networks |
| POST | `/api/connect` | Connect to WiFi network |
| GET | `/api/status` | Get connection status |
| POST | `/api/disconnect` | Disconnect and clear credentials |
| GET | `/api/vibration/data` | Download 424-byte vibration data packet |

## Version History
 - **v1.5** - **ADC采集改进**（2025-03-17）
  - 修复CTRL1配置错误（0xBA → 0xA0）
  - 添加数据预处理（符号扩展、反转、偏移校准）
  - 改为连续转换模式（与参考项目uniBedDot一致）
  - SPI频率提升至4MHz
  - 添加超时保护和任务看门狗
  - 详见：[doc/adc_improvements_summary.md](doc/adc_improvements_summary.md)


- **v1.0** - Initial release with WiFi configuration
- **v1.1** - Added MAX11210 ADC and vibration sampling
- **v1.2** - Added UART driver for 4G module
- **v1.3** - Added LED indicator and time synchronization
- **v1.4** - Fixed stack overflow, optimized for 16MB flash

## License

This project is open source and available for educational and commercial use.

## Documentation

- [UART Protocol Specification](doc/uart_protocol_for_device.md)
- [Build Guide](BUILD_GUIDE.md)
- [Project Instructions](CLAUDE.md)

## Support

For issues and questions:
- ESP-IDF Documentation: https://docs.espressif.com/projects/esp-idf/
- ESP32-S3 Datasheet: https://www.espressif.com/en/support/documents/technical-documents