IoT Open Tech

# Filen app.json

# Användning

Filen app.json används i Edge-appar för att informera användarens gränssnitt om vilka parametrar som behöver sättas samt vilken typ av parameter det är. Filen informerar även gränssnittet om olika sidor som bör öppnas och vad varje sida skall innehålla. Förutsättningen för detta är att användaren i ett steg innan också har valt vilken installation som just denna instans ska köras på samt vad för namn som instansen skall ha. Det är upp till det specifika användargränssnittet att implementera de olika komponenterna beskrivna i detta dokument.

# Fält (inputs)

De olika fälten som användaren kan fylla i definieras här med en kort beskrivning av vad man skall kunna välja på. Resultatet av konfigurationen fylls sedan i config delen i JSON requesten för att skapa instansen.

All fält har följande variabler:

Namn Standard Beskrivning
required false Sätts till true om användaren måste fylla i fältet.
name Vilket namn som skall visas för användaren.
type Vilken typ av fält användaren ska fylla i, som beskrivet nedan.
description Hjälptext för att beskriva hur detta fält kommer användas i appen.

# single_function_selector

Låt användaren välja en funktion i en lista av funktioner. Det går även att låta användaren välja ett värde för vald funktion, till exempel om appen styr en dimmer och den skall slås på till 50%. Vid val av värdet bör användargränssnittet hantera olika funktionstyper.

Namn Standard Beskrivning
filter {} Ett JSON-objekt med metadata nyckel-värde för att filtrera ut funktionerna som går att välja på.
value false Sätt till true om användaren förväntas fylla i ett värde.

# Konfigurationsresultat

Med värden:

{
  "input-name": {
    "<function-id>": <value>
  }
}

Utan värden:

{
  "input-name": <function-id>
}

# multi_function_selector

Samma som föregående men användaren kan välja flera funktioner.

Namn Standard Beskrivning
filter {} Ett JSON-objekt med metadata nyckel-värde för att filtrera ut funktionerna som går att välja på.
value false Sätt till true om användaren förväntas fylla i ett värde.

# Konfigurationsresultat

Med värden:

{
  "input-name": {
    "<function-id-1>": <value>,
    "<function-id-2>": <value>
  }
}

Utan värden:

{
  "input-name": [
    <function-id-1>,
    <function-id-2>
  ]
}

# single_device_selector and multi_device_selector

Samma som funktions-väljaren men med enheter i stället.

# single_notification_output_selector

Gör att användaren kan välja på existerande notifikationsutskick på installationen. Det kan också finnas möjlighet för användaren att lämna den aktuella konfigurationen för att skapa ett nytt utskick i en separat flöde. Om detta är fallet bör användaren komma tillbaka till detta flöde (med alla inställningar kvar) och sedan kunna välja den nyss skapade notifikationen.

Namn Standard Beskrivning
allow_add true Om användaren tillåts lägga till nya utskick.

# Konfigurationsresultat

{
  "input-name": <notification-output-id>
}

# multi_notification_output_selector

Samma som oven, men användaren kan välja på flera utskick.

Namn Standard Beskrivning
allow_add true Om användaren tillåts lägga till nya utskick.

# Konfigurationsresultat

{
  "input-name": [
    <notification-output-id-1>,
    <notification-output-id-2>
  ]
}

# text

Låt användaren välja en text. Användaren kan tvingas mata in en text som uppfyller specifierad regex.

Namn Standard Beskrivning
default Vilket värde som skall stå i fältet om det är tomt.
multiline false Om användaren kan kan mata in en eller flera rader text.
validator Valbart Regexp som fältet valideras med, tom betyder ingen validering.
on_error Valbart felmeddelande som visas om texten inte matchar valideringen ovan.

# Konfigurationsresultat

{
  "input-name": "<value>"
}

# number

Namn Standard Beskrivning
default Vilket värde som skall stå i fältet om det är tomt.

# Konfigurationsresultat

{
  "input-name": <value>
}

# option

Låt användaren välja en av flera värden.

Namn Standard Beskrivning
default Vilket värde som är valt från början.
values { } En mappning mellan värde och namn på värdet som ett JSON-objekt.

# Konfigurationsresultat

{
  "input-name": <value>
}

