Defining Device Types

For SmartServer 3.4 and 3.5, see Defining Device Types (Release 3.4 and 3.5)

For SmartServer 3.3 and prior, see Defining Device Types (Release 3.3 and Prior)

You will create device type definitions to enable the SmartServer to interact with and configure your edge devices.   See Device Type Definition for a description of device types and how they are used.  This page describes how to create, manage, and package device types, and consists of the following:

The Device Types widget provides the ability to create, view, and edit device types. Device type definition (DTD) files are CSV files that list the device type names, program identifier (ID), application image names, and graphics assets to be used as icons for specified device types. These file use a .dtd extension. 

You first have to import any XIF files (see Collecting or Creating Device Definitions), resource files, application image files, system image files, and graphics files that you plan to use. When an XIF file that does not already have an associated device type defined is imported, a default device type will be created with the device type name equal to the XIF file name, the protocol and program ID set from the XIF file, and the graphics file set to a default device icon.

Once imported, you will be able to create new device types in the Device Types widget, and since the referenced files are already available in the database, you will only have to type a device type name (all the other entries will be selections from pull-down lists).

You can create a device type package (DTP) file that is an archive file that contains assets, resources, and definitions for defining new device types using the Export feature on the Device Types widget.

Users with Administrator, Owner, Controller, or Tenant roles can use this widget to create, modify, and delete device types datapoints within the geozones where they have the Administrator, Owner, Controller, or Tenant roles.  

Creating a Graphics File

You can specify a graphics file to customize the image displayed for a device type.  You can supply the graphics file as a .JPG or .PNG. file.  Files with a .JPG extension are interpreted as JPEG files, as defined by ISO/IEC 10918-1. Files with a .PNG extension are interpreted as Portable Network Graphics files, as defined by ISO/IEC 15948. 

Creating a Device Type

You can create a device type using the Device Types widget. To do so, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the Create Device button ().



  4. Enter the device type parameters as appropriate, including:

    • Device Type  a unique name for the device type
    • Protocol  the communications protocol (BACnetEnOcean for local EnOcean interface, LON, LoRaWANModbus, iotc for remote EnOcean interface)
    • XIF File – provides the ability to upload an XIF file plus a list of all available XIF files with the selected protocol in the SmartServer CMS database

    • Program ID – read-only field with the program ID of the selected XIF file

    • Default Application Image – provides the ability to upload an application image file plus a list of all available application image files with the selected protocol in the SmartServer CMS database. (For SmartServer IoT 2.5, this option is only available for LON devices.)

    • Automatic Application Image Load – indicates if the default application image must be loaded upon initial provisioning a device of the specified type. The default value is cleared. It is cleared and grayed out if a Default Application Image is not selected

    • Default System Image – provides the ability to upload a system image file plus a list of all available system image files with the selected protocol in the database.  (For SmartServer IoT 2.5, this option is only available for LON devices.)

    • Automatic System Image Load – indicates if the default system image must be loaded upon initial provisioning a device of the specified type. The default value is cleared. It is cleared and grayed out if a Default System Image is not selected.

    • Graphics File – provides the ability to upload a graphics file plus a list of all available graphics files in the SmartServer CMS database


    Create Device Type settings


    Create Device Type settings – LON example


    Create Device Type settings – EnOcean example


  5. Click SAVE to create the new device type.

Once a device type is created, you can add devices (see Discovering, Defining, or Importing Devices) and provision them (see Provisioning, Deprovisioning, and Replacing Devices).

Viewing Device Types

You can set filters on the Device Types widget to view selected device type definitions.  By default, the CMS lists all defined device types.

To set a filter, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the Set Filter button ().



    The Set filters view appears.



  4. Enter the search criteria. Click the down arrow to select the filter options (i.e., by name, segment controller, XIF file, driver, and/or program ID) and click the plus sign ( ) to add filters.



  5. Click Apply Filters.

    The results below show the name filter results for Segment Controller = smartserver-17qes5s and Device = Tstat-01.



    The Device Types widget display includes:

    • Device Type – the device type name

    • Driver – the protocol specified by the device template

    • Device Count – the number of defined devices implementing the device template

    Each heading has a Sort button (). When clicked, the device type list is sorted in forward or reverse order by the selected heading.

  6. The Reset Filter button () clears the filter settings.

