# 알림 도움말

> TeslaMate 옆에서 Notifier를 실행하는 데 필요한 모든 것, 그리고 이벤트가 오지 않을 때 확인할 항목.

## 시작하기 전에

세 가지면 되고, 대부분의 TeslaMate 설치에는 앞의 두 가지가 이미 있습니다.

- MQTT 브로커가 있는 TeslaMate. Mosquitto는 TeslaMate 기본 Compose 파일에 포함되어 있습니다.
- TeslaMate와 같은 머신의 Docker, 또는 브로커에 접근할 수 있는 아무 호스트.
- 아웃바운드 인터넷 연결. 인바운드 포트는 필요 없고 TeslaMate를 외부에 공개하지 않아도 됩니다.

## Notifier 설치

TeslaMate는 스스로 아이폰에 연결할 수 없고, iOS 알림은 Apple을 거쳐야만 도착합니다. Notifier는 MQTT를 지켜보다가 이벤트를 넘겨주는 작은 컨테이너입니다. TeslaMate 옆에서 실행되며 포트를 열지 않습니다.

### 1. 앱에서 토큰 받기

HedgieMate를 열고 설정에서 푸시 알림으로 이동해 알림을 켭니다. 앱이 hm_로 시작하는 연결 토큰과 현재 연결된 TeslaMate 서버의 ID를 보여줍니다. 둘 다 복사하세요.

_토큰은 앱과 컨테이너를 연결합니다. 비밀번호처럼 다루세요._

### 2. Compose 파일에 컨테이너 추가

TeslaMate를 실행하는 docker-compose.yml을 열고 아래 서비스를 추가합니다. 같은 파일에 두면 브로커와 네트워크를 공유하므로 MQTT_HOST는 브로커의 서비스 이름이면 됩니다.

```yaml
# add under services: in the docker-compose.yml you run TeslaMate from
  hedgiemate-notifier:
    image: hedgiemate/notifier:latest
    restart: unless-stopped
    depends_on:
      - mosquitto
    environment:
      HEDGIEMATE_USER_TOKEN: "hm_your_token_here"
      SERVER_ID: "your-server-uuid"
      MQTT_HOST: "mosquitto"
      MQTT_PORT: "1883"
      CAR_IDS: "1"
      LOG_LEVEL: "info"
    volumes:
      - hedgiemate-notifier-data:/data

# and under the top-level volumes: key, adding it if the file has none
  hedgiemate-notifier-data:
```

_볼륨은 선택 사항입니다. 재시작 후에도 차량 이름을 유지하며, 없어도 릴레이가 이름을 채웁니다. 바인드 마운트 대신 이름이 있는 볼륨을 쓰세요. 컨테이너는 root가 아닌 사용자로 실행되어 Docker가 root로 만든 호스트 디렉터리에는 쓸 수 없습니다._

### 3. 실행

새 서비스를 올립니다. 스택의 나머지는 재시작할 필요가 없습니다.

```bash
docker compose up -d hedgiemate-notifier
```

그다음 로그를 확인하세요. 정상적으로 시작하면 브로커 연결과 감시 중인 차량 ID가 출력됩니다.

```bash
docker compose logs -f hedgiemate-notifier
```

### 4. 앱에서 확인

앱이 몇 초 안에 서버를 연결됨으로 표시합니다. 이후 차량별로 각 이벤트를 켜고 끌 수 있습니다.

_차량이 실제로 상태를 바꾸기 전에는 아무것도 오지 않습니다. 첫 이벤트를 가장 빨리 보려면 충전 케이블을 연결해 보세요._

### Compose 없이

TeslaMate를 Compose로 관리하지 않는다면 docker run으로도 동일하게 동작합니다. MQTT_HOST를 컨테이너가 접근 가능한 호스트로 지정하세요.

```bash
docker run -d \
  --name hedgiemate-notifier \
  --restart unless-stopped \
  -e HEDGIEMATE_USER_TOKEN="hm_your_token_here" \
  -e SERVER_ID="your-server-uuid" \
  -e MQTT_HOST="your-mqtt-host" \
  -e CAR_IDS="1" \
  hedgiemate/notifier:latest
```

### TeslaMate가 여러 대인 경우

서버마다 Notifier를 하나씩 실행하세요. 같은 연결 토큰이 모든 서버에서 동작하며, 앱에서 서버를 구분하는 것은 서버 ID입니다.

## 설정

모든 설정은 환경 변수로 합니다. 세 개는 필수이고 나머지는 기본값으로 동작합니다.

| 변수 | 기본값 | 설명 |
| --- | --- | --- |
| `HEDGIEMATE_USER_TOKEN` (필수) | 없음 | 앱에서 받은 연결 토큰. hm_로 시작합니다. |
| `MQTT_HOST` (필수) | 없음 | MQTT 브로커의 호스트 이름. Compose 안에서는 서비스 이름이며 보통 mosquitto입니다. |
| `SERVER_ID` (필수) | 없음 | 앱에서 받은 서버 UUID. 없어도 컨테이너는 시작하지만, 앱에서 설정한 서버별 및 차량별 설정이 무시됩니다. |
| `MQTT_PORT` | `1883` | 브로커 포트. |
| `MQTT_USERNAME` | 없음 | 브로커가 인증을 요구할 때 사용할 사용자 이름. |
| `MQTT_PASSWORD` | 없음 | 브로커 비밀번호. |
| `MQTT_CLIENT_ID` | `hedgiemate-notifier` | 브로커에서 사용할 클라이언트 ID. 다른 것이 이미 이 ID로 연결한다면 변경하세요. |
| `MQTT_TLS` | `false` | TLS 브로커면 true로 설정합니다. 기본 포트가 8883으로 바뀝니다. |
| `MQTT_NAMESPACE` | 없음 | TeslaMate에서 MQTT_NAMESPACE를 설정했다면 같은 값을 넣으세요. 토픽이 teslamate/cars/# 형태가 됩니다. |
| `CAR_IDS` | `1` | 감시할 차량 ID를 쉼표로 구분해 지정합니다. 예: 1,2. 차량마다 별도의 상태 머신을 갖습니다. |
| `LOG_LEVEL` | `info` | debug, info, warn 또는 error. |
| `RELAY_URL` | `https://push.hedgiemate.com` | 릴레이 주소. 변경할 이유는 없습니다. |

## 모든 이벤트

각 행은 앱에서 차량별로 켜고 끄는 개별 스위치입니다. Live Activities 업데이트는 알림이 아니므로 목록에 없습니다.

| 알림 | 전송 시점 |
| --- | --- |
| 주행 시작 | `state → driving` |
| 주행 종료 | `state leaves driving` |
| 충전 시작 | `charging_state → Charging` |
| 충전 완료 | `charging_state → Complete` |
| 충전 중단됨 | `charging_state leaves Charging without Complete` |
| 충전기 연결됨 | `plugged_in → true` |
| 충전기 분리됨 | `plugged_in → false` |
| 배터리 부족 | `battery_level ≤ BATTERY_LOW_THRESHOLD` |
| 목표 배터리 도달 | `battery_level ≥ BATTERY_HIGH_THRESHOLD` |
| 센트리 녹화 | `center_display_state = 7` |
| 소프트웨어 업데이트 | `update_available → true` |
| 지오펜스 진입 | `geofence set` |
| 지오펜스 이탈 | `geofence cleared or changed` |
| 절전 모드 전환 중 | `state → asleep pending` |
| 절전 모드 | `state → asleep` |
| 차량 깨어남 | `state leaves asleep` |

## 아무것도 오지 않을 때

위에서부터 차례로 확인하세요. 대부분은 처음 세 가지 중 하나입니다.

### 앱에서 서버가 연결되지 않았다고 계속 표시됩니다

docker compose ps로 컨테이너가 실제로 실행 중인지 확인한 뒤 로그를 읽어보세요. 가장 흔한 원인은 잘못된 MQTT_HOST입니다. Compose 안에서는 브로커의 서비스 이름인 mosquitto이지 localhost가 아닙니다.

### 컨테이너는 도는데 이벤트가 전혀 발생하지 않습니다

CAR_IDS가 TeslaMate가 쓰는 차량 ID와 일치해야 합니다. TeslaMate는 차량 번호를 1부터 매기며, 차량이 여러 대면 모두 나열합니다: CAR_IDS=1,2.

### MQTT는 연결되는데 로그가 조용합니다

TeslaMate에서 MQTT_NAMESPACE를 설정했다면 Notifier에도 같은 값을 넣으세요. 값이 없으면 토픽 이름이 맞지 않아 컨테이너가 읽을 것이 없습니다.

