# [003] thermal derating 활성화 시그널

- **Status:** Open
- **Priority:** Medium
- **Raised:** 2026-04-08
- **Raised by:** 앱 팀 (Bruce)
- **앱 측 영향 코드:**
  - `packages/roomfit_exercise/lib/src/metrics/calculators/standard_vbt_calculator.dart` — velocity loss / fatigue 계산
  - `packages/roomfit_exercise/lib/src/metrics/completed_rep.dart` — `deratingActive` 플래그 추가 예정
  - `docs/reference/rep-detection-research.md` §8.3, §8.8 백로그 항목

---

## 배경

VBT(Velocity-Based Training) 분석의 핵심 지표 중 하나는 **velocity loss %**입니다.
세트가 진행될수록 사용자의 mean concentric velocity가 떨어지는 비율로 피로도를
추정합니다 (대표적으로 10%, 20%, 30% loss를 cutoff로 사용).

문제는 Roomfit이 motor-based 시스템이라 **모터 자체의 thermal derating**이 같은
효과를 만들 수 있다는 것입니다:

- 사용자가 같은 effort로 당기고 있어도, 모터가 열 보호를 위해 토크 출력을
  제한하면 cable에 걸리는 force가 줄어들고, 사용자는 더 빨리 당기게 되며,
  관측되는 velocity는 *오히려 증가*하거나 force가 *임의로 감소*하는 식의
  왜곡이 생깁니다.
- 이 구간을 fatigue에 포함시키면 velocity loss %가 의미를 잃습니다 (모터
  derating으로 인한 변화를 사용자의 피로로 오인).

따라서 분석 레이어에서 **derating 구간의 샘플을 별도로 마킹**하고, velocity
loss / MCV / peak power 계산에서 제외할 수 있어야 합니다.

## 질문

### Q1. 펌웨어 내부에 thermal derating 상태를 나타내는 플래그/변수가 있습니까?

예상되는 후보:
- `WP_Weight.Safety.IqLimit` (전류 제한값) — 평소 대비 낮춰진 상태인지 비교 가능?
- `Motor1.Fb.Temperature` 또는 유사한 모터 온도 측정값
- 별도의 `IsThermallyLimited` 같은 플래그?

해당 값이 어디 있는지 그리고 derating "활성"의 정의(예: 정격 대비 N% 이상
제한된 상태가 M ms 이상 지속) 알려주시면 좋겠습니다.

### Q2. dev report에 **derating 플래그 1바이트** (또는 비트필드)를 추가할 수 있습니까?

요청 [001]의 `Drive_Status` 바이트와 함께 같은 펌웨어 PR로 묶을 수 있다면
이상적입니다. 예:

```c
d[40]=Drive_Status;
d[41]=DeratingFlags;  // bit 0: motorL thermal limit
                      // bit 1: motorR thermal limit
                      // bit 2: voltage sag protection
                      // bit 3..7: reserved
```

byte 단위든 bit 단위든 펌웨어 내부 표현에 맞춰주시면 앱이 그에 맞춰 파싱합니다.

### Q3. 별도 push response가 더 적절한 경우

만약 derating이 매우 드문 이벤트라 매 50ms 리포트에 1바이트를 더하는 것이
부담스럽다면, **state 전환 시점에만** 별도 cmd 코드로 push하는 방법도 가능합니다.

- 예: `0x9?` `DERATING_STATE` — payload `[motorIdx, active, reason]`
- 단점: 앱이 reconnect 직후 현재 derating 상태를 모를 수 있음. 그래서 dev
  report에 매번 포함시키는 게 더 안전합니다.

### Q4. (참고) voltage sag도 같은 카테고리로 봐도 되겠습니까?

배터리/PSU 전압이 떨어지면 모터가 받을 수 있는 전력이 줄어 사실상 derating과
동일한 효과가 나옵니다. 펌웨어가 voltage 기반으로 force를 별도로 제한하는
로직이 있는지 + 있다면 derating 신호와 합쳐서 같은 비트로 노출 가능한지
확인 부탁드립니다.

## 참고 (References)

- VBT velocity loss 학술 배경: `docs/reference/rep-detection-research.md` §4.2
- 백로그 항목: `docs/reference/rep-detection-research.md` §8.3, §8.8
- 앱 측 velocity loss 계산 위치 (TBD): `velocity_loss_analyzer.dart`

---

## MCU 측 응답

<!-- 펌웨어 팀이 작성. 자유 형식. 작성자/날짜/펌웨어 버전 함께 부탁드립니다. -->

_(미응답)_

---

## 결과 (Outcome)

<!-- 응답 받은 후 앱 팀이 정리. 적용된 펌웨어 버전, 앱 측 후속 PR 번호, 검증 결과 등. -->

_(N/A)_