User Manual

Introduction

IOTOWN(아이오타운)은 사물인터넷(Internet of Things; IoT) 시스템을 쉽게 구축할 수 있도록 하는 웹 서비스입니다. 이 장에서는 IOTOWN 서비스의 목적과 사용 시나리오를 소개합니다. 이와 관련하여 IOTOWN 서비스의 구조와 구성요소를 소개하여 기본 개념에 대한 이해를 구합니다. 그리고 IoT.won의 각 기능들에 대해 간략히 소개합니다.

서비스의 목적

사물인터넷은 무선 및 유선 기반의 센싱 시스템을 인터넷 및 웹과 연결함을 의미하는 것으로 이를 통해 센싱 데이터의 활용이 용이해져 그 가치가 극대화됩니다. 기존의 사물인터넷은 이를 구축하기 위해서는 일반적으로 사물(thing)의 성격, 내장된 마이크로프로세서, 통신 수단 등에 따라 연동을 위한 소프트웨어를 그때 그때 별도로 구현해야 합니다. IOTOWN은 이를 하나의 기반 소프트웨어로 제공함으로써 별도 구현에 대한 시간적, 금전적 비용을 줄이는 것을 목표로 합니다.

서비스 구조 및 구성요소

IOTOWN은 게이트웨이와 장치, 내부 DB, 그리고 대시보드 기능과 open API 등으로 구성됩니다.

게이트웨이 (Gateway)

장치와 IOTOWN 시스템 중간에 위치하여 장치가 제공하는 센싱 데이터를 IOTOWN 호환 포맷으로 변환 및 IOTOWN에서 송신한 커맨드를 장치로 전달하는 역할. 통상 ARM Cortex-A 계열, MIPS 등 프로세서 기반에 유선(이더넷), 및 무선(WiFi, Bluetooth, LoRa, ZigBee 등) 통신 인터페이스를 갖춘 라우터.

장치 (Node)

실제 사용자가 필요한 현장에 설치되어 센서를 통해 각종 물리현상에 대한 데이터를 추출 및 이를 무선을 통해 데이터를 전송하는 장치. 또는 무선을 통해 사용자로부터 명령을 수신받아 현장의 장치를 제어하는 장치. 통상 ARM Cortex-M 계열, MSP430, AVR 등 마이크로프로세서 및 무선(Bluetooth, LoRa, ZigBee 등) 통신 인터페이스, 그리고 센서 및 액츄에이터로 구성된 장치(thing)

내부 DB

각 장치로부터 IOTOWN로 수집된 센싱 데이터 및 각종 자료구조가 저장되는 곳.

Dashboard

실시간으로 수집된 센싱 데이터를 시각적으로 표현하는 웹 페이지.

Open API

내부 DB에 저장된 데이터를 서드파티에서 사용할 수 있도록 제공되는 HTTP 및 JSON 기반 Open API.

IOTOWN 버전 종류

IOTOWN은 서비스 제공 형태 및 구축 형태에 따라 다음 버전들이 있습니다.

• IOTOWN: 콕스랩에서 호스팅하는 공용 웹 서비스. 누구나 가입이 가능합니다. 내부 DB에 최장 일주일간 데이터가 저장됩니다.
• IOTOWN-Biz: 설치형 IOTOWN 소프트웨어. 기업용 유료 서비스로 기업이 보유하고 있는 서버에 직접 (원격) 설치해 드립니다. 서버 당 게이트웨이 최대 500대, 장치 최대 1만대까지 지원합니다.
• IOTOWN-Mini: 산업용 미니PC급 시스템에 설치되어 해당 미니PC와 함께 판매되는 형태. 서버 당 게이트웨이 최대 10대, 장치 최대 200대까지 지원합니다.

IOTOWN 제공 기능

Device Management

Gateway Management

새로운 게이트웨이를 추가하거나 기존 게이트웨이를 삭제, 및 게이트웨이 현황을 살펴볼 수 있는 인터페이스입니다.

게이트웨이 관리 페이지에서는 게이트웨이들의 상세한 정보를 볼 수 있습니다.

