64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- Root `CMakeLists.txt` defines the ESP-IDF project (`project(BLE-Printer)`).
|
|
- `main/` is the primary component.
|
|
- `main/main.c` contains the `app_main` entry point.
|
|
- `main/src/` holds module implementations (`gap.c`, `gatt_svc.c`, `heart_rate_mock.c`, `led.c`).
|
|
- `main/include/` provides public headers mirroring module names.
|
|
- `sdkconfig.defaults*` files store per-target defaults (e.g., `sdkconfig.defaults.esp32c3`).
|
|
- `.vscode/` and `.devcontainer/` include editor/devcontainer settings.
|
|
|
|
## Build, Flash, and Development Commands
|
|
- `idf.py set-target esp32` (or `esp32c3`, `esp32c6`, etc.) selects the chip target.
|
|
- `idf.py build` builds the firmware (requires an ESP-IDF environment).
|
|
- `idf.py -p /dev/ttyACM0 flash monitor` builds, flashes, and opens the serial monitor (`Ctrl-]` to exit).
|
|
- Ensure `IDF_PATH` is set via the ESP-IDF export script before running `idf.py`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Language: C with ESP-IDF conventions.
|
|
- Indentation: 4 spaces; braces stay on the same line as control statements and function declarations.
|
|
- Naming: lower_snake for files and functions (e.g., `gatt_svc_init`, `heart_rate_task`).
|
|
- Headers live in `main/include/` and match module names.
|
|
- Prefer `static` for file-local helpers; use `ESP_LOGx` macros for logging.
|
|
|
|
## Testing Guidelines
|
|
- No automated test suite is present in this repository.
|
|
- Manual verification: flash to hardware and validate GATT behavior with a BLE client (for example, nRF Connect) and serial logs.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- This directory does not contain Git history, so no established commit format is visible.
|
|
- Suggested format: `type(scope): summary` (for example, `feat(gatt): add battery service`).
|
|
- PRs should include target chip, test steps (`idf.py …` commands), and relevant serial logs or BLE client screenshots.
|
|
|
|
## BLE Project Context & Configuration
|
|
|
|
**Goal**:
|
|
The ESP32 (running ESP-IDF) must act as a **BLE Central (GATT Client)** to replace the Android App described in the documentation. It needs to connect to a specific BLE Printer.
|
|
|
|
**Reference Document**:
|
|
The paramaters please strickly refer to `BLE_PAIRING_PARAMETERS.md`, focusing on **Section 9 and Section 10**.
|
|
|
|
## Document Relationship and Locations
|
|
- `./APP_BLE打印控制实现说明.md`: Implementation guide for the BLE thermal printer host-side Android APP.
|
|
- `./ESP32_ESP-IDF移植实施文档.md`: ESP32 (ESP-IDF) migration implementation document derived from the Android APP solution.
|
|
|
|
<!-- **Key Implementation Specs**:
|
|
1. **Target Device**:
|
|
- Scan filter: Service UUID or Name `lyfPrinter` (Case insensitive).
|
|
- Connection: One-to-one connection.
|
|
2. **GATT Attributes**:
|
|
- Service: Scan for UUIDs dynamically.
|
|
- Write Char: `0000fff2-0000-1000-8000-00805f9b34fb` (Write No Response).
|
|
- Notify Char: `0000fff1-0000-1000-8000-00805f9b34fb`.
|
|
- MTU: Request size `247` after connection.
|
|
3. **Security/Pairing**:
|
|
- According to Section 9.5, the target device likely allows **Direct Connection (Just Works)** without explicit bonding.
|
|
- Do not enforce high-security pairing unless the connection fails. -->
|
|
|
|
## Configuration Tips
|
|
- Avoid committing local `sdkconfig`; prefer `sdkconfig.defaults*` for shared defaults per target.
|
|
|
|
## 协议帧格式 ##
|
|
- Refer to `Communication_Protocol.md`
|