MDL (Model Description Language)

MDL은 IoT 장비의 기능을 정의하는 JSON/YAML 기반의 선언적 언어입니다. 장비가 수행할 수 있는 세 가지 핵심 작업을 체계적으로 정의하여, APC 플랫폼이 자동으로 구조화된 사용자 인터페이스를 생성할 수 있도록 합니다.

핵심 개념

MDL은 다음 세 가지 구성 요소로 이루어집니다:

Sensors: 장비가 수집하는 데이터
Actions: 장비를 제어하는 명령
Events: 장비에서 발생하는 알림

개발 권장사항

💡 Best Practice: 펌웨어 개발 전에 MDL을 먼저 정의하는 것을 권장합니다. 이를 통해 명확한 인터페이스 설계가 가능하며, APC 플랫폼의 자동 UI 생성 기능을 최대한 활용할 수 있습니다.

Sensors (센서)

센서는 장비가 주기적으로 수집하여 전송하는 데이터의 최소 단위입니다. 하나의 장비는 여러 개의 센서 데이터를 각기 다른 주기로 전송할 수 있습니다.

공통 속성

모든 센서 타입에 공통으로 적용되는 속성들입니다:

속성	타입	필수	설명
`name`	string	✅	센서의 표시명
`type`	string	✅	데이터 타입 (number, boolean, enum, timestamp, binary, location, array)
`description`	string	❌	센서에 대한 설명
`unit`	string	❌	측정 단위
`unitPrefix`	string	❌	단위 접두사
`frequency`	string/number	❌	데이터 전송 주기

Number Type

숫자 형태의 센서 데이터를 정의합니다.


sensors:
  ambientTemp:
    name: 실내온도
    type: number
    description: 실내 온도 측정값
    unit: '°C'
    min: -40 # 설계상 최솟값
    max: 125 # 설계상 최댓값
    precision: 1 # 센서 정밀도
    threshold: 2 # 전송 임계값 (이전 값 대비 절대값)
    frequency: PT30S # ISO 8601 Duration 형식

주요 속성:

min/max: 설계된 범위 (실제 데이터는 이 범위를 초과할 수 있음)
precision: 센서의 정밀도
threshold: 이전 전송값 대비 이 값 이상 차이날 때만 전송

Boolean Type

참/거짓 형태의 센서 데이터를 정의합니다.


sensors:
  doorState:
    name: 문상태
    type: boolean
    description: 문 개폐 상태
    trueLabel: '열림' # true일 때 표시될 레이블
    falseLabel: '닫힘' # false일 때 표시될 레이블
    frequency: 1

Enum Type

미리 정의된 값들 중 하나를 가지는 센서 데이터입니다.


sensors:
  qualityGrade:
    name: 품질등급
    type: enum
    description: 제품 품질 등급
    values: [A, B, C, D] # 가능한 값들의 배열
    frequency: 300

Timestamp Type

시간 정보를 담는 센서 데이터입니다.


sensors:
  lastReboot:
    name: 마지막재부팅
    type: timestamp
    description: 마지막 재부팅 시간
    format: iso8601
    frequency: 0 # 상태성 데이터 (변화 시에만 전송)

Binary Type

바이너리 데이터(이미지, 파일 등)를 다루는 센서입니다.


sensors:
  snapshot:
    name: 스냅샷
    type: binary
    description: 카메라 스냅샷
    encoding: base64
    frequency: 0 # 이벤트 트리거형

Location Type

위치 정보를 다루는 센서입니다.


sensors:
  gps:
    name: GPS좌표
    type: location
    description: 장비의 GPS 좌표
    format: latlon # 위도/경도 형식
    frequency: 10

Actions (액션)

액션은 장비에 명령을 전송하여 특정 동작을 수행하게 하는 기능입니다. 사용자가 인터페이스를 통해 장비를 제어할 수 있도록 합니다.

액션 구조


actions:
  actionName:
    name: '표시명'
    description: '액션에 대한 설명'
    builder: '실제 전송될 명령어 템플릿'
    parameters:
      # 파라미터 정의

단일 파라미터 액션


actions:
  setTemperature:
    name: 온도설정
    description: 목표 온도를 설정합니다
    builder: 'setTemp {targetTemp}'
    parameters:
      targetTemp:
        name: 목표온도
        type: number
        description: 설정할 온도 값
        min: 16
        max: 30
        step: 0.5
        unit: '°C'

Select 파라미터

미리 정의된 옵션 중에서 선택하는 파라미터입니다.


actions:
  setPower:
    name: 전원제어
    description: 장비 전원을 켜거나 끕니다
    builder: 'setPower {power}'
    parameters:
      power:
        name: 전원상태
        type: select
        description: 설정할 전원 상태
        enumDef:
          on: '켜기'
          off: '끄기'

복합 파라미터 액션

여러 개의 파라미터를 가지는 액션입니다.


actions:
  setRGBLED:
    name: RGB LED 설정
    description: RGB LED의 색상을 설정합니다
    builder: 'setLED {R} {G} {B}'
    parameters:
      R:
        name: Red
        description: 빨간색 값
        type: number
        min: 0
        max: 255
        step: 1
        format: integer
      G:
        name: Green
        description: 녹색 값
        type: number
        min: 0
        max: 255
        step: 1
        format: integer
      B:
        name: Blue
        description: 파란색 값
        type: number
        min: 0
        max: 255
        step: 1
        format: integer

파라미터 타입별 속성

파라미터 타입	주요 속성	설명
`number`	`min`, `max`, `step`, `format`	숫자 입력 제어
`select`	`enumDef`	선택 옵션 정의

Events (이벤트)

이벤트는 장비에서 발생하는 특별한 상황을 알리는 메시지입니다. 장비의 상태 변화나 알림이 필요한 상황에서 사용됩니다.


events:
  deviceBoot:
    name: 장비부팅
    message: '장비가 재시작되었습니다'
 
  temperatureAlert:
    name: 온도경고
    message: '온도가 임계값을 초과했습니다'
 
  connectionLost:
    name: 연결끊김
    message: '네트워크 연결이 끊어졌습니다'

실제 사용 예시

온도 감지 경보기 모델


# 모델: 온도 감지 경보기
sensors:
  temperature:
    name: 온도
    type: number
    unit: "°C"
    min: -20
    max: 80
    precision: 0.1
    threshold: 0.5
    frequency: PT30S
 
  humidity:
    name: 습도
    type: number
    unit: "%"
    min: 0
    max: 100
    precision: 1
    threshold: 2
    frequency: PT60S
 
actions:
  setAlarmThreshold:
    name: 경보임계값설정
    description: 온도 경보 임계값을 설정합니다
    builder: "setThreshold {temp}"
    parameters:
      temp:
        name: 임계온도
        type: number
        min: 30
        max: 80
        step: 1
        unit: "°C"
 
events:
  temperatureAlert:
    name: 온도경보
    message: "온도가 설정된 임계값을 초과했습니다"

조직별 디바이스 인스턴스

A 조직: “화재 감지 디바이스1” → APC Link: abc001
B 조직: “화재 감지 디바이스2” → APC Link: abc002

각 조직은 동일한 모델을 기반으로 하지만 독립적인 디바이스 인스턴스를 운영할 수 있습니다.