MQTT 프로토콜을 사용하여 장치 데이터와 커맨드를 발행할 수 있습니다.
연결 설정
| 항목 | 값 | 설명 |
|---|---|---|
| Host | your-server | IOTOWN 서버 주소 |
| Port | 8883 | MQTT TLS 포트 |
| Username | {group_id} | 그룹 UUID |
| Password | {api_key} | 그룹 API 키 |
보안을 위해 TLS(8883 포트)만 지원합니다. 평문 연결(1883)은 비활성화되어 있습니다.
Group ID와 API Key 확인 방법
| 계정 레벨 | Group ID / API Key 위치 |
|---|---|
관리자 | 그룹 페이지에서 각 그룹의 인증 정보 |
매니저 | 헤더 우측의 프로필 메뉴 > 내 그룹 인증 정보 |
토픽 구조
| 토픽 | 방향 | 용도 |
|---|---|---|
iotown/{group_id}/{device_id}/data | 장치 → 서버 | 데이터 전송 |
iotown/{group_id}/{device_id}/command/request | 서버 → 장치 | 커맨드 전송 |
iotown/{group_id}/{device_id}/command | 서버 → 장치 | 커맨드 수신 |
데이터 전송
장치에서 서버로 데이터를 발행합니다.
데이터 전송 토픽
MQTT Topic
iotown/{group_id}/{device_id}/data
데이터 전송 페이로드
JSON 형식으로 데이터를 전송합니다.
JSON
{
"temperature": 25.5,
"humidity": 60,
"status": "normal"
}HTTP API와 달리 MQTT 페이로드는 데이터 필드 자체이며 deviceId나 data 래핑이 없습니다 — deviceId/groupId는 토픽에서 추출되기 때문입니다. 또한 MQTT는 JSON만 지원하므로 파일 첨부가 필요하면 REST API의 multipart 전송을 사용하세요.
장치 타임스탬프 (_timestamp)
데이터 측정(생성) 시간과 서버 수신 시간이 다를 경우에 사용합니다. 오랜 시간이 경과한 데이터를 측정 시간에 맞도록 서버에 저장할 수 있습니다.
페이로드에 _timestamp 필드를 포함하면 서버 수신 시간 대신 장치가 보고하는 측정 시간을 사용할 수 있습니다.
JSON
{
"temperature": 25.5,
"humidity": 60,
"_timestamp": "2025-01-08T12:00:00.000Z"
}- ISO 8601 형식 (예:
2025-01-08T12:00:00.000Z) 또는 Unix 밀리초 타임스탬프 (예:1736337600000) 지원 _timestamp를 생략하면 서버 수신 시간이 사용됩니다_timestamp는 시스템 예약 필드이므로 데이터에 포함되지 않고 타임스탬프로만 사용됩니다
deviceId가 존재하지 않으면 자동으로 장치가 생성됩니다.
커맨드 전송
서버에서 장치로 커맨드를 발행합니다.
커맨드 전송 토픽
MQTT Topic
iotown/{group_id}/{device_id}/command/request
커맨드 전송 페이로드
커맨드는 문자열로 전송됩니다. 형식은 자유롭게 정의할 수 있습니다.
텍스트 명령
set_interval 30JSON 명령
{"action": "reboot", "delay": 5}커맨드 수신
장치에서 서버로부터 전송된 커맨드를 수신합니다.
커맨드 수신 토픽
MQTT Topic
iotown/{group_id}/{device_id}/command
장치는 이 토픽을 구독(subscribe)하여 서버로부터 커맨드를 수신합니다.
커맨드 수신 페이로드
커맨드는 문자열로 수신됩니다. 전송 시 사용한 형식 그대로 전달됩니다.
텍스트 명령
set_interval 30JSON 명령
{"action": "reboot", "delay": 5}command/request 토픽으로 전송된 커맨드는 IOTOWN 서버가 command 토픽으로 릴레이합니다.
Rate Limit
| 제한 대상 | 제한 |
|---|---|
| 데이터 발행 | 60회/분 (장치당) |
| 커맨드 발행 | 60회/분 (장치당) |
Rate Limit 초과 시 메시지는 무시됩니다 (MQTT 특성상 별도 응답 없음).