Echelon i.LON SmartServer 2.0 User Manual
Page 227
i.LON SmartServer 2.0 Programmer’s Reference
14-27
To issue a network management command, you need to provide one or more <Item> elements with a
LON_Device_Cfg type. Each <Item> element needs to include the <UCPTname>, <UCPThandle>,
<UCPTuniqueId>, and <UCPTprogramId> properties of the device upon which network management
commands are to be issued. In addition, you should provide any other properties whose values are to
be preserved (if you do not provide a property, the current value stored in it is erased). Particularly,
you should provide the <UCPTcommissionStatus and <UCPTapplicationStatus> properties when
appropriate; otherwise, the device may be decommissioned and set offline. Specific network
management commands require additional properties as described in the following sections that
describe how to use each command.
Note: Section 21.1.5, Commissioning External Devices in Visual Basic.NET, includes a C#
programming example demonstrating how to issue network management commands in the L
ON
W
ORKS
Device SOAP interface in order to commission unconfigured external L
ON
W
ORKS
devices. Section
21.2.5, Commissioning External Devices in Visual Basic.NET, includes a Visual Basic example
demonstrating how to do this.
ChangeApplicationStatus
You can use this command to set the device application online or offline. This command requires the
desired <UCPTapplicationStatus> property, which may be APP_RUNNING (online) or
APP_STOPPED (offline).
If you are setting a device application offline, you should still provide the <UCPTcommissionStatus>
property and set it to COMMISSIONED; otherwise, the commission status will be changed to
COMSTATE_NUL (never reached) and the device is decommissioned. The following example
demonstrates how to set a device application offline.
<Set xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem>
<Item
xsi:type="LON_Device_Cfg">
<UCPTname>Net/LON/DIO-1</UCPTname>
<UCPThandle>5</UCPThandle>
<UCPTuniqueId>00a145791500</UCPTuniqueId>
<UCPTprogramId>80000105288a0403</UCPTprogramId>
<UCPTcommissionStatus
LonFormat="UCPTcommissionStatus">COMMISSIONED</UCPTcommissionStatus>
<UCPTapplicationStatus>APP_STOPPED</UCPTapplicationStatus>
<Command>
<UCPTcommand>ChangeApplicationStatus</UCPTcommand>
<UCPTstatus
LonFormat="UCPTstatus">STATUS_REQUEST</UCPTstatus>
</Command>
</Item>
</iLonItem>
</Set>
ChangeCommissionStatus
You can use this command to commission or decommission a device. If you are commissioning a
device, you should also set the device application online using the ChangeApplicationStatus command.
If you are decommissioning a device, you need to provide the <UCPTcommissionStatus> property and
set it to DECOMMISSIONED. The following example demonstrates how to commission a device and
set the device application online.
<Set xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem>
<Item
xsi:type="LON_Device_Cfg">
<UCPTname>Net/LON/DIO-1</UCPTname>
<UCPThandle>5</UCPThandle>
<UCPTuniqueId>00a145791500</UCPTuniqueId>
<UCPTprogramId>80000105288a0403</UCPTprogramId>
<UCPTapplicationStatus>APP_RUNNING</UCPTapplicationStatus>
<UCPTcommissionStatus
LonFormat="UCPTcommissionStatus">COMMISSIONED</UCPTcommissionStatus>
<Command>
<UCPTcommand>ChangeApplicationStatus</UCPTcommand>
<UCPTstatus
LonFormat="UCPTstatus">STATUS_REQUEST</UCPTstatus>
</Command>
<Command>
<UCPTcommand>ChangeCommissionStatus</UCPTcommand>