Device Types

This section provides instructions on how to add and manage device types within the Widgelix IoT cloud platform.

A Device Type is a template that allows you to provide properties that can be shared across all the devices of a particular device type.

For example, if you have 10 Busylights, a template can be created including common properties that can be shared across all of them. A non-sharable property that cannot be included in the template could be their device IDs because they differ from device to device.

In the left menu, click on Device Types.

If no device type has been created within your organization yet, the Device Types - Create your first device type page will be displayed.

Otherwise, the Device Type page will be displayed, showing the list of previously created device types.

Adding a Device Type

In the Widgelix IoT cloud platform, you have the flexibility to add new devices individually through the Create option or import them using the Load From Repository option.

Using Create Option

Click the +Create Device Type or +Create button, depending on the page you are on.

The Device Type page will be displayed, which consists of the following tabs: About, Uplink Data, Downlink Data, Tags, Additional Parameters, and Widgets.

About

The About tab allows you to provide basic information about your device type:

In the Name text box, enter the name of the device.

In the Description text box, enter a short description including what the device is intended for.

In the Manufacturer text box, enter the name of the device manufacturer.

Click on the picture box to browse and upload an image of the device.

Click on the + Map Marker button and select a suitable icon for your device. You can also use the Search box to find the icon by typing its name, for example, 'temperature'.

Click on the Next button.

You will be directed to the Uplink Data tab.

Uplink Data

The Uplink Data tab allows you to provide information about the uplink data that is being sent from your device.

This section is optional, and you may skip it without providing uplink information.

In the Code text area, type or paste the uplink payload formatter code, which is written in JavaScript.

Ensure that the uplink payload formatter code has thedecode()function.

Here is an example of an uplink payload formatter code:

function decode(payload, data) {
  for (var bytes = [], c = 0; c < payload.length; c += 2) {
    bytes.push(parseInt(payload.substr(c, 2), 16))
  }
  
  if (bytes.length === 24) {
    return {
      lastColorRed: bytes[16],
      lastColorBlue: bytes[17],
      lastColorGreen: bytes[18],
      lastColorOnTime: bytes[19],
      lastColorOffTime: bytes[20],
      messagesReceived: getValue(bytes, 8),
      messagesSent: getValue(bytes, 12),
      swRev: bytes[21],
      hwRev: bytes[22],
      adrState: bytes[23],
      rssi: getValue(bytes, 0),
      snr: getValue(bytes, 4),
    }
  } else { return {} }
}


function getValue(bytes, at) {
  return bytes[at] | (bytes[at+1] << 8) | (bytes[at+2] << 16) | (bytes[at+3] << 24);
}

To test the uplink payload formatter, enter the binary payload in HEX into the Payload text box and then click on the Run button.

Here is an example of a binary payload in HEX that you can use with the above uplink payload formatter:

D0FFFFFF2500000001000000020000007FFF00FF00240C01

If it is valid, the decoded payload will display in the Output text area and it will look something like this:

{
    "lastColorRed": 127,
    "lastColorBlue": 255,
    "lastColorGreen": 0,
    "lastColorOnTime": 255,
    "lastColorOffTime": 0,
    "messagesReceived": 1,
    "messagesSent": 2,
    "swRev": 36,
    "hwRev": 12,
    "adrState": 1,
    "rssi": -48,
    "snr": 37
}

In the Data Fields section, you can add keys that allow you to extract data from the payload.

In the Name text box, enter the key of the data field exactly as it appears in your uplink payload formatter. For example, according to the above uplink payload formatter code, the keys to be used are lastColorRed, lastColorBlue, lastColorGreen,lastColorOnTime, lastColorOffTime, messagesReceived, messagesSent, swRev, hwRev, adrState, rssi and snr.

Select the appropriate unit of measurement (if applicable) from the Units drop-down list.

Type the minimum and maximum values (if applicable) for the measurement in the Min and Max text boxes, respectively.

Click on the + button to add more data fields.

Alternatively, you can load the data fields in bulk from the decoded payload in the format of JSON object literal:

{
    "lastColorOnTime": 255,
    "lastColorOffTime": 0,
    "messagesReceived": 1,
    "messagesSent": 2,
    "swRev": 36,
    "hwRev": 12,
    "adrState": 1,
    "rssi": -48,
    "snr": 37
}

Click on the Load From Payload button.

Type or paste your JSON object literal in the Load Data Fields from Payload modal.

Click on the Load button.

The field names (keys) will be automatically filled in from the JSON object literal. Then, you can manually set units, min, and max values.

Widgelix also supports extracting the device id and device position (only applicable if the device has GPS support) from the payload:

