# 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`