In this tutorial, you will learn how to use Restcomm Geolocation API together with Restcomm GMLC for retrieving location information from GSM networks.  

Requirements

  • Restcomm-Connect running on your local server previously configured to send HTTP messages to the desired Restcomm GMLC IP and port.

  • Restcomm GMLC running on your local server with a default port offset of 100. This is needed as either Restcomm-Connect and Restcomm GMLC are based on JBoss Application Server. This wiki explains it very well for JBoss AS. However, for restless souls, the best way to start multiple instances is passing the system property jboss.service.binding.set while you start the JBoss AS like explained in step 1 below.

  • Make sure that JBOSS_HOME is properly set for either Restcomm-Connect and Restcomm GMLC if running Open Source builds.

Step 1 - Shift default port offset for running Restcomm GMLC

For running Restcomm-Connect and Restcomm-GMLC you’ll need to configure Restcomm GMLC to use a port offset. Please proceed then in identical way as explained HERE for running Restcomm, SMSC and USSD Gateways in the same server. In this case we will setup Restcomm GMLC to run with the default port with an offset of 100. Hence,

  • Restcomm GMLC will use port 8180 to access the GUI.

  • Restcomm GMLC will use port 5160 to listen to SIP messages.

  • Restcomm GMLC will use port 3535 for the CLI shell.

Step 2 - Configure Restcomm-Connect to work along with desired Restcomm GMLC

Let’s assume your local server’s IP is 192.168.26.132. Then, edit the following Restcomm-Connect configuration file $RESTCOMM_HOME/standalone/deployments/restcomm.war/WEB-INF/conf/restcomm.xml so that the following section looks like this:

<!-- TelScale GMLC -->
		<gmlc>
			<gmlc-uri>http://192.168.26.132:8180/restcomm/gmlc/rest?msisdn=</gmlc-uri>
			<gmlc-user></gmlc-user>
			<gmlc-password></gmlc-password>
		</gmlc>

Step 3 - Run Restcomm-Connect, Restcomm GMLC in simulator mode and jSS7 simulator

  • Go to $RESTCOMM_HOME/bin/restcomm and proceed with editing the network configuration in by editing restcomm.conf file accordingly, e.g.

# Network configuration
NET_INTERFACE='eth0'
PRIVATE_IP='192.168.26.132'
SUBNET_MASK='255.255.255.0'
NETWORK='192.168.26.0'
BROADCAST_ADDRESS='192.168.26.255'
  • Initiate Restcomm-Connect by executing the BASH file like this: sudo ./start-restcomm.sh.

  • It’s recommended you verify everything is running properly with screen. If you want to follow this advice, please run the following sudo screen -r restcomm. If you ever want to stop this screen view while not stopping Restcomm-Connect, click Ctrl+A followed by Ctrl+D.

  • Run Restcomm GMLC in simulator mode, bound to the eth0 IP and with default port shifted by 100 by going to $GMLC_HOME/jboss-5.1.0.GA/bin and executing the BASH file like this: sudo ./run.sh -b 192.168.26.132 -c simulator -Djboss.service.binding.set=ports-01.

  • Go to $GMLC_HOME/tools/telscale-jss7-simulator/bin/ and run jSS7 simulator by executing the BASH file like this: sudo ./run.sh gui. For further instructions on how to operate jSS7 simulator for MAP ATI operations, please refer to the explanation detailed HERE.

Step 4 - Execute Restcomm Geolocation API location requests

  • Login to Restcomm-Connect. For this example this would happen by introducing the user credentials in http://192.168.26.132:8080. Restcomm-Connect’s dashboard will appear, then get the Account SID and Auth Token values. For this example, we will use Account SID = ACae6e420f425248d6a26948c17a9e2acf and Auth Token = f8bc1274677b173d1a1cf3b9924eaa7e values, as obtained from the image below. Please notice that these values change accordingly to your credentials (Email/Account SID and password used to sign in to Restcomm-Connect).

restcomm-rvd-smstest1

Step 4.1 - Immediate type of Geolocation requests

  • For Immediate type of Geolocation HTTP POST requests you only need two mandatory parameters: DeviceIdentifier and StatusCallback. Please refer to Restcomm Geolocation API documentation for a full description on Immediate type of Geolocation as explained HERE.

  • Assuming for the former values 59899077937 and http://52.19.10.207:8888/rcgla correspondingly, execute the following HTTP POST command:

curl -X POST -H "application/json" http://ACae6e420f425248d6a26948c17a9e2acf:f8bc1274677b173d1a1cf3b9924eaa7e@192.168.26.132:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Immediate -d "DeviceIdentifier=59899077937" -d "StatusCallback=http://52.19.10.207:8888/rcgla"

You should obtain the following XML formatted response:

<RestcommResponse>
  <Geolocation>
    <Sid>GLa6f05ba18e934c90801e10939cc117b6</Sid>
    <DateCreated>Sun, 19 Feb 2017 22:17:02 -0200</DateCreated>
    <DateUpdated>Sun, 19 Feb 2017 22:17:02 -0200</DateUpdated>
    <DateExecuted>Sun, 19 Feb 2017 22:17:02 -0200</DateExecuted>
    <AccountSid>ACae6e420f425248d6a26948c17a9e2acf</AccountSid>
    <DeviceIdentifier>59899077937</DeviceIdentifier>
    <GeolocationType>Immediate</GeolocationType>
    <GeolocationData>
      <CellId>221</CellId>
      <LocationAreaCode>32000</LocationAreaCode>
      <MobileCountryCode>250</MobileCountryCode>
      <MobileNetworkCode>1</MobileNetworkCode>
      <NetworkEntityAddress>5555555666</NetworkEntityAddress>
      <LocationAge>5</LocationAge>
    </GeolocationData>
    <ApiVersion>2012-04-24</ApiVersion>
    <Uri>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Immediate/GLa6f05ba18e934c90801e10939cc117b6</Uri>
  </Geolocation>
</RestcommResponse>

Notice that the parameters obtained under GeolocationData correspond to the ones provided by the jSS7 simulator after it received the MAP ATI request from Restcomm GMLC. These values are the same as the ones you would obtain by executing the following HTTP GET request from a Web browser directly to Restcomm GMLC: http://192.168.26.132:8180/restcomm/gmlc/rest?msisdn=59899077937 whose response would be the ones obtained from a MAP ATI request to the HLR, containing the Cell Global Identity, Age of Location and the MSC/VLR address (Global Title) the target mobile subscriber (MSISDN) is attached to according to latest location update between VLR and HLR:

mcc=250,mnc=1,lac=32000,cellid=221,aol=5,vlrNumber=5555555666

For a JSON type of response, just append .json in the HTTP POST request. Let’s see this by gathering the generated record with Sid=GLa6f05ba18e934c90801e10939cc117b6 after the former HTTP POST request by executing the following HTTP GET request:

curl -X GET -H "application/json" http://ACae6e420f425248d6a26948c17a9e2acf:f8bc1274677b173d1a1cf3b9924eaa7e@192.168.26.132:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Immediate/GLa6f05ba18e934c90801e10939cc117b6.json

You should obtain the following JSON formatted response:

{
  "sid": "GLa6f05ba18e934c90801e10939cc117b6",
  "date_created": "Sun, 19 Feb 2017 22:17:02 -0200",
  "date_updated": "Sun, 19 Feb 2017 22:17:02 -0200",
  "date_executed": "Sun, 19 Feb 2017 22:17:02 -0200",
  "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
  "device_identifier": "59899077937",
  "geolocation_type": "Immediate",
  "geolocation_data": {
    "cell_id": "221",
    "location_area_code": "32000",
    "mobile_country_code": 250,
    "mobile_network_code": "1",
    "network_entity_address": 5555555666,
    "location_age": 5
  },
  "api_version": "2012-04-24",
  "uri": "/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Immediate/GLa6f05ba18e934c90801e10939cc117b6.json"
}

Step 4.2 - Notification type of Geolocation requests

  • For Notification type of Geolocation HTTP POST requests you need more mandatory parameters, i.e. DeviceIdentifier and StatusCallback as in Immediate type, plus EventGeofenceLatitude, EventGeofenceLongitude, GeofenceRange and GeofenceEvent. Please refer to Restcomm Geolocation API documentation for a full description on Notification type of Geolocation as explained HERE.

  • Assuming for the former values 59827098828 and http://162.19.10.207:8988/rcgla/Fer, -33.426280, 101.566567, 500 and in correspondingly, execute the following HTTP POST command:

