장치 관리

사이드바 운영 → 장치 메뉴에서 테넌트의 모든 장치를 등록·관리합니다. 장치를 서버에 연결하는 프로토콜 차원의 설명(MQTT 토픽, 페이로드 형식)은 텔레메트리 수집을 참고하세요. 이 페이지는 화면에서의 조작 순서를 다룹니다.

장치 목록 화면

장치 관리 화면 상단에는 두 개의 버튼이 있습니다.

장치 등록 — 장치를 하나 추가합니다.
CSV 일괄 등록 — CSV 파일로 여러 장치를 한 번에 등록합니다. (아래 CSV 일괄 등록 참조)

목록 위 필터로 자산 필터(특정 자산 소속 장치만)와 게이트웨이(전체 / 게이트웨이만 / 일반 장치만)를 좁힐 수 있습니다. 목록 컬럼은 이름 / 소속 자산 / 유형 / 상태 / 연결 / 마지막 통신 / 작업이며, 연결 상태는 온라인 · 오프라인 · 미연결 세 가지로 표시됩니다. 게이트웨이 장치에는 게이트웨이 배지가, 게이트웨이가 자동 등록한 자식 장치에는 ↳ via 게이트웨이명 링크가 붙습니다.

행을 클릭하면 장치 상세로 이동하고, 작업 열의 아이콘으로 편집 / 토큰 보기 / 삭제를 바로 실행할 수 있습니다.

장치 등록하기

장치 등록 버튼을 누릅니다.
새 장치 등록 다이얼로그에서 입력합니다.
- 소속 자산 — 라인/구역 등 자산에 소속시키려면 선택 (미지정 가능)
- 장치 이름 (필수)
- 게이트웨이 장치 체크박스 — 엣지 게이트웨이가 v1/gateway 프로토콜로 자식 장치 데이터를 중계하는 장치라면 체크합니다.
- 장치 프로파일 — 미지정 시 기본(Default) 프로파일이 자동 할당됩니다.
- 레이블 (선택)
등록을 누르면 장치가 생성되고 접속 토큰이 자동 발급됩니다.

접속 토큰과 데이터 전송

목록에서 토큰 보기를 누르면 토큰 모달이 열립니다. 여기에 장치 펌웨어에 넣을 모든 접속 정보가 모여 있습니다.

장치 토큰 — HTTP/MQTT 인증에 사용하는 문자열 (복사 버튼 제공)
접속 정보 패널
- HTTP 엔드포인트: {서버주소}/api/v1/devices/{토큰}/telemetry
- MQTT 토픽: v1/devices/{토큰}/telemetry
- curl 예시 (복사 버튼):
```
curl -X POST https://<서버주소>/api/v1/devices/<토큰>/telemetry \
  -H 'Content-Type: application/json' \
  -d '{"temperature":25.3}'
```
고객 클레임 코드 패널 — 코드 발급을 누르면 일회성 코드가 생성됩니다. 이 코드를 고객에게 전달하면 고객이 장치 클레임으로 장치를 자기 고객사에 귀속시킬 수 있습니다.
토큰 재발급 — 토큰이 유출됐을 때 새 토큰으로 교체합니다. 기존 토큰은 즉시 무효화되므로 펌웨어의 토큰도 함께 갱신해야 합니다.

전송한 데이터가 들어오는지 확인하려면 장치 상세의 텔레메트리 탭을 열어 보세요.

장치 상세 화면

목록에서 장치를 클릭하면 탭 구조의 상세 화면이 열립니다.

탭	하는 일
속성	SERVER / SHARED / CLIENT 3개 스코프의 속성 관리. SERVER·SHARED는 속성 추가 버튼으로 직접 추가·편집·삭제할 수 있고, CLIENT는 장치가 보고한 값이라 읽기 전용입니다. SHARED 속성을 저장하면 MQTT로 장치에 즉시 푸시됩니다.
텔레메트리	시간 범위(1시간/6시간/24시간/7일)·집계(AVG/MAX/MIN/SUM/COUNT)·간격을 지정해 차트와 최신 값 표를 확인합니다. CSV 내보내기로 원본 데이터를 다운로드할 수 있습니다.
알람	이 장치에서 발생한 알람 목록. 활성 알람은 확인(Ack)·해제(Clear) 버튼으로 처리합니다.
RPC	장치로 원격 명령을 보냅니다. 메서드 이름(예: `reboot`, `setTemperature`)과 JSON 파라미터, 응답 대기 시간을 입력하고 전송. 하단 전송 이력에서 장치의 응답(success/timeout/error)을 확인합니다.
계산 필드	텔레메트리/속성으로부터 파생값을 자동 계산해 텔레메트리·속성으로 기록하는 규칙을 정의합니다.
관계	다른 장치/자산과의 관계(포함/연결/관리/관련)를 목록 또는 그래프 뷰로 관리합니다.
OTA	이 장치의 펌웨어 업데이트 이력(대기/진행 중/완료/실패, 진행률)을 확인합니다.
장치 정보	ID·유형·게이트웨이 여부·연결 상태·생성일 등 읽기 전용 요약.
인증	장치 인증 방식을 액세스 토큰(기본) 또는 MQTT 사용자/비밀번호(Client ID·사용자명·비밀번호) 중에서 선택합니다.
토큰	토큰 확인·복사·재발급.