Copying a Device Type

You can copy a device type using the Device Types widget. To do so, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the Action button () and select the Copy action.



  4. Enter a new device type name, and select the XIF file, default application image file (for SmartServer IoT 2.5, LON device support only), default system image file (for SmartServer IoT 2.5, LON device support only), and graphic file as appropriate. 

    The Automatic Application/System Image Load checkbox indicates if the default application/system image must be loaded upon initial provisioning a device of the specified type. The default value is cleared. It is cleared and grayed out if a Default Application/System Image is not selected.




  5. Click SAVE to copy device type.

Editing a Device Type

You can edit a device type using the Device Types widget. To do so, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the Action button () for the selected device type and select the Edit action.



  4. Edit the device type parameters as appropriate, including:

    • Device Type
    • XIF File
    • Default Application Image
    • Default System Image
    • Graphic File
    • Automatic Application/System Image Load checkbox

3. Click SAVE to save the edited device type.

Removing a Device Type

You can remove a device type using the Device Types widget. To do so, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the Action button () and select the Remove action.



  4. Click OK in the confirmation dialog box to remove the selected device type.

Removing Multiple Device Types

You can remove multiple device types using the Device Types widget. To do so, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the checkmark for the device types you wish to remove from the Device Types widget, or click the Select All button () to select all device types.

    The checkmark changes from blue to yellow.



  4. Click the Action button () and select the Remove Selected Device Types action.



  5. Click OK in the confirmation dialog box to remove the selected device types.


Creating a Device Type Definition (DTD) File

Typically you create a device type definition as described above in the Creating a Device Type section, but you can export, view, and modify the definition as a CSV file as described here.

A device type definition (DTD) file is a CSV file that lists the device type names, program identifier (ID), application image names, and graphics assets to be used as icons for specified device types.

The following embedded metadata tags are usually in the first line of the DTD file, but can appear anywhere:
#filetype,dtd

A DTD file is identified by its file name and categorized by the #filetype tag equal to dtd and its extension .DTD or .CSV (not case sensitive).

DTD File Parameters

A DTD file contains the following columns (headings and values are not case sensitive):

Parameter                Description
Device TypeUnique name for the device type.  This is the name that will be shown to the user when defining the device in the CMS(required parameter)
ProtocolCommunications protocol, e.g., BACnetEnOcean for local EnOcean interface, LON, LoRaWANModbus, iotc for remote EnOcean interface (required parameter)
Program ID

Unique program ID used to find the XIF file. Upon import, if the program ID exists because of a previously imported XIF, the automatically created type is deleted. (required parameter)

Default AppFilename for the default application image file. (optional parameter; does not apply to Modbus)
Default SysFilename for the default system image file. (optional parameter; does not apply to Modbus)
Auto App LoadBoolean indicating if the Default_App must be loaded upon initial provisioning a device of the specified type. Default value is false. (optional parameter; does not apply to Modbus)
Auto Sys LoadBoolean indicating if the Default_Sys must be loaded upon initial provisioning a device of the specified type. Default value is false. (optional parameter; does not apply to Modbus)
Graphics FileName of the graphics file for the device type icon. (optional parameter)

DTD File Example

The example below shows more than one device type being created for the same program ID to allow for different polling, logging, or alarming for two devices of the same type.

#filetype,dtd
Device Type,Protocol,Program ID,Default App,Default Sys,Auto App Load,Auto Sys Load,Graphics File
FT 6000 EVB Multisensor A,LON,9FFF:FF05:0184:0430,NcMultiSensor.apb,Neuron S6 V21.sys,TRUE,TRUE,FT 6000 EVB.png
FT 6000 EVB Multisensor B,LON,9FFF:FF05:0184:0430,NcMultiSensor.apb,Neuron S6 V21.sys,TRUE,TRUE,FT 6000 EVB.png


Creating a Device Type Package (DTP) File

