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/driver. Possible values are: all (*) – for all types bacnet – for BACnet enocean – for local EnOcean mode, available with SmartServer 4.0 and higher iap – for IAP iotc – for remote EnOcean mode with IoTC, available with SmartServer 4.3 Update 1 and higher; and for remote EnOcean mode with SmartStudio, available for SmartServer 4.5 Update 1 and higher lon – for LON lorawan – for LoRaWAN, available with SmartServer 4.0 and higher modbus – for 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 – for BACnet enocean – for local EnOcean mode, available with SmartServer 4.0 and higher iap – for IAP iotc – for remote EnOcean mode with IoTC, available with SmartServer 4.3 Update 1 and higher; and for remote EnOcean mode with SmartStudio, available for SmartServer 4.5 Update 1 and higher lon – for LON lorawan – for LoRaWAN, available with SmartServer 4.0 and higher modbus – for 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 – for BACnet
enocean – for local EnOcean mode, available with SmartServer 4.0 and higher
iap – for IAP
iotc – for remote EnOcean mode with IoTC, available with SmartServer 4.3 Update 1 and higher; and for remote EnOcean mode with SmartStudio, available for SmartServer 4.5 Update 1 and higher
lon – for LON
lorawan – for LoRaWAN, available with SmartServer 4.0 and higher
modbus – for 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