게이트웨이 장치에는 게이트웨이, 연결된 장치 탭이 추가로 나타납니다. (아래 게이트웨이 운영 참조)

CSV 일괄 등록

장치 관리 또는 장치 프로파일 화면의 CSV 일괄 등록 버튼으로 최대 수백 대의 장치를 한 번에 등록합니다.

템플릿 다운로드로 형식을 받습니다. 헤더는 name,device_type,label,description이며 name만 필수입니다.
CSV 선택으로 파일을 올리면 즉시 등록이 실행됩니다.
결과 화면에서 성공/실패 건수와 각 장치의 토큰을 확인하고, 토큰 CSV 다운로드로 전체 토큰 목록(device-tokens.csv)을 받아 장치에 배포합니다.

장치 자가 등록 (프로비저닝)

장치마다 관리자가 토큰을 발급하는 대신, 장치가 부팅 시 스스로 등록하고 토큰을 받아가게 할 수 있습니다.

관리 → 장치 프로파일에서 프로파일을 만들거나 수정합니다.
장치 자가 등록 옵션을 선택합니다.
- 신규 생성 허용 (키/시크릿 일치 시) — 처음 보는 장치 이름도 자동 생성
- 사전 등록 장치만 — 미리 등록해 둔 장치만 토큰 수령 가능
저장하면 Provision Key/Secret이 자동 생성되고, 다이얼로그에 장치 연결 가이드 패널이 나타납니다. Endpoint(/api/v1/provision)·Key·Secret과 curl 예시를 복사해 펌웨어에 넣으세요.
```
curl -X POST https://<서버주소>/api/v1/provision \
  -H 'Content-Type: application/json' \
  -d '{"device_name":"my-device-001","provision_key":"<KEY>","provision_secret":"<SECRET>"}'
```
장치는 부팅 시 위 요청 1회로 등록되어 device_token을 응답으로 받고, 이후 POST /api/v1/devices/{token}/telemetry로 데이터를 전송합니다.

키/시크릿이 유출됐다면 가이드 패널의 재발급 버튼으로 교체할 수 있습니다.

장치 클레임 (고객 귀속)

관리자가 발급한 클레임 코드를 고객 사용자가 입력하면 해당 장치가 그 고객사에 귀속됩니다.

관리자: 토큰 모달의 고객 클레임 코드 → 코드 발급으로 코드를 만들어 고객에게 전달합니다.
고객 사용자: 사이드바 운영 → 장치 클레임에서 코드를 입력하고 장치 클레임을 누릅니다.
성공하면 장치가 고객사에 할당되고, 코드는 일회성으로 소멸합니다.

게이트웨이 운영

Modbus·OPC-UA 등 직접 인터넷에 연결되지 않는 필드 장비는 엣지 게이트웨이 (linkboard-gateway)를 통해 중계합니다. 장치 등록 시 게이트웨이 장치를 체크하면 상세 화면에 두 개의 탭이 추가됩니다.

게이트웨이 탭

통계 카드 — 자식 장치 수 / 온라인 / 오프라인 / 미연결, 마지막 중계 시각
엣지 게이트웨이 연결 정보 — 게이트웨이 토큰과 발행 토픽 3종을 복사할 수 있습니다.
- 텔레메트리: v1/gateway/{토큰}/telemetry
- 연결 알림: v1/gateway/{토큰}/connect
- 속성: v1/gateway/{토큰}/attributes
자동 등록 설정 — 미등록 자식 장치 자동 등록 허용을 끄면 이미 등록된 자식만 데이터를 중계하고 새 이름은 무시합니다. 기본 자식 장치 유형(예: sensor)도 지정할 수 있습니다.
커넥터 설정 (원격) — 게이트웨이가 현장에서 수집할 커넥터(Simulator / MQTT / Modbus TCP / OPC-UA)를 웹에서 구성합니다. 저장 & 푸시를 누르면 설정이 게이트웨이의 SHARED 속성 connectors로 저장되어 MQTT로 엣지에 즉시 전달·핫리로드됩니다. 커넥터별 카드에서 활성 토글· 재시작·편집·삭제가 가능하고, 고급(JSON) 토글로 JSON 배열을 직접 편집할 수도 있습니다. 하단 게이트웨이 로그에는 게이트웨이가 보고한 최근 로그 50줄이 표시됩니다.

커넥터 종류별 주요 설정:

커넥터	설정 항목
Modbus TCP	호스트·포트·Unit ID·폴링 주기, 장치별 레지스터 매핑(키/주소/종류/타입/배율)
OPC-UA	엔드포인트·보안 정책·인증, 노드 매핑(키/노드 ID)
MQTT	브로커 호스트·포트·인증, 구독 토픽별 값 매핑(키 ← JSONPath)
Simulator	발행 주기, 가상 장치별 키 생성기(sine/random/walk/const, 최소/최대)

연결된 장치 탭

이 게이트웨이가 중계하는 자식 장치 목록입니다. 자동 등록된 장치 외에, 장치 연결 버튼으로 기존 장치를 검색해 수동으로 연결하거나 연결 해제할 수 있습니다.

장치 목록 화면​

장치 등록하기​

접속 토큰과 데이터 전송​

장치 상세 화면​

CSV 일괄 등록​

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

장치 클레임 (고객 귀속)​

게이트웨이 운영​

게이트웨이 탭​

연결된 장치 탭​