curl -X POST -H "application/json" http://ACae6e420f425248d6a26948c17a9e2acf:f8bc1274677b173d1a1cf3b9924eaa7e@192.168.26.132:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Notification.json -d "DeviceIdentifier=59827098828" -d "EventGeofenceLatitude=-33.426280" -d "EventGeofenceLongitude=101.566567" -d "GeofenceRange=500" -d "GeofenceEvent=in" -d "StatusCallback=http://162.19.10.207:8988/rcgla/Fer"

You should obtain the following JSON formatted response:

{
  "sid": "GL7aef69951fee4ae2b1c8988473d5e7b0",
  "date_created": "Sun, 19 Feb 2017 22:43:03 -0200",
  "date_updated": "Sun, 19 Feb 2017 22:43:03 -0200",
  "date_executed": "Sun, 19 Feb 2017 22:43:03 -0200",
  "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
  "device_identifier": "59827098828",
  "geolocation_type": "Notification",
  "geolocation_data": {
    "cell_id": "221",
    "location_area_code": "32000",
    "mobile_country_code": 250,
    "mobile_network_code": "1",
    "network_entity_address": 5555555666,
    "location_age": 5,
    "event_geofence_latitude": "-33.426280",
    "event_geofence_longitude": "101.566567"
  },
  "api_version": "2012-04-24",
  "uri": "/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Notification/GL7aef69951fee4ae2b1c8988473d5e7b0.json"
}

Let’s gather the generated record with Sid=GL7aef69951fee4ae2b1c8988473d5e7b0 in XML format after the former HTTP POST request by executing the following HTTP GET request:

curl -X GET http://ACae6e420f425248d6a26948c17a9e2acf:f8bc1274677b173d1a1cf3b9924eaa7e@192.168.26.132:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Notification/GL7aef69951fee4ae2b1c8988473d5e7b0
<RestcommResponse>
  <Geolocation>
    <Sid>GL7aef69951fee4ae2b1c8988473d5e7b0</Sid>
    <DateCreated>Sun, 19 Feb 2017 22:43:03 -0200</DateCreated>
    <DateUpdated>Sun, 19 Feb 2017 22:43:03 -0200</DateUpdated>
    <DateExecuted>Sun, 19 Feb 2017 22:43:03 -0200</DateExecuted>
    <AccountSid>ACae6e420f425248d6a26948c17a9e2acf</AccountSid>
    <DeviceIdentifier>59827098828</DeviceIdentifier>
    <GeolocationType>Notification</GeolocationType>
    <GeolocationData>
      <CellId>221</CellId>
      <LocationAreaCode>32000</LocationAreaCode>
      <MobileCountryCode>250</MobileCountryCode>
      <MobileNetworkCode>1</MobileNetworkCode>
      <NetworkEntityAddress>5555555666</NetworkEntityAddress>
      <LocationAge>5</LocationAge>
      <EventGeofenceLatitude>-33.426280</EventGeofenceLatitude>
      <EventGeofenceLongitude>101.566567</EventGeofenceLongitude>
    </GeolocationData>
    <ApiVersion>2012-04-24</ApiVersion>
    <Uri>/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Geolocation/Notification/GL7aef69951fee4ae2b1c8988473d5e7b0</Uri>
  </Geolocation>
<RestcommResponse>

Again, the parameters obtained the parameters obtained under GeolocationData correspond to the ones provided by the jSS7 simulator after it received the MAP ATI request from Restcomm GMLC, i.e. Cell Global Identity, Age of Location and the MSC/VLR address (Global Title) the target mobile subscriber (MSISDN) is attached to, plus the geographic coordinates set for the geofence. Keep in mind that for Notification type of Geolocation, a MAP ATI operation is useless. Further generation location procedures either for MAP operations or Diameter requests for LTE networks would be needed for this (which will be explained in further tutorials and as already detailed in Restcomm Geolocation API documentation and Restcomm GMLC Admin Guide). Anyway, notice that Notification type of Geolocation is already available as per the examples described above.