You should now have an access token and know how to make requests to the Igloo API, if you don’t, check out the introduction guide.

Creating a new thing

We will now create your first device with Igloo, for the time being we will make the requests manually, you will then learn how to do everything with code; this way you will see what you can do with Igloo before having to get your hands dirty with the code.

In Igloo your IoT devices are called things, you can register a new thing with the following mutation:

mutation {
  createThing(type: "Example") {
    id
    claimCode
    qrCode
    token
  }
}

If you have Portal open on the “Things” page you will see a new thing appear in the list.

In the mutation we read these very important fields:

  • id: this is a unique identifier for your thing, every time you will update or read data about this thing you will refer to it by id
  • claimCode and qrcode are used by you or the user that bought your devices to get access to the thing in the Remote app. Remote asks to type claimCode or scan the qrCode, we suggest you print the qrCode on your device or put it inside the box
  • token: putting the access token for your account in the code of your device can open you up to security threats: if someone gets access to the code running on a single device they will have access to your account and all your things. This is why we provide you with a thing token that has only access to that specific thing. This way even if they get access to the source code they will only be able to read the data about that one device.
    While you are testing out Igloo there is no need to use this token, but we strongly recommend that you use it in the final product.

You can read data about your thing with a query (you can see all the available fields in the API documentation)

query {
  thing(id: "id-of-your-thing") {
    type
    firmware
    online
    batteryStatus
  }
}
Adding data to your thing

Different things can store different types of data: you can create variables on a thing, this way you can choose which data structure your thing should have, for example:

  • a weather thing could have a float variable for the pressure, another one for the temperature and a last one for wind speed
  • a lamp thing could have a single boolean variable for on/off
  • a seismometer could have a float series storing all the values measured in the last week

It is up to you to choose which variables to have in your thing. To create a new variable on a thing you can use a mutation like this one

mutation {
  createBooleanVariable(
    name: "On/Off"
    userPermission: READ_WRITE
    thingId: "id-of-your-thing"
    value: false
  ) {
    id
    userPermission
    name
  }
}

Let’s go through the mutation parameters one by one

  • name is the user-friendly name of the value; it is shown in the apps, but to update the variable you only need its id
  • userPermission specifies whether you can update this value from the apps, READ_WRITE variables are useful to remotely control a thing (for example turning it on or off), whereas READ_ONLY variables are useful to get data from the thing (for example the temperature measured)
  • thingId is the ID of the thing on which you want to create the variable

After running the mutation, if you have Portal (or Remote) open and the thing selected you will see the variable appear in the right panel.

You can update the value of the variable (or any other field) using a mutation

mutation {
  booleanVariable(
    id: "id-of-your-variable"
    value: true
  ) {
    value
  }
}
Which variable types can I use?

The supported variable types are:

  • BooleanVariable: stores a single boolean value
  • FloatVariable: stores a float value, two of the fields that it accepts are min and max, if they are both set the apps will show a slider that allows to pick a value between them
  • StringVariable: stores a text value, it accepts a maxChars field to limit the length of the text that can be set with the Remote app
  • FloatSeriesVariable: stores a list of nodes, each node has a timestamp and a float value, to add a node use the createFloatSeriesNode mutation

You can read more about each variable type and all the optional fields you can set, see the variable guide.
The way your variable is displayed will change depending on the optional fields you set, for example the StringVariable is displayed as a textbox by default, but if you specify the allowedValues field then it will become a drop down selection and if you set it as READ_ONLY it simply shows its value as text.

Notifications

We have a notification system too: notifications are always linked to a thing and they are sent to all users that have access to that thing. To create a notification use the following mutation:

mutation {
  createNotification(thingId: "your-thing-id", content:"Hey, look at me!") {
    id
  }
}

Notifications on desktop are delivered as web push notifications, so they will pop up as native notifications, soon the mobile apps will have native notifications too. Both on desktop and mobile the notifications can be seen in the Remote app.