glp/0/{SID}/(rq|fb)/dev/do

Method invocation for complex and often time-consuming tasks. Action assignment is accepted in the request channel, but action objects are not directly reflected in the feedback channel. Success of the action is indicated by the action result. For example, the provision() action causes the device state to change to "provisioned" once the action completes with success.

Multiple actions can be triggered in rapid succession. The processor queues the actions and executes them in the order received, or executes them in parallel, where this is possible. Tools write to the action object to the request channel. Feedback is provided with the device’s status object through the feedback channel, and with error or warning diagnostics in the event channel if necessary.

Note: Not all IAP/MQ objects support actions. In general only the top-level objects do: devices, groups, jobs and so on. Device interface blocks or datapoints within interface blocks do not support direct action, but may be affected by actions executed on the device that “hosts” these blocks and datapoints.

Example

{
action: "add",
args: {
...
}
}

Device Do Action

The device’s action object, Do, is used to invoke operations with the properties listed in the following table.

Field Name	Type	Description

Field Name

Type

Description

action

string

(Required) The name of the command or method to execute. IAP supports the following device Do actions:

Do Action	Description
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.
create	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	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	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.
join	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.
load	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.
message	(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	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.
remove	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	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	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	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	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	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.

args

object

An object with arguments subject to the chosen action.

DEVICE INFORMATION:
name = "Sensor1"
protocol = lon
device type = 6kEvbMultiSensor
handle = 2   // From Handle Allocation, created devices will use 2.1, 2.2 and so on

CREATE:

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"create",
    "args": {
       "unid":"256",
       "type":"6kEvbMultiSensor"
    }  
}'

CHANGE CONFIGURATION: change device name

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/cfg -m '{
    "name":"Sensor1",
    "Loc": {
       "desc":"",
       "lat":"37.3847",
       "lng":"-121.9847"
       "ele":"null"
    }  
}'

CHECK LICENSE: 

mosquitto_sub -t -v glp/0/17q2d9v/rq/dev/lon/2.2/lic
Response:
{
    "licensed":true
}

PROVISION: Wait for device to be licensed before trying to provision a device

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"provision"
     
}'

DEPROVISION:

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"deprovision"
     
}'

WINK:(we don't support this for IOX)
mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"wink"
     
}'

DEVICE TEST:(we don't support this for IOX)
mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"test"
     
}'

DELETE:(we don't support this for IOX)
mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"delete"
     
}'