MDL (Model Description Language)

MDL is a JSON/YAML-based declarative language for defining the functions of IoT devices. By systematically defining the three core operations that a device can perform, the APC platform can automatically generate a structured user interface.

Core Concepts

MDL consists of the following three components:

Sensors: Data collected by the device
Actions: Commands to control the device
Events: Notifications generated by the device

Development Best Practices

💡 Best Practice: It is recommended to define the MDL before firmware development. This enables clear interface design and maximizes the automatic UI generation features of the APC platform.

Sensors

A sensor is the minimum unit of data that a device periodically collects and transmits. A device can transmit multiple sensor data at different intervals.

Common Properties

Properties common to all sensor types:

Property	Type	Required	Description
`name`	string	✅	Display name of the sensor
`type`	string	✅	Data type (number, boolean, enum, timestamp, binary, location, array)
`description`	string	❌	Description of the sensor
`unit`	string	❌	Measurement unit
`unitPrefix`	string	❌	Unit prefix
`frequency`	string/number	❌	Data transmission interval

Number Type

Defines sensor data in numeric form.


sensors:
  ambientTemp:
    name: Indoor Temperature
    type: number
    description: Indoor temperature measurement
    unit: '°C'
    min: -40 # Designed minimum value
    max: 125 # Designed maximum value
    precision: 1 # Sensor precision
    threshold: 2 # Transmission threshold (absolute value compared to previous value)
    frequency: PT30S # ISO 8601 Duration format

Key Properties:

min/max: Designed range (actual data may exceed this range)
precision: Sensor precision
threshold: Only transmit if the difference from the previous value is greater than or equal to this value

Boolean Type

Defines sensor data in true/false form.


sensors:
  doorState:
    name: Door State
    type: boolean
    description: Door open/close state
    trueLabel: 'Open' # Label when true
    falseLabel: 'Closed' # Label when false
    frequency: 1

Enum Type

Sensor data that takes one of a set of predefined values.


sensors:
  qualityGrade:
    name: Quality Grade
    type: enum
    description: Product quality grade
    values: [A, B, C, D] # Array of possible values
    frequency: 300

Timestamp Type

Sensor data containing time information.


sensors:
  lastReboot:
    name: Last Reboot
    type: timestamp
    description: Last reboot time
    format: iso8601
    frequency: 0 # State data (transmit only on change)

Binary Type

Sensor for handling binary data (images, files, etc.).


sensors:
  snapshot:
    name: Snapshot
    type: binary
    description: Camera snapshot
    encoding: base64
    frequency: 0 # Event-triggered

Location Type

Sensor for handling location information.


sensors:
  gps:
    name: GPS Coordinates
    type: location
    description: Device GPS coordinates
    format: latlon # Latitude/longitude format
    frequency: 10

Actions

An action is a function that sends a command to the device to perform a specific operation. It allows users to control the device through the interface.

Action Structure


actions:
  actionName:
    name: 'Display Name'
    description: 'Description of the action'
    builder: 'Command template to be sent'
    parameters:
      # Parameter definitions

Single Parameter Action


actions:
  setTemperature:
    name: Set Temperature
    description: Set the target temperature
    builder: 'setTemp {targetTemp}'
    parameters:
      targetTemp:
        name: Target Temperature
        type: number
        description: Value to set
        min: 16
        max: 30
        step: 0.5
        unit: '°C'

Select Parameter

A parameter that selects from predefined options.


actions:
  setPower:
    name: Power Control
    description: Turn the device on or off
    builder: 'setPower {power}'
    parameters:
      power:
        name: Power State
        type: select
        description: Power state to set
        enumDef:
          on: 'On'
          off: 'Off'

Composite Parameter Action

An action with multiple parameters.


actions:
  setRGBLED:
    name: Set RGB LED
    description: Set the color of the RGB LED
    builder: 'setLED {R} {G} {B}'
    parameters:
      R:
        name: Red
        description: Red value
        type: number
        min: 0
        max: 255
        step: 1
        format: integer
      G:
        name: Green
        description: Green value
        type: number
        min: 0
        max: 255
        step: 1
        format: integer
      B:
        name: Blue
        description: Blue value
        type: number
        min: 0
        max: 255
        step: 1
        format: integer

Parameter Type Properties

Parameter Type	Key Properties	Description
`number`	`min`, `max`, `step`, `format`	Numeric input control
`select`	`enumDef`	Defines select options

Events

An event is a message that notifies of a special situation occurring on the device. Used for device state changes or situations requiring notification.


events:
  deviceBoot:
    name: Device Boot
    message: 'The device has restarted'
 
  temperatureAlert:
    name: Temperature Alert
    message: 'The temperature has exceeded the threshold'
 
  connectionLost:
    name: Connection Lost
    message: 'Network connection lost'

Example Usage

Temperature Sensor Alarm Model


# Model: Temperature Sensor Alarm
sensors:
  temperature:
    name: Temperature
    type: number
    unit: "°C"
    min: -20
    max: 80
    precision: 0.1
    threshold: 0.5
    frequency: PT30S
 
  humidity:
    name: Humidity
    type: number
    unit: "%"
    min: 0
    max: 100
    precision: 1
    threshold: 2
    frequency: PT60S
 
actions:
  setAlarmThreshold:
    name: Set Alarm Threshold
    description: Set the temperature alarm threshold
    builder: "setThreshold {temp}"
    parameters:
      temp:
        name: Threshold Temperature
        type: number
        min: 30
        max: 80
        step: 1
        unit: "°C"
 
events:
  temperatureAlert:
    name: Temperature Alert
    message: "The temperature has exceeded the set threshold"

Device Instances by Organization

Organization A: “Fire Detection Device 1” → APC Link: abc001
Organization B: “Fire Detection Device 2” → APC Link: abc002

Each organization can operate independent device instances based on the same model.