Device Types

Owned by Nina Cardillo
Last updated: 29-Mar-2024
14 min read


URI Definition

Method        

URI and Fields

GET




/iap/devTypes/{device_type}

Returns a set of existing device types (DeviceTypeDTO).

Path Parameters

The following list describes the path parameters for the device_type path element.

Parameter                   Description                                                                                                                                                 
typeName This is the default parameter, used if query *+... is not specified.  
typeFor ProgramID
programIdthe same Program ID value
protocol

Specifies the protocol.  Possible values are:

  • All (*)
  • BACnet
  • EnOcean
  • IAP
  • LON
  • LoRaWAN
  • Modbus
xifNameName of the XIF file.
filenamename of the file associated with device type
isDefaultspecifies whether device type is the default one
scIdsegment controller id
scNamesegment controller name

Query Parameters

You can specify a query parameter appended to the end of your URI, preceded with a "?" character. 

Parameter        Description                                                                                                                                  
customerIdquery parameter representing Id of customer, that owns the Device Type
sortOrderSpecifies the sort order.  Either ascending or descending (asc or desc).
Default is asc.
sortBySpecifies the name of a parameter.  Either:  typeName, type, protocol, or xifName.
Default is typeName.
shortif false, number of devices that use device type and xif file names will be provided in output, true by default
pgSpecifies the page number (1-0x7fffffff).
Default is null.
szSpecifies the page size (1-0x7fffffff).

Default is null.

Return Codes

200         Success.                                                                                                                                                               
422Error.  Includes an error message if the device_type path element is incorrectly formatted.

Success response

Collection of devices types corresponding requested filter.

Examples

https://localhost/iap/devTypes/*?customerId=81&short=false
 [
    {
        "id": 129,
        "name": "LH-PM100E_S6k",
        "programId": "9000011503020465",
        "protocol": "lon",
        "icon": "/iap/metafile/PsYDurnVb033NNMTWWITh6OMKtpXvz/content",
        "iconName": "PM.png",
        "cid": 84,
        "xifName": "LH-PM100E_6k.XIF",
        "autoSysLoad": false,
        "autoAppLoad": false,
        "numberOfDevices": 1,
        "protocolName": "LON",
        "isDefault": false
    },
    {
        "id": 130,
        "name": "LH-PM100E_S5k",
        "programId": "9000011503020455",
        "protocol": "lon",
        "icon": "/iap/metafile/PsYDurnVb033NNMTWWITh6OMKtpXvz/content",
        "iconName": "PM.png",
        "cid": 84,
        "xifName": "LH-PM100E_5k.XIF",
        "autoSysLoad": false,
        "autoAppLoad": false,
        "numberOfDevices": 0,
        "protocolName": "LON",
        "isDefault": false
    }
]
/iap/protocols

Returns a set of available protocols (ProtocolDTO).

Body Parameters

Parameter                   Description                                                                                                                                                  
systemName 

Specifies the protocol.

userNameSpecifies the name of the protocol.

Body Example:

[                                                                                                                                                           
    {
        "systemName": "bacnet",
        "userName": "BACnet"
    },
    {
        "systemName": "lon",
        "userName": "LON"
    },
 ...

]

Return Codes

200         Success.                                                                                                                                                               

/iap/metafile/{file_type}

Returns a set of file names known in the CMS, with links for downloading. 

Path Parameters

The following list describes the possible values for file_type.

Parameter                   Description                                                                                                                                                 
app Returns Neuron application image files (.apb, .ndl, .nxe).  
iconReturns device icon files.
sys

Returns Neuron system image files (.ndl, .nx).

xifReturns LON and Modbus XIF files.

URI Examples

/iap/metafile/app?protocol={protocol}&sortOrder={asc/desc}&sortBy={field_name}&pg={page_number}&sz={page_size}

/iap/metafile/icon?sortOrder={asc/desc}&sortBy={field_name}&pg={page_number}&sz={page_size}

/iap/metafile/sys?protocol={protocol}&sortOrder={asc/desc}&sortBy={field_name}&pg={page_number}&sz={page_size}

/iap/metafile/xif?protocol={protocol}&programId={programId}&sortOrder={asc/desc}&sortBy={field_name}&pg={page_number}&sz={page_size}

Query Parameters

You can specify a query parameter appended to the end of your URI, preceded with a "?" character. 

For example:

/iap/metafile/app?protocol={protocol}&sortOrder={asc/desc}&sortBy={field_name}&pg={page_number}&sz={page_size}


Parameter        Type           Description                                                                                                                                  
protocolString

