Configuration Schemas
Overview
Devices connected to the Xyte cloud can utilize the ability to support remote configuration. This allows the End Customer to change configuration parameters both on the device (via UI, Remote, etc) and via the Cloud UI.
This is done by sharing a JSON configuration object between the device and the cloud server.
Since editing raw JSON would be cumbersome and error prone for the End Customer, the Cloud UI supports the JSON Schema format. A JSON schema specifies a set of format constraints that determine the structure of the JSON configuration file.
JSON Schema
Schema Structure
Xyte supports JSON Schema up to version 7.
While the configuration files themselves are unique for each instance of a device, the JSON schemas are set per device model and hence affect all instances of that model.
Resources
- JSON Schema docs - Read more about JSON Schema here.
- JSON to JSON Schemas Convertor - Using this tool you can easily create a basic schema from your configuration file, which you can edit later.
- JSON Schema Playground - Once you’ve created a JSON schema, you can edit and test it using this tool.
- JSON Schema Validator - Use this tool to validate your JSON schema.
Schema Structure
Note that due to Xyte's UI, all JSON properties must be encapsulated within an object; they cannot reside in the root object of the schema.
Examples
{
"definitions": {},
"properties": {
"occupancyProperties": {
"$id": "#/properties/occupancyProperties",
"type": "object",
"title": "Occupancy Sensor Settings",
"required": [
"timeout",
"whenVacatedMode"
],
"properties": {
"timeout": {
"$id": "#/properties/occupancyProperties/properties/timeout",
"type": "integer",
"title": "Sensor's timeout in seconds",
"readOnly": false,
"minimum": 5,
"maximum": 1800
},
"whenVacatedMode": {
"$id": "#/properties/occupancyProperties/properties/whenVacatedMode",
"type": "string",
"title": "Sensor's on vacation mode",
"decription": "<add desc>",
"readOnly": false,
"enum":[
"Or",
"And"
]
}
}
}
}
}
{
"properties": {
"deviceInfo": {
"$id": "#/properties/deviceInfo",
"type": "object",
"title": "Device Information",
"properties": {
"model": {
"$id": "#/properties/generalProperties/properties/model",
"type": [
"string",
"null"
],
"title": "Model",
"readOnly": true
}
}
},
"generalProperties": {
"$id": "#/properties/generalProperties",
"type": "object",
"title": "General Properties",
"description": "General properties",
"required": [],
"properties": {
"fwVersion": {
"$id": "#/properties/generalProperties/properties/fwVersion",
"type": ["string","null"],
"title": "Firmware Version",
"readOnly": true
},
"programIDTag": {
"$id": "#/properties/generalProperties/properties/programIDTag",
"type": ["string","null"],
"title": "Program ID Tag",
"readOnly": true
}
}
},
"networkProperties": {
"$id": "#/properties/networkProperties",
"type": "object",
"title": "Network Properties",
"description": "Network properties",
"required": [],
"properties": {
"macAddress": {
"$id": "#/properties/networkProperties/properties/macAddress",
"type": ["string","null"],
"title": "MAC Address",
"readOnly": true
},
"dhcp": {
"$id": "#/properties/networkProperties/properties/dhcp",
"type": "boolean",
"title": "DHCP",
"default": true
},
"staticIpAddress": {
"$id": "#/properties/networkProperties/properties/staticIpAddress",
"type": ["string","null"],
"format": "ipv4",
"title": "IP Address",
"description": "IP address"
},
"staticNetMask": {
"$id": "#/properties/networkProperties/properties/staticNetMask",
"type": ["string","null"],
"format": "ipv4",
"title": "Mask Address",
"description": "Mask address"
},
"staticDefRouter": {
"$id": "#/properties/networkProperties/properties/staticDefRouter",
"type": ["string","null"],
"format": "ipv4",
"title": "Default Gateway",
"description": "Default gateway"
},
"hostname": {
"$id": "#/properties/networkProperties/properties/hostname",
"type": ["string","null"],
"format": "hostname",
"title": "Hostname",
"description": "Hostname"
},
"domainName": {
"$id": "#/properties/networkProperties/properties/domainName",
"type": ["string","null"],
"title": "Domain Name",
"description": "Domain name"
},
"dnsServers": {
"$id": "#/properties/networkProperties/properties/dnsServers",
"type": "array",
"title": "DNS Servers",
"minItems": 0,
"maxItems": 3,
"description": "DNS servers",
"items": {
"type": ["string","null"]
}
}
},
"dependencies": {
"dhcp": {
"oneOf": [
{
"properties": {
"dhcp": {
"enum": [
true
]
},
"staticIpAddress": {
"readOnly": true
},
"staticNetMask": {
"readOnly": true
},
"staticDefRouter": {
"readOnly": true
},
"dnsServers": {
"maxItems":0,
"readOnly": true
}
}
},
{
"properties": {
"dhcp": {
"enum": [
false
]
},
"staticIpAddress": {
"readOnly": false
},
"staticNetMask": {
"readOnly": false
},
"staticDefRouter": {
"readOnly": false
},
"dnsServers": {
"maxItems":3,
"readOnly": false
}
}
}
]
}
}
},
"edgeProperties":{
"$id": "#/properties/edgeProperties",
"type": "object",
"title": "Edge Properties",
"properties": {
"globalScan": {
"$id": "#/properties/edgeProperties/properties/globalScan",
"type": "boolean",
"title": "Discover All",
"description":"Check \"Discover All\" to auto-discover all Crestron Ethernet devices on the same LAN",
"default": false,
"readOnly": false
}
}
}
},
"definitions": {}
}
VS Code is a great tool that you can use to easily edit a JSON schema and test it in real time. See this short tutorial for tips on how to do so:
Dynamic JSON Schema
Since the JSON Schema is set in common for all devices of a particular model, the result might be limited in some use cases. Such as when the End Customer should be presented with a drop down list of options, that are not the same for all devices.
E.g. List of available inputs to a monitor - a list that is different for each device.
To support this, the OEM can add dynamic options that will be loaded from the Device's Details field.
How to use dynamic list
- Enable "Enable Dynamic Config" under Partners Portal -> Models -> Model -> Config Schema (located at the bottom right of the screen)
- Add a field with
enum_typeset toXYTE_DETAILSandfield_pathset to the location of the options array expected to be found in the Device's Details area.
Sample setup
- Set the devices details to:
{ "options": { "inputs": [ "mic", "hdmi", "usb" ] } } - Set the Config Schema to:
{ "type": "object", "properties": { "sound": { "type": "string", "title": "Sound", "enum_type": "XYTE_DETAILS", "field_path": "options.inputs" } } }
The resulting UI will appear as:
Updated 7 days ago