• Recent Act.: 최근 활동 시간입니다. 활동은 장치로부터 수신한 데이터를 전달 및 keep-alive 신호를 수신하였음을 의미합니다. 상태가 정상(1분 이내에 keep-alive 신호를 수신)이면 파란색으로, 그렇지 않으면 빨간색으로 표시됩니다.
• Reg. Date: 해당 게이트웨이가 최초로 IOTOWN에 등록된 날짜입니다.
• CPU Temp.: 게이트웨이의 온도
  GPS: 게이트웨이의 위치 좌표. 좌표는 게이트웨이에서 자동으로 보내줄 수 있으며, 수동으로 사용자가 설정할 수도 있습니다.
• Connected Nodes: 해당 게이트웨이에 연결된 장치 수 및 장치 목록을 표시합니다.
• LoRaWAN(LoRaWAN 게이트웨이일 때만 해당): 지원 대역이 표시되며, Statistics 버튼을 클릭하면 통계 정보를 볼 수 있습니다.

버튼을 누르면 게이트웨이의 Type, Desc. 등을 수정할 수 있습니다. 버튼을 누르면 게이트웨이를 삭제할 수 있습니다.

게이트웨이 추가 / 가져오기 / 내보내기 / 제거

새로운 게이트웨이를 추가 / 가져오기 / 내보내기 / 제거하려면 우측 상단의 버튼을 클릭합니다.

Add Gateway

Gateway ID, EUI, 종류, 및 설명 등을 입력한 후, ‘Register’을 클릭하면 게이트웨이가 추가됩니다.

• Gateway ID: 게이트웨이 식별자. 숫자가 아닌 문자로 시작해야 합니다.
• EUI: IEEE의 EUI-64를 의미하며, MSB first 순서로 입력해야 합니다.
• Type: Gateway의 종류를 입력합니다.
• Description: 기타 설명을 입력합니다.
• LoRaWAN Band: LoRaWAN Gateway인 경우 지원 대역을 다음 중 하나로 선택합니다.
  • KR920
  • KR920_FSK
  • AS923
  • AS923_INDONESIA
  • AS923_JAPAN

Import from CSV file

CSV 파일로부터 게이트웨이를 가져옵니다. CSV 파일은 ‘Add Gateway’와 마찬가지로 GatewayID, EUI, Type, Description, LoRaWAN 필드들이 지정되어야 합니다.

다음 CSV 예시를 참고하세요.

Import 결과는 ‘Duplicated (중복)’ 및 ‘Failure (실패)’ 개수로 표시됩니다.

Export to CSV file

현재 게이트웨이 목록을 CSV 파일로 다운로드합니다. 클릭하면 위와 같은 Download Link가 제공되며, 이를 통해 다운로드 가능합니다.

Delete by CSV file

삭제할 게이트웨이 목록을 CSV 파일로부터 제공받아 삭제합니다.

삭제 결과는 ‘Not found (존재하지 않음)’, ‘Failure (실패)’로 표시됩니다.

Delete All

모든 게이트웨이를 삭제합니다. 사용자의 실수를 방지하기 위하여 ‘YES’를 한번 더 입력해야 합니다.

LoRaWAN Statistics

LoRaWAN Gateway의 Statistics 버튼을 클릭하면 다음과 같은 팝업 창이 열립니다. 이를 통해 해당 게이트웨이의 과거 시간대별 통신 상황(총 송수신 횟수, 성공한 송수신 횟수)을 확인할 수 있습니다.

Node Management

새로운 장치를 추가하거나 기존 장치를 삭제, 및 장치 현황을 살펴볼 수 있는 인터페이스입니다.

‘장치 설명’의 버튼을 누르면 장치 설명을 수정할 수 있습니다. 버튼을 누르면 장치가 삭제됩니다. 연결 기록에서는 부팅 기록과 최근 통신시간을 확인할 수 있습니다.

LoRaWAN 단말인 경우, ‘LoRaWAN Info ∨’를 클릭하면 LoRaWAN 관련 추가 정보를 확인할 수 있습니다.

