Clock

EMDK For Xamarin - 2.5

Overview

Clock allows an administrator to manually set the Date, Time and Time Zone on a device, or to configure the device to automatically acquire those settings from a network (such as acquiring the Date and Time from an NTP server or acquiring the Date, Time and Time Zone from a cellular network). Clock also allows an administrator to choose between 12-hour (a.m./p.m.) and 24-hour (military time) display formats.

Zebra Android devices track the current Date and Time using the Coordinated Universal Time (UTC) standard. That information enables the Clock to accurately calculate the local Date and Time, expressed as the Local Time Coordinate (LTC). UTC is the equivalent of LTC at the Prime Meridian in Greenwich, England, where no offsets apply. For most other places, LTC is calculated starting with the UTC and adding or subtracting time based on the Time Zone in which the device being used, plus or minus the Daylight Saving Time offset, if any.

Clock sets Date and Time values in Coordinated Universal Time (UTC) to ensure proper conversion to local time based on Time Zone and Daylight Saving Time offsets. If LTC were used as a starting point, the order in which the Date, Time, and Time Zone were input could effect the resulting values. For more information, please see LTC Calculation Examples at the end of this guide.

Main Functionality

  • Set the current Time
  • Set the current Date
  • Set the Time Zone
  • Display 12-hour (a.m./p.m.) or 24-hour "military time" formats
  • Set device to acquire Date, Time and Time Zone from a network (when possible)
  • Set the NTP server address
  • Set the AutoTime sync interval

Auto Time Enable/Disable

Controls whether the Date and Time on the device will be set manually or automatically with values from a cellular network or NTP server. When AutoTime is enabled, the device will attempt to obtain the Date and Time from a cellular network (if one is available) or will contact an NTP server (if provided) at the interval specified in the Syncinterval parameter. When AutoTime is disabled, the Date and Time can be set manually to any valid values.

Regardless of how the values are obtained, Clock sets the Date and Time in Coordinated Universal Time (UTC) to ensure proper conversion to local time.

Parm Name: AutoTime

Option Name Description Requires
false false This value (or the absence of this parm from the XML) disables AutoTime, preventing the device from automatically setting the Date and Time to values acquired from a network.

OSX: 1.3+

MX: 4.2+

true true Enables AutoTime, allowing the device to automatically set the Date and Time to values acquired from a network.

OSX: 1.3+

MX: 4.2+

NTP Server Address

Used to specify the URL or IP address of the NTP server that the device can contact at the specified Sync Interval to acquire the Date and Time when AutoTime is enabled. Devices operating on a cellular network can typically acquire the Date, Time (and optionally the Time Zone) from the carrier network. Devices that do not support cellular communication or that may temporarily lack access to a supported cellular network can acquire Date and Time (but NOT the Time Zone) from an NTP server via a non-cellular network, such as Wi-Fi or Ethernet.

Parm input rules:

  • Accepts a string containing a valid URL or IP address of the NTP server
  • If left empty (or parm is absent from the XML), a default NTP server will be used

Shown if: Auto Time is "true"

Parm Name: NTPServer

Requires:

  • MX: 4.2+
  • Android API Level: 19+

Set Sync Interval

Used to specify the interval at which a device will attempt to contact the specified NTP server to acquire the Date and Time when AutoTime is enabled. For devices operating on a cellular network, AutoTime typically acquires the Date and Time from the carrier network.

Shown if: AutoTime is "true"

Parm Name: SyncInterval

Option Name Description Requires
00:30:00 30 minutes Sets the device to contact the NTP server every 30 minutes.

MX: 4.2+

Android API Level: 16+

00:60:00 60 minutes Sets the device to contact the NTP server every 60 minutes.

MX: 4.2+

Android API Level: 16+

06:00:00 6 hours Sets the device to contact the NTP server every 6 hours.

MX: 4.2+

Android API Level: 16+

24:00:00 24 hours Sets the device to contact the NTP server every 24 hours.

MX: 4.2+

Android API Level: 16+

Auto Time Zone Enable/Disable

