Models

There are six main models in Yggio:

• User
• Usergroup
• Iotnode
• 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. RPs) 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,
  rabbitRouting: Object,
  updatedAt: Date,
  reportedAt: Date
}

Note that the model will contain additional attributes based on what kind of device it is.

name and description are for display purposes.
category is used for grouping iotnodes to enable easy filtering.
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.

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,

  // either http
  http: {
    url: String
  }
  // or mqtt
  mqtt: {
    type: String,
    recipient: 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 Will be populated with mqtt.recipient which states an keycloakUser or a basicCredentialsSet.

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.

BasicCredentialsSet

BasicCredentialsSet is a set of username & password that can be used in Yggio. Currently it's only used when publishing MQTT-messages to Yggio.

{
  username: String,
  password: String,
}

username password

ReservedMqttTopic

ReservedMqttTopic is used to reserve mqtt topics on Yggio and pairs it with a BasicCredentialsSet. This ensures that only authorized users and devices have access to this topic.

{
  topic: String,
  basicCredentialsSetId: Id,
}

topic the reserved topic. basicCredentialsSetId is a reference to a BasicCredentialsSet.