Add new GSMLocation API and example

Author: sandeepmistry

.travis.yml

@@ -27,6 +27,7 @@ script:
   - buildExampleSketch GPRSPing
   - buildExampleSketch GsmSSLWebClient
   - buildExampleSketch GPRSUdpNtpClient
+  - buildExampleSketch GsmLocation
   - buildExampleToolsSketch BandManagement
   - buildExampleToolsSketch GsmScanNetworks
   - buildExampleToolsSketch PinManagement

examples/GsmLocation/GsmLocation.ino

@@ -0,0 +1,89 @@
+/*
+  Location
+
+  This sketch uses the celluar network to determine the location of a MKR GSM 1400 board
+  and prints it to the Serial monitor. The location is  based on the cellular towers in 
+  range, and requires a GPRS data connection to be enabled.
+
+  Circuit:
+   MKR GSM 1400 board
+   Antenna
+   SIM card with a data plan
+
+  created 15 Dec 2017
+  by Sandeep Mistry
+*/
+
+// libraries
+#include <MKRGSM.h>
+
+#include "arduino_secrets.h"
+// Please enter your sensitive data in the Secret tab or arduino_secrets.h
+// PIN Number
+const char PINNUMBER[]     = SECRET_PINNUMBER;
+// APN data
+const char GPRS_APN[]      = SECRET_GPRS_APN;
+const char GPRS_LOGIN[]    = SECRET_GPRS_LOGIN;
+const char GPRS_PASSWORD[] = SECRET_GPRS_PASSWORD;
+
+// initialize the library instance
+GSMLocation location;
+GPRS gprs;
+GSM gsmAccess;
+
+float latitude;
+float longitude;
+long altitude;
+long accuracy;
+
+void setup() {
+  // initialize serial communications and wait for port to open:
+  Serial.begin(9600);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for native USB port only
+  }
+
+  Serial.println("Starting GSM location.");
+  // connection state
+  boolean notConnected = true;
+
+  // After starting the modem with GSM.begin()
+  // attach the shield to the GPRS network with the APN, login and password
+  while (notConnected) {
+    if ((gsmAccess.begin(PINNUMBER) == GSM_READY) &
+        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD) == GPRS_READY)) {
+      notConnected = false;
+    } else {
+      Serial.println("Not connected");
+      delay(1000);
+    }
+  }
+
+  location.begin();
+}
+
+void loop() {
+  // update the location variables
+  latitude = location.latitude();
+  longitude = location.longitude();
+  altitude = location.altitude();
+  accuracy = location.accuracy();
+
+  Serial.print("Location: ");
+  Serial.print(latitude, 7);
+  Serial.print(", ");
+  Serial.println(longitude, 7);
+
+  Serial.print("Altitude: ");
+  Serial.print(altitude);
+  Serial.println("m");
+
+  Serial.print("Accuracy: +/- ");
+  Serial.print(accuracy);
+  Serial.println("m");
+
+  Serial.println();
+
+  delay(1000);
+}
+

examples/GsmLocation/arduino_secrets.h

@@ -0,0 +1,4 @@
+#define SECRET_PINNUMBER     ""
+#define SECRET_GPRS_APN      "GPRS_APN" // replace your GPRS APN
+#define SECRET_GPRS_LOGIN    "login"    // replace with your GPRS login
+#define SECRET_GPRS_PASSWORD "password" // replace with your GPRS password

keywords.txt

@@ -17,6 +17,7 @@ GSMPIN	KEYWORD1
 GSMBand	KEYWORD1
 GSMSSLClient	KEYWORD1
 GSMUdp	KEYWORD1
+GSMLocation	KEYWORD1
 
 #######################################
 # Methods and Functions 
@@ -61,6 +62,10 @@ readDTMF	KEYWORD2
 writeDTMF	KEYWORD2
 enableI2SInput	KEYWORD2
 disableI2SInput	KEYWORD2
+latitude	KEYWORD2
+longitude	KEYWORD2
+altitude	KEYWORD2
+accuracy	KEYWORD2
 
 #######################################
 # Constants

src/GSMLocation.cpp

