Sms Messages

There are two types of SMS data:

  • Data: Data SMS messages are sent from the device using the python function idigisms_send() and the messages are stored in FileData (see FileData).Data from the device is stored as a file in storage:
    • Python programs specify the data contents and optionally the file name, called the path in idigisms_send().
    • If a path is not specified, the file is stored with the name SmsUnnamed. If the fdArchive option is true, the file is archived.
  • DIA data: Remote Manager parses DIA (Device Integration Application) messages and adds the parsed messages to the DIA data specific storage or as a file in generic storage depending on whether the device has a DIA Data Management service subscription (see DIA (device integration application).

© 2023 Digi International Inc. All rights reserved.

Sending Sms Messages

Remote Manager sends SMS requests to registered devices using the SCI (Server Command Interface) web service, and the messages are handled in a manner similar to RCI (Remote Command Interface) messages.

To send an SMS message using the Remote Manager SCI web service, specify the message as a child of the of the SCI <send_message> operation using the tag as a child element. Remote Manager creates a job for each web services request, and the job can be synchronous or asynchronous. You can retrieve Remote Manager job results the same way as you retrieve results for RCI jobs.

Send message options and SMS messages

Use the following <send_message> options to control how Remote Manager handles SMS message requests:

  • 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. Using this option, you can control the number of Remote Manager SMS messages directly sent. The default is none. Note that all and errors work the same way for all SCI requests, including SMS message requests.
  • cache = “true | false | only” Remote Manager does not currently service SMS requests from the cache. Therefore, specifying only returns an error. In addition, true or false result in the request being sent to the device. The default is false.

© 2023 Digi International Inc. All rights reserved.

SMS Command XML Child Elements

The XML child elements for an SMS command.

Command Description
ping Ping the device via SMS to determine whether device can receive SMS messages. No parameters.
provision Configure the device with the Remote Manager server telephone number and optionally the service ID. The restrict sender flag must be off in the device for this command. No parameters.
raw Send raw SMS message from the device with no modification from Remote Manager. This is useful in cases when customers wish to use every byte of the SMS message (Remote Manager protocol takes approximately 5 bytes per message of overhead) or when using a device that doesn’t have Remote Manager protocol support but does have SMS support. SMS raw messages can be a maximum of 160 characters. The supported characters are dependent on your carrier, but are character only (not binary). They are not guaranteed to be delivered, may be delivered more than once, and are not guaranteed to be correct (they are subject to corruption).
reboot Reboot the device immediately. No parameters.
request_connect Request a Remote Manager data connection. If a connection has already been made, forces a reconnect of the management session. No parameters.
command Send a command. Options include: maxResponseSize=’’’’’ Set maximum size of the response. If the response is larger than the maxResponseSize, the response is truncated. The value is the number of SMS messages that make up the response. 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 parameter is omitted, the message is delivered to the listener on the device that is registered to the null path.
dia Send a DIA command to the running DIA instance. The format of this request is documented in the DIA SMS presentation documentation.
Optional attribute for the above commands format=“base64|text” Set the encoding of the request to Base64 or text: use base64 for Base64 encoding; use text for plain text. The default format is text. All subcommands (cli, user_msg, and so on) support the format=“base64|text” attribute. If the server detects characters that will cause the response to be invalid XML, it encodes the response in Base64 and indicates this with the format=“base64” attribute. That is, even if a request uses format=“text”, the reply may have format=“base64” set.

© 2023 Digi International Inc. All rights reserved.

Using SMS Command to Send a Request Connect

You can use Remote Manager to send an SMS request connect message to a Remote Manager-registered device to cause the device to connect back to the server using the device-initiated connection method over TCP/IP. Once the device is connected, you can initiate web services requests and Remote Manager UI actions for the device. In this way, devices do not need to maintain a Remote Manager connection at all times. Instead, connections can be established dynamically as needed.

© 2023 Digi International Inc. All rights reserved.

Provision Sms

To use SMS with a device, Remote Manager needs the telephone number of the device. Typically, when a registered device connects for the first time, the telephone number is read from the device and automatically provisioned. However, there are cases where auto-provisioning does not occur. For example, a device connects for the first time and cellular is not yet configured or a device is provisioned before connecting to Remote Manager. In these cases, you must manually provision the device with the telephone number.

To provision the telephone number for a Remote Manager-registered device, the telephone number must be added to an entry in the NetworkInterface that represents a SIM installed on the device. To provision a device, follow these general steps:

Step1: Retrieve the telephone number from a device

Step 2: Find the NetworkInterface record for the device

Step 3: Update NetworkInterface record

Step 4: Configure phone number without an existing NetworkInterface record

© 2023 Digi International Inc. All rights reserved.

Step 1: Retrieve the Phone Number from a Device

You can retrieve the telephone number of the device using the following RCI request. The sample response contains the telephone number of the device (phnum):

<rci_request version="1.1">
    <query_state>
       <mobile_stats />
    </query_state>
</rci_request>
<rci_reply version="1.1">
    <query_state>
       <mobile_stats>
          <mobile_version>1.1</mobile_version>
          <modemtype>GSM</modemtype>
          <rssi>-42</rssi>
          <quality max="5">5</quality>
          <g3rssi>0</g3rssi>
          <g3quality max="5">0</g3quality>
          <rstat code="1">Registered (Home Network)</rstat>
          <cid>34016</cid>
          <lac>32004</lac>
          <imsi>310410316937398</imsi>
          <iccid>89014104243169373988</iccid>
          <phnum>19522213895</phnum>    <!-- phone number of the device -->
          <manuf>SIEMENS</manuf>
          <model>TC63</model>
          <sn>355633002498656</sn>
          <rev>REVISION 02.000</rev>
          <varinfo index="1">
             <desc>Network Name</desc>
             <data>N/A</data>
          </varinfo>
          <varinfo index="2">
             <desc>(E)GPRS Status</desc>
             <data>GPRS Attached</data>
          </varinfo>
          <varinfo index="3">
             <desc>Current Band</desc>
             <data>850 MHz, 1900 MHz</data>
          </varinfo>
          <varinfo index="4">
             <desc>User Band Selection</desc>
             <data>Automatic</data>
          </varinfo>
          <varinfo index="5">
             <desc>Mobile Channel</desc>
             <data>235</data>
          </varinfo>
          <varinfo index="6">
             <desc>Mobile Country Code</desc>
             <data>310</data>
          </varinfo>
          <varinfo index="7">
             <desc>Mobile Network Code</desc>
             <data>410</data>
          </varinfo>
          <varinfo index="8">
             <desc>User Carrier Selection</desc>
             <data>Automatic</data>
          </varinfo>
          <varinfo index="9">
             <desc>PLMN Color</desc>
             <data>3</data>
          </varinfo>
          <varinfo index="10">
             <desc>Base Station Color</desc>
             96
             <data>5</data>
          </varinfo>
          <varinfo index="11">
             <desc>Max Power RACH</desc>
             <data>0</data>
          </varinfo>
          <varinfo index="12">
             <desc>Min Rx Level</desc>
             <data>-111</data>
          </varinfo>
          <varinfo index="13">
             <desc>Base Coefficient</desc>
             <data>68</data>
          </varinfo>
          <varinfo index="14">
             <desc>SIM Status</desc>
             <data>5: SIM Initialization Complete</data>
          </varinfo>
          <varinfo index="15">
             <desc>SIM PIN Status</desc>
             <data>Ready</data>
          </varinfo>
          <stats_index>5</stats_index>
          <multi_sim_enabled>no</multi_sim_enabled>
       </mobile_stats>
    </query_state>
</rci_reply>

© 2023 Digi International Inc. All rights reserved.

Step 2: find the NetworkInterface Record for the Device

The information within this step only applies to configurations that have an existing entry in NetworkInterface record to update. If you perform the GET below and determine that your configuration does not have a niId value, skip this step and proceed to step 4.

To find the NetworkInterface record to update for your Remote Manager-registered device, perform a GET similar to the following:

GET /ws/DeviceInterface/?condition=devConnectwareId='00000000-00000000-00409DFF-FF2EB94D'

Replace ‘00000000-00000000-00409DFF-FF2EB94D’ with the device ID of your device.

Here is a sample reply:

<result>
   <resultTotalRows>3</resultTotalRows>
   <requestedStartRow>0</requestedStartRow>
   <resultSize>1</resultSize>
   <requestedSize>1000</requestedSize>
   <remainingSize>0</remainingSize>
   <DeviceInterface>
      <id>
         <devId>6</devId>
         <devVersion>0</devVersion>
         <niId>26</niId>
         <niVersion>0</niVersion>
      </id>
      <devRecordStartDate>2011-01-13T18:22:00Z</devRecordStartDate>
      <devMac>00:40:9D:2E:B9:4D</devMac>
      <devCellularModemId>355633002498656</devCellularModemId>
      <devConnectwareId>00000000-00000000-00409DFF-FF2EB94D</devConnectwareId>
      <cstId>10</cstId>
      <grpId>10</grpId>
      <devEffectiveStartDate>2011-01-05T21:37:00Z</devEffectiveStartDate>
      <devTerminated>false</devTerminated>
      <niRecordStartDate>2011-02-15T21:45:00Z</niRecordStartDate>
      <niInterfaceType>0</niInterfaceType>
      <niEffectiveStartDate>2011-02-15T20:25:00Z</niEffectiveStartDate>
      <niTerminated>false</niTerminated>
      <niPhone>N/A</niPhone>
      <niActivePhone>false</niActivePhone>
      <niIdigiPhone>12029823370</niIdigiPhone>
   </DeviceInterface>
</result>

Within the result, find the nild of the NetworkInterface record to be updated. In the above example, the nild is 26. Use the niId to retrieve the NetworkInterface record:

/ws/NetworkInterface/26/0 (replace with your device's niId, 0 means most recent version) 
<result>
   <resultTotalRows>1</resultTotalRows>
   <requestedStartRow>0</requestedStartRow>
   <resultSize>1</resultSize>
   <requestedSize>1000</requestedSize>
   <remainingSize>0</remainingSize>
   <NetworkInterface>
      <id>
         <niId>26</niId>
         <niVersion>0</niVersion>
      </id>
      <niRecordStartDate>2011-02-15T21:45:00Z</niRecordStartDate>
      <devId>6</devId>
      <devVersion>0</devVersion>
      <niInterfaceType>0</niInterfaceType>
      <cstId>10</cstId>
      <grpId>10</grpId>
      <niEffectiveStartDate>2011-02-15T20:25:00Z</niEffectiveStartDate>
      <niTerminated>false</niTerminated>
      <niPhone>N/A</niPhone>
      <niPhoneCarrier>3</niPhoneCarrier>
      <niActivePhone>false</niActivePhone>
      <niIdigiPhone>12029823370</niIdigiPhone>
      <niIdigiServiceId></niIdigiServiceId>
   </NetworkInterface>
</result>

© 2023 Digi International Inc. All rights reserved.

Step 3: Update Networkinterface Record

To update the NetworkInterface record with the device Modem ID, copy the contents of from the GET above. Update the niPhone tag with the phone number you discovered in Step1: Retrieve the telephone number from a device (replace N/A with your device phone number). Change the status of niActivePhone and then remove the id tag.

The values added below are: niActivePhone: true (to indicate this is the active Remote Manager SMS record. There can be more than one NetworkInterface record per device. Only one can have niActivePhone true). niPhone: The phone number of the SIM (discovered in step 1).

PUT /ws/NetworkInterface/26

Payload:

<?xml version="1.0" encoding="UTF-8"?>
<NetworkInterface>
   <niRecordStartDate>2011-02-15T21:45:00Z</niRecordStartDate>
   <devId>6</devId>
   <devVersion>0</devVersion>
   <niInterfaceType>0</niInterfaceType>
   <cstId>10</cstId>
   <grpId>10</grpId>
   <niEffectiveStartDate>2011-02-15T20:25:00Z</niEffectiveStartDate>
   <niTerminated>false</niTerminated>
   <niPhone>19522213895</niPhone>
   <niActivePhone>true</niActivePhone>
</NetworkInterface>

© 2023 Digi International Inc. All rights reserved.

Step 4: Configure Phone Number without an Existing NetworkInterface Record

The information within this step only applies to configurations that do not have an existing entry in NetworkInterface to update (as described in step 2).

Find the the devId for your Remote Manager-registered device

Perform a GET on /ws/DeviceCore?condition=devConnectwareId=‘00000000-00000000-00409DFF-FF4A3946’ (replace with your device ID).

<?xml version="1.0" encoding="UTF-8"?>
<result>
   <resultTotalRows>1</resultTotalRows>
   <requestedStartRow>0</requestedStartRow>
   <resultSize>1</resultSize>
   <requestedSize>1000</requestedSize>
   <remainingSize>0</remainingSize>
   <DeviceCore>
      <id>
         <devId>1224</devId>  <!-- devId of the device -->
         <devVersion>28</devVersion>
      </id>
      <devRecordStartDate>2011-12-20T20:34:00.000Z</devRecordStartDate>
      <devMac>00:40:9D:4A:39:46</devMac>
      <devCellularModemId>357975020409993</devCellularModemId>
      <devConnectwareId>00000000-00000000-00409DFF-FF4A3946</devConnectwareId>
      <cstId>27</cstId>
      <grpId>27</grpId>
      <devEffectiveStartDate>2011-12-20T20:23:00.000Z</devEffectiveStartDate>
      <devTerminated>false</devTerminated>
      <dvVendorId>4261412864</dvVendorId>
      <dpDeviceType>ConnectPort X4</dpDeviceType>
      <dpFirmwareLevel>34406404</dpFirmwareLevel>
      <dpFirmwareLevelDesc>2.13.0.4</dpFirmwareLevelDesc>
      <dpRestrictedStatus>0</dpRestrictedStatus>
      <dpLastKnownIp>10.8.16.16</dpLastKnownIp>
      <dpGlobalIp>66.77.174.126</dpGlobalIp>
      <dpConnectionStatus>1</dpConnectionStatus>
      <dpLastConnectTime>2011-12-20T20:24:00.000Z</dpLastConnectTime>
      <dpContact />
      <dpDescription />
      <dpLocation />
      <dpPanId>0xd367</dpPanId>
      <xpExtAddr>00:13:A2:00:40:66:A1:B2</xpExtAddr>
      <dpServerId>ClientID[3]</dpServerId>
      <dpZigbeeCapabilities>383</dpZigbeeCapabilities>
   </DeviceCore>
</result>

Update the devId, niInterfaceType, and niPhone tags

  • Update the devId tag below with the devId number discovered in step a, devId is 1224 in the above example. Replace the devId number in the example below with your device’s devId number.
  • Ensure the the niInterfaceType value is set to 0.
  • Update the niPhone tag below with the phone number (found within the phnum tag) discovered in step 1. Replace the phone number displayed in the example below with your device’s phone number.

The values added below are: devId: The devID number of the device. niPhone: The phone number of the device (discovered in step 1). niInterfaceType: The interface type of the device (0 means most recent version).

POST /ws/NetworkInterface

<NetworkInterface>
   <devId>1224</devId>
   <niInterfaceType>0</niInterfaceType>
   <niTerminated>false</niTerminated>
   <niPhone>19522213895</niPhone>
</NetworkInterface>

Configure Device to Receive SMS Commands

The following example RCI request will configure a device to enable SMS, configure SMS, disable client initiated Remote Manager connections, and configure paged Remote Manager connections. See below for an explanation of the parameters.

RCI request:

<rci_request version="1.1">
   <set_setting>
      <smscell>
         <state>on</state>
      </smscell>
      <idigisms>
         <state>on</state>
         <restrict_sender>on</restrict_sender>
         <phnum>12029823370</phnum>
         <service_identifier></service_identifier>
      </idigisms>
      <mgmtconnection index="1">
         <connectionType>client</connectionType>
         <connectionEnabled>off</connectionEnabled>
      </mgmtconnection>
      <mgmtconnection index="4">
         <connectionType>paged</connectionType>
         <connectionEnabled>on</connectionEnabled>
         <pagedConnectionOverrideEnabled>on</pagedConnectionOverrideEnabled>
         <serverArray index="1">
            <serverAddress>en://login.remotemanager.digi.com</serverAddress>
         </serverArray>
      </mgmtconnection>
      <mgmtglobal>
         <connIdleTimeout>2220</connIdleTimeout>
      </mgmtglobal>
      <mgmtnetwork index="1">
         <networkType>modemPPP</networkType>
         <connectMethod>mt</connectMethod>
         <mtRxKeepAlive>3000</mtRxKeepAlive>
         <mtTxKeepAlive>3000</mtTxKeepAlive>
         <mtWaitCount>3</mtWaitCount>
      </mgmtnetwork>
   </set_setting>
</rci_request>

RCI for SMS

RCI group: idigisms

Field Options Description
state on, off Remote Manager SMS support enabled or disabled. If off, SMS messages will not be processed.
phnum number The phone number that the device will use to send messages to Remote Manager. This needs to be obtained from Digi (each cluster has its own phone number).
service_identifier string An ID that when combined with the phone number forms the complete address of Remote Manager server. This needs to be obtained from Digi (each cluster has its own phone number).
restrict_sender on, off If on, only Remote Manager SMS messages originating from “phnum” and with the service ID “service_identifier” will be honored as Remote Manager SMS messages.

RCI group: smscell

Field Options Description
state on, off Enables basic SMS support for a device. This needs to be on for Remote Manager SMS to communicate.

RCI group: mgmtconnection index = “1” (client initiated Remote Manager connections)

Field Options Description
connectionEnabled on, off Enables client initiated connections. When off, the device will not attempt to keep a Remote Manager connection open.

RCI group: mgmtconnection index = “4” (paged - i.e. temporary - - Remote Manager connections)

Field Options Description
connectionEnabled on, off Enables temporary connections. A connection request results in a paged Remote Manager connection being established to the server. If this parameter is off, a connection will not be made.
pagedConnectionOverrideEnabled on, off When on, paged connections will take priority over client initiated requests so that connection requests always result in a new connection. Set to on.
serverArrayindex=“1” serverAddress url Send to the dns name of Remote Manager server in the form: en://<dns-name>.

RCI group: mgmtglobal

Field Options Description
connIdleTimeout Timeout in seconds Connection is dropped after this number of seconds of inactivity. Any traffic on the connection, including keep-alive traffic, count as non-idle for purposes of this timer.

RCI group: mgmtnetwork index = “1 “ (cellular Remote Manager connection configuration)

Field Options Description
mtRxKeepAlive Timeout in seconds Receive keep-alive timeout. Must be higher than connIdleTimeout or connIdleTimeout is defeated.
mtTxKeepAlive Timeout in seconds Transmit keep-alive timeout. Must be higher than connIdleTimeout or connIdleTimeout is defeated.
mtWaitCount Number Number of missed keep-alives before connection is considered dropped. Shown for completeness only; is not directly related to connection request behavior.

Send Remote Manager SMS Request Connect

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

<sci_request version="1.0">
   <send_message synchronous="true" syncTimeout="60" reply="all">
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
      <sms>
         <request_connect />
      </sms>
   </send_message>
</sci_request>

Details: SCI is used to send SMS requests to Remote Manager-registered devices. The behavior is very similar to RCI processing from a user’s perspective.

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.

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

  • synchronous= “true|false”

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

  • syncTimeout= “x”

Time in seconds that the operation is given to complete. Valid for synchronous jobs only.

  • reply= “all|errors|none”

“all " means return a reply SMS, “errors " means request a reply but the result of the command will only show errors, “none " means do not request a response.

This controls whether an SMS reply is sent by the device back to the server for a command. This is primarily intended to allow the SMS user to directly control the number of Remote Manager SMS messages being sent, since they are charged for each one. Note, this option is honored even when it results in less than ideal behavior. For instance, a no-reply ping is useless.

SMS requests are specified by the tag <sms> 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 Remote Manager-registered device. In that entry, the element dpConnectionStatus is 0 if the device is disconnected and 1 if connected:

<dpConnectionStatus>0</dpConnectionStatus>

A GET on /ws/DeviceCore returns a list of all Remote Manager-registered devices. To retrieve status for a single device, issue a GET on /ws/DeviceCore/{id} where the 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 Remote Manager:

POST /ws/sci

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