• Node: LoRaWAN Node 정보
  • AppKey: 장치 등록시 자동으로 생성되며, 여기서 획득한 키를 Nol.A-SDK의 LoRaMac API에서 사용해야 합니다. IOTOWN은 AppEUI를 무시합니다. 버튼을 클릭하여 변경할 수도 있습니다.
  • Device Profile: 사용할 대역과 LoRaWAN Specification version, Class 등이 표시되며, 버튼을 클릭하여 변경 가능합니다.
  • Battery Status: 장치의 전원 상태를 표시합니다. 이 정보는 LoRaWAN DevStatus MAC commands를 통해 1시간에 1번 장치로부터 해당 정보를 제공받습니다.
  • Link Margin: 장치의 게이트웨이와 연결 상태를 dB 단위로 표시합니다. 이 역시 LoRaWAN DevStatus MAC commands를 통해 1시간에 1번 장치로부터 해당 정보를 제공받습니다.
• Session: 장치가 OTAA(Over-The-Air Activation)를 완료한 후 세션 정보를 확인하거나 초기화할 수 있습니다.
  • Load: 장치에서 OTAA 성공한 후, 이 버튼을 클릭하면 생성된 세션 정보 및 업데이트되는 FCntUp, FCntDown 값을 확인할 수 있습니다.
  • Reset: 세션 정보를 초기화합니다. 초기화 후에는 장치에서 통신이 불가능해지며, 다시 OTAA를 수행하여야 합니다.
  • AppSKey, NwkSKey, DevAddr: 생성된 세션 관련 정보입니다.
  • FCntUp, FCntDown: 장치와의 통신에서 사용하고 있는 현재의 uplink, downlink에 대한 frame counter 값입니다.
• Downlink Queue: Downlink 전송에 사용되는 큐를 조회 / 제거합니다.
  • Refresh: 현재 대기 중인 downlink 메시지 갯수를 조회합니다.
  • Clear: 현재 대기 중인 downlink 메시지들을 모두 제거합니다.

장치 추가 / 가져오기 / 내보내기 / 제거

새로운 장치를 추가 / 가져오기 / 내보내기 / 제거하려면 우측 상단의 버튼을 클릭합니다.

Add Node

Node ID, 종류, 및 설명 등을 입력 후, ‘Register’을 클릭하면 새로운 장치가 추가됩니다.

• Node ID : 숫자가 아닌 영문으로 시작해야 합니다. LoRaWAN 단말인 경우, LW+’EUI-64’ 형태여야 하며, EUI-64는 MSB-first 순서여야 합니다.
• Node Type: 장치의 종류를 입력합니다.
• Node Description: 장치에 대한 설명을 입력합니다.
• Device Profile (LoRaWAN 장치만 해당): LoRaWAN 대역과 MAC version, class 등을 지정합니다.

Import from / Export to CSV file

CSV 파일로부터 가져오기 및 CSV 파일로 내보내기는 게이트웨이의 CSV 파일로 가져오기 및 CSV 파일로 내보내기와 동일합니다. 단, CSV 양식에 차이가 있습니다.

• NodeID: 장치 식별자
• NodeType: 장치의 종류
• NodeDesc: 장치에 대한 설명
• AppKey (LoRaWAN 장치만 해당): LoRaWAN OTAA에 사용되는 128-bit 키
• DeviceProfile (LoRaWAN 장치만 해당): LoRaWAN 대역과 MAC version, class

Delete by CSV file & Delete All

CSV 파일로 제거하기 및 전체 삭제는 게이트웨이의 CSV 파일로 제거하기와 전체 삭제와 동일합니다.

Dashboard

Dashboard는 설치된 장치 장치들과 사용자간 상호작용을 위한 페이지입니다. Dashboard에서는 장치들이 보내준 데이터들을 위젯을 통해 실시간으로 시각화합니다. 또한 위젯을 통해 장치들에게 명령을 보낼 수도 있습니다. 사용자는 하나 이상의 Dashboard를 생성 및 사용할 수 있습니다. Dashboard에는 하나 이상의 위젯을 배치하여 사용할 수 있습니다.

새로운 위젯을 추가하기 위하여 우측 상단의 버튼을 클릭하면 추가할 위젯의 종류를 선택할 수 있습니다.

Default Widget