@@ -0,0 +1,125 @@
+/*
+  This file is part of the MKR GSM library.
+  Copyright (C) 2017  Arduino AG (http://www.arduino.cc/)
+
+  This library is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License as published by the Free Software Foundation; either
+  version 2.1 of the License, or (at your option) any later version.
+
+  This library is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with this library; if not, write to the Free Software
+  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+
+#include "GSMLocation.h"
+
+#define GSM_LOCATION_UPDATE_INTERVAL 1100
+
+GSMLocation::GSMLocation() :
+  _locationUpdated(false),
+  _lastRequestTime(0),
+  _latitude(0),
+  _longitude(0),
+  _altitude(0),
+  _uncertainty(0)
+{
+  MODEM.addUrcHandler(this);
+}
+
+GSMLocation::~GSMLocation()
+{
+  MODEM.removeUrcHandler(this);
+}
+
+int GSMLocation::begin()
+{
+  MODEM.send("AT+ULOCCELL=1");
+
+  if (MODEM.waitForResponse() != 1) {
+    return 0;
+  }
+
+  updateIfNeeded();
+
+  for (unsigned long start = millis(); !_locationUpdated && millis() < (start + 10000); ) {
+    MODEM.poll();
+  }
+
+  return 1;
+}
+
+float GSMLocation::latitude()
+{
+  updateIfNeeded();
+
+  return _latitude;
+}
+
+float GSMLocation::longitude()
+{
+  updateIfNeeded();
+
+  return _longitude;
+}
+
+long GSMLocation::altitude()
+{
+  updateIfNeeded();
+
+  return _altitude;
+}
+
+long GSMLocation::accuracy()
+{
+  updateIfNeeded();
+
+  return _uncertainty;
+}
+
+void GSMLocation::handleUrc(const String& urc)
+{
+  if (urc.startsWith("+UULOC: ")) {
+    String temp = urc;
+    int lastCommaIndex;
+
+    _locationUpdated = true;
+
+    lastCommaIndex = temp.lastIndexOf(',');
+    _uncertainty = temp.substring(lastCommaIndex + 1).toInt();
+    temp.remove(lastCommaIndex);
+
+    lastCommaIndex = temp.lastIndexOf(',');
+    _altitude = temp.substring(lastCommaIndex + 1).toInt();
+    temp.remove(lastCommaIndex);
+
+    lastCommaIndex = temp.lastIndexOf(',');
+    _longitude = temp.substring(lastCommaIndex + 1).toFloat();
+    temp.remove(lastCommaIndex);
+
+    lastCommaIndex = temp.lastIndexOf(',');
+    _latitude = temp.substring(lastCommaIndex + 1).toFloat();
+    temp.remove(lastCommaIndex);
+  }
+}
+
+void GSMLocation::updateIfNeeded()
+{
+  MODEM.poll();
+
+  if ((millis() - _lastRequestTime) < GSM_LOCATION_UPDATE_INTERVAL) {
+    return;
+  }
+
+  _lastRequestTime = millis();
+  MODEM.send("AT+ULOC=2,2,0,1,1");
+
+  if (MODEM.waitForResponse() != 1) {
+    return;
+  }
+}

src/GSMLocation.h

@@ -0,0 +1,55 @@
+/*
+  This file is part of the MKR GSM library.
+  Copyright (C) 2017  Arduino AG (http://www.arduino.cc/)
+
+  This library is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License as published by the Free Software Foundation; either
+  version 2.1 of the License, or (at your option) any later version.
+
+  This library is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with this library; if not, write to the Free Software
+  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+
+#ifndef _GSM_LOCATION_H_INCLUDED
+#define _GSM_LOCATION_H_INCLUDED
+
+#include <Arduino.h>
+
+#include "Modem.h"
+
+class GSMLocation : public ModemUrcHandler {
+
+public:
+  GSMLocation();
+  virtual ~GSMLocation();
+
+  int begin();
+
+  float latitude();
+  float longitude();
+  long altitude();
+  long accuracy();
+
+  void handleUrc(const String& urc);
+
+private:
+  void updateIfNeeded();
+
+private:
+  bool _locationUpdated;
+  unsigned long _lastRequestTime;
+
+  float _latitude;
+  float _longitude;
+  long _altitude;
+  long _uncertainty;
+};
+
+#endif

src/MKRGSM.h

@@ -33,5 +33,6 @@
 
 #include "GSMSSLClient.h"
 #include "GSMUdp.h"
+#include "GSMLocation.h"
 
 #endif