Getting started

Introduction

The Settings API was created so that settings are being managed by the RAIL and allows other (third-party) apps to save-load settings in a way that control can still read & update them.

How it’s done is by using the android broadcast system. It will send out a broadcast when the RAIL (re)starts or if an app has been installed and will ask to register it’s settings to the RAIL.

This section describes describe how you can add, update and get settings from the Settings API.
Every publish message has a key, which is a String based ID, and a category_name to create a unique message.

Add settings

Introduction

The Settings API is designed to store settings and categorize them into different (sub)categories. Each (sub)category contains a label_key, which is a name in the form of a translation key from the Translations API, you give to your (sub)category, a map of settings and a map of subcategories. It is also possible to give extra information to your (sub)category by adding a description key that is also stored in the Translations API.
A setting exists out of a map which contains a setting_key as the key and an object that stores all the properties needed to store a setting as the value.

A basic setting constist of at least 3 properties: label_key
default_value
type
Optional properties are: description_key
required
hidden
default_values (only used for multi-select type)
options (only used for select types)
range (only used for number & integer type)

Setting types

As settings are stored in a json, every value is string based. The Settings API itself doesn’t know the type of the setting by it’s own. For this reason every setting needs a specific type to be defined.

Possible setting types: string
string_multiline
password
integer
number
boolean
select_single
select_multi
date (ISO 8601 format: YYYY-MM-DD)
time (ISO 8601 format: hh:mm:ss.sss)
date_time (ISO 8601 format: YYYY-MM-DDThh:mm:ss.sss)

Options

When having a setting that could have multiple actions to perform. You’ll need to define those actions. To do this you can simply define these actions in options.

Every option consist of: a key
a label_key or label (this depends if the name for this option is translatable or not)
a value

When adding a new setting to an existing category you’ll need to include all old and new settings that should be included into that specific category. The reason for this is that this action overrides the whole (sub)category and thus all it’s settings.

Publish topic

zbos/settings/add

Payload example 1

Basic add MQTT publish message.

In this payload example, you can see "category_name": "base_settings". When you want to link this settings to an application created by the application API, this category_name must be equal to the id of the application.

In this example the Translation API is used to define the label_keys and description_keys. Where default from` default.pref_title_required_string` is the category defined in the translation API. For more information on this check Translation API.

{
  "key": "021d4e",
  "category": {
    "settings": {
      "required_string_setting": {
        "type": "string",
        "required": true,
        "default_value": "I am a required setting",
        "label_key": "default.pref_title_required_string",
        "description_key": "default.pref_summary_required_string"
      },
      "integer_setting": {
        "type": "integer",
        "range": {
          "min": 0,
          "max": 150
        },
        "default_value": "100",
        "label_key": "default.pref_title_integer",
        "description_key": "default.pref_summary_integer"
      },
      "number_setting": {
        "type": "number",
        "range": {
          "min": 1,
          "max": 150
        },
        "required": true,
        "default_value": "100.50",
        "label_key": "default.pref_title_number",
        "description_key": "default.pref_summary_number"
      },
      "boolean_setting": {
        "type": "boolean",
        "default_value": "true",
        "label_key": "default.pref_title_boolean",
        "description_key": "default.pref_summary_boolean"
      },
      "hidden_select_single_setting": {
        "type": "select_single",
        "hidden": "true",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_single_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_single_option_2"
          }
        ],
        "default_value": "option_1",
        "label_key": "default.pref_title_select_single",
        "description_key": "default.pref_summary_select_single"
      },
      "select_multi_setting": {
        "type": "select_multi",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_multi_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_multi_option_2"
          },
          {
            "key": "option_3",
            "value": "Option 3",
            "label_key": "default.pref_title_select_multi_option_3"
          }
        ],
        "label_key": "default.pref_title_select_multi",
        "description_key": "default.pref_summary_select_multi"
      }
    },
    "label_key": "default.pref_title_base_settings"
  },
  "category_name": "base_settings"
}

Payload example 2

Basic add MQTT publish message with subcategories.