Take device id from payload: First, turn on the 'Take device id from payload' slider button. In the Field name for device ID, type the key exactly as it appears in your uplink payload formatter.

Take position from payload: First, turn on the 'Take position from payload' slider button. In the Latitude field name and Longitude field name, type the keys exactly as they appear in your uplink payload formatter.

Click on the Next button.

You will be directed to the Downlink Data tab.

Downlink Data

The Downlink Data tab allows you to provide information about the downlink data that is being received by your device.

This section is optional, and you may skip it without providing downlink information.

In the Code text area, type or paste the downlink payload formatter code, which is written in JavaScript.

Ensure that the downlink payload formatter code has thedecode()function.

Here is an example of a downlink payload formatter code:

function decode(payload, params) {
    const red = ('00' + payload.red.toString(16)).slice(-2)
    const green = ('00' + payload.green.toString(16)).slice(-2)
    const blue = ('00' + payload.blue.toString(16)).slice(-2)
    const on = ('00' + payload.on.toString(16)).slice(-2)
    const off = ('00' + payload.off.toString(16)).slice(-2)
    return `${red}${blue}${green}${on}${off}`
}

To test the downlink payload formatter, type or paste its JSON payload (JSON object literal) into the Payload text box and then click on the Run button.

Here is a sample JSON payload you can use to test the downlink payload formatter code listed above:

{
  "red": 255,
  "green": 0,
  "blue": 0,
  "on": 255,
  "off": 0
}

If it is valid, the encoded binary payload in HEX will display in the Output text box and it will look something like this:

"ff0000ff00"

Click on the Next button.

You will be directed to the Tags tab.

Additional Parameters

The Additional Parameters tab allows you to provide additional parameters for your device type.

This section is optional, and you may skip it without providing additional parameters.

In the Additional Parameters tab, you can enable extracting radio parameters and battery parameters from the uplink payload.

Radio: Enabling the Radio option decodes RSSI and SNR from the payload.

Turn on the Take radio parameters from payload slider button.
In the Field name for RSSI and Field name for SNR text boxes, type the keys exactly as they appear in your uplink payload formatter.

Battery: Enabling the Battery option decodes battery voltage from the payload.

Turn on the Take battery parameters from payload slider button.
In the Field name for battery value text box, type the key exactly as it appears in your uplink payload formatter.
In the Power consumption per cycle, mAh text box, enter the power consumption of your device per transmission in mAh.
Select the battery type/chemistry from the Battery type drop-down list.
In the Capacity text box, enter the battery capacity in mAh.

Click on the Next button.

You will be directed to the Widgets tab.

Widgets

The Widgets tab allows you to select the widgets that you want to use for data visualization in order to gain a better understanding of the data.

In the Widgets tab, click on the +Add Widget button.

In the Select Widget modal, click on the widget type that you want to add, for example, Chart.

The complete instructions on how to configure each widget type can be found on the Widgets page.

After adding the necessary widgets, click on the Save button to add the device type to your organization.

The new device type is listed on the Device Type page.

Load From Repository

On the Device Type page, click on the Load From Repository button.

The Load From Repository modal opens.

In the Load From Repository modal, select the manufacturer from the Manufacturers drop-down list. This action will list all the devices belonging to the selected manufacturer. If there are a large number of devices shown in the list, you can search for a specific device type by its name using the Search box.

Select the device type from the list you want to add.

In the Name text box, enter a name for the selected device type.

Click on the Save button to add the device type to your organization.

The new device type is listed on the Device Type page.

Editing a Device Type

After creating a device type, you can edit any property except for the device type name.

If you only have Viewer rights, you cannot edit a device type.

On the Device Types page, click on the name of the device type from the list that you want to edit.

All the properties of the device type will open on a single page in edit mode.

Once you have finished, scroll down the page and click the Save button to save the changes.

Deleting a Device Type

A device type can be deleted from the organization, and cannot be undone.

If you only have Viewer rights, you cannot delete a device type.

On the Device Types page, click on the name of the device type from the list that you want to delete.

The Edit Device Type page will be displayed. Scroll down the page and then click on the Delete button.

The Delete device type model will be displayed.

In the text box, type in the exact name of the device type.

Click on the Delete button.

The device type will be removed from your organization.

The Delete operation can't be undone.

Searching Device Types

Device types can be searched by name. Type the name of the device you want to search for in the Search text box. As you type, the devices will be filtered based on the text you are entering.

You can also filter the devices by the manufacturer. To view the Manufacturer search box, click on the Filters button.

The device type list can be sorted in ascending or descending order by clicking on the respective column name in the table for Name, Description, and Manufacturer.

When you hover your mouse over a column header, one of the following tooltips will be displayed, indicating what you should do: