VesiScan-Basic_Zephyr/README.md

# VesiScan BASIC - Zephyr

- nRF52840 기반 VesiScan BASIC 펌웨어의 Zephyr/nRF Connect SDK 프로젝트
- 현재 빌드 대상은 `nrf52840dk_nrf52840` 기준
- MCUboot + BLE MCUmgr DFU, BLE NUS 명령, 배터리/IMU/Piezo/echo ADC capture 등 포함

## 프로젝트 구조

```text
VesiScan-Basic_Zephyr/
├── CMakeLists.txt
├── prj.conf
├── boards/
│   ├── nrf52840dk_nrf52840.overlay
│   └── nrf52840dk_nrf52840.conf
├── sysbuild/
│   ├── mcuboot.conf
│   ├── hci_ipc.conf
│   └── mcuboot_power_hold_module/
├── src/
│   ├── main.c / main.h                                 # 전원, 버튼, 부팅, work queue
│   ├── app_nvs.c / app_nvs.h                           # settings/NVS 저장소
│   ├── power_control.c / power_control.h
│   ├── ble
│   │    ├── ble_service.c / ble_service.h              # BLE NUS, 광고, 보안, DFU 광고 전환
│   ├── command/
│   │   ├── handlers
│   │   ├── cmd_common.c / cmd_common.h
│   │   ├── cmd_table.c / cmd_table.h
│   │   └── parser.c / parser.h                         # BLE 명령 파서와 응답 생성
│   ├── drivers/
│   │   ├── battery/                                    # 배터리 ADC
│   │   ├── echo_adc/                                   # ADC121S051 SPIM capture
│   │   ├── imu/                                        # ICM42670P I2C/FIFO
│   │   ├── led/                                        # LED 패턴
│   │   └── piezo/                                      # Piezo TX/MUX 제어
│   └── measurement/
│       └── piezo_measurement.c / piezo_measurement.h   # Piezo burst ~ capture
├── tools/
├── manual/
└── curcuit/
```

## 빌드

nRF Connect SDK / west 사용:

```powershell
west build -b nrf52840dk_nrf52840 -p auto
west flash
```

또는 로컬에 맞춘 기존 `tools/` 스크립트 또는 VS Code Task를 사용 (`tools/flash_*.ps1`).

빌드 결과로 `zephyr.elf`, `merged.hex` 및 versioned DFU zip 생성됨

아래 파일을 변경한 경우에는 pristine build 필요:

- `prj.conf`
- `boards/*.overlay` 또는 보드 설정
- `CMakeLists.txt` / sysbuild 설정

## 주요 핀 매핑

| 이름 | 핀 | 역할 |
|---|---|---|
| `PWR_HOLD` | P0.08 | 전원 래치, active high |
| `BUTTON_CHECK` | P1.08 | 전원 버튼 |
| `LED_BLE` | P0.12 | 녹색 LED, active low |
| `FUNCTION_LED` | P0.29 | 주황 LED, active low |
| Battery ADC | P0.04 / AIN2 | 배터리 전압 측정 |
| I2C0 SCL | P1.14 | ICM42670P SCL |
| I2C0 SDA | P1.15 | ICM42670P SDA |
| `PIEZO_PWR` | P1.09 | 피에조 전원 enable |
| `PIEZO_PE` | P0.25 | 피에조 pulse enable |
| `PIEZO_P_OUT` | P1.07 | 피에조 P 출력 |
| `PIEZO_N_OUT` | P1.06 | 피에조 N 출력 |
| `PIEZO_DMP` | P1.00 | 피에조 dump |
| `MUX_EN_A` | P0.21 | MUX enable A |
| `MUX_EN_B` | P0.23 | MUX enable B |
| `MUX_SEL0` | P1.10 | MUX select 0 |
| `MUX_SEL1` | P0.28 | MUX select 1 |
| `ECHO_SCLK` | P0.14 | ADC121S051 SCLK |
| `ECHO_MISO` | P0.15 | ADC121S051 MISO |
| `ECHO_CS` | P0.19 | ADC121S051 CS |

`CONFIG_SERIAL=n`으로 UART0를 비활성화하여 P0.08 충돌 회피

## 전원 동작

| 동작 | 조건 | 결과 |
|---|---|---|
| 부팅 | 전원 버튼 2초 이상 유지 | P0.08 래치 ON, LED 광고 패턴, BLE 광고 시작 |
| 짧은 부팅 시도 | 부팅 중 2초 전 버튼 해제 | 래치 해제, 전원 OFF |
| 수동 전원 OFF | ON 상태에서 버튼 재누름 2초 이상 | 광고 중지, LED 표시 후 전원 래치 해제 |
| BLE 10분 광고 만료 | 최초 부팅 광고 또는 정상 disconnect 후 광고 | 광고 중지, 전원 OFF 예약 |
| DFU/soft reset 복귀 | DFU 확인/리셋 플래그 감지 | 버튼 없이 전원 유지 및 광고 복귀 |

## BLE 기능

- Device name: `SERIAL_NO` 기반
- Advertising interval: 40ms
- Normal advertising timeout: 10분
- DFU advertising: SMP UUID, timeout 미적용
- NUS UUID 광고 포함
- 연결 파라미터 선호값: 15ms / latency 0 / supervision timeout 10s
- NUS TX는 mutex + completion semaphore로 순차 전송
- BLE RX는 별도 work queue에서 명령 처리
- 보안 설정: fixed passkey, MITM, Secure Connections only

## BLE 명령 포맷