{
  "key": "021d4e",
  "category": {
    "settings": {
      "required_string_setting": {
        "type": "string",
        "required": true,
        "default_value": "I am a required setting",
        "label_key": "default.pref_title_required_string",
        "description_key": "default.pref_summary_required_string"
      },
      "integer_setting": {
        "type": "integer",
        "range": {
          "min": 0,
          "max": 150
        },
        "default_value": "100",
        "label_key": "default.pref_title_integer",
        "description_key": "default.pref_summary_integer"
      },
      "number_setting": {
        "type": "number",
        "range": {
          "min": 1,
          "max": 150
        },
        "required": true,
        "default_value": "100.50",
        "label_key": "default.pref_title_number",
        "description_key": "default.pref_summary_number"
      },
      "boolean_setting": {
        "type": "boolean",
        "default_value": "true",
        "label_key": "default.pref_title_boolean",
        "description_key": "default.pref_summary_boolean"
      },
      "hidden_select_single_setting": {
        "type": "select_single",
        "hidden": "true",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_single_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_single_option_2"
          }
        ],
        "default_value": "option_1",
        "label_key": "default.pref_title_select_single",
        "description_key": "default.pref_summary_select_single"
      },
      "select_multi_setting": {
        "type": "select_multi",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_multi_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_multi_option_2"
          },
          {
            "key": "option_3",
            "value": "Option 3",
            "label_key": "default.pref_title_select_multi_option_3"
          }
        ],
        "label_key": "default.pref_title_select_multi",
        "description_key": "default.pref_summary_select_multi"
      }
    },
    "subcategories": {
      "base_subcategory_settings": {
        "settings": {
          "classroom_number": {
            "type": "string",
            "default_value": "202/B",
            "label_key": "default.pref_title_classroom_number"
          }
        },
        "label_key": "default.pref_title_base_subcategory_settings"
      }
    },
    "label_key": "default.pref_title_base_settings"
  },
  "category_name": "base_settings"
}

Payload example 3

Replace category with a json file that contains the content for category.

{
  "key": "021d4e",
  "file": "path/to/base_settings.json",
  "category_name": "base_settings"
}

The file path needs to be stored on the robot itself.

// base_settings.json
{
  "category": {
    "settings": {
      "required_string_setting": {
        "type": "string",
        "required": true,
        "default_value": "I am a required setting",
        "label_key": "default.pref_title_required_string",
        "description_key": "default.pref_summary_required_string"
      },
      "integer_setting": {
        "type": "integer",
        "range": {
          "min": 0,
          "max": 150
        },
        "default_value": "100",
        "label_key": "default.pref_title_integer",
        "description_key": "default.pref_summary_integer"
      },
      "number_setting": {
        "type": "number",
        "range": {
          "min": 1,
          "max": 150
        },
        "required": true,
        "default_value": "100.50",
        "label_key": "default.pref_title_number",
        "description_key": "default.pref_summary_number"
      },
      "boolean_setting": {
        "type": "boolean",
        "default_value": "true",
        "label_key": "default.pref_title_boolean",
        "description_key": "default.pref_summary_boolean"
      },
      "hidden_select_single_setting": {
        "type": "select_single",
        "hidden": "true",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_single_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_single_option_2"
          }
        ],
        "default_value": "option_1",
        "label_key": "default.pref_title_select_single",
        "description_key": "default.pref_summary_select_single"
      },
      "select_multi_setting": {
        "type": "select_multi",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_multi_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_multi_option_2"
          },
          {
            "key": "option_3",
            "value": "Option 3",
            "label_key": "default.pref_title_select_multi_option_3"
          }
        ],
        "label_key": "default.pref_title_select_multi",
        "description_key": "default.pref_summary_select_multi"
      }
    },
    "subcategories": {
      "base_subcategory_settings": {
        "settings": {
          "classroom_number": {
            "type": "string",
            "default_value": "202/B",
            "label_key": "default.pref_title_classroom_number"
          }
        },
        "label_key": "default.pref_title_base_subcategory_settings"
      }
    },
    "label_key": "default.pref_title_base_settings"
  }
}