(Optional) A value to be used for filtering.  Used for XIF and image files only.

Possible values:  

  • bacnet
  • enocean
  • iap
  • lon
  • lorawan
  • modbus

Default: null

programIdString

(Optional) A value to be used for filtering.  Used for XIF files only. 

Valid values: a hexidecimal string

No default value.    

sortOrderString

(Optional) Specifies the sort order.  Either ascending or descending (asc or desc).

Default: asc

sortByString

(Optional) Specifies the name of a parameter to be sorted on. 

Possible values:  typeName, type, protocol, or xifName.

Default: typeName

pgInteger

(Optional) Specifies the page number. 

Possible values: 1 - 0x7fffffff

Default: null

szInteger

(Optional) Specifies the page size.

Possible values: 1 - 0x7fffffff

Default: null

Return Codes

200         Success.                                                                                                                                                               
/iap/devTypes/count

Gets number of Device Types for specified customer.

Query Parameters

CustomerId – query parameter representing Id of customer, that owns the Device Type.

Success response 

Total number of available Device Types.

Examples

https://localhost/iap/devTypes/count?customerId=84


RESPONSE:
{
    "value": 4
}


/iap/devTypes/download/{id}

Creates DTD file containing Device Types definitions for specified Device Type.

Parameter

id - The ID of the Device Type to be exported to the DTD file.

Success Response

DTD file with specified device type.

Examples

https://localhost/iap/devTypes/download/125


RESPONSE:
DTD file with the following content:
#filetype,dtd
"Device Type",Protocol,"Program ID","Default App","Default Sys","Auto App Load","Auto Sys Load","Graphics File",Default LH-PM100E_S6k,lon,9000011503020465,,,false,false,PM.png,false

POST








/iap/devTypes

Creates a new device type (CreateDevicyTypeDTO).

Payload Parameters

Parameter        Type           Description                                                                                                                                  
nameString(Required) Specifies the device type name.  Case insensitive.
protocolString

(Required) Specifies the protocol name.  Possible values:

  • bacnet
  • enocean
  • iap
  • lon
  • lorawan
  • modbus
xifNameString

Specifies the XIF file name.

Required only for device types for LON or Modbus protocols.

xifName is not allowed for device types for IAP or BACnet protocols.

programIdString

(Optional) Specifies the device type program ID.

Valid values: a hexidecimal string

defaultAppString(Optional) LON devices only. Specifies the application image file name. 
autoAppLoadBoolean

(Optional) LON devices only. Enables automatic application image loading. 

Possible values: True/False.   

Default is False.

defaultSysString(Optional) LON devices only. Specifies the system image file name.
autoSysLoadBoolean

(Optional) LON devices only. Enables automatic system image loading.

Possible values: True/False.   

Default is False.

iconNameString(Optional) Specifies the graphic file name.

Query Parameters

customerId – query parameter representing ID of the customer, that will own created Device Type

segmentId - if specified then load request would be send only for the segment controller with such ID

Return Codes

204         Success.                                                                                                      
422Error.  Includes an error message describing any validation failure.

Success Response

Response code 200 in case of success or some error code otherwise.

Examples

Example: Create Device Type
https://localhost/iap/devTypes?customerId=84&segmentId=1

REQUEST BODY
{
    "name" : "EVB Meter",
    "protocol" : "lon",
    "xifName" : "PM1006k_min.XIF",
    "programId" : "9000:0115:0302:0466",
    "defaultApp" : null,
    "autoAppLoad" : false,
    "defaultSys" : null,
    "autoSysLoad" : false,
    "icon" : "PM.png",
    "isDefault": false
}

RESPONSE:
Response code 200
/iap/devTypes/delete

Deletes either all device types, or, when device types are specified in the Body, it deletes the specified device types.  Before any device types are deleted, delete performs the following checks:

  • If device types are specified in the the body, delete checks whether any specified device types are being used by any device.  If a specified device type is being used, then no device types are deleted, and an error is returned.  The delete is only performed when none of the specified device types are being used by any device.

  • If no device types are specified in the the body, delete checks whether any device types are being used by any device.  If any device type is being used, then no device types are deleted, and an error is returned.  The delete is only performed when no device types are being used by any device.

Parameter

Include in request body a collection of Device Type IDs to be deleted.

Return Codes

204         Success.                                                                                                                                                              
422Error.  Includes an error message if any device types, or selected device types, are being used and
cannot be deleted.

Success Response

Response code 200 in case of success or some error code otherwise.

Examples

https://localhost/iap/devTypes/delete

