Difference between revisions of "SHIP:System Variable:shiptime"

From Serious Documentation
Jump to: navigation, search
Line 12: Line 12:
  
 
within a {{Node|listener}} with the {{Prop|listener|listeningto}} property set to "shiptime.minute" will automatically keep the text value updated every second.
 
within a {{Node|listener}} with the {{Prop|listener|listeningto}} property set to "shiptime.minute" will automatically keep the text value updated every second.
 +
 +
== Assigning and Manipulating {{SysVar|shiptime}} ==
 +
 +
Similar to all {{DataType|Time}} type variables, {{SysVar|shiptime}} has subfields such as .year, .minute, etc. See {{DataType|Time}} for a complete description of the {{DataType|Time}}
 +
 +
data type and subfields and the auto-translation and auto-rollover functionality built into {{DataType|Time}} variables.
 +
 +
One must take special care manipulating {{SysVar|shiptime}}, as unlike normal {{DataType|Time}} variables, {{SysVar|shiptime}} changes underneath the program constantly ... once per second.
 +
 +
You can adjust {{SysVar|shiptime}} subfields at will (e.g. {{SysVar|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 {{SysVar|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 {{SysVar|shiptime}} is changing a constantly moving target.
 +
 +
For atomic setting/getting of more than one subfield, use the .value field which encompasses atomically all the other subfields. Often you may want to use a shadow variable of {{DataType|Time}}. For example, assigning timevar.value = {{SysVar|shiptime}}.value will atomically copy {{SysVar|shiptime}}
 +
 +
to timevar. Your code can now safely manipulate individual subfields of timevar, then assign it back to {{SysVar|shiptime}}.value when complete.
 +
 +
== Date/Time Source and Power Cycles/Reboots ==
 +
 +
The {{SysVar|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. Of course, you must somehow set the time on installation or every time the battery is changed, and 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 {{SysVar|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) and the GUI could then assign that value to {{SysVar|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 {{SysVar|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 {{SysVar|shiptime}} to an external source periodically (for example at each power/reboot cycle and at midnight each night or every several hours).

Revision as of 05:40, 18 August 2016

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 and the auto-translation and auto-rollover functionality built into Time variables.

One must take special care manipulating shiptime, as 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 encompasses atomically 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. Of course, you must somehow set the time on installation or every time the battery is changed, and 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) and 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).

Retrieved from "https://techref.myserious.com/index.php?title=SHIP:System_Variable:shiptime&oldid=5589"