Default 위젯은 간단하게 수신된 데이터와 수신 시각을 표현합니다. 추가시 ‘Node ID’만 선택하면 됩니다.

추가하면 다음과 같이 대시보드에 새로운 위젯이 추가됩니다.

위젯 제목 우측 톱니바퀴 아이콘을 클릭하면 표시할 데이터를 선택할 수 있습니다. 아래와 같이 LoRa Attributes를 해제하면 사용자가 전송한 데이터만 선택적으로 표시할 수도 있습니다.

Line Chart Widget

Line Chart 위젯은 실시간으로 들어오는 센서 데이터를 선 그래프로 표현하기 위한 위젯입니다. 추가시 다음과 같은 정보를 입력해야 합니다.

• Node ID: 표현하기 위한 데이터를 송신하는 장치 ID
• Data Type: 표현하기 위한 데이터 이름
• Min. Value: 해당 데이터의 최소값. 이 값이 y축의 최소값이 됩니다.
• Max. Value: 해당 데이터의 최대값. 이 값이 y축의 최대값이 됩니다.
• Graph Length: 표현하기 위한 데이터의 개수.

위젯 제목 우측 톱니바퀴 아이콘을 통해 설정값을 변경할 수 있습니다.

Gauge Widget

Gauge 위젯은 설정한 최소/최대값 범위에 대해 가장 최근 값의 정도를 표현합니다. 위젯 추가시 다음의 정보를 입력해야 합니다.

• Node ID: 표현하기 위한 데이터를 송신하는 장치 ID
• Data Type: 표현하기 위한 데이터 이름
• Min. Value: 해당 데이터의 최소값
• Max. Value: 해당 데이터의 최대값

위젯 제목 우측 톱니바퀴 아이콘을 통해 Data Type, Min.Value, 및 Max. Value를 다시 설정할 수 있습니다.

Command Widget

Command 위젯은 사용자가 장치로 데이터를 전송할 때 사용합니다.

위젯 추가시에는 Node ID만 지정하면 됩니다.

이 위젯을 통해서 hexadecimal 데이터를 보낼 수도 있고, 일반 string 데이터를 전송할 수도 있습니다.

위와 같이 입력 후 ‘SEND’ 버튼을 클릭하면 문자열 ‘1234’가 전송됩니다.

‘Hex’를 체크하고, 위와 같이 입력 후 ‘SEND’ 버튼을 클릭하면 16진수 0x30 0x31 0x32 0x33 0x34 (총 5 바이트)가 전송됩니다.

‘SEND’ 버튼을 클릭하면 위와 같이 ‘Waiting ACK’ 상태가 됩니다. 이후, 해당 장치로부터 데이터를 잘 수신했다는 의미의 ‘ACK’ 신호가 들어오면 다음과 같이 ‘Success’가 표시됩니다.

Thermometer Widget

Thermometer 위젯은 온도계 형태로 데이터를 시각화하기 위한 위젯입니다. 다음과 같이 정보를 입력하여 위젯을 생성합니다.

• Node ID: 표현하기 위한 데이터를 송신하는 장치 ID
• Data Type: 표현하기 위한 데이터 이름
• Min. Value: 해당 데이터의 최소값
• Max. Value: 해당 데이터의 최대값
• Unit: 단위

위젯 제목 우측 톱니바퀴 아이콘을 클릭하여 Data Type, Min. Value, Max. Value 및 Unit 등을 설정할 수 있습니다.

Linear Gauge

Linear Gauge 위젯은 거리 등 선형적인 측정치를 시각화하기 적합한 위젯입니다. 다음과 같이 정보를 입력하여 위젯을 생성합니다.

• Node ID: 표현하기 위한 데이터를 송신하는 장치 ID
• Data Type: 표현하기 위한 데이터 이름
• Min. Value: 해당 데이터의 최소값
• Max. Value: 해당 데이터의 최대값
• Unit: 단위

위젯 제목 우측 톱니바퀴 아이콘을 클릭하여 Data Type, Min. Value, Max. Value 및 Unit 등을 설정할 수 있습니다.

DB 모니터

