Add setClock and autoTimeZoneForBegin. Add Example13_SetClockWithNTP. Correct socketReadAvailableUDP.

Author: PaulZC

examples/SARA-R5_Example13_SetClockWithNTP/SARA-R5_Example13_SetClockWithNTP.ino

@@ -0,0 +1,167 @@
+/*
+
+  SARA-R5 Example
+  ===============
+
+  Set Clock With NTP
+
+  Written by: Paul Clark
+  Date: January 9th 2022
+
+  This example demonstrates how to set the SARA-R5's internal Real Time Clock using NTP.
+  When the SARA-R5 registers on a network, it will set its clock automatically if:
+    Automatic time zone is enabled
+    Your network supports NITZ (Network Identity and Time Zone)
+  But for things like AssistNow Offline, it is convenient to have the SARA's RTC set to UTC.
+  Then the clock can be used to select the AssistNow data for now/today without time zone headaches.
+  This example shows how to:
+    Disable the automatic time zone (using autoTimeZoneForBegin before .begin)
+    Set the SARA's clock to UTC using NTP (see SARA-R5_NTP.ino)
+
+  The PDP profile is read from NVM. Please make sure you have run examples 4 & 7 previously to set up the profile.  
+
+  Feel like supporting open source hardware?
+  Buy a board from SparkFun!
+
+  Licence: MIT
+  Please see LICENSE.md for full details
+
+*/
+
+//=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+#include <SparkFun_u-blox_SARA-R5_Arduino_Library.h> //Click here to get the library: http://librarymanager/All#SparkFun_u-blox_SARA-R5_Arduino_Library
+
+// Uncomment the next line to connect to the SARA-R5 using hardware Serial1
+#define saraSerial Serial1
+
+// Uncomment the next line to create a SoftwareSerial object to pass to the SARA-R5 library instead
+//SoftwareSerial saraSerial(8, 9);
+
+// Create a SARA_R5 object to use throughout the sketch
+// Usually we would tell the library which GPIO pin to use to control the SARA power (see below),
+// but we can start the SARA without a power pin. It just means we need to manually 
+// turn the power on if required! ;-D
+SARA_R5 mySARA;
+
+// Create a SARA_R5 object to use throughout the sketch
+// We need to tell the library what GPIO pin is connected to the SARA power pin.
+// If you're using the MicroMod Asset Tracker and the MicroMod Artemis Processor Board,
+// the pin name is G2 which is connected to pin AD34.
+// Change the pin number if required.
+//SARA_R5 mySARA(34);
+
+// Create a SARA_R5 object to use throughout the sketch
+// If you are using the LTE GNSS Breakout, and have access to the SARA's RESET_N pin, you can pass that to the library too
+// allowing it to do an emergency shutdown if required.
+// Change the pin numbers if required.
+//SARA_R5 mySARA(34, 35); // PWR_ON, RESET_N
+
+//=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+void setup()
+{
+  String currentOperator = "";
+
+  Serial.begin(115200); // Start the serial console
+
+  // Wait for user to press key to begin
+  Serial.println(F("SARA-R5 Example"));
+  Serial.println(F("Wait for the SARA NI LED to light up - then press any key to begin"));
+  
+  while (!Serial.available()) // Wait for the user to press a key (send any serial character)
+    ;
+  while (Serial.available()) // Empty the serial RX buffer
+    Serial.read();
+
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  //mySARA.enableDebugging(); // Uncomment this line to enable helpful debug messages on Serial
+
+  // For the MicroMod Asset Tracker, we need to invert the power pin so it pulls high instead of low
+  // Comment the next line if required
+  mySARA.invertPowerPin(true);
+
+  // Disable the automatic time zone so we can use UTC. We need to do this _before_ .begin
+  mySARA.autoTimeZoneForBegin(false);
+
+  // Initialize the SARA
+  if (mySARA.begin(saraSerial, 115200) )
+  {
+    Serial.println(F("SARA-R5 connected!"));
+  }
+  else
+  {
+    Serial.println(F("Unable to communicate with the SARA."));
+    Serial.println(F("Manually power-on (hold the SARA On button for 3 seconds) on and try again."));
+    while (1) ; // Loop forever on fail
+  }
+  Serial.println();
+
+  // First check to see if we're connected to an operator:
+  if (mySARA.getOperator(&currentOperator) == SARA_R5_SUCCESS)
+  {
+    Serial.print(F("Connected to: "));
+    Serial.println(currentOperator);
+  }
+  else
+  {
+    Serial.print(F("The SARA is not yet connected to an operator. Please use the previous examples to connect. Or wait and retry. Freezing..."));
+    while (1)
+      ; // Do nothing more
+  }
+
+  // Deactivate the PSD profile - in case one is already active
+  if (mySARA.performPDPaction(0, SARA_R5_PSD_ACTION_DEACTIVATE) != SARA_R5_SUCCESS)
+  {
+    Serial.println(F("Warning: performPDPaction (deactivate profile) failed. Probably because no profile was active."));
+  }
+
+  // Load the PSD profile from NVM - these were saved by a previous example
+  if (mySARA.performPDPaction(0, SARA_R5_PSD_ACTION_LOAD) != SARA_R5_SUCCESS)
+  {
+    Serial.println(F("performPDPaction (load from NVM) failed! Freezing..."));
+    while (1)
+      ; // Do nothing more
+  }
+
+  // Activate the profile
+  if (mySARA.performPDPaction(0, SARA_R5_PSD_ACTION_ACTIVATE) != SARA_R5_SUCCESS)
+  {
+    Serial.println(F("performPDPaction (activate profile) failed! Freezing..."));
+    while (1)
+      ; // Do nothing more
+  }
+
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  //Get the time from an NTP server and use it to set the clock. See SARA-R5_NTP.ino
+  uint8_t y, mo, d, h, min, s;
+  bool success = getNTPTime(&y, &mo, &d, &h, &min, &s);
+  if (!success)
+  {
+    Serial.println(F("getNTPTime failed! Freezing..."));
+    while (1)
+      ; // Do nothing more
+  }
+
+  //Set the SARA's RTC. Set the time zone to zero so the clock uses UTC
+  if (mySARA.setClock(y, mo, d, h, min, s, 0) != SARA_R5_SUCCESS)
+  {
+    Serial.println(F("setClock failed! Freezing..."));
+    while (1)
+      ; // Do nothing more
+  }
+  
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  // Read and print the clock as a String
+  Serial.print(F("The UTC time is: "));
+  String theTime = mySARA.clock();
+  Serial.println(theTime);
+}
+
+void loop()
+{
+  // Nothing to do here
+}

