Device Types

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.  

type

For ProgramID

programId

the same Program ID value

protocol

Specifies the protocol.  Possible values are:

  • All (*)

  • BACnet

  • EnOcean

  • IAP

  • IoTC

  • LON

  • LoRaWAN

  • Modbus

xifName

Name of the XIF file.

filename

name of the file associated with device type

isDefault

specifies whether device type is the default one

scId

segment controller id

scName

segment controller name

Query Parameters

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

Parameter        

Description               

customerId

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

sortOrder

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

sortBy

Specifies the name of a parameter.  Either:  typeName, type, protocol, or xifName.
Default is typeName.

short

if false, number of devices that use device type and xif file names will be provided in output, true by default

pg

Specifies the page number (1-0x7fffffff).
Default is null.

sz

Specifies the page size (1-0x7fffffff).

Default is null.

Return Codes

200         

Success.                                                                                                                                                       

422

Error.  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.

userName

Specifies 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).  

icon

Returns device icon files.

sys

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

xif

Returns 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. 

Example

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

Parameter        

Type           

Description                                                                                                                                  

protocol

String

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

Possible values:  

  • bacnet

  • enocean

  • iap

  • iotc

  • lon

  • lorawan

  • modbus

Default: null

programId

String

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

Valid values: a hexidecimal string

No default value.    

sortOrder

String

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

Default: asc

sortBy

String

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

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

Default: typeName

pg

Integer

(Optional) Specifies the page number. 

Possible values: 1 - 0x7fffffff

Default: null

sz

Integer

(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,90000115

POST

 

 

 

 

 

 

 

/iap/devTypes

Creates a new device type (CreateDevicyTypeDTO).

Payload Parameters

Parameter        

Type           

Description                                                     

name

String

(Required) Specifies the device type name.  Case insensitive.

protocol

String

(Required) Specifies the protocol name.  Possible values:

  • bacnet

  • enocean

  • iap

  • iotc

  • lon

  • lorawan

  • modbus

xifName

String

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.

programId

String

(Optional) Specifies the device type program ID.

Valid values: a hexidecimal string

defaultApp

String

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

autoAppLoad

Boolean

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

Possible values: True/False.   

Default is False.

defaultSys

String

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

autoSysLoad

Boolean

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

Possible values: True/False.   

Default is False.

iconName

String

(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.                                                                                                      

422

Error.  Includes an error message describing any validation failure.

Success Response

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

Examples

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.                                                                                                                                                              

422

Error.  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                                                 

packaged

Boolean

(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

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).  

icon

Files to import are device icon files.

sys

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

xif

Files 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                                                    

protocol

String

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

Possible values:  

  • bacnet

  • enocean

  • iap

  • lon

  • lorawan

  • modbus

customerID

String

(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--

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

Response { "confirmationId":"99ddb7fb-5dd5-401e-92a6-897198870813", "importInfo":{ "totalDeviceTypes":1, "newDeviceTypes":0, "updatedDeviceTypes":1, "updatedDevices":1 }, "validFor":600000, "importType":"REPLACE_PROTOCOL" }
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                                                      

id

DeviceType

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                                                     

name

String

(Required) Specifies the device type name.  Case insensitive.

xifName

String

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.

defaultApp

String

(Optional) Specifies the application image file name.

autoAppLoad

Boolean

(Optional) Enables automatic application image loading. 

Possible values: True/False.   

Default is False.

defaultSys

String

(Optional) Specifies the system image file name.

autoSysLoad

Boolean

(Optional) Enables automatic system image loading.

Possible values: True/False.   

Default is False.

iconName

String

(Optional) Specifies the graphic file name.

Return Codes

204        

Success.                                                                                                                                                              

422

Error.  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

 

 

 

 

 

Related content