장치들이 보낸 데이터들은 IOTOWN 내부 DB에 저장됩니다. DB 모니터는 내부 DB에 저장된 데이터를 장치 및 시간 조건에 따라 조회할 수 있습니다.

장치는 하나 이상을 선택할 수 있으며, 선택하지 않으면 모든 장치들을 대상으로 합니다.

시간은 FROM, TO를 지정할 수 있습니다.

아무 조건도 지정하지 않으면 모든 데이터가 조회됩니다.

사용자 정보

Group ID 등을 포함한 사용자 정보를 열람, 수정합니다. Group ID는 MQTT 기반 callback 사용시 필요합니다.

CoXlab이 서비스하는 IOTOWN (https://town.coxlab.kr)에서는 Group ID 확인만 가능합니다.

IOTOWN-Biz에서는 사용자에 대한 설명도 표시, 수정할 수 있습니다.

사용자 정보

Open API를 이용할 때, 또는 MQTT 기반 callback을 사용할 때 Open API Token을 사용합니다.

토큰을 갱신하면 해당 토큰을 이용 중인 사용자들의 접근이 차단되므로 신중하게 사용하시기 바랍니다.

IOTOWN-Biz

IOTOWN-Biz는 설치형 서버 소프트웨어(유료)입니다. 이 섹션은 IOTOWN-Biz에서 제공되는 추가 기능에 관하여 설명합니다.

Service Start / Stop / Restart

IOTOWN-Biz는 사용자가 지정한 서버에 설치되어 운용됩니다. 사용자는 여러가지 운영상의 이유로 IOTOWN 서비스를 임의로 중단시킬 수 있습니다.

$ cd /opt/IoT.own
$ sudo docker compose down

중단된 IOTOWN은 서버를 재시작하여도 자동으로 실행되지 않습니다. 다음과 같이 서비스를 시작할 수 있습니다.

$ cd /opt/IoT.own
$ sudo docker compose up -d

한번 시작된 IOTOWN 서비스는 계속 동작하게 되며, 서버가 재시작되어도 자동으로 재시작 합니다.

HTTPS 인증서 적용 등을 이유로 서비스를 재시작하기 위해서는 다음과 같이 실행합니다.

$ cd /opt/IoT.own
$ sudo docker compose restart

Group & User Management

그룹 및 계정 관리 기능은 관리자 계정만 접근이 가능합니다. 1개의 그룹은 N개의 계정을 포함할 수 있으며, 동일 그룹내의 계정들은 게이트웨이 및 장치를 공유합니다. 예외로 관리자 계정은 모든 그룹의 장치 접근이 가능합니다.

Group Management

관리자 계정으로 로그인한 후, 우측 상단에 +버튼을 눌러 그룹을 추가할 수 있습니다.

그룹의 이름을 입력하고, 그룹이 소유할 수 있는 게이트웨이, 장치 최대 개수를 입력합니다. 그리고 DB에 저장되는 데이터의 최대 보존 기간을 설정할 수 있습니다(단위 : 일).

User Management

우측 상단의 리스트 박스에 User Management 메뉴가 있습니다. 역시 관리자 계정만 접근 가능합니다.

우측 상단의 +버튼을 눌러 계정을 추가할 수 있습니다. 계정이 소속될 그룹을 반드시 선택해야합니다. Manager 권한은 장치 및 위젯의 추가/삭제가 가능하며 staff 권한은 위젯 추가/삭제만 가능합니다.

HTTPS 인증서

IOTOWN은 기본으로 self-signed 인증서 기반의 HTTPS 프로토콜로 서비스되도록 배포됩니다. 이 상태에서는 타 서비스와 연동에 제한이 있을 수 있습니다. 따라서 정상적인 서비스를 위해서는 도메인 이름과 이를 인증하기 위한 인증서 적용이 추천됩니다.

HTTPS 인증서는 /opt/IoT.own/configuration/iot.own/certs에 위치시켜야 합니다.

파일의 형태는 모두 *.pem 이어야 하며 이름은 다음과 같아야 합니다.

• 인증서 (Certificate): http.pem
• 키 (Private Key): http-key.pem

인증서와 키 파일을 적용한 후에는 서비스를 재시작하여야 합니다.