SM/UDP Request Connect

Remote Manager can be used to send a SM/UDP “request connect” message to a Remote Manager-registered device which will cause it to connect back to the server using the device-initiated connection method over TCP/IP. Once it is connected, web services requests and UI actions can be made to the device. With this support, devices no longer need to maintain a Remote Manager connection at all times. Connections instead can be established dynamically.

This section describes the web services actions to accomplish this. All of these actions can be performed in the Remote Manager UI as well.

Configure Device to Receive SM/UDP Commands

The following example will configure a Remote Manager-registered device to enable SM/UDP.

POST to /ws/DeviceCore to provision a device with SM/UDP enabled.

<DeviceCore> 
  <devMac>00:40:9D:00:00:00</devMac> 
  <dpUdpSmEnabled>true</dpUdpSmEnabled>
</DeviceCore>

The device will be added to your account and configured to enable SM/UDP.

If you want to disable SM/UDP for a device, use the following example.

PUT to /ws/DeviceCore to update the device and disable SM/UDP.

<DeviceCore> 
  <devConnectwareId>00000000-00000000-00409DFF-FF000000</devConnectwareId>
  <dpUdpSmEnabled>false</dpUdpSmEnabled>
</DeviceCore>

After sending this request the device will no longer be configured for SM/UDP.

Message Compression

<dpSmCompressionAvailable>true/false</dpSmCompressionAvailable>

This configures the server to allow compression to be used for SM requests. Defaults to false, but can be inferred by a device sending a compressed request.

Pack Command

<dpSmPackAvailable>true/false</dpSmPackAvailable>

This configures the server to allow pack commands to be sent to the device. The pack command allows multiple SM commands to be merged and sent in a single datagram to reduce data usage and overhead. Defaults to false, but can be inferred by a device sending a pack command.

Battery Operated Mode

<dpSmBatteryOperated>true/false</dpSmBatteryOperated>

This configures the server to send requests to the device in battery operated mode. Battery operated mode can be used for devices that should only recieve a single reply to a request sent to the server, where it was indicated that the device needed a response. This tells the device that it can immediately shut down its network connection to conserve power. This mode implies that the device also supports the pack command. Unless the device requires this mode, it may add unnecessary limitations. Defaults to false.

Send SM/UDP Request Connect

To send a connect request to a device via SM/UDP, POST the following SCI request to /ws/sci:

<sci_request version="1.0"> 
  <!-- It is suggested SM/UDP requests be done asynchronously as they can
  take a while and requests done synchronously may time out before the
  response has been received.  See the Check Request Status Example
  for information on retrieving status and results. -->
  <send_message synchronous="false"> 
    <targets> 
      <device id="00000000-00000000-00000000-00000000"/> 
    </targets>
    <sm_udp>
      <request_connect/>
    </sm_udp>
  </send_message>
</sci_request>

Details: SCI is used to send SM/UDP requests to Remote Manager-registered devices. The behavior is very similar to RCI processing.

As in RCI, web services requests result in jobs being created in Remote Manager. These jobs can be synchronous or asynchronous and job results are retrieved the same way they are for RCI jobs.

Digi recommends you execute SM/UDP requests asynchronously. Synchronous requests may time out before the response has been received.

The <send_message> command will be used, <send_message> options have the following effect with SM/UDP:

  • synchronous=“true|false”

“true” results in a synchronous request; “false” for asynchronous.

SM/UDP requests are specified by the tag <sm_udp> as a child element of <send_message>.

<request_connect>, requests a device to connect using EDP (reconnects if already connected).

  • request_connect takes no parameters

Wait for Device to Connect

The connection status of any Remote Manager-registered device may be found by performing a GET on /ws/DeviceCore.

The result has an entry for each Device Cloud-registered device. In that entry, the element dpConnectionStatus is 0 if the device is disconnected and 1 if connected:

<dpConnectionStatus>0</dpConnectionStatus>

Note: A GET on /ws/DeviceCore returns a list of all Device Cloud-registered devices. To retrieve status for a single device, issue a GET on /ws/DeviceCore/{id} where id is the id associated with a particular device.

Send a Disconnect

Once work is complete to a device, a web services client may optionally disconnect the registered device from Device Cloud:

POST /ws/sci

<sci_request version="1.0">
   <disconnect>
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
   </disconnect>
</sci_request>