Models

There are six main models in Yggio:

  • User
  • Usergroup
  • Iotnode
  • Provider
  • Channel
  • Location

Entities of these models can be fetched, created, modified and deleted through the REST API.

Each created model entity will get a _id for referencing purposes. An Id is a 24 characters long hex string (e.g. 507f1f77bcf86cd799439011).

User

A user is created when a person creates an account in Yggio. It is used for authentication and access control to other resources.

User data structure:

{
  username: String,
  displayName: String,
  email: String,
  password: String,
  globalVisibility: Boolean
}

username and password is used for authentication.
displayName can be set if the user does not want their username to be displayed publicly.
email is a required field that must be a valid email address.
globalVisibility controls whether the the username can be searched for and seen by other Yggio users. This is set to false by default when creating a new user.

Usergroup

A user group is a set of users. It is used for two things: iotnode access rights and app filter.

Using a usergroup to set iotnode access rights makes it easier to control access rights for an iotnode for multiple users simultaneously. See the iotnode section for more information.

Usergroup data structure:

{
  owner: Id,
  name: String,
  members: [Id],
  appFilter: {
    enabled: Boolean,
    allowedApps: [String]
  }
}

owner is a reference to the user that owns the usergroup. When creating a new usergroup, the owner will be the user that created it.
name is used for display purposes.
members contains references to all the users that are members of the usergroup. When creating a new usergroup, the user that created it will be added to members.
appFilter is used to control which apps (i.e. providers) are visible to the members of the usergroup.

Iotnode

An iotnode is usually a representation of a physical device. However, it can also be a virtual device.

Iotnode data structure:

{
  name: String,
  description: String,
  category: String,
  nodeType: String,
  rabbitRouting: Object,
  updatedAt: Date,
  reportedAt: Date
}

Note that the model will contain additional attributes based on what nodeType it is. Most of the node types has a value attribute where the device's reported values are stored. See Supported devices page.

An iotnode can be a translated iotnode. See the Translated iotnode page for more information.

name and description are for display purposes.
category is used for grouping iotnodes to enable easy filtering.
nodeType states what type of iotnode it is. It can only be one of the supported node types.
rabbitRouting is only used internally, and should not be modified by external developers.
updatedAt is a timestamp that states when any attribute was last updated (e.g. name, value etc.).
reportedAt is a timestamp that states when the iotnode last got a report from the physical device.

Provider

A provider is a representation of an external app that is connected to Yggio. If you as a developer create an app that uses Yggio you would need to create a provider.

Provider data structure:

{
  name: String,
  info: String,
  owner: Id,
  logo: Id,
  redirect_uri: [String],
  client_id: String,
  secret: String
}

name is used when listing the available apps for the user in Control Panel. It is also unique for the Yggio instance. info is for display purposes.
owner is a reference to the user who created the provider.
logo is a reference to an uploaded logo image.
redirect_uri is the url to the application. It's used for directing users to the application as well as for OAuth.
client_id and secret are used for OAuth and is generated when creating a provider.

For more information about OAuth, see the OAuth page.

Channel

A channel is used by the publisher to send updates to an external service (e.g. an application) when an iotnode's data gets updated.
The data can be sent through either HTTP or MQTT.
The request's body will include the iotnode as well as information about which attributes were updated.

Channel data structure:

{
  name: String,
  iotnode: Id,

  http: {
    url: String
  }
  -- OR --
  mqtt: {
    topic: String
  }
}

name is an arbitrary string.
iotnode is a reference to the iotnode.
http.url is the url the messages will be POSTed to.
mqtt.topic is the topic the messages will be published to.

Location

The location model is used to group iotnodes together and bind them to a location on the world map.

Location data structure:

{
  name: String,
  description: String,
  user: Id,
  lat: Number,
  lng: Number,
  layers: [LocationLayer]
  defaultLayer: LocationLayer,
}

Note that there are some additional UI related attributes. These are deprecated and will be removed in the future.

name and description are for display purposes.
user is a reference to the user who created the location.
lat and lng are coordinates for where the location is located in the world.
layers include all of the added layers and defaultLayer is the layer that is shown first when entering a location. See the LocationLayer section below.

LocationLayer

LocationLayer is used to group items (iotnodes) in a location. For example: if a location is a building, a locationLayer can be seen as a floor in that building.

{
  name: String,
  items: [LocationItem]
}

LocationItem

LocationItem is a wrapper for an individual iotnode in a location.

{
  name: String,
  deviceId: Id,
}

name is for display purposes.
deviceId is a reference to an iotnode.

ProtocolCredentials

ProtocolCredentials is currently only intended for updating generic devices. And currently it is only implemented for MQTT. In future it will also be used when pushing over HTTP.

{
  owner: id,
  type: String
}

owner - the Yggio-user who owns the node. When creating protocol credentials this will be set to the user doing the request. type - the protocol type, mqtt (and in future http).

mqtt

Example for 'mqtt'-body.

{
  owner: id,
  type: String,
  username: String,
  password: String,
  clientId: String,
  topic: String
}

username, password and clientId are all used for the MQTT-broker user. They are not required to be related to the Yggio-user nor the device they are intended to update.
topic is a MQTT-compatible topic but with the additional limitations:

  • The topic must end with #-wildcard. (not OK:generic/company/device).
  • The topic must have at least 2 levels #, (not OK:company/#).
  • The topic must not use +-wildcard, (not OK: generic/company/+/temperature/#).
  • The topic must not start with /, (not OK: /generic/company/#).
  • The topic can only use [a-zA-Z0-9\-_./], (not OK: generic/company/@device/#).