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.