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>