# checkbox

Låt användaren välja en eller flera värden som checkboxar.

Namn Standard Beskrivning
default Vilket värde som är valt från början.
values { } En mappning mellan värde och namn på värdet som ett JSON-objekt.

# Konfigurationsresultat

{
  "input-name": [
    <value-1>,
    <value-2>
  ]
}

# toggle

Låt användaren välja mellan två värden som antingen eller.

Namn Standard Beskrivning
default false Vilket värde som är valt från början.
false_value Värdet som sätts om knappen är "av".
true_value Värde som sätts om knappen är "på".

# Konfigurationsresultat

{
  "input-name": <value>
}

# repeat

Låt användaren välja samma variabel flera gånger vilket resulterar i en lista av objekt i konfigurationen.

Namn Standard Beskrivning
min 0 Minsta antal gånger som fältet skall repeteras.
max obegränsad Max antal gånger som fältet skall repeteras.
input_fields Namn på de fält som skall repeteras.

# Konfigurationsresultat

{
  "input-name": [
    {
      "input-name-1": <config-object>,
      "input-name-2": <config-object>
    },
    {
      "input-name-1": <config-object>,
      "input-name-2": <config-object>
    }
  ]
}

# Guide

Guide-delen av filen beskriver olika sidor med inställningar som användaren måste gå igenom för att konfigurera appen. Varje sida består av en eller flera fält. Varje fält renderas enligt beskrivningen ovan. Sidorna renderas i samma ordning som denna array.

Varje sida kan ha en titel och en beskrivning för att förklara för användaren vilket område som fylls i här. Sidan innehåller också en lista med de fält som skall visas på just denna sida. Namnen på fälten motsvarar JSON-nyckeln i input_fields.

# Exempel

Detta är en exempelkonfiguration med två functions-val och ett textfält.

{
  "author": "IoT Open",
  "licence": "MIT",
  "input": {
    "actuator_function": {
      "type": "single_function_selector",
      "name": "Controlled functions",
      "description": "This function that is turned to on when app is triggered."
    },
    "trigger_function": {
      "type": "single_function_selector",
      "name": "Trigger function",
      "description": "The door that will trigger the light to turn on.",
      "value": true
    },
    "timeout": {
      "type": "number",
      "name": "Light on time",
      "description": "The time that the control function will be on before turning off again in minutes.",
      "default": "10"
    },
    "trigger_value": {
      "type": "single_function_selector",
      "name": "Function",
      "description": "Select function",
      "value": true,
      "filter": {
        "type": "temperature"
      }
    },
    "temp": {
      "type": "repeat",
      "name": "Temperature triggers",
      "description": "Select a function and the value that should trigger the app to run.",
      "min": 2,
      "max": 4,
      "input_fields": [
        "trigger_value"
      ]
    },
    "notification": {
      "type": "single_notification_output_selector",
      "name": "Notification",
      "description": "Select how you should be notified if the app have to send an alarm."
    },
    "text_example": {
      "type": "text",
      "multiline": false,
      "default": "Example text",
      "validator": "[a-zA-Z]*",
      "on_error": "The text can only contain letters"
    }
  },
  "guide": [
    {
      "id": "stage_1",
      "title": "Function selection",
      "description": "Set the functions you want to use.",
      "input_fields": [
        "trigger_function",
        "actuator_function"
      ]
    },
    {
      "id": "stage_2",
      "title": "Timeout settings",
      "description": "",
      "input_fields": [
        "timeout",
        "temp",
        "notification",
        "example_text"
      ]
    }
  ]
}

Resultatet av beskrivningen ovan är en konfiguration som kan skickas till API:et och ser ut såhär:

{
  "app_id": 5,
  "installation_id": 12,
  "version": "1.0.0",
  "config": {
    "timeout": 10,
    "trigger_function": 123,
    "actuator_function": {
      "4456": 255
    },
    "temp": [
      {
        "trigger_value": {
          "9": 26
        }
      },
      {
        "trigger_value": {
          "9": 35
        }
      },
      {
        "trigger_value": {
          "12": 10
        }
      }
    ],
    "notification": 456,
    "example_text": "HelloWorld"
  },
  "name": "My app instance"
}

← Package lynx →