Configure

The Configure schema allows a device to control what properties are editable, and control the type of data stored to those properties. We support much of JSON Schema, but not all the options are available.

Octoblu provides some specific extensions to the standard JSON Schema. This guide will cover some of the Octoblu specific ideas, and will not be a general JSON Schema tutorial.

Multiple Configurations

This first thing you will notice is that Octoblu supports multiple configuration schemas.

{
  "schemas": {
    "configure": {
      "first": { ... },
      "second": { ... },
      "third": { ... }
    }
  }
}

When the user views this configuration in Octoblu, they will be presented a choice between the schemas. This allows the schema author to provide different configurations, Basic and Advanced for example.

Grouping

Octoblu will allow you to group configurations together. For example, if a device offers different types of shells to the user, the schema author could group them by operating system.

{
  "schemas": {
    "configure": {
      "powershell": {
        "x-group-name": "Windows"
      },
      "cmd.exe": {
        "x-group-name": "Windows"        
      },
      "bash": {
        "x-group-name": "UNIX-ish"
      }
    }
  }
}

Form Schema

x-form-schema is required in order to reference a Form schema. Octoblu will search the schemas.form object for a matching key and apply that form schema.

{
  "schemas": {
    "version": "2.0.0",
    "configure": {
      "default": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "default": false
          }
        },
        "x-form-schema": {
          "angular": "configure.default.angular"
        }
      }
    },
    "form": {
      "configure": {
        "default": {
          "angular": [ ... ]
        }
      }
    }
  }
}

Default Configure Schema

Any schema named default will be selected unless you override the schemas.selected.configure property of your device and set it to the key of the configure schema object.

{
  "name": "Device A",
  "schemas": {
    "configure": {
      "not-the-default": { ... }
    },
    "selected": {
      "configure": "not-the-default"
      }
  }
}

Reference an external schema

Octoblu supports the standard $ref capability of JSON Schema. Octoblu will resolve the reference and apply the schema to the device.

{
  "schemas": {
    "configure": {
      "device-a": {
        "$ref": "https://data-forwarder-mongodb.octoblu.com/schemas/v1/configure.json"
      }
    }
  }
}

Reference another device schema

Octoblu allows you to reference a schema on another device, provided the device is given proper permissions. You can reference any property of the device and it will be used as the configuration schema.

The URI follows this pattern: meshbludevice://uuid/#/path/to/property.

// Device A
{
  "name": "Device A",
  "meshblu": {
    "version": "2.0.0",
      "whitelists": {
      "discover": {
        "view": [
          { "uuid": "device-b" }
        ]
      } 
      }
  },
  "friendSchemas": {
      "deviceB": { ... }
  }
}

// Device B
{
  "name": "Device B",
  "schemas": {
    "configure": {
      "device-a": {
        "$ref": "meshbludevice://device-a/#/friendSchemas/deviceB"
      }
    }
  }
}