REQUEST BODY:
[473]

RESPONSE:
Response code 200
/iap/devTypes/export

Exports specified device types with all related resources.  Device types are specified in the REST body.  

export builds DTD files containing all information about the specified device types, and DTP archive containing DTD and all related resources (XIF, icon, application and system image files) if requested.  

If packaged format is specified (in the query parameter), then one DTD file is built for all specified device types, all related resource files are found, packed with the DTD file into one DTP archive, and sent in response.

If packaged format is not specified (in the query parameter), then one DTD file is built for each specified device type, all related resource files are found, links to download all the DTD files, and  resources are collected and sent in response.

Query Parameters

You can specify a query parameter appended to the end of your URI, preceded with a "?" character. 

Parameter        Type             Description                                                                                                                               
packagedBoolean

(Optional) Specifies export format. 

Possible values: True/False.   

Default is True.

Return Codes

200         Success.                                                                                                                                                              

Request Body Parameters

Include in request body a collection of Device Type IDs to be exported.

Success Response

Collection of device type resources that can be exported.

Examples

https://localhost/iap/devTypes/export

REQUEST BODY:
[125,126]

RESPONSE:
[
    {
        "name": "PM.png",
        "link": "/iap/metafile/7srJq70WSI3D4sHnrbT2aOsytHhj4W/content"
    },
    {
        "name": "LH-PM100E_5k.XIF",
        "link": "/iap/metafile/wmr5Ge5ThjnE19tp3WgOVpDoCcDG4C/content/inflated"
    },
    {
        "name": "LH-PM100E_6k.XIF",
        "link": "/iap/metafile/L8ANUSjnkjzuqdvtlLrltSVEAaQRmM/content/inflated"
    },
    {
        "name": "LH-PM100E_S5k.dtd",
        "link": "/iap/devTypes/download/126"
    },
    {
        "name": "LH-PM100E_S6k.dtd",
        "link": "/iap/devTypes/download/125"
    }
]
/iap/devTypes/export/packaged

Exports all device types with all related resource files in a single DTP archive.   This archive contains one DTD file containing all device types and all related resource files.

export builds DTD files containing all information about the specified device types, and DTP archive containing DTD and all related resources (XIF, icon, application and system image files) if requested.  

If packaged format is specified (in the query parameter), then one DTD file is built for all specified device types, all related resource files are found, packed with the DTD file into one DTP archive, and sent in response.

If packaged format is not specified (in the query parameter), then one DTD file is built for each specified device type, all related resource files are found, links to download all the DTD files, and  resources are collected and sent in response.

If no Device Type IDs specified, all DTDs and all related resource files will be packaged to resulting DTP file.

Parameters

Include in request body a collection of Device Type IDs to be exported.

Return Codes

200         Success.                                                                                                                                                              

Success Response

DTP package

Examples

https://localhost/iap/devTypes/export/packaged

REQUEST BODY:
[125,126]

RESPONSE:
DTP package with specified device types
/iap/metafile/{file_type}

Imports specific files to the CMS.

Path Parameters

The following list describes the possible values for file_type.  file_type is optional.

Parameter                   Description                                                                                                                                                 
app Files to import are Neuron application image files (.apb, .ndl, .nxe).  
iconFiles to import are device icon files.
sys

Files to import are Neuron system image files (.ndl, .nx).

xifFiles to import are LON and Modbus XIF files.

URI Examples

/iap/metafile?customerId={customerId}

/iap/metafile/app?customerId={customerId}&protocol={protocol}                                            

/iap/metafile/icon?customerId={customerId}&protocol={protocol}

/iap/metafile/sys?customerId={customerId}&protocol={protocol}

/iap/metafile/xif?customerId={customerId}&protocol={protocol}

Query Parameters

You can specify a query parameter appended to the end of your URI, preceded with a "?" character. 

For example: /iap/metafile/app?customerId={customerId}&protocol={protocol}

Parameter        Type           Description                                                                                                                                  
protocolString

(Optional) Specifies the protocol that the file is associated with. 

Possible values:  

  • bacnet
  • enocean
  • iap
  • lon
  • lorawan
  • modbus
customerIDString(Required) Specifies the customer that has access to the file.


Example: Importing a XIF file (same process can be used for importing dtp, zip, bac, mod, btm, device.csv, and other file types).

 /iap/metafile?customerId={customerId}

HTTPS header must use Content-Type of  multipart/form-data.  Adding the boundary string is optional.


-----------------------------11130049656327408512700814640
Content-Disposition: form-data; name="jsonFile"; filename="blob"
Content-Type: application/json

