Igloo supports several types of variables, in this guide we will se all the features of each type.

All types of variable support these fields:

  • developerOnly: if set to true the variable is only visible to the account of the producer (the user that created the thing) and not to the user that associated it with the pairCode nor the users they shared the thing with. We suggest you use developerOnly variables to store technical or diagnostic data that the end user wouldn’t understand;
  • name: the name of the variable, shown as title of the tile in the apps;
  • index: used to sort variables in the apps, if not specified the variables will be displayed ordered by creation time;

Many variable types also have these fields:

  • value: contains the value of the Variable. It’s not available in FloatSeriesVariables, because they don’t store a single value;
  • visualization: specifies which kind of visualization should be used in the apps; for example a FloatSeriesVariable has a visualization line, that shows a line chart, and a visualization bar, that shows a bar chart;
  • userPermission: it can be set as READ_ONLY or READ_WRITE and it indicates whether the user that paired the device can edit the variables through the apps or not. It’s not present on FloatSeriesVariable (it’s always READ_ONLY) and ImpulseVariable (it’s always READ_WRITE)
Variable

Many queries will return a generic Variable type that allows you to access only the fields supported by all variable types, for example

{
  thing(id:"{{thingId}}"){
    variables(limit:5){
      id
    }
  }
}

If you want to access a field that is unique to one type of variable, for example the precision field in float variables, you have to specify which type of variable you expect to receive

{
  thing(id:"{{thingId}}"){
    variables(limit:5){
      ...on FloatVariables{
        precision
      }
    }
  }
}
The lifecycle of a Variable

For each variable type there is a query <type>Variable to fetch such a variable passing it’s id. For example

{
  floatVariable(id:"{{variableId}}"){
    value
    min
    max
  }
}

If you want to access a variable without knowing it’s type, you can use the generic variable query, but you can fetch only fields that are available on any variable type

{
  variable(id:"{{variableId}}"){
    createdAt
    name
  }
}

To create a new variable you should use the create<Type>Variable mutation. You should always pass these fields

  • thingId: the ID of the thing on which you want to create the variable
  • name: the human friendly name for the variable
  • userPermission: for the variable types that support it (all except FloatSeriesVariable and ImpulseVariable) this field is required. It’s value can only be READ_ONLY or READ_WRITE and it should be passed without quotes (it’s not a string, it’s an enum)

You can also pass any of the other supported variable fields.

For example to create a FloatVariable:

mutation {
  createFloatVariable(thingId: "{{thingId}}", userPermission: READ_ONLY, name: "Esempio") {
    id
  }
}

To update a variable you can use the update<Type>Variable mutation and pass the id of the variable you want to update

mutation {
  updateFloatVariable(id: "{{floatVariableId}}", value: 75) {
    id
  }
}

And finally you can delete a variable using the deleteVariable mutation

mutation{
  deleteVariable(id: "{{floatValueId}}")
}
Float variables

The type FloatVariable represents a floating point number, for example the temperature measured now by a sensor. FloatVariable has some additional fields:

  • min: the minimum value your FloatValue can be (it is enforced when updating the value field), for example the min of light sensor measured light level could be 0;
  • max: like min but for the maximum value;
  • unitOfMeasurement: the unit you are measuring the value in, for example the unitOfMeasurement of a thermometer could be “°C”, it is used in the apps to display the value;
  • precision: precision with which the value was measured, e.g. precision: 0.01 means that 0.01 is the least difference measurable. This is only for visualization purposes: the value field will be stored as passed even if it has greater precision than specified in the precision field;
  • allowedValues: an optional array containing the allowed values for the variable. For example allowedValues: [1,2,5,10];
  • visualization: the visualizations supported for FloatVariable are wifi, battery, chargingBattery and classic. The classic visualization is the recommended one in most cases and adapts to the other fields: e.g. it shows a slider if min and max are set and a numeric input if they are not;
FloatVariable Screenshot
Float Variable Screenshot
String variables

The type StringVariable can represent any string, for example the status of your smart coffee machine (“Idle”, “Brewing” or “Coffee ready”). StringVariable‘s additional fields are:

  • maxChars: the maximum number of character the value field can have, mostly useful if your string is READ_WRITE
  • allowedValues: an array of the possible values for the value field (this will be enforced), for example the coffee flavor of our coffee machine
  • visualization: StringVariable supports an icon visualization that shows the icon corresponding to the variable’s value. It also supports the hex, hsl, rgb and color visualization that displays the value of the variable (it should always be an hex encoded color) as a color and shows either a machine-representation or a human friendly name.
Boolean Variables

The type BooleanVariable is the simplest of them all, it’s used to represent a boolean value like the ON/OFF status of your thing.

It’s only additional field is visualization that specifies an icon for the toggle button.  The supported visualizations are the following: classic, thumb, visibility, favorite, lock, star, flash, dayAndNight, wifi, tethering, bluetooth, link, location, mic, volume, camera, cloud, alarm, charging, notes, timer, sound, sync, airplaneMode, notifications, person, usb, download, doNotDisturb, flashlight.

Float Series Variables

The type FloatSeriesVariable is used to store a series of float values measured over time, for example the UV radiation measured at 1 hour intervals for a week. It’s nodes field is an array of nodes, each node has a timestamp and a value.
In addition to the createFloatSeriesVariable and updatefloatSeriesVariable mutations used to create and update the variable you can use createFloatSeriesNode and updatefloatSeriesNode to create and update the nodes.
It supports the unitOfMeasurement, min, max and precision fields, they behave like the ones for float variables, but they are enforced on every node. In addition to those it has the following fields:

  • storedNodes: specifies how many nodes to keep in storage (excess nodes are automatically deleted in chronological order)
  • shownNodes: specifies how many nodes to show in the apps (the user can always unzoom to show more nodes)
  • visualization: the supported visualization for FloatSeriesVariable are line, bar, mark and area
Impulse Variables

The type ImpulseVariable is used to let the user trigger an action on the device; for example you can use an ImpulseVariable to show an “Open door” button in the apps. When the user clicks on the button in the apps your device can be notified in real-time by listening to the impulseTriggered subscription.

The visualization field specifies the icon to show on the button, the supported values are close, done, refresh, up, down, left, right, exit, schedule, report, phone, photo, home, like, dislike, delete, favorite, code, wifi, freeze, build, dislike, light, lock, unlock, star, person, alert, sync, water, power, touch, bolt, send, message, drop, celebration, sound, tethering, hand, link, day, night, zoomIn, zoomOut, bluetooth, sensor, eject, swap, plusOne, download, upload.

File Variables

The type FileVariable is used to upload a file to Igloo; for example an IoT surveillance camera can upload the video footage of a suspected intrusion.

It’s supported fields are:

  • fileName: the name the file will have when the user downloads it, including the file extension
  • maxSize: the maximum size of the file expressed in bytes. It can be used when the variable is READ_WRITE to prevent the user from uploading files that are too big for your device to handle
  • visualization: the supported visualizations are download to show a download button and video, audio and image to show a preview of the file in the apps