SM/UDP

The SM/UDP (Short Message/User Datagram Protocol) feature allows devices to leverage the very small data footprint of Remote Manager SM protocol (currently used for SMS) over UDP. However, it is important to note that SM/UDP requests vary greatly from SMS as SM/UDP requests are not immediately sent to a device. Instead, requests of this type are queued as devices may not be publicly addressable. This creates a way for devices to interact with Remote Manager in a way that is efficient from a data perspective and does not require a persistent connection. This feature enables devices with constrained data plans to keep data traffic to an absolute minimum by only occasionally sending data readings to Remote Manager.

Initially, no requests are queued in the server. A device will send a request to the server and the server will process the request, sending a reply to the device only if the device specified that one should be sent in the request.

At some point an SM/UDP request may be targeted for the device. This request can be sent via a Web Services request, using the options within the Actions Menu of the Devices page, or as the result of an automation. When a device sends an SM/UDP request (known as a datagram) to Remote Manager, Remote Manager will process the request and queue it for delivery to the device. The next time the device sends a message (regardless of whether a reply was specified), Remote Manager will check for queued messages and send them down to the device.

For example, if you send the SM/UDP Reboot request to your device, the device will not reboot immediately. Instead, the SM/UDP Reboot request will be queued for the device. The next time an SM/UDP request is sent to the device, Remote Manager will check for queued messages and send the queued SM/UDP Reboot request to the device instructing it to reboot itself. Once a request is queued for a device, it may remain queued for multiple days. Once the request is actually sent to a device, it typically has a timeout of 60 seconds (plus a small window in some circumstances).

Sending and Receiving SM/UDP messages

Remote Manager sends SM/UDP requests to Remote Manager-registered devices via SCI. SM/UDP requests are handled in a similar manner to RCI messages. They are specified as a child of the <send_message> command. As in RCI, web services requests cause Remote Manager to create jobs. These jobs can be synchronous or asynchronous and job results are retrieved the same way they are for RCI jobs.

It is suggested that SM/UDP requests be done asynchronously since requests of this type require the device to send a message before a server message can be sent, and therefore can potentially take a long time to complete. Synchronous requests are acceptable in situations where the device is frequently sending messages to the server.

send_message options have the following effect with SM/UDP:

synchTimeout=“xxx” Behavior is identical to existing SCI requests.
reply=“all|errors|none” Controls whether a reply is sent by the device back to the server for a command. This is primarily intended to allow you to control the number of SM/UDP messages being sent directly. The default is “none”. Note that “all” and “errors” continue to work as they do currently in other SCI requests.
cache=“true|false|only” Remote Manager does not currently service SM/UDP requests from the cache. Therefore, specifying “only” will return an error. In addition, “true” or “false” will result in the request being sent to the device. The default is “false”.

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

SM/UDP Command XML Child Elements

The following xml elements can be children of an SM/UDP command

Command	Description
ping	Request to determine whether device is able to receive SM/UDP requests - No parameters
reboot	Reboot device immediately - No parameters
request_connect	Request a Remote Manager data connection. If a connection has already been made, this will force a reconnect of the management session. - No parameters
command	Command line interface request maxResponseSize=’’’’’ Set maximum size of the response. If the response is larger than this value, it will be truncated. The value is the number of SM/UDP messages into which the response is broken. This is an optional parameter. If not specified, the size of the response is determined by the device.
user_msg	Send a message to a registered listener in python. This command is similar to the RCI do_command custom target command. path=’’’’’ Send requests to a specific listener. If this optional command is omitted, the message is delivered to the listener on the device that is registered to the null path.
Optional attribute for the above commands	format=“base64\|text” Set the encoding of the request to Base64 or text. Using “base64” indicates Base64 encoding, and “text” means the request is in plain text. The default for format is text. All subcommands (cli, user_msg, etc.) support the format=“base64\|text” attribute.Note If the server detects characters that will cause the response to be invalid XML, it will encode the response in Base64 and indicate this with the format=“base64” attribute. That is, even if a request uses format=“text”, the reply may have format=“base64” set.

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>