{"fileName":"6kEvbMultiSensor.XIF"}
-----------------------------11130049656327408512700814640
Content-Disposition: form-data; name="metaFile"; filename="6kEvbMultiSensor.XIF"
Content-Type: application/octet-stream

File: 6kEvbMultiSensor.XIF generated by LONNCC32 Version 6.39.02, XIF Version 4.501
Copyright (c) Echelon Corporation 1989-2018
All Rights Reserved. Run on Fri Aug 24 18:36:06 2018
:
:
:
NVVAL
\x01
\x00 \x28
\x0D \xAC
\x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00
\x00 \x00 \x68 \x00 \x02 \x00 \x02 \xFF
\xFE \x00 \x00
-----------------------------11130049656327408512700814640--



Note: line terminator is <cr><lf> and is used after boundary strings, after header information, before the file contents and after the file contents.

Request

POST /iap/metafile?customerId=33
PAYLOAD
-----------------------------11130049656327408512700814640
Content-Disposition: form-data; name="jsonFile"; filename="blob"
Content-Type: application/json

{"fileName":"6kEvbMultiSensor.XIF"}
-----------------------------11130049656327408512700814640
Content-Disposition: form-data; name="metaFile"; filename="6kEvbMultiSensor.XIF"
Content-Type: application/octet-stream

File: 6kEvbMultiSensor.XIF generated by LONNCC32 Version 6.39.02, XIF Version 4.501
Copyright (c) Echelon Corporation 1989-2018
All Rights Reserved. Run on Fri Aug 24 18:36:06 2018
:
:
:
NVVAL
\x01
\x00 \x28
\x0D \xAC
\x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00
\x00 \x00 \x68 \x00 \x02 \x00 \x02 \xFF
\xFE \x00 \x00
-----------------------------11130049656327408512700814640--


Return Codes

204         Success.    This only means the request was correctly formatted. It doesn't mean that the payload is correct or that that the SmartServer can process the data.                                                                                                                                           
415
Content-Type header needs to be multipart/form-data.
428
For zip files with multiple files, means that the zip file or included files may have been already downloaded.
You need to send another POST request with the confirmation Id, which is included in HTTP 428 response, to import this zip file
Example HTTP 428 Response
Response
{
	"confirmationId":"99ddb7fb-5dd5-401e-92a6-897198870813",
	"importInfo":{
		"totalDeviceTypes":1,
		"newDeviceTypes":0,
		"updatedDeviceTypes":1,
		"updatedDevices":1
	},
	"validFor":600000,
	"importType":"REPLACE_PROTOCOL"
}
Request to Confirm Import (after receiving HTTP 428 response)
POST https://10.0.0.113/iap/metafile/confirm?confirmationId=99ddb7fb-5dd5-401e-92a6-897198870813&customerId=33

No REQUEST PAYLOAD

Return Codes

204         Success.                                                                                                                              
PUT


/iap/devTypes/{id}

Updates an existing device type, where Id specifies the device type ID to be updated.

Path Parameter

Parameter        Type           Description                                                                                                                                  
idDeviceType

Specifies the device type ID to be updated. 

Possible value: 1-0x7fffffffffffffff

Query Parameters

customerId – query parameter representing ID of customer

Request Body 

Parameter        Type           Description                                                                                                                                  
nameString(Required) Specifies the device type name.  Case insensitive.
xifNameString

Specifies the XIF file name.

Required only for device types for LON or Modbus protocols.

xifName is not allowed for device types for IAP or BACnet protocols.

defaultAppString(Optional) Specifies the application image file name.
autoAppLoadBoolean

(Optional) Enables automatic application image loading. 

Possible values: True/False.   

Default is False.

defaultSysString(Optional) Specifies the system image file name.
autoSysLoadBoolean

(Optional) Enables automatic system image loading.

Possible values: True/False.   

Default is False.

iconNameString(Optional) Specifies the graphic file name.


Return Codes

204        Success.                                                                                                                                                              
422Error.  Includes a message describing validation failure.

Success Response

Response code 200 in case of success or some error code otherwise.

Examples

https://localhost/iap/devTypes/473?customerId=84

REQUEST BODY:
{
    "name" : "EVB Meter",
    "xifName" : "PM1006k_min.XIF",
    "programId" : "9000011503020466",
    "defaultApp" : null,
    "autoAppLoad" : false,
    "defaultSys" : null,
    "autoSysLoad" : false,
    "icon" : "EVB_Meter.png",
    "isDefault": false
}

RESPONSE:
Response code 200