YAML Project Format

YAML (YAML Ain't Markup Language) is a text format for representing structured data. It uses indentation (spaces) to express hierarchy, making it easy to read and write without special tools.

Key-Value Pairs

Basic data is written as key: value pairs:

name: "My Project"
rotation_type: 1
enabled: true

Indentation = Nesting

Nested structures are expressed by indenting with spaces (2 spaces per level):

plc:
  provider: KEYENCE
  config:
    ip_or_hostname: "192.168.0.10"
    port_no: 8501

Lists (Arrays)

List items start with - (hyphen + space):

pages:
  - uuid: "page-001"
    page_no: 1
    title: Main
  - uuid: "page-002"
    page_no: 2
    title: Settings

Data Types

Comments

Lines starting with # are comments and ignored:

# This is a comment
name: "My Project"   # Inline comments are also supported

A YAML project is a folder containing a project.yaml file and an optional images/ subfolder:

ProjectName/
  project.yaml       # Project configuration (required)
  images/             # Image files (optional)
    {uuid}.png        # Background images referenced by uuid

The project.yaml file contains all project settings, pages, items, and configurations. Images referenced in the project (background images for project, pages, or items) are stored as PNG files in the images/ folder, named by their UUID.

Here is a minimal working project with one page containing a label and a button:

uuid: "00000000-0000-0000-0000-000000000001"
name: "My Project"
screen_size_string: "768x1024"
rotation_type: 1

plc:
  model: KV-8000
  provider: KEYENCE
  plc_channel:
    config:
      ip_or_hostname: "192.168.0.10"
      port_no: 8501

pages:
  - uuid: "00000000-0000-0000-0000-100000000001"
    page_no: 1
    title: Main
    items:
      - uuid: "00000000-0000-0000-0000-200000000001"
        class: Label
        frame_string: "{{50, 50}, {200, 40}}"
        title: Temperature
        text_color_name: "RGBA,0.0,0.0,0.0,1.0"
      - uuid: "00000000-0000-0000-0000-200000000002"
        class: Button
        frame_string: "{{50, 120}, {120, 50}}"
        title: Start
        switch_device_name: MR100
        switch_mode: momentary

Required fields: plc and pages are mandatory. Import will fail with an error if the plc section is missing. uuid and name are optional and will be auto-generated if omitted. Each page's uuid and page_no are also auto-filled if omitted. Each item's uuid and frame_string are optional (defaults will be applied). class is required, but lowercase or alternative names (e.g., gauge, slider, alarm, grid) are accepted.

Top-level properties that configure the overall project:

grid:
  style: 1
  enabled: 1
  pixel: 10.0

The plc section configures the PLC connection. This section is required. Import will fail if it is omitted. For supported PLC providers and models, see the PLC Connection documentation.

KEYENCE Example

plc:
  model: KV-8000
  provider: KEYENCE
  plc_channel:
    config:
      ip_or_hostname: "192.168.0.10"
      port_no: 8501

Mitsubishi (MC Protocol) Example

plc:
  model: iQ-R
  provider: MITSUBISHI
  plc_channel:
    config:
      ip_or_hostname: "192.168.0.10"
      port_no: 5000

OMRON (FINS) Example

plc:
  model: NJ
  provider: OMRON
  plc_channel:
    config:
      ip_or_hostname: "192.168.0.10"
      port_no: 9600
      self_node: 0
      destination_node: 0

MODBUS/TCP Example

plc:
  model: MODBUS
  provider: MODBUS
  plc_channel:
    config:
      ip_or_hostname: "192.168.0.10"
      port_no: 502
      unit_id: 1

PLC Provider / Model / Channel Reference

Config Options

pages:
  - uuid: "page-uuid-1"
    page_no: 1
    title: Main
    background_color_name: "RGBA,0.95,0.95,0.95,1.0"
    items:
      - ...

Page Navigation (Swipe)

Pages can be linked for swipe navigation using UUID references:

Each item has a class field that determines its type:

All items share these common properties:

Displays static or device-driven text.

- uuid: "label-uuid"
  class: Label
  frame_string: "{{50, 50}, {200, 40}}"
  title: Temperature
  text_color_name: "RGBA,0.0,0.0,0.0,1.0"
  background_color_name: "RGBA,0.9,0.9,0.9,1.0"
  alignment: 1
  font_size: 18.0

Interactive button that can toggle PLC devices and display lamp states. If no switch device is specified, it behaves as a lamp indicator.

- uuid: "button-uuid"
  class: Button
  frame_string: "{{50, 100}, {120, 50}}"
  title: Start
  alternate_title: Stop
  switch_device_name: MR100
  switch_mode: momentary
  lamp_device_name: MR100
  lamp_color_name: "RGBA,0.0,0.8,0.0,1.0"
  style: irPanel

Switch Properties

Lamp Properties

Page Navigation

Button Style

Displays and optionally edits numeric or text values from PLC devices.

- uuid: "value-uuid"
  class: ValueField
  frame_string: "{{300, 100}, {150, 40}}"
  title: Temperature
  device_name: DM100
  editable: 0
  decimal_place: 1
  unit: "\u00B0C"
  number_type: 2
  min_value: 0.0
  max_value: 999.0
  text_color_name: "RGBA,0.0,0.0,0.0,1.0"
  field_background_color_name: "RGBA,1.0,1.0,1.0,1.0"

A value field with increment/decrement buttons, or displayed as a slider or progress bar.

- uuid: "slider-uuid"
  class: SteppedValueField
  frame_string: "{{50, 200}, {300, 40}}"
  title: Speed
  device_name: DM200
  step_value: 1.0
  min_value: 0.0
  max_value: 100.0
  style: slider

Inherits all Value Field properties (device_name, min_value, max_value, number_type, etc.).

Analog gauge display that reads a PLC device value.

- uuid: "meter-uuid"
  class: Meter
  frame_string: "{{50, 300}, {200, 200}}"
  title: Pressure
  device_name: DM300
  min_value: 0.0
  max_value: 100.0
  figures: 5
  major: 20
  minor: 10
  unit: MPa
  decimal_place: 1

Meter Zones

meter_zones:
  - color_name: "RGBA,0.0,0.8,0.0,1.0"
    from_value: 0.0
    to_value: 60.0
  - color_name: "RGBA,1.0,0.8,0.0,1.0"
    from_value: 60.0
    to_value: 80.0
  - color_name: "RGBA,1.0,0.0,0.0,1.0"
    from_value: 80.0
    to_value: 100.0

A standalone status indicator. Uses the same class as Button (Button) but without a switch device, acting as a lamp indicator.

- uuid: "lamp-uuid"
  class: Button
  frame_string: "{{300, 50}, {60, 60}}"
  title: Running
  lamp_device_name: MR200
  lamp_color_name: "RGBA,0.0,0.8,0.0,1.0"
  alternate_lamp_color_name: "RGBA,0.5,0.5,0.5,1.0"
  style: Circle

Uses the same lamp properties as Button (lamp_device_name, lamp_color_name, lamp_negative, etc.). Omit switch_device_name to make it a lamp indicator.

Displays a list of messages from a message set. Messages are activated based on PLC device values.

- uuid: "message-uuid"
  class: Message
  frame_string: "{{50, 400}, {400, 200}}"
  message_set_uuid: "msgset-uuid-1"
  active_color_name: "RGBA,1.0,0.0,0.0,1.0"
  inactive_color_name: "RGBA,0.9,0.9,0.9,1.0"
  active_only: true

A table/grid layout that repeats a template item across rows and columns with device address offsets. For full matrix documentation, see Matrix .

- uuid: "matrix-uuid"
  class: Matrix
  frame_string: "{{50, 50}, {600, 400}}"
  matrix_rows: 5
  matrix_columns: 3
  matrix_device_offset: 10
  matrix_add_borders: true
  matrix_border_color_name: "RGBA,0.7,0.7,0.7,1.0"
  matrix_has_column_header: true
  matrix_has_row_header: true

Matrix Template

Matrices can define a cell template that is automatically expanded across all rows and columns on import. The template defines what items appear in each cell, and device offset rules control how device addresses increment across the grid.

The template is defined using matrix_template_json. You can write it directly as a YAML array of item definitions (a JSON string is also accepted). Coordinates are relative to the cell origin (0, 0). When a matrix has a template but has not been expanded yet, it is automatically expanded during YAML import.

- uuid: "matrix-uuid"
  class: Matrix
  frame_string: "{{50, 50}, {600, 300}}"
  matrix_rows: 3
  matrix_columns: 4
  matrix_add_borders: true
  matrix_border_color_name: "RGBA,0.7,0.7,0.7,1.0"
  matrix_template_cell_width: 140.0
  matrix_template_cell_height: 60.0
  matrix_template_json:
    - class: Label
      uuid: "tpl-001"
      frame_string: "{{2, 2}, {60, 26}}"
      title: CH1
      font_size: 12.0
      text_color_name: "RGBA,0.3,0.3,0.3,1.0"
    - class: ValueField
      uuid: "tpl-002"
      frame_string: "{{2, 30}, {136, 28}}"
      device_name: DM100
      number_type: 2
      decimal_place: 1
      unit: "\u00B0C"
      text_color_name: "RGBA,0.0,0.0,0.0,1.0"
      field_background_color_name: "RGBA,1.0,1.0,1.0,1.0"
      border_style: 3
  matrix_device_offset_rules:
    - id: "rule-1"
      itemUUID: "*"
      property: device_name
      rowOffset: 10
      colOffset: 1

Device Offset Rules

matrix_device_offset_rules is an array of rules that control how device addresses change across rows and columns.

The device address for each cell is calculated as:
offset = row * rowOffset + col * colOffset

Template Example Explained

The example above creates a 3x4 temperature monitoring grid:

• Each cell contains a label ("CH1") and a value field reading from DM100
• The title text auto-increments: CH1, CH2, CH3, ...
• Device offset rule: rowOffset: 10, colOffset: 1
  Cell (0,0) reads DM100, cell (0,1) reads DM101, cell (1,0) reads DM110, etc.

Embeds a web browser view within the page.

- uuid: "web-uuid"
  class: WebPage
  frame_string: "{{50, 50}, {600, 400}}"
  url: "https://example.com"

Translations for item text are defined at the project level in the localizedStrings array. Each entry maps an item UUID and field key to a translated string for a specific locale.

localizedStrings:
  - localeIdentifier: ja
    key: "item-uuid-1.title"
    text: "\u30B9\u30BF\u30FC\u30C8"
  - localeIdentifier: ja
    key: "item-uuid-1.alternate_title"
    text: "\u30B9\u30C8\u30C3\u30D7"
  - localeIdentifier: fr
    key: "item-uuid-1.title"
    text: "D\u00E9marrer"

Localizable Fields

• title — Item title
• alternate_title — Alternate title (Button toggle state)
• unit — Unit text (ValueField, Meter)
• message_ — Message text (MessageItem)
• detail_message — Detail message text (MessageItem)
• title_ — Message set title

Message sets define groups of messages that can be displayed by Message items. Each message is triggered by a PLC device value.

messageSets:
  - uuid: "msgset-uuid-1"
    no: 1
    title_: Alarms
    order_style: 0
    messageItems:
      - device_name: DM500
        value: 1.0
        number_type: 0
        message_: "Motor overload"
        detail_message: "Motor overload detected. Check motor wiring."
        disabled: false
        order_style: 0
      - device_name: DM500
        value: 2.0
        number_type: 0
        message_: "Temperature high"
        detail_message: "Temperature exceeds the limit."
        disabled: false
        order_style: 1

Message Item Properties

Colors are specified as strings in RGBA format:

"RGBA,R,G,B,A"

Where R, G, B, A are floating-point values from 0.0 to 1.0.

Examples

Item positions and sizes use CGRect string format:

"{{x, y}, {width, height}}"

Values are in points. The origin (0, 0) is the top-left corner of the page. The coordinate system matches the screen_size_string dimensions.

Examples

"{{0, 0}, {768, 1024}}"      # Full page (portrait)
"{{50, 50}, {200, 40}}"       # Small item at top-left area
"{{384, 512}, {100, 50}}"     # Centered item (approximate)

For a landscape project with screen_size_string: "768x1024" and rotation_type: 1, the coordinate space is 1024 points wide and 768 points tall.

To use background images for the project, pages, or items:

1. Place PNG image files in the images/ folder, named by UUID (e.g., abc-123.png).
2. Reference the image in the YAML using a background_image object:

background_image:
  uuid: "abc-123"
  kind: page_background

Image Kinds

Device names depend on the PLC provider. Here are common device names for each provider:

KEYENCE (KV Series)

Mitsubishi (MC Protocol)

OMRON (FINS)

MODBUS/TCP

Note: Bit devices (like MR, M, CO) are used for switch_device_name, lamp_device_name, and visible_device_name. Word devices (like DM, D, HR) are used for device_name (value reading/writing).

A complete project with KEYENCE KV-8000 PLC, two pages, various items, a message set, and Japanese localization:

uuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
name: "Factory Monitor"
screen_size_string: "768x1024"
rotation_type: 1
style: default
background_color_name: "RGBA,0.95,0.95,0.95,1.0"

grid:
  style: 1
  enabled: 1
  pixel: 10.0

plc:
  model: KV-8000
  provider: KEYENCE
  plc_channel:
    config:
      ip_or_hostname: "192.168.0.10"
      port_no: 8501

pages:
  - uuid: "page-0001"
    page_no: 1
    title: Main
    right_page_uuid: "page-0002"
    items:
      - uuid: "item-0001"
        class: Label
        frame_string: "{{20, 20}, {300, 40}}"
        title: Factory Monitor
        text_color_name: "RGBA,0.0,0.0,0.0,1.0"
        font_size: 24.0
        alignment: 0
      - uuid: "item-0002"
        class: Button
        frame_string: "{{20, 80}, {150, 60}}"
        title: Start
        alternate_title: Stop
        switch_device_name: MR100
        switch_mode: alternate
        lamp_device_name: MR100
        lamp_color_name: "RGBA,0.0,0.8,0.0,1.0"
        style: irPanel
      - uuid: "item-0003"
        class: Button
        frame_string: "{{200, 80}, {60, 60}}"
        title: Run
        lamp_device_name: MR200
        lamp_color_name: "RGBA,0.0,0.8,0.0,1.0"
        alternate_lamp_color_name: "RGBA,0.5,0.5,0.5,1.0"
        style: Circle
      - uuid: "item-0004"
        class: Label
        frame_string: "{{20, 170}, {120, 30}}"
        title: Temperature
        text_color_name: "RGBA,0.3,0.3,0.3,1.0"
      - uuid: "item-0005"
        class: ValueField
        frame_string: "{{150, 160}, {150, 50}}"
        device_name: DM100
        number_type: 2
        decimal_place: 1
        unit: "\u00B0C"
        min_value: 0.0
        max_value: 999.0
        text_color_name: "RGBA,0.0,0.0,0.0,1.0"
        field_background_color_name: "RGBA,1.0,1.0,1.0,1.0"
        border_style: 3
      - uuid: "item-0006"
        class: Meter
        frame_string: "{{20, 230}, {280, 280}}"
        title: Pressure
        device_name: DM200
        number_type: 2
        min_value: 0.0
        max_value: 100.0
        figures: 6
        major: 20
        minor: 10
        unit: MPa
        decimal_place: 1
        meter_zones:
          - color_name: "RGBA,0.0,0.8,0.0,1.0"
            from_value: 0.0
            to_value: 60.0
          - color_name: "RGBA,1.0,0.8,0.0,1.0"
            from_value: 60.0
            to_value: 80.0
          - color_name: "RGBA,1.0,0.0,0.0,1.0"
            from_value: 80.0
            to_value: 100.0
      - uuid: "item-0007"
        class: SteppedValueField
        frame_string: "{{350, 160}, {300, 50}}"
        title: Speed
        device_name: DM300
        step_value: 5.0
        min_value: 0.0
        max_value: 100.0
        number_type: 2
        unit: "%"
        style: slider
      - uuid: "item-0008"
        class: Button
        frame_string: "{{850, 20}, {120, 40}}"
        title: "Alarms >>"
        page_uuid: "page-0002"

  - uuid: "page-0002"
    page_no: 2
    title: Alarms
    left_page_uuid: "page-0001"
    items:
      - uuid: "item-0009"
        class: Label
        frame_string: "{{20, 20}, {200, 40}}"
        title: Alarm List
        text_color_name: "RGBA,0.0,0.0,0.0,1.0"
        font_size: 24.0
      - uuid: "item-0010"
        class: Message
        frame_string: "{{20, 80}, {600, 400}}"
        message_set_uuid: "msgset-0001"
        active_color_name: "RGBA,1.0,0.9,0.9,1.0"
        inactive_color_name: "RGBA,0.95,0.95,0.95,1.0"
        active_text_color_name: "RGBA,0.8,0.0,0.0,1.0"
        inactive_text_color_name: "RGBA,0.3,0.3,0.3,1.0"
        show_detail: true
        show_title: true
      - uuid: "item-0011"
        class: Button
        frame_string: "{{850, 20}, {120, 40}}"
        title: "<< Main"
        page_uuid: "page-0001"

messageSets:
  - uuid: "msgset-0001"
    no: 1
    title_: Alarms
    order_style: 0
    messageItems:
      - device_name: DM500
        value: 1.0
        number_type: 0
        message_: "Motor overload"
        detail_message: "Motor overload detected. Check wiring."
        disabled: false
        order_style: 0
      - device_name: DM500
        value: 2.0
        number_type: 0
        message_: "Temperature high"
        detail_message: "Temperature exceeds limit."
        disabled: false
        order_style: 1
      - device_name: DM500
        value: 3.0
        number_type: 0
        message_: "Emergency stop"
        detail_message: "Emergency stop activated."
        disabled: false
        order_style: 2

localizedStrings:
  - localeIdentifier: ja
    key: "item-0001.title"
    text: "\u5DE5\u5834\u30E2\u30CB\u30BF\u30FC"
  - localeIdentifier: ja
    key: "item-0002.title"
    text: "\u30B9\u30BF\u30FC\u30C8"
  - localeIdentifier: ja
    key: "item-0002.alternate_title"
    text: "\u30B9\u30C8\u30C3\u30D7"
  - localeIdentifier: ja
    key: "item-0003.title"
    text: "\u904B\u8EE2\u4E2D"
  - localeIdentifier: ja
    key: "item-0004.title"
    text: "\u6E29\u5EA6"
  - localeIdentifier: ja
    key: "item-0006.title"
    text: "\u5727\u529B"
  - localeIdentifier: ja
    key: "item-0007.title"
    text: "\u901F\u5EA6"
  - localeIdentifier: ja
    key: "item-0009.title"
    text: "\u30A2\u30E9\u30FC\u30E0\u4E00\u89A7"

• Auto-completion: The uuid for projects, pages, and items is optional and will be auto-generated on import. name, page_no, and frame_string are also auto-filled with defaults when omitted.
• PLC Configuration is Required: The plc section must always be specified. Import will fail with an error if it is omitted. Specifying provider and model is sufficient; internal PLC class_name values are auto-resolved.
• Class Name Alternatives: The class field is case-insensitive. The following alternative names are also accepted: gauge→Meter, alarm→Message, grid→Matrix, slider→Slider, progress_bar→Progress, value_field→ValueField, web_page→WebPage.
• Alternative frame_string Format: In addition to "{{x, y}, {width, height}}", the format "x, y, width, height" is also accepted.
• Coordinate System: For landscape projects (rotation_type: 1) with screen_size_string "768x1024", the usable area is 1024 wide x 768 tall. Avoid placing items beyond these bounds.
• Device Name Consistency: Ensure device names match the PLC provider's syntax. Use bit devices for switches/lamps and word devices for values.
• Minimum Spacing: Leave at least 5-10 points between items for readability.
• Font Sizes: Recommended sizes: titles 18-24pt, labels 14-16pt, values 16-20pt.
• Message Sets: The message_set_uuid on a Message item must match a UUID in the messageSets array.
• Localization: The key in localizedStrings follows the format "{item_uuid}.{field_name}". Common fields: "title", "alternate_title", "unit".
• Import Behavior: When importing, if a project with the same UUID already exists, it will be overwritten. To create a new copy, change the UUID.
• Lite Edition Limits: In irBoard Lite, imported projects are truncated to a maximum of 2 pages and 10 items per page. Pages and items beyond these limits are silently removed during import. A notification is shown after import if truncation occurred.