Result

{"success":true} // true if succeeded, false if failed

Update settings

Introduction

Updating a setting will use the setting_key which is defined when adding a setting to the Settings API.

Publish topic

zbos/settings/update

Payload example 1

{
  "key": "e991ea",
  "category": {
    "settings": {
      "required_string_setting": {
        "value": "Value 1B"
      },
      "integer_setting": {
        "value": "50"
      },
      "number_setting": {
        "value": "110.20"
      },
      "boolean_setting": {
        "value": "false"
      },
      "hidden_select_single_setting": {
        "value": "option_2",
        "hidden": "false"
      },
      "select_multi_setting": {
        "values": [
          "option_2",
          "option_3"
        ]
      }
    },
    "subcategories": {
      "base_subcategory_settings": {
        "settings": {
          "classroom_number": {
            "value": "201/A"
          }
        }
      }
    }
  },
  "category_name": "base_settings"
}

Result

{"success":true} // true if succeeded, false if failed

Get settings

Introduction

Retrieving settings can be done in 2 ways. With the use of setting_keys or without which will return all the current settings defined in that category.

Publish topic

zbos/settings/get

Payload example 1

If you only need to get 1 or a list of setting(s) from a category you can include the setting_key in the setting_keys list.

{
  "key": "0d5261",
  "category": "base_settings",
  "setting_keys": [
    "required_string_setting",
    "classroom_number"
  ]
}

Payload example 2

To receive all settings from a category you can simply leave setting_keys null which returns all settings.

{
  "key": "0d5261",
  "category": "base_settings"
}

Result

The result will be in the form of:

{
  "category": {
    "label_key": "default.pref_title_base_settings",
    "orphaned": "false",
    "settings": {
      "orphaned": "false",
      "required_string_setting": {
        "default_value": "I am a required setting",
        "label_key": "default.pref_title_required_string",
        "description_key": "default.pref_summary_required_string",
        "type": "string",
        "required": true,
        "value": "Value 1B"
      },
      "integer_setting": {
        "default_value": "100",
        "label_key": "default.pref_title_integer",
        "description_key": "default.pref_summary_integer",
        "type": "integer",
        "range": {
          "min": 0,
          "max": 150
        },
        "value": "50"
      },
      "number_setting": {
        "default_value": "100.50",
        "label_key": "default.pref_title_number",
        "description_key": "default.pref_summary_number",
        "type": "number",
        "range": {
          "min": 1,
          "max": 150
        },
        "value": "110.20"
      },
      "boolean_setting": {
        "default_value": "true",
        "label_key": "default.pref_title_boolean",
        "description_key": "default.pref_summary_boolean",
        "type": "boolean",
        "value": "false"
      },
      "hidden_select_single_setting": {
        "default_value": "option_1",
        "label_key": "default.pref_title_select_single",
        "description_key": "default.pref_summary_select_single",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_single_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_single_option_2"
          }
        ],
        "type": "select_single",
        "hidden": "false",
        "value": "option_2"
      },
      "select_multi_setting": {
        "label_key": "default.pref_title_select_multi",
        "description_key": "default.pref_summary_select_multi",
        "options": [
          {
            "key": "option_1",
            "value": "Option 1",
            "label_key": "default.pref_title_select_multi_option_1"
          },
          {
            "key": "option_2",
            "value": "Option 2",
            "label_key": "default.pref_title_select_multi_option_2"
          },
          {
            "key": "option_3",
            "value": "Option 3",
            "label_key": "default.pref_title_select_multi_option_3"
          }
        ],
        "type": "select_multi",
        "values": [
          "option_2",
          "option_3"
        ]
      }
    },
    "subcategories": {
      "label_key": "default.pref_title_base_subcategory_settings",
      "orphaned": "false",
      "base_subcategory_settings": {
        "settings": {
          "classroom_number": {
            "default_value": "202/B",
            "label_key": "default.pref_title_classroom_number",
            "type": "string",
            "value": "201/A",
          }
        }
      }
    }
  }
}