What time is it?
Do you know what time it is? Does your SNAP PAC controller know what time it is? Are they the same time? Who’s right?
In this week's blog we are going to talk about this big ball of wibbly wobbly timey wimey stuff.… No, not time travel, but actual time…. Specifically how to set your PAC Controller to the current time.
No reading ahead; remember, time flies like an arrow and fruit flies like a banana.
SNTP will catch the drift.
The SNAP PAC controller, like most electronic timekeeping devices, uses a small quartz crystal in an oscillator circuit to provide a continuous stream of pulses to a realtime clock. This crystal can drift in frequency over time because of temperature, humidity, and other electrical and environmental reasons. This drift will cause the realtime clock inside the controller to vary from the correct time. The amount of drift depends on many factors, and while you can do some compensation, at the end of the day, the realtime clock will be in error. Sometimes it will be only a few seconds or so a day, sometimes more; sometimes it will be fast, sometimes it will be slow.
The good news is that from firmware version 9.2 and higher, we have a range of PAC Control SNTP commands that we can use to adjust the clock on the controller to synchronize with a more accurate clock over the Internet.
NTP or Network Time Protocol was first used in 1979 and implemented into Unix around 1985. Almost as soon as computers were networked together it became clear that we needed a way to ensure they all stayed synchronized. After all, no one wants to get an email 5 minutes before it was sent.
Not long after NTP became established it also became clear that many devices, usually smaller embedded devices, just did not need the full power and complexity of NTP, so Simple Network Time Protocol (SNTP) was implemented. This is what the PAC Controllers use.
There are many cool aspects of the Simple Network Time Protocol, but one key aspect is how it keeps track of the round-trip packet delay between the device asking for time and the time server. By using two timestamps, originate and receive, the round-trip packet delay of the network is part of the clock synchronization algorithm and is eliminated from the final time stamp.
Quick side note: if you are running SoftPAC you don't need to run these commands, as the Windows operating system takes care of the PC clock setting and adjustments.
Ok, enough with the history lesson, how do I set the clock in my controller already?
There are two commands that are required. Run them when you want to set/adjust/tweak the clock. Generally, once a day is fine. Here is some sample code to do just that.
// Set the controller date/time once a day. Handle both timezone and daylight savings at the same time.
seconds_since_midnight = GetSecondsSinceMidnight();
if (seconds_since_midnight == 0) then
time_zone_status = SetTimeZoneConfiguration("PST1,11,0,1,0200/PDT,3,0,2,0200");
time_sync_status = SynchronizeClockSNTP(5, s_time_server_url);
// Must have this delay so we only set the clock once a night.
In this case, the string s_time_server_url is equal to: "udp:time.nist.gov:123"
Let's break it down and see what is happening here. First up, we are checking if it is midnight. Even though it may not be exactly midnight (because the controller clock might have drifted through the day), we are about to correct any drift, no matter if it is fast or slow, and thus each day's drift is not going to be compounded on the previous day's drift.
Note that you might want to run this at some other time if you have batch jobs or data logs that run or roll over at midnight. If you do, just pick a seconds-since-midnight value other than zero.
If the controller realtime clock setting is critical, you are welcome to run the command, say, every hour or so, but it should not be necessary to run it more often than this. And if it is, then you are in a special use case and should consider other ways to set the time accurately (for example, GPS).
So back to our example: at midnight we run the two commands. First up we have to set the controller time zone and daylight savings rules. If we don’t, then the controller clock will be set for UTC. This may be exactly what you need in some cases, but most people want their PAC Controller clocks to be set to the local time and to handle the daylight savings rules for them.
Let's pull this time zone configuration command apart a tiny bit and use it as an example of why commands like this make it critical that we RTFM, that is, Read The Fantastic Manual. When we look at the string that follows the command, the first thing we see is "PST1". Temecula is on the west coast of the U.S. in the PST time zone, so what’s the "1" for? The fantastic manual (PAC Control Command Reference, form 1701) shows that for this Set Time Zone Configuration command we must use only the Time Zone Abbreviations that are listed in the back of the manual. There we see "PST1" (ours) and "PST2" which sets the clock to Philippine Standard Time. There is no PST, and if we were to set the string to that, we would get an error. The lesson from this is always (always) RTFM. It really is Fantastic and it really will save you time!
From there, the rest of the string sets the daylight savings rules of when to spring forward and when to fall back. November is the 11th month and March is the 3rd month, it happens on a Sunday (day 0), and it is the first and second Sunday of the month, and each time it happens at 2:00 a.m…. BOOM! In one string, we have just handled the timezone and daylight savings!
Next up, we actually set the clock. In the example we are using here, the controller has a gateway IP address and DHCP server IP address set (via PAC Manager) and so knows how to get out to the Internet and look up the host name of the timer server set in the string. In this case that’s time.nst.gov on port 123. We have a 5-second timeout on this command in my example, so that if there is a problem connecting with the time server, we don’t get hung up and sit here forever in the code.
Once it gets the response from the time server, the controller takes care of setting the clock for you. In my very simple example code, we do not check the command status; we just assume it has worked. But you might want to add some retry or notification code if the time failed to be set.
What if your controller doesn't have access to the Internet? Is your real time clock doomed to drift aimlessly through space and time? Well, no, you have some options.
Firstly, perhaps your IT department runs a time server in your facility, and your controller, while not having Internet access, can access that server on its local network. As long as it is running an SNTP server, you can use the same commands, but pointed at the IP address of that PC to get and set the controller clock.
If your PAC Controller is out on its own, truly an island, with no connection to the Internet or servers on a local area network, then take a look at using a GPS. GPS offers a serial connection that provides a very accurate time stamp. If you're interested in this, let me know; I would love to do a blog on the topic.
What time is it really?
One of my favorite web sites has this as a bit of a byline: “A man with one clock knows what time it is. A man with two clocks is never sure.” I love this.
SNTP is going to get us really close to the current time. Now that our SNAP PAC controllers have these commands it is super simple to set our controllers to the same time that another computer thinks it is. As you can see from that website, you can chase time standards for a long, long time (heh, see what I did there).
Once we set the realtime clock on our PAC controller, it’s time to do things at the right time!
How? Glad you asked. Subscribe to this blog and come back next week, as we will be talking about some of the different ways to schedule tasks.
Till next week, Cheers Mate.