Skip to main content
Version: LinkBoard v1.0.110

텔레메트리 수집

LinkBoard는 MQTT(EMQX 5.x, MQTT 5.0) · HTTP · WebSocket 세 가지 경로로 장치 데이터를 수집합니다. CoAP/LwM2M/SNMP는 아직 지원하지 않습니다.

장치 인증​

장치는 두 가지 자격증명 방식 중 하나로 연결합니다 (devices.credentials_type).

방식설명
ACCESS_TOKEN장치별 토큰을 MQTT username으로 사용합니다. HTTP 수집 시에도 토큰으로 인증합니다. (기본값)
MQTT_BASICclient_id / username / password 조합으로 인증합니다.

자격증명은 PUT /api/v1/devices/{id}/credentials로 설정·변경합니다(비밀번호는 해시로만 저장되며 조회 시 노출되지 않습니다).

프로덕션 MQTT 인증은 EMQX가 HTTP auth 콜백(POST /api/v1/devices/mqtt-auth)으로 백엔드에 위임하며, 백엔드는 EMQX 5.x 계약에 따라 항상 200과 {"result": "allow"} 또는 {"result": "deny"}를 반환합니다. 개발 기본값은 익명 연결을 허용하므로, 프로덕션에서는 반드시 활성화해야 합니다 (셀프호스팅 배포 참고).

프로비저닝 (자가 등록)​

Device Profile의 provision_type을 지정하면 장치가 부팅 시 스스로 등록하고 토큰을 수령할 수 있어, 장치를 하나씩 수동 등록할 필요가 없습니다.

  • DISABLED — 자가 등록 비활성 (기본값)
  • ALLOW_CREATE — 이름 기준으로 멱등하게 신규 생성
  • CHECK_PRE_PROVISIONED — 미리 등록된 동명 장치가 있을 때만 허용

장치는 프로파일의 provision_key/provision_secret과 함께 POST /api/v1/provision을 호출합니다 (JWT 불필요). 키/시크릿은 프로비저닝을 켤 때 서버가 자동 생성합니다.

클레임 (고객 귀속)​

관리자가 POST /api/v1/devices/{id}/claim-code로 일회성 클레임 코드를 발급하면, 고객 사용자가 POST /api/v1/devices/claim으로 그 코드를 입력해 자신의 고객사에 장치를 귀속시킬 수 있습니다.

MQTT 토픽 구조​

v1/devices/{device_token}/telemetry             # 데이터 발행
v1/devices/{device_token}/attributes            # Client-side 속성 업데이트
v1/devices/{device_token}/attributes/response   # Shared Attribute 수신 (장치가 구독)
v1/devices/{device_token}/rpc/request           # RPC 요청

텔레메트리 페이로드​

// 단순 형식
{ "temperature": 25.3, "humidity": 60 }

// 타임스탬프 포함 형식
[
  { "ts": 1700000000000, "values": { "temperature": 25.3 } },
  { "ts": 1700000001000, "values": { "temperature": 25.5 } }
]

저장 구조​

수집된 데이터는 PostgreSQL/TimescaleDB 하이퍼테이블에 타입별 컬럼 분리 방식으로 저장됩니다.

CREATE TABLE telemetry (
  device_id   UUID        NOT NULL,
  ts          TIMESTAMPTZ NOT NULL,
  key         TEXT        NOT NULL,
  bool_v      BOOLEAN,
  str_v       TEXT,
  long_v      BIGINT,
  dbl_v       DOUBLE PRECISION,
  json_v      JSONB,
  PRIMARY KEY (device_id, ts, key)
);
SELECT create_hypertable('telemetry', 'ts', chunk_time_interval => INTERVAL '1 day');

실시간 조회​

/ws/telemetry/{device_id} WebSocket 엔드포인트로 실시간 스트리밍을 구독할 수 있습니다. 대시보드 위젯은 이 경로로 실시간 데이터를 받고, 과거 구간은 REST API로 조회합니다.