시작하기 전에
세 가지면 되고, 대부분의 TeslaMate 설치에는 앞의 두 가지가 이미 있습니다.
- MQTT 브로커가 있는 TeslaMate. Mosquitto는 TeslaMate 기본 Compose 파일에 포함되어 있습니다.
- TeslaMate와 같은 머신의 Docker, 또는 브로커에 접근할 수 있는 아무 호스트.
- 아웃바운드 인터넷 연결. 인바운드 포트는 필요 없고 TeslaMate를 외부에 공개하지 않아도 됩니다.
Notifier 설치
TeslaMate는 스스로 아이폰에 연결할 수 없고, iOS 알림은 Apple을 거쳐야만 도착합니다. Notifier는 MQTT를 지켜보다가 이벤트를 넘겨주는 작은 컨테이너입니다. TeslaMate 옆에서 실행되며 포트를 열지 않습니다.
-
앱에서 토큰 받기
HedgieMate를 열고 설정에서 푸시 알림으로 이동해 알림을 켭니다. 앱이 hm_로 시작하는 연결 토큰과 현재 연결된 TeslaMate 서버의 ID를 보여줍니다. 둘 다 복사하세요.
토큰은 앱과 컨테이너를 연결합니다. 비밀번호처럼 다루세요.
-
Compose 파일에 컨테이너 추가
TeslaMate를 실행하는 docker-compose.yml을 열고 아래 서비스를 추가합니다. 같은 파일에 두면 브로커와 네트워크를 공유하므로 MQTT_HOST는 브로커의 서비스 이름이면 됩니다.
docker-compose.yml# 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로 만든 호스트 디렉터리에는 쓸 수 없습니다.
-
실행
새 서비스를 올립니다. 스택의 나머지는 재시작할 필요가 없습니다.
터미널docker compose up -d hedgiemate-notifier
그다음 로그를 확인하세요. 정상적으로 시작하면 브로커 연결과 감시 중인 차량 ID가 출력됩니다.
터미널docker compose logs -f hedgiemate-notifier
-
앱에서 확인
앱이 몇 초 안에 서버를 연결됨으로 표시합니다. 이후 차량별로 각 이벤트를 켜고 끌 수 있습니다.
차량이 실제로 상태를 바꾸기 전에는 아무것도 오지 않습니다. 첫 이벤트를 가장 빨리 보려면 충전 케이블을 연결해 보세요.
Compose 없이
TeslaMate를 Compose로 관리하지 않는다면 docker run으로도 동일하게 동작합니다. MQTT_HOST를 컨테이너가 접근 가능한 호스트로 지정하세요.
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<namespace>/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 |
| 위치 | |
| 지오펜스 진입 | geofence set |
| 지오펜스 이탈 | geofence cleared or changed |
| 보안 | |
| 센트리 녹화 | center_display_state = 7 |
| 차량 | |
| 소프트웨어 업데이트 | update_available → true |
| 절전 모드 전환 중 | 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 코드입니다. 코드를 읽어보거나 문제가 있으면 이슈를 남겨 주세요.