### 어떤 이벤트는 오고 어떤 것은 오지 않습니다

모든 이벤트는 앱에서 차량별 스위치입니다. 설정에서 해당 서버를 열고 그 차량의 이벤트 목록을 확인하세요.

### 배터리 알림이 전혀 오지 않습니다

BATTERY_LOW_THRESHOLD와 BATTERY_HIGH_THRESHOLD의 기본값은 20과 90입니다. 충전 세션마다 한 번 발생하므로, 충전을 시작한 뒤 기준을 넘지 않은 차량은 알림을 보내지 않습니다.

### 며칠 지나면 알림이 끊깁니다

서비스에 restart: unless-stopped가 있어 호스트와 함께 다시 뜨는지 확인하세요. 그다음 iOS를 확인하세요. 집중 모드나 앱의 알림 설정이 알림을 막고 있을 수 있습니다.

### Live Activities가 나타나지 않습니다

iOS 설정에서 HedgieMate의 Live Activities가 허용되어 있어야 하고, 진행 중인 세션이 있어야 합니다. Dynamic Island는 iPhone 14 Pro 이상이 필요합니다.

### 브로커가 로그인이나 TLS를 요구합니다

MQTT_USERNAME과 MQTT_PASSWORD를 설정하세요. TLS는 MQTT_TLS를 true로 두면 되고, 기본 포트가 8883으로 바뀝니다.

### 어떤 동작을 하는지 보고 싶습니다

LOG_LEVEL을 debug로 바꾸고 상황을 재현한 뒤 원래대로 되돌리세요. debug는 모든 MQTT 메시지와 그로부터 내린 판단을 기록합니다.

## 질문

### Notifier가 왜 필요한가요?

TeslaMate는 여러분의 서버에서 돌아가기 때문에 아이폰에 직접 연결할 수 없고, iOS 알림은 Apple만 전달할 수 있습니다. Notifier가 그 사이를 잇습니다. MQTT 토픽을 지켜보다가 상태 변화를 감지하고 이벤트를 전송합니다.

### TeslaMate가 인터넷에서 접근 가능해야 하나요?

아니요. Notifier는 나가는 연결만 만들기 때문에 알림을 위해 무언가를 공개하거나 포트를 열 필요가 없습니다.

### 서버에서 실제로 나가는 정보는 무엇인가요?

이벤트 종류, 배터리 잔량, 충전 상태, 그리고 지오펜스를 쓴다면 지오펜스 이름입니다. 좌표와 주행 경로는 TeslaMate에 남고 서버 주소는 전송되지 않습니다. 이벤트 데이터는 몇 시간 뒤 삭제됩니다.

### TeslaMate와 다른 머신에서 실행할 수 있나요?

MQTT 브로커에 접근할 수 있다면 가능합니다. MQTT_HOST를 해당 호스트로 지정하고 그곳에서 브로커 포트에 접근되는지 확인하세요.

### 차량이 여러 대여도 되나요?

됩니다. CAR_IDS에 ID를 나열하면 차량마다 별도의 상태 추적과 앱 내 스위치를 갖습니다.

### 릴레이에 연결할 수 없으면 어떻게 되나요?

컨테이너가 간격을 늘려가며 몇 번 재시도한 뒤 해당 이벤트를 버립니다. 계속 실행되며 다음 상태 변화는 정상적으로 처리합니다.

### 저장하는 데이터가 있나요?

차량 이름 캐시뿐이며, 그것도 선택 볼륨을 연결한 경우에만 저장됩니다. 나머지는 컨테이너가 실행되는 동안 메모리에만 있습니다.

### 업데이트는 어떻게 하나요?

이미지를 다시 받고 서비스를 재생성하면 됩니다. 릴리스 노트는 GitHub의 releases 페이지에 있습니다.

### 알림을 끄려면 어떻게 하나요?

앱에서 끄거나 컨테이너를 중지하세요. 둘 중 하나만으로 충분하며, TeslaMate 스택의 다른 구성 요소는 Notifier에 의존하지 않습니다.

## 소스 코드

Notifier는 MIT 라이선스의 Go 코드입니다. 코드를 읽어보거나 문제가 있으면 이슈를 남겨 주세요.

- [저장소](https://github.com/LukStankovic/hedgiemate-notifier)
- [릴리스와 changelog](https://github.com/LukStankovic/hedgiemate-notifier/releases)

이미지: hedgiemate/notifier:latest