SHIP:System Variable:shiptime

See System Variables for a complete list of SHIP system variables.

System Variable	Data Type	Permissions	Description
shiptime	Time	Read/Write	This variable tracks the current system time. You can change these values, but they are only retained across power cycles if the platform has battery-backed RTCC capabilities.

It is very easy to create a clock in our GUI by listening to shiptime. The simple script

: text.value = toString(shiptime.hour,2) + ":" + toString(shiptime.minute,2) ;

within a listener with the listeningto property set to "shiptime.minute" will automatically keep the text value updated every second.

Assigning and Manipulating shiptime

Similar to all Time type variables, shiptime has subfields such as .year, .minute, etc. See Time for a complete description of the Time data type and subfields, as well as the auto-translation and auto-rollover functionality built into Time variables.

One must take special care manipulating shiptime. Unlike normal Time variables, shiptime changes underneath the program constantly ... once per second.

You can adjust shiptime subfields at will (e.g. shiptime.month =1 will set the current month to January). However, assigning a field as it is about to change may have unexpected results. For example, setting shiptime.month to 1 just as hour/minute/second/day are at the end of a month will result in an immediate increment (within 1 second) of the .month field to 2. As a programmer, you must be cognizant that changing a subfield of shiptime is changing a constantly moving target.

For atomic setting/getting of more than one subfield, use the .value field which atomically encompasses all the other subfields. Often you may want to use a shadow variable of Time. For example, assigning timevar.value = shiptime.value will atomically copy shiptime to timevar. Your code can now safely manipulate individual subfields of timevar, then assign it back to shiptime.value when complete.

Date/Time Source and Power Cycles/Reboots

The shiptime system variable tracks the current system date/time -- the Real Time Clock/Calendar, or "RTCC", capability.

If the hardware platform has a battery backup on it, timekeeping will continue through power cycles and reboots. You must still somehow set the time on installation or when the battery is changed. Your GUI can include a "settings" page where this is done by the end user.

Alternatively, if your system is cloud connected or has some other timekeeping system, your GUI can communicate this value from the attached systems in your device and update shiptime.value accordingly. For example, if your SIM is connected to a SCM208 communications module which in turn is communicating via WiFi to the cloud, the SCM208 code could pull the current date/time from an NNTP server and share that value with the SIM (over the Modbus or SHIPBridge protocol connection) where the GUI could then assign that value to shiptime.

Accuracy

If the hardware platform has an actual 32kHz crystal, this will be a relatively accurate timekeeping value over months if not years. Some platforms even have a coin cell battery backup for the RTCC which will keep the clock running when the system is turned off.

If the hardware platform does not have a 32kHz crystal -- a common occurrence on low-cost variants such as the SIM535-A03 -- the MCU high frequency (e.g. 12MHz or 8MHz) clock is divided down inside the firmware and drives the shiptime variable's value on a second-by-second basis. This may have drift and accuracy issues, and in these situations it is wise to sync shiptime to an external source periodically (for example at each power/reboot cycle and at midnight each night or every several hours).