You can create a device type package (DTP) file that is an archive file that contains assets, resources, and definitions for defining new device types. It provides the ability to package multiple files needed to define new device types and to import the entire DTP in a single step. A DTP file is identified by its file name and categorized by its extension .ZIP, .GZIP, .DTP, .DTP.ZIP, or .GDTP (not case sensitive).

The compression method is determined by the extension, with .ZIP and .DTP files in zip format, and .GZIP and .GDTP files in gzip format. Once imported, the SmartServer CMS extracts all the files in the archive and processes them based on the file import rules.

Spaces are not supported in the zip file name or in the contained directory names.

Importing a Device Type

Device type files can be imported individually, or you can package files together into a zip file (DTP file) and import multiple files in one operation. The files that you import into the SmartServer CMS are stored in the CMS database. You cannot undo a file import.

Once data is imported, it is available from the CMS database where you imported it, and it is also available on another SmartServer IoT that has been restored from a database backup of your first SmartServer IoT so that you can provision a new SmartServer IoT with the same device type definitions. Alternatively, you can create a single DTP file that you import into new SmartServer IoTs as you deploy them, simplifying the process of defining the device types you commonly use for new installations.

When creating CSV files using Excel, parameters and values must be placed into separate cells otherwise Excel places quotes around the text and the file will not compile. For example, putting #filetype,BACnet_xif into one cell causes Excel to put quotes around the text, which are not visible. In this case, #filetype should appear in one cell and BACnet_xif in the other.

You can import devices types using the Import / Export dialog, which is available from the main CMS dashboard Import / Export button (). For SmartServer 3.6 and prior, you can also import device types from the Device Types widget using the Import Device Types button (). 

To import a device type, perform the following steps:

  1. If you are importing LoRaWAN or remote EnOcean interface device types for SmartServer Pi 4.3, then first perform the steps found in /wiki/spaces/TEMP/pages/384270337

  2. Open the SmartServer CMS.

  3. Click the Import / Export button () on the CMS dashboard.




    The Import / Export dialog appears.



  4. Select the device types file to be imported and place it in the Drop Files to Import or Browse box.



  5. Click IMPORT.

    Notification messages (similar to the one shown below) will appear indicating that device types are being uploaded and the CPU usage on the main CMS page will show increased activity. 



  6. When the device types file has finished loading, click CANCEL to close the Import / Export dialog.

Exporting a Device Type

You can export your device type definitions to a device type definition (DTD) file from the Device Types widget.  You can use this capability to export a set of device type definitions to any number of new SmartServers in a single operation per SmartServer.

To export a device type, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the Action button () and select the Export action.



  4. Enable or disable the Download as Package option.  If you enable Download as Package when you click Export the CMS creates a device type definition (DTD) file with your selected device type definitions, creates a device logging and alarming (DLA) file with your DLA specifications, collects all of your other device type definition files including resource files, CON files, and graphics files, and packages them into a single zip archive called the device type package (DTP).  If you do not enable Download as Package, the CMS creates the DTD file but does not package all the dependent files with it.  You can use the DTP file to specify the same device type definitions on multiple SmartServers.  You can collect all your device type definition files on one SmartServer, use it to create a DTP file, and then import the DTP file on your other SmartServers using the Import action that is available through the Device Types widget.



  5. Click DOWNLOAD ALL to export the device type.

Exporting Multiple Device Types

You can export multiple device type definitions to a device type definition (DTD) file from the Device Types widget.  You can use this capability to export a set of device type definitions to any number of new SmartServers in a single operation per SmartServer.

To export multiple device types, perform the following steps:

  1. Open the SmartServer CMS.

  2. Open the Device Types widget. Click the Expand button (  ). 



  3. Click the checkmark for the device types you wish to export on the Device Types widget, or click the Select All button () to select all device types.

    The checkmark changes from blue to yellow.



  4. Click the Action button () and select the Export Selected Device Types action.



  5. Enable or disable the Download as package option.

    The Export feature saves a DTP containing DTDs for the selected device types, and all dependent files if the Download as a package option is selected, or DTDs for the selected device types and all dependent files if the Download as a package option is not selected. 



  6. Click DOWNLOAD ALL to export the device types.