```text
[TAG 4 bytes][DATA N bytes][CRC16 2 bytes]
```

- TAG: ASCII 4바이트, 예: `msn?`, `mbb?`
- DATA: 명령별 payload
- CRC16: CRC-CCITT, initial `0xFFFF`
- 응답 TAG: 보통 요청의 `m`을 `r`로 바꾼 형태, 예: `msn?` -> `rsn:`

## 구현된 명령

| 명령 | 응답 | 기능 | 상태/비고 |
|---|---|---|---|
| `msq?` | `rsq:` | 전원 OFF | 구현 완료 |
| `mss?` | `rss:` | 재부팅 | 구현 완료 |
| `msr?` | `rsr:` | 본딩 삭제 후 재부팅 | 구현 완료, SMP enabled 기준 |
| `mdf?` | `rdf:` | DFU 광고 모드 진입 | 구현 완료, NUS -> SMP UUID 전환 |
| `msn?` | `rsn:` | 배터리 전압 측정 | 구현 완료 |
| `mls?` | `rls:` | LED 상태 변경 | 구현 완료 |
| `msp?` | `rsp:` | IMU accel/gyro 단발 측정 | 구현 완료 |
| `mst?` | `rst:` | IMU internal temperature | 구현 완료 |
| `mpa?` | `rpa:` | Piezo 전원 ON | 구현 완료, 테스트용 |
| `mpb?` | `rpb:` | Piezo 전원 OFF | 구현 완료, 테스트용 |
| `mpc?` | `rpc:` | Piezo burst only | 구현 완료, 테스트용 |
| `mec?` | `reb:` -> `raa:` | 단일 채널 burst + echo capture | 구현 완료, 테스트용 |
| `mad?` | `reb:` -> `raa:` | ADC only capture | 구현 완료, 테스트용 |
| `maa?` | `reb:` x6 -> `raa:` | 6채널 echo sweep | 구현 완료, 테스트용 |
| `mbb?` | `rbb:` -> `reb:` x6 -> `raa:` | 배터리 + IMU + 온도 + 6채널 echo | 구현 완료 |
| `mtb?` | `reb:` x6 + `rim:` -> `raa:` | Piezo sweep + IMU FIFO | 구현 완료 |
| `mcf?` | `rcf:` | 측정 파라미터 읽기 | 구현 완료 |
| `mcs?` | `rcs:` | 측정 파라미터 쓰기 | 구현 완료, NVS 저장 |
| `mid?` | `rid:` | HW/SN/FW identity 읽기 | 구현 완료 |
| `mfv?` | `rfv:` | FW version 읽기 | 구현 완료 |
| `mwh?` | `rwh:` | HW version 쓰기 | 구현 완료, NVS 저장 |
| `mrh?` | `rrh:` | HW version 읽기 | 구현 완료 |
| `mws?` | `rws:` | Serial number 쓰기 | 구현 완료, NVS 저장 |
| `mrs?` | `rrs:` | Serial number 읽기 | 구현 완료 |
| `mpz?` | `rpz:` | Passkey 쓰기 | 구현 완료, NVS 저장, 최초 1회만 가능 |
| `mqz?` | `rqz:` | Passkey 읽기 | 구현 완료, 삭제 예정 |
| `mim?` | `rim:` | IMU FIFO | 구현 완료 |

## 저장되는 설정

| 항목 | 저장소 key | 쓰기 명령 | 비고 |
|---|---|---|---|
| 피에조 측정 파라미터 | `vesiscan/piezo` | `mcs?` | validate 통과 시 복원 |
| HW version | `vesiscan/hw` | `mwh?` | 고정 길이 ASCII |
| Serial number | `vesiscan/serial` | `mws?` | 광고 name에도 사용 |
| Passkey | `vesiscan/passkey` | `mpz?` | 고정 길이 6자리 |
| Passkey 변경 플래그 | `vesiscan/passkey_changed` | `mpz?` | 1이면 추가 변경 차단 |
| BLE bonding/settings | Zephyr `bt` subtree | BLE stack | `CONFIG_BT_SETTINGS=y` |

## 주요 prj.conf 설정

| 설정 | 값 | 역할 |
|---|---|---|
| `CONFIG_SERIAL` | `n` | UART 비활성화, P0.08 충돌 방지 |
| `CONFIG_BT` | `y` | BLE stack |
| `CONFIG_BT_NUS` | `y` | Nordic UART Service |
| `CONFIG_BT_SMP` | `y` | BLE pairing/security |
| `CONFIG_BT_SMP_ENFORCE_MITM` | `y` | MITM 요구 |
| `CONFIG_BT_SMP_SC_ONLY` | `y` | LE Secure Connections only |
| `CONFIG_BT_SETTINGS` | `y` | BLE bonding/settings 저장 |
| `CONFIG_BT_L2CAP_TX_MTU` | `247` | 큰 NUS 패킷 전송 |
| `CONFIG_ADC` | `y` | 배터리 ADC |
| `CONFIG_I2C` | `y` | IMU I2C |
| `CONFIG_NRFX_SPIM` | `y` | ADC121S051 SPIM capture |
| `CONFIG_BOOTLOADER_MCUBOOT` | `y` | MCUboot 사용 |
| `CONFIG_MCUMGR_TRANSPORT_BT` | `y` | BLE DFU transport |
| `CONFIG_NVS` | `y` | NVS 저장소 |
| `CONFIG_SETTINGS` | `y` | Zephyr settings subsystem |
| `CONFIG_SETTINGS_NVS` | `y` | settings NVS backend |