add

Devices that support dynamic interfaces, as indicated with the interfaceType property in the device status object, also support add and remove actions to add and remove items to and from a dynamic device interface. For information on dynamic device interfaces, see Dynamic Interfaces.

The unique ID provided with add must not already be in use.

See Add Action Properties for a description of the add properties.

Creates the device within IAP, publishes its status and configuration objects in the feedback channel and leaves the device in the unprovisioned state, unless the optional provision argument was also supplied and set to "true".  

The device’s interface objects become available in the feedback channel at some point between create and successful completion of provision. The exact time when the device’s interface becomes available depends on the circumstances, including the edge protocol, the edge processor, and the device type.

The create action produces a device object that can then be used with further actions or configured with value assignments. The exact effect of this action on the edge device depends on the edge driver.   

See Create Action Properties for a description of the create properties.

delete deprovisions the device, if possible. When a communication failure prevents the deprovisioning (for example, because the physical device has already been removed), this is not considered a failure.

delete takes no arguments.

deprovision returns a device to its unprovisioned state, similar to its state before it was first provisioned. The device is inactive in this state, until it is re-provisioned.

deprovision takes no arguments.

The join action is used to initiate procedures specific to the edge protocol. Typically, join is used to join the edge network by announcing the device’s presence in that network, or enabling the receipt of edge network-specific registration messages. For example, a locally hosted LonWorks device can use this action to issue its service message, and a Bluetooth device can become discoverable with this action.

The join action can trigger a join event.  For more information join events, see Events.

join takes no arguments.

IAP supports loading data to edge servers and edge devices.

• To load a single edge device, publish a load action object to the edge device’s do topic at:
  glp/0/{SID}/rq/dev/Edge_Protocol_ID}/{Handle}/do .

• To load multiple edge devices, publish a load action object to a group’s do topic at:
  glp/0/{SID}/rq/grp/{Handle}/do .

The group can contain devices, interface blocks, or other groups. All those targets share the same image. In the event of a firmware load, all targets must be firmware image compatible (e.g. all CPD 3000, all CLP 3000, but no mix). The edge device is responsible for detecting and reporting violation of this requirement.

For more information on loading, see Load Do Action.

(Optional) An application message consists of a message code and message data. To send a message, publish the application message object with the args argument to the device’s do topic. Once completed with success or failure, the processor publishes an application message completion object. Processors that do not support arbitrary application messages raise an error when a message action is encountered.

Messages can be unacknowledged, acknowledged, or requests. Both acknowledged and request messages support a timeout parameter and a maximum retry count. The unacknowledged message supports a repeat count.

See Message Action Properties for a description of the application message properties.

provision provisions a device. To provision a device in IAP means to do whatever it takes to get the device from its present state to a fully operational state. Successful completion leaves the device in the provisioned state.

The device’s interface must be fully reported when the device enters the provisioned state, and data about profile, datapoint and property types must be available at this time.

See Provision Action Properties for a description of the provision properties.

Devices that support dynamic interfaces, as indicated with the interfaceType property in the Device Status object, also support add and remove actions to add and remove items to and from a dynamic device interface. For information on dynamic device interfaces, see Dynamic Interfaces.

The unique ID provided with add must not already be in use.

See Remove Action Properties for a description of the remove properties.

repair is a request to return the device into the provisioned and fully operational state, even if the device is in that state already, according to the IAP. In many cases, repair will re-provision the device, but a processor can include other steps to understand the present state and rectify any issues.

Repair expects no arguments.

replace is a request to replace one physical device with another while keeping the device’s logical representation in IAP and in the edge protocol unchanged. The replacement device must implement the same interface as the device it replaces, or a superset thereof. The processor enforces this. Connections or groups continue to function as before, once the replace operation is complete.

See Replace Action Properties for a description of the replace properties.

reset is a request to reset the edge device and restart the device. reset is used as an attempt to recover from malfunction and should complete in less than 5 minutes. Persistent state and configuration must be preserved. It is not required that edge devices perform a physical reset (“warm boot”) in response to a requested reset action. The implementation of the reset action is the responsibility of edge device and edge processor, and can vary with different device types, processors, or edge protocols.

Expects no arguments.

test causes a check the device’s health and status, and updates the device’s status object in the feedback channel. test is a diagnostic tool that immediately obtains current LQI information and reachability statistics from the target device, and does not rely on cached information.  

Expects no arguments.

wink triggers a suitable and benign temporary visual or audible response from the edge device to assist a human operator to uniquely identify a specific physical device. The exact behavior is specific to the device, and detailed in the device’s product documentation. For example, a light could enter an on/off switching cycle at a 0.5 Hz rate for 5 seconds, while another device could flash a dedicated LED or sound a buzzer.

Expects no arguments.