first commit

AGENTS.md

@@ -0,0 +1,63 @@
+# 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`