examples/SARA-R5_Example13_SetClockWithNTP/SARA-R5_NTP.ino

@@ -0,0 +1,175 @@
+
+#include <time.h> // Note: this is the standard c time library, not Time.h
+
+// Get the time from NTP
+// This code is based heavily on:
+// https://docs.arduino.cc/tutorials/mkr-nb-1500/mkr-nb-library-examples#mkr-nb-gprs-udp-ntp-client
+// Many thanks to: Michael Margolis, Tom Igoe, Arturo Guadalupi, et al
+
+// NTP Server
+//const char* ntpServer = "africa.pool.ntp.org";        // The Network Time Protocol Server
+//const char* ntpServer = "asia.pool.ntp.org";          // The Network Time Protocol Server
+//const char* ntpServer = "europe.pool.ntp.org";        // The Network Time Protocol Server
+const char* ntpServer = "north-america.pool.ntp.org"; // The Network Time Protocol Server
+//const char* ntpServer = "oceania.pool.ntp.org";       // The Network Time Protocol Server
+//const char* ntpServer = "south-america.pool.ntp.org"; // The Network Time Protocol Server
+
+//=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+bool getNTPTime(uint8_t *y, uint8_t *mo, uint8_t *d, uint8_t *h, uint8_t *min, uint8_t *s)
+{
+  int serverPort = 123; //NTP requests are to port 123
+  
+  // Set up the packetBuffer for the NTP request
+  const int NTP_PACKET_SIZE = 48; // NTP time stamp is in the first 48 bytes of the message
+  byte packetBuffer[NTP_PACKET_SIZE]; //buffer to hold incoming and outgoing packets
+  
+  // set all bytes in the buffer to 0
+  memset(packetBuffer, 0, NTP_PACKET_SIZE);
+
+  // Initialize values needed to form NTP request
+  packetBuffer[0] = 0b11100011;   // LI, Version, Mode
+  packetBuffer[1] = 0;     // Stratum, or type of clock
+  packetBuffer[2] = 6;     // Polling Interval
+  packetBuffer[3] = 0xEC;  // Peer Clock Precision
+  // 8 bytes of zero for Root Delay & Root Dispersion
+  packetBuffer[12]  = 49;
+  packetBuffer[13]  = 0x4E;
+  packetBuffer[14]  = 49;
+  packetBuffer[15]  = 52;
+
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  //Open a socket to the NTP server
+
+  int socketNum = mySARA.socketOpen(SARA_R5_UDP);
+  if (socketNum == -1)
+  {
+    Serial.println(F("getNTPTime: socketOpen failed!"));
+    return (false);
+  }
+
+  Serial.print(F("getNTPTime: using socket "));
+  Serial.println(socketNum);
+
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  // Send the request - NTP uses UDP
+  
+  if (mySARA.socketWriteUDP(socketNum, ntpServer, serverPort, (const char *)&packetBuffer, NTP_PACKET_SIZE) != SARA_R5_SUCCESS) // Send the request
+  {
+    Serial.println(F("getNTPTime: socketWrite failed!"));
+    mySARA.socketClose(socketNum); // Be nice. Close the socket
+    return (false);    
+  }
+
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  // Wait up to 10 seconds for the response
+  unsigned long requestTime = millis();
+
+  while (millis() < (requestTime + 10000))
+  {
+    // We could use the Socket Read Callback to get the data, but, just for giggles,
+    // and to prove it works, let's poll the arrival of the data manually...
+    int avail = 0;
+    if (mySARA.socketReadAvailableUDP(socketNum, &avail) != SARA_R5_SUCCESS)
+    {
+      Serial.println(F("getNTPTime: socketReadAvailable failed!"));
+      mySARA.socketClose(socketNum); // Be nice. Close the socket
+      return (false);
+    }
+
+    if (avail >= NTP_PACKET_SIZE) // Is enough data available?
+    {
+      if (avail > NTP_PACKET_SIZE) // Too much data?
+      {
+        Serial.print(F("getNTPTime: too much data received! Length: "));
+        Serial.print(avail);
+        Serial.print(F(". Reading "));
+        Serial.print(NTP_PACKET_SIZE);
+        Serial.println(F(" bytes..."));
+      }
+      
+      if (mySARA.socketReadUDP(socketNum, NTP_PACKET_SIZE, (char *)&packetBuffer) != SARA_R5_SUCCESS)
+      {
+        Serial.println(F("getNTPTime: socketRead failed!"));
+        mySARA.socketClose(socketNum); // Be nice. Close the socket
+        return (false);
+      }
+      
+      // Extract the time from the reply
+
+      Serial.print(F("getNTPTime: received "));
+      Serial.print(avail);
+      Serial.println(F(" bytes. Extracting the time..."));
+      
+      //the timestamp starts at byte 40 of the received packet and is four bytes,
+      // or two words, long. First, esxtract the two words:
+      unsigned long highWord = word(packetBuffer[40], packetBuffer[41]);
+      unsigned long lowWord = word(packetBuffer[42], packetBuffer[43]);
+  
+      // combine the four bytes (two words) into a long integer
+      // this is NTP time (seconds since Jan 1 1900):
+      unsigned long secsSince1900 = highWord << 16 | lowWord;
+  
+      Serial.print(F("getNTPTime: seconds since Jan 1 1900 = "));
+      Serial.println(secsSince1900);
+  
+      // now convert NTP time into everyday time:
+      Serial.print(F("getNTPTime: Unix time = "));
+  
+      // Unix time starts on Jan 1 1970. In seconds, that's 2208988800:
+      const unsigned long seventyYears = 2208988800UL;
+  
+      // subtract seventy years:
+      unsigned long epoch = secsSince1900 - seventyYears;
+  
+      // print Unix time:
+      Serial.println(epoch);
+
+      // Instead of calculating the year, month, day, etc. manually, let's use time_t and tm to do it for us!
+      time_t dateTime = epoch;
+      tm *theTime = gmtime(&dateTime);
+
+      // Load the time into y, mo, d, h, min, s
+      *y = theTime->tm_year - 100; // tm_year is years since 1900. Convert to years since 2000.
+      *mo = theTime->tm_mon + 1; //tm_mon starts at zero. Add 1 for January.
+      *d = theTime->tm_mday;
+      *h = theTime->tm_hour;
+      *min = theTime->tm_min;
+      *s = theTime->tm_sec;
+
+      // Finish off by printing the time
+      Serial.print(F("getNTPTime: YY/MM/DD HH:MM:SS : "));
+      if (*y < 10) Serial.print(F("0"));
+      Serial.print(*y);
+      Serial.print(F("/"));
+      if (*mo < 10) Serial.print(F("0"));
+      Serial.print(*mo);
+      Serial.print(F("/"));
+      if (*d < 10) Serial.print(F("0"));
+      Serial.print(*d);
+      Serial.print(F(" "));
+      if (*h < 10) Serial.print(F("0"));
+      Serial.print(*h);
+      Serial.print(F(":"));
+      if (*min < 10) Serial.print(F("0"));
+      Serial.print(*min);
+      Serial.print(F(":"));
+      if (*s < 10) Serial.print(F("0"));
+      Serial.println(*s);
+
+      mySARA.socketClose(socketNum); // Be nice. Close the socket
+      return (true); // We are done!
+    }
+    
+    delay(100); // Wait before trying again
+  }
+
+  //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+  Serial.println(F("getNTPTime: no NTP data received!"));
+  mySARA.socketClose(socketNum); // Be nice. Close the socket
+  return (false);
+}

keywords.txt

@@ -72,6 +72,8 @@ getSubscriberNo	KEYWORD2
 getCapabilities	KEYWORD2
 reset	KEYWORD2
 clock	KEYWORD2
+setClock	KEYWORD2
+autoTimeZoneForBegin	KEYWORD2
 autoTimeZone	KEYWORD2
 setUtimeMode	KEYWORD2
 getUtimeMode	KEYWORD2