버전: LinkBoard v1.0.188

텔레메트리 수집

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

장치 인증

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

방식	설명
`ACCESS_TOKEN`	장치별 토큰을 MQTT username으로 사용합니다. HTTP 수집 시에도 토큰으로 인증합니다. (기본값)
`MQTT_BASIC`	client_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 } }
]

이미지 수집 (미디어)

텔레메트리 페이로드는 JSON이라 이미지를 담을 수 없습니다. 카메라·비전 검사처럼 이미지를 보내야 하는 장치는 별도의 미디어 경로를 씁니다.

POST /api/v1/devices/{장치토큰}/media          # 직결 장치
POST /api/v1/gateway/{게이트웨이토큰}/media    # 게이트웨이가 자식 대신 업로드 (device=자식이름)

인증은 텔레메트리와 같은 장치 토큰이며 사용자 로그인이 필요 없습니다. png · jpg · jpeg · webp · gif를 허용하고 크기 상한이 있습니다(기본 10MB). 확장자뿐 아니라 파일 내용까지 검사하므로 확장자만 바꿔 올리는 것은 거부됩니다.

핵심은 저장 위치와 참조가 분리된다는 점입니다.

이미지 파일 자체는 시계열 테이블이 아니라 파일 저장소에 보관됩니다.
텔레메트리에는 그 이미지의 URL만 기록됩니다(기본 키 이름 snapshot).

덕분에 시계열 저장소가 바이너리로 부풀지 않으면서도, 이미지 카드 위젯과 Rule Engine이 평소의 텔레메트리 키를 다루듯 최신 이미지를 그대로 쓸 수 있습니다.

조회는 반대로 인증이 필요합니다. 업로드는 장치 토큰으로 열려 있지만, 저장된 이미지를 내려받는 경로는 로그인한 사용자의 권한을 확인하므로 URL이 새어나가도 다른 테넌트가 볼 수 없습니다. 장치 상세의 미디어 탭에서 최근 이미지를 모아볼 수 있고, 보존 기간을 넘긴 미디어는 파일과 기록이 함께 정리됩니다.

저장 구조

수집된 데이터는 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로 조회합니다.

장치 인증​

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

클레임 (고객 귀속)​

MQTT 토픽 구조​

텔레메트리 페이로드​

이미지 수집 (미디어)​

저장 구조​

실시간 조회​