# 블루투스 패킷 통신 프로토콜 개발 가이드

**Last Updated**: 2026-04-01

이 문서는 과거 Bluetooth protocol 정리 문서였지만, 현재 repo 구조와는 많이 달라졌습니다.  
이 문서는 **legacy 메모**로만 유지하고, 실제 기준 문서는 아래 두 개를 사용합니다.

- [mcu-protocol.md](./mcu-protocol.md): 현재 앱/MCU 기준 전체 protocol 문서
- [mcu-compatibility-matrix.md](./mcu-compatibility-matrix.md): 버전 혼선, legacy ACK, parser 호환 처리 정리

## 현재 기준 구현 위치

- packet 생성/검증: `packages/roomfit_protocol/lib/src/codec/packet_builder.dart`
- frame 파싱: `packages/roomfit_protocol/lib/src/codec/frame_codec.dart`
- command 정의: `packages/roomfit_protocol/lib/src/commands/command.dart`
- response 정의: `packages/roomfit_protocol/lib/src/responses/response.dart`
- response registry: `packages/roomfit_protocol/lib/src/responses/response_registry.dart`
- transport pipeline: `packages/roomfit_protocol/lib/src/device_link.dart`
- BLE adapter: `lib/core/adapters/ble_transport.dart`
- device state projection: `lib/core/device/device_gateway_impl.dart`

## 이 문서를 legacy로 두는 이유

기존 내용에는 현재 repo에 없는 구조와 이름이 포함되어 있었습니다.

- `initialState.ts`
- `constant.dart`
- `ble_buffer_service_impl.dart`
- `device_command_controller.dart`
- `device_state_service.dart`
- `BluetoothPacketUtils`
- 옛 command/response 명칭

이 내용은 historical context로는 의미가 있지만, 현재 구현의 진실원천으로 쓰면 안 됩니다.

## 운영 원칙

앞으로 Bluetooth/MCU protocol 관련 정리는 이 파일에 새로 누적하지 않습니다.

1. 구현 스펙 변경: [mcu-protocol.md](./mcu-protocol.md) 갱신
2. 버전 mismatch/호환 예외 추가: [mcu-compatibility-matrix.md](./mcu-compatibility-matrix.md) 갱신
3. 행동 보장: 대응 테스트 추가