Overview Guide

• Was ist das Infrafon-Ökosystem?
• Wie greifen DataView und Server API ineinander?
• Wo starte ich als Erstes? → Networking & DataView.

KioskMgr API

• Screens auflisten und aktiv setzen.
• Navigation: zu Seite X springen.
• Aktionen: z. B. Beep/Vibration anstoßen.

Server API Reference

• Auth: Bearer Token senden.
• Geräte- und Statusabfragen.
• Webhooks & Pagination im Blick behalten.

DataView Reference

• Seiten & Widgets bilden das UI.
• Startseite festlegen, Navigation definieren.
• Nächste Schritte: Beispiele & Best Practices.

Networking Guide

This guide shows how Infrafon devices choose, configure, and use networks — from high‑bandwidth (MQTT/JSON over Wi‑Fi/LTE‑M) to low‑bandwidth (compact TLV messages over BLE/LoRa).

Tip: First read the Overview Guide and the DataView Reference.

Quick Start

Create a network.json and define preferred connections plus fallback:

{
  "networks": {
    "wifiOffice": {
      "type": "wifi",
      "auth": { "ssid": "INFRAFON-Office", "wpa2_password": "••••••••" },
      "entityMgrServer": { "url": "mqtts://ies.example.tld:8883", "user": "device123", "pass": "device123" },
      "checkPeriodSecs": 60
    },
    "lteFallback": {
      "type": "lte",
      "auth": { "apn": "iot.1nce.net" },
      "entityMgrServer": {
        "url": "mqtts://ies.example.tld:8883",
        "auth": { "mqttUser": "device123", "mqttPassword": "device123" }
      },
      "checkPeriodSecs": 120
    },
    "bleGateway": { "type": "ble" },
    "loraCity": {
      "type": "lora",
      "auth": { "devEUI": "AA...FF", "appEUI": "38B8EBE000000000", "appKey": "AA...FF" },
      "checkPeriodSecs": 300,
      "tlvmap": true
    }
  },
  "networkOrder": ["wifiOffice", "lteFallback", "bleGateway", "loraCity"],
  "retryTimeoutMins": 5
}

Selection & Fallback: The device tries entries in networkOrder in sequence. If one fails, it moves on; after a timeout it retries from the top.

Wi‑Fi (type: "wifi")

Fields

• auth.ssid (required)
• auth.wpa2_password (PSK) or enterprise fields: wpa2_user, wpa2_identity, wpa2_keyfile, wpa2_certfile, wpa2_cafile
• entityMgrServer.url (mqtt:// or mqtts://), optional user/pass or auth.*
• checkPeriodSecs (MQTT keepalive/ping)

Enterprise example

{
  "type": "wifi",
  "auth": {
    "ssid": "Corp-Secure",
    "wpa2_user": "device123",
    "wpa2_identity": "device123@corp",
    "wpa2_keyfile": "/etc/certs/dev-key.pem",
    "wpa2_certfile": "/etc/certs/dev-cert.pem",
    "wpa2_cafile": "/etc/certs/ca.pem"
  },
  "entityMgrServer": { "url": "mqtts://ies.corp.tld:8883" }
}

LTE‑M (type: "lte")

Fields

• auth.apn (e.g., iot.1nce.net)
• entityMgrServer.url, entityMgrServer.auth.mqttUser, entityMgrServer.auth.mqttPassword
• checkPeriodSecs

Example

{
  "type": "lte",
  "auth": { "apn": "iot.1nce.net" },
  "entityMgrServer": {
    "url": "mqtts://ies.example.tld:8883",
    "auth": { "mqttUser": "device123", "mqttPassword": "device123" }
  },
  "checkPeriodSecs": 120
}

BLE (type: "ble")

No special fields required in the network block. Communication via GATT:

• Service UUID: EAD20001-F3EA-4A35-A223-9802AC9C53DF
• Downlink (write): EAD20002-… (JSON or TLV; ~240 B — increase MTU if needed)
• Ack (notify): EAD20003-… (0 = queued, 1 = processed)
• Uplink (read): EAD20006-… (single message)
• Uplink count (notify): EAD20007-…

Avoid permanent connections; iBeacons signal pending messages (UUID LSB / major / minor).

LoRaWAN (type: "lora")

Fields

• auth.devEUI, auth.appEUI, auth.appKey
• checkPeriodSecs (periodic UL “pings” to open DL windows)
• tlvmap: true (enable TLV mapping)

Header (UL, compact)

• Byte 0: bits 0–3 last received DL‑ID; bits 4–5 protocol version; bit 6 listen flag; bit 7 parity
• Byte 1: number of TLV elements

MQTT/JSON (high‑bandwidth)

Downlink (example)

{ "app": { "home": { "banner": "Welcome" } }, "ack": true }

Quick test

# adjust topic/host
mosquitto_pub -h ies.example.tld -t devices/<deviceId>/down -m '{"ack":true,"cmd":"ping"}'
mosquitto_sub -h ies.example.tld -t devices/<deviceId>/up -v

TLV (low‑bandwidth)

Concept: Tag‑Length‑Value — compact, field‑based (ideal for BLE/LoRa).

Mapping (JSON ⇄ TLV)

{
  "lang": "tlv_up",
  "dict": {
    "app.home.alerts.ackyes": "0",
    "app.home.alerts.id": "1",
    "devdata.accel.orient": "2",
    "devdata.power.gauge": "3"
  }
}
{
  "lang": "tlv_down",
  "dict": {
    "0": "devcfg.vibr.song",
    "1": "devcfg.audioout.alert",
    "2": "devcfg.nfc.emul",
    "3": "app.home.site_logo",
    "4": "app.home.counter"
  }
}

Value encoding (short)

• null → length 0
• 0..65535 → 1–2 bytes little‑endian
• boolean → 1 byte (0/1)
• arrays/objects → JSON.stringify
• strings → ISO‑Latin‑1; length < 3 padded to 3 with ``

Example (UL JSON → TLV, shortened)

• JSON: {"pri":1,"devdata":{"power":{"gauge":64},"accel":{"orient":"VU"}}}
• TLV (hex): 33 01 40 32 03 56 55 00

Troubleshooting & Best Practices

• Wi‑Fi: deploy enterprise certificates correctly; prefer mqtts://.
• LTE‑M: correct APN; moderate keepalive (battery).
• BLE: increase MTU; leverage iBeacon pull mechanism.
• LoRa: set checkPeriodSecs > 0; map only needed TLVs.
• Acks: for critical downlinks set ack:true and verify the UL confirmation.

Infrafon CC2 Device — Application DataView Developer’s Guide

Distribution: Restricted – share only with partners/clients under contract or NDA Copyright: © Infrafon GmbH 2021–2025

About this document This guide explains how to design DataViews (application UIs) for the Infrafon device and how to exchange messages with the backend via MQTTS. It includes topic conventions, JSON payloads, UI concepts (pages, widgets, dialogs), actions/rules, and configuration examples.

Version History

Contents

• Introduction
• Terminology
• Application Backend Integration
  • Connection & Authentication
  • MQTT Topics
  • JSON Message Format
• Device UI
  • DeviceUI Manager
  • Display Layout
  • Navigation
  • DataViews
  • InfoPages
  • InfoWidgets
  • Formatters (Text)
  • Available Fonts
  • Formatters (Graphic)
  • Buttons
  • Data Entry Dialogs (DED)
  • Dynamic Field Updates
  • Device Home Page
• Application DataView Manager
  • Allocdata JSON Structure
• DataView JSON Example
• Multilanguage / Localization
• Application Actions
• Device Manager: Devices & Attributes
• RuleMgr (On-device Rules)
• Practical Examples

Introduction

Infrafon devices render application UIs called DataViews, composed of pages and widgets, and exchange app data over MQTTS with an Infrafon Entity Server (IES). Each application lifecycle (allocate/unallocate) and device state is represented via JSON config and topic-based messaging.

Terminology

Application Backend Integration

Connection & Authentication

• Transport: MQTT over TLS (server PKI; optional client cert).
• Each client uses an application token scoping the topics (<entityname>, device visibility).

MQTT Topics

Subscribe/publish using your entity and device/dispenser IDs:

ife/<entityname>/device/msgs-up/<deviceId>     # SUB: data from device
ife/<entityname>/device/msgs-down/<deviceId>   # PUB: data to device (update UI / outputs)
ife/<entityname>/dispenser/system-up/<dispId>  # SUB: dispenser state/sensors (if applicable)

JSON Message Format

Every topic uses a common envelope. Include only fields you need.

{
  "devcfg": { /* device config object */ },
  "devdata": { /* device data attributes */ },
  "devwork": { "actions": [ /* device-level actions */ ] },
  "app": {
    "<app-name>": {
      /* uplink app data */
      "data": { /* downlink app data for widgets */ },
      "actions": [ /* UI/app actions for downlink */ ]
    }
  }
}

Device UI

DeviceUI Manager

• Owns display/touch, draws widgets using low-level primitives.
• Exposes a high-level page/widget API for consistent UX.

Display Layout

• System bar (top): status & icons.
• InfoPage (remaining area): widgets defined by the app.
• DataEntryDialog (modal): full-screen dialog for editing values.

Navigation

• Back: previous page / Cancel in dialogs.
• OK/Home: OK in dialogs; on InfoPage goes to page id 1 or device Home.
• Forwards: next page; for questionnaires, accepts the answer.

Buttons also emit press, release, double click, longpress events used by rules.

DataViews

A DataView bundles pages (and optional questionnaires). Core attributes:

{
  "displayName": "App name",
  "displayIcon": "iconRef",
  "target_size": {"w":176,"h":264},
  "infopages": [ /* pages */ ],
  "questionnaires": [ /* optional */ ],
  "dicts": [ /* language dicts */ ]
}

Note: If target_size differs from device resolution, coordinates scale to fit; verify visually on a target device.

InfoPages

• Array of InfoWidgets rendered in order.
• Optional id (integer). If pages are sequential 1..N, the Forwards/Back buttons cycle them.

{
  "id": 1,
  "displayName": "Overview",
  "infowidgets": [ /* widgets */ ]
}

InfoWidgets

Widgets show text or graphic values and can be static, dynamic, editable, or button.

{
  "interaction": "dynamic",          // static | dynamic | editable | button
  "name": "app.status",              // required for dynamic/editable
  "region": { "x":16,"y":40,"w":160,"h":40 },
  "format": "text",                  // text | graphic
  "formatter": { "name": "string", "font": {"name":"times","sz":22}, "halign":"left","valign":"top", "autobreak": true },
  "value": "System ready",
  "displayValue": "Status: {}",
  "actions": [ { "a": "gotoPage", "p": "2" } ],  // for button or after edit
  "ded": { "type":"int-keyboard", "title":"Set threshold", "range":{"low":0,"high":100}, "auto_ok":true }
}

Interaction types

Formatters (Text)

Common formatter names: string, bool, number, percentage, datetime/date/time, list, msg, msglist.

• Shared attributes include font, halign, valign, autobreak, fg_colour, bg_colour, outline, invert.
• bool formatter uses text_true / text_false.
• number can round using dp.
• percentage clamps 0–100 and appends %.
• msg/msglist extract fields f1..f3 with optional widths f1_sz..f3_sz; msglist.sortby sorts records.

Example (datetime & bool):

{
  "format": "text",
  "formatter": { "name": "datetime", "halign": "left" },
  "value": "2025-08-22T12:00:00Z"
},
{
  "format": "text",
  "formatter": { "name": "bool", "text_true":"Enabled", "text_false":"Disabled" },
  "value": "true"
}

Available Fonts

• courier: Regular 10/12/14 px; Bold 14 px
• times: Regular 26/34/38 px
• Defaults: name:any, weight:regular, sz:22; if requested size unavailable, nearest lower size is used.

Formatters (Graphic)

Common: icon/basic, bool (icon_true/icon_false), percentage (circle/bar), star (0–5), list (selected option’s text → icon ref), qr.

Example (progress bar):

{
  "format": "graphic",
  "formatter": { "name": "percentage", "graphictype": "bar" },
  "value": "70"   // 70% (rounded to 10% steps)
}

Buttons

Buttons use any formatter; value supplies text or graphic. Add an outline to draw a boundary.

Data Entry Dialogs (DED)

Full-screen modals for editing values; key types include:

• inp_bool, inp_1ofn, msglist
• int-keyboard, float-keyboard
• 1oflist_4choice, noflist_4choice, 1oflist_12choice, noflist_12choice
• bool_slider, bool_yesno, int_stepper, rating_star, listedit

Example:

"ded": {
  "type": "1oflist_12choice",
  "title": "Select mode",
  "auto_ok": true
}

Dynamic Field Updates

• Backend can update dynamic widgets via MQTT; device redraws immediately.
• Device sensors can also feed widget values (e.g., devdata.power.voltage).

Device Home Page

• Default Home shows logo and app buttons.
• Create a DataView named home with page id 1 to override. Ensure you include navigation to other apps if needed.

Application DataView Manager

Device states: unallocated, allocated, dfu, error. Global settings live in config/global.json. Each state can load an allocdata JSON with network & DataView configuration.

Allocdata JSON Structure

{
  "data": {
    "global": {
      "dev": {
        "<device>": { /* device config overrides */ }
      }
    },
    "network": {
      "networks": { "<netName>": { /* config */ } },
      "networkOrder": ["<netName>", "..."]
    },
    "user": {
      "visitor": "Jane Doe",
      "apps": {
        "local:myapp.json": {
          "id": "myapp",
          "src": "local",
          "data": { /* initial widget values per app */ }
        }
      }
    },
    "apps": { /* inline DataViews if src:inline */ },
    "dicts": [ "config/names.json", "config/locations.json" ]
  }
}

DataView JSON Example

{
  "displayName": "My App",
  "displayIcon": "appIcon",
  "infopages": [
    {
      "id": 1,
      "displayName": "Overview",
      "infowidgets": [
        {
          "interaction": "dynamic",
          "name": "status",
          "region": { "x": 8, "y": 28, "w": 160, "h": 40 },
          "format": "text",
          "formatter": {
            "name": "string",
            "font": { "name": "times", "sz": 22 },
            "halign": "left",
            "valign": "top",
            "autobreak": true
          },
          "displayValue": "Status: {}",
          "value": "Ready"
        },
        {
          "interaction": "button",
          "region": { "x": 8, "y": 80, "w": 160, "h": 40 },
          "format": "graphic",
          "formatter": { "name": "percentage", "graphictype": "bar" },
          "value": "40",
          "actions": [ { "a": "gotoPage", "p": "2" } ]
        }
      ]
    }
  ],
  "dicts": [ { "lang":"en", "description":"English", "dict": { "Ready":"Ready" } } ]
}

Multilanguage / Localization

Provide dictionaries inside your DataView or as external files. All text values are looked up; if missing, the literal is shown.

"dicts": [
  { "lang": "en", "description": "English", "dict": { "mywidgetname": "My Widget" } },
  { "lang": "fr", "description": "Français", "dict": { "mywidgetname": "Mon Widget" } }
]

Set device language via devcfg.ui.lang or user selection in the System DataView.

Application Actions

Actions can be triggered by widgets, MQTT, or rules.

Device Manager: Devices & Attributes

Device config via devcfg.*, sensor data via devdata.*. Typical examples:

{
  "devcfg": {
    "ui": { "lang": "en", "enable_lock": true, "lock_timeout_secs": 30 },
    "audioout": { "alert": "AT1", "durMS": 1000, "vol": 80 },
    "wifi": { "connect_timeout_seconds": 12, "connect_retry_seconds": 180 },
    "led": { "led0": "F0", "led1": "S0" }
  },
  "devdata": {
    "power": { "voltage": 4.0, "gauge": 78, "isCharging": false },
    "fw": { "ver_str": "v1.0.7", "device_id": "ABCDEF123456" }
  }
}

Many more attributes exist (BLE scan, Wi‑Fi scan, NFC, accelerometer, duress/alerting, etc.). Consult your device profile for required fields.

RuleMgr (On-device Rules)

Define local rules that react to button, network, or sensor events and run actions.

{
  "data": {
    "global": {
      "dev": {
        "rules": {
          "onButton": [
            { "id":"okLong", "button":1, "is":"longpress", "do":[ { "a":"gotoPage","p":"system.1" } ] }
          ],
          "onOverLimit": [
            { "id":"lowBattery", "dname":"power.voltage", "limit":4.0,
              "active":[ { "a":"msg","p":"Low battery" }, { "a":"beep","p":"AT1" } ],
              "clear":[ { "a":"msg","p":"Battery OK" } ]
            }
          ]
        }
      }
    }
  }
}

Practical Examples

1) Minimal DataView (one page, two widgets)

{
  "displayName": "Status",
  "infopages": [
    {
      "id": 1,
      "infowidgets": [
        {
          "interaction": "dynamic",
          "name": "status",
          "region": { "x":10,"y":20,"w":156,"h":28 },
          "format": "text",
          "formatter": { "name":"string","font":{"name":"times","sz":22},"halign":"left" },
          "displayValue": "Status: {}",
          "value": "Ready"
        },
        {
          "interaction": "button",
          "region": { "x":10,"y":56,"w":156,"h":28 },
          "format": "text",
          "formatter": { "name":"string","font":{"name":"times","sz":22},"halign":"center","outline":"solid_square" },
          "value": "Next",
          "actions": [ { "a":"gotoPage","p":"2" } ]
        }
      ]
    }
  ]
}

2) Uplink telemetry sample

{
  "devdata": {
    "power": { "voltage": 4.01, "gauge": 62, "isCharging": false },
    "accel": { "orient": "VN" }
  },
  "app": {
    "visitor": {
      "data": { "status": "Checked in" }
    }
  }
}

3) Downlink update + UI navigation

{
  "app": {
    "visitor": {
      "data": { "status": "Please proceed to Desk 2" },
      "actions": [ { "a": "gotoPage", "p": "1" } ]
    }
  }
}

4) Questionnaire stub (future use)

{
  "questionnaires": [
    {
      "id": "feedback",
      "displayName": "Feedback",
      "questions": [
        { "name":"q1", "value":"", "ded": { "type": "1oflist_4choice", "title":"Rate service" } }
      ]
    }
  ]
}