Enables a cellular-equipped device to acquire the Time Zone in which it is located from the carrier network (if supported by that network). The Time Zone is used by Clock to calculate the local time on the device. When AutoTimeZone is disabled, the Time Zone can be set manually through the UI or programmatically using the Time Zone parameter. The AutoTimeZone feature applies only to cellular-equipped devices.

Warning: When changing the Auto Time Zone Enable/Disable setting, the Settings panel will not reflect the new setting if the panel was launched from the Android Recent Apps list. To avoid the appearance of this incorrect setting (which has no effect on proper device operation), the Settings app can be cleared from the Recent Apps list by adding the relevant XML from the App Manager to any profile created to set the clock.

Parm Name: AutoTimeZone

Option Name Description Requires
false false This value (or the absence of this parm from the XML) disables Auto Time Zone, preventing the device from automatically acquiring the Time Zone from the carrier network.

OSX: 1.3+

MX: 6.0+

true true Enables the device to automatically acquire the current Time Zone (if supported by the carrier network).

OSX: 1.3+

MX: 6.0+

Set Time Zone

Used to set the Time Zone for calculating the Local Time Coordinate (LTC) on the device. Specifying an empty value (or the absence of this parm from the XML) will retain any previously configured setting.

Parm input rules:

  • Accepts a string with a maximum of 255 characters
  • If left empty (or parm is absent from the XML), previous Time Zone setting will be retained
  • The string must be one of the following:
    • A value equal to the "GMT" or Greenwich Mean Time zone
    • A value equal to the "UTC" (the equivalent of GMT)
    • A value that starts with the prefix "GMT" and contains an offset in hours or hours and minutes. For example:
      • GMT-10 (GMT minus 10 hours)
      • GMT+05:30 (GMT plus 5 1/2 hours)
    • An Olsen/tz Time Zone identifier (i.e. "America/New_York")

For more information, refer to these reference sites:

Shown if: Auto Time Zone is "false"

Parm Name: TimeZone

Requires:

  • MX: 4.1+
  • Android API Level: 1+

Set Date

Used to manually set the Date on the device. Date and Time values given to the Clock must be represented as UTC. (see Overview). Specifying an empty value (or the absence of this parm from the XML) will retain any previously configured Date.

Parm input rules:

  • Accepts a string of exactly 0 or 10 characters only
  • The 10-character string must be in the format of "YYYY-MM-DD"
  • Date must be represented as a UTC value (see Overview)

Shown if: Auto Time is "false"

Parm Name: Date

Requires:

  • MX: 4.1+
  • Android API Level: 8+

Set Time

Used to set the Time on the device. Date and Time values given to the Clock must be represented as UTC (see Overview). Specifying an empty value (or the absence of this parm from the XML) will retain any previously configured Time.

Parm input rules:

  • Accepts a string of exactly 0 or 8 characters only
  • The 8-character string must be in the 24-hour format "HH:MM:SS" (i.e. "23:59:59" is one second before midnight)
  • Time must be represented as a UTC value (see Overview)

Shown if: Auto Time is "false"

Parm Name: Time

Requires:

  • MX: 4.1+
  • Android API Level: 8+

24-Hour Time Enable/Disable

Controls whether to display time on the device in 24-hour "military time" format. When military time is Off, time is displayed in standard 12-hour (a.m./p.m.) format.

Parm Name: MilitaryTime

Option Name Description Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to time display format; any previously selected setting will be retained.

MX: 6.0+

1 Turn on Displays time in 24-hour (military time) format.

MX: 6.0+

2 Turn off Displays time in 12-hour (a.m./p.m.) format.

MX: 6.0+

LTC Calculation Examples

Date and Time values given to the Clock must be represented as UTC. This ensures an accurate result when calculating the local date and time for the device based on offsets for Time Zone and Daylight Saving Time, if any. If local time is used as a starting point, the order in which the Date, Time, and Time Zone are set could effect the resulting values. The examples below explain how to make these calculations correctly.

UTC is the equivalent of LTC at the Prime Meridian in Greenwich, England, where no offsets apply. For most other places, LTC is calculated starting with the UTC and adding or subtracting time based on the Time Zone in which the device being used, plus or minus the Daylight Saving Time offset, if any.

For more information, refer to these reference sites:

Example #1

This example inverts the UTC offset. Since UTC time is later than Eastern time, hours are added to the desired Eastern time to calculate its UTC equivalent. When this figure is put into the device, the Clock will recalculate the value to arrive at the desired local time for display and program use.

1. Note the desired local time for the device:

  • Device Location = New York, New York, USA
  • Date = January 15, 2010
  • Time = 2:15 p.m. (14:15:00)

2. Make the following observations about device location:

  • The device is located in the Eastern USA Time Zone
  • The GMT offset for that Time Zone is -5 hours (5 hours earlier than UTC)
  • The Time Zone does not observe Daylight Saving Time on that Date

3. Calculate the UTC value from the desired LTC:

  • Apply the UTC offset (-05:00) for the selected Time Zone:
    • 14:15:00 + 05:00 = 19:15:00 (adding time because UTC is later than Eastern USA time)
  • Consider Daylight Saving Time offset (not in effect on that date):
    • Daylight Saving Time began March 14, 2010
    • Daylight Saving Time ended November 7, 2010
  • Applying no Date offset, since the Time offset did not cause "roll over" or "roll under"

4. The values specified to the Clock would therefore be:

  • TimeZone = "America/New_York"
  • Date = "2010-01-15"
  • Time = "19:15:00"

When converted by the Clock, these UTC values would appear as the correct LTC values on the device.

Example #2

This example inverts the UTC offset. Since UTC time is earlier than India time, hours are subtracted from the desired Bangalore time to calculate its UTC equivalent, which results in a (backward) cross of the Prime Meridian (dateline). When this figure is put into the device, the Clock will recalculate the value to arrive at the desired local time and day for display and program use.

1. Note the desired local time for the device:

  • Device Location = Bangalore, India
  • Date = July 11, 2010
  • Time = 2:55 a.m. (02:55:00)

2. Make the following observations about device location:

  • The device is located in the India Time Zone
  • The GMT offset for that Time Zone is +05:30 (+5 1/2 hours ahead of GMT)
  • That Time Zone does not observe Daylight Saving Time

3. Calculate the UTC value from the desired LTC:

  • Apply the GMT offset (+05:30) for the selected Time Zone
    • 02:55:00 - 05:30 = 21:25:00 (rolls backward over 00:00; subtract 1 day)
  • Applying no Daylight Saving Time offset
    • India does not observe Daylight Saving Time
  • Applying a 1-day negative Date offset since the Time offset caused a "roll under"

4. The values specified to the Clock would therefore be:

  • TimeZone = "Asia/Calcutta"
  • Date = "2010-07-10"
  • Time = "21:25:00"

Note the Date is July 10, 2010, one day before the desired local time. That is because when it's 2:55 a.m. on July 11 in India, it's 9:25 p.m. (5 1/2 hours earlier) in Greenwich, England (where UTC originates), and the date is still July 10.

When converted by the Clock, these UTC values would appear as the correct LTC values on a device in Bangalore.

Clock Coding Examples

Set the Time Zone, Date, and Time


<wap-provisioningdoc>
    <characteristic type="Clock" version="4.2" >
        <parm name="AutoTime" value="false"/>
        <parm name="TimeZone" value="GMT-5"/>
        <parm name="Date" value="2015-07-09"/>
        <parm name="Time" value="10:25:33"/>
    </characteristic>
</wap-provisioningdoc>

Set the NTP Server Interval


<wap-provisioningdoc>
    <characteristic type="Clock" version="4.2" >
        <parm name="AutoTime" value="true"/>
        <characteristic type="AutoTimeDetails">
            <parm name="SyncInterval" value="00:30:00"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Set the NTP Server IP Address and Interval


<wap-provisioningdoc>
    <characteristic type="Clock" version="4.2" >
        <parm name="AutoTime" value="true"/>
        <characteristic type="AutoTimeDetails">
            <parm name="NTPServer" value="1.2.3.4"/>
            <parm name="SyncInterval" value="00:30:00"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>