Clock

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

EMDK For Android - 7.0

Overview

Clock allows an administrator to manually set the Date, Time and Time Zone on a device using local or UTC time, 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 local Time
  • Set the current Date
  • Set the current UTC Time
  • Set the current UTC Date
  • Set the time Coordinate System to use (local or UTC)
  • Set the Time Zone (for calculating date/time from UTC values)
  • 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 (checkbox)

Controls whether the Date and Time on the device are set using values from a cellular network or NTP server or must be set manually. When AutoTime is enabled, the device attempts to obtain the Date and Time from a cellular network (if one is available) or contacts 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.

Parm Name: AutoTime

Option Name Description Note Requires
false (unchecked) Disables AutoTime, preventing the device from automatically setting the Date and Time using values acquired from a network.

OSX: 1.3+

MX: 4.2+

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

OSX: 1.3+

MX: 4.2+

NTP Server Address

Used to enter 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: The Auto Time checkbox is "checked"

Parm Name: NTPServer

Requires:

  • MX: 4.2+
  • Android API: 19+

Set Sync Interval

Used to enter 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: The Auto Time checkbox is "checked"

Parm Name: SyncInterval

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

MX: 4.2+

Android API: 16+

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

MX: 4.2+

Android API: 16+

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

MX: 4.2+

Android API: 16+

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

MX: 4.2+

Android API: 16+

Coordinate System

Used to select the Time and Date coordinates to be entered into the device for setting the system clock. Selecting Universal (option 1) causes values entered using UTCDate and UTCTime parameters to be converted by the Clock CSP to local time based on offsets for Time Zone and Daylight Saving Time.

Also see the LTC Calculation Examples section of this guide.

Shown if: The Auto Time checkbox is "unchecked"

Parm Name: CoordinateSystem

Option Name Description Note Requires
0 Local Configures the device to accept local Time (relative to the device location), adjusted for Time Zone.

MX: 10.2+

1 Universal Configures the device to accept Coordinated Universal Time (UTC), the absolute time at the Prime Meridian.

MX: 10.2+

Set Date

Used to manually set the local Date on the device. Entering an empty value (or the absence of this parm from the XML) causes the previously configured Date to remain unchanged.

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"

Note: This parameter DOES NOT perform adjustments to UTC values based on time zone or Daylight Savings offsets. To enable such functionality, select "Universal" in the Coordinate System parameter and enter date and time using the UTCDate and UTCTime parameters.

Shown if: The Auto Time checkbox is "unchecked" AND "Coordinate System" is set to Local

Parm Name: Date

Requires:

  • MX: 4.1+
  • Android API: 8+

Set Time

Used to set the local Time on the device. Entering an empty value (or the absence of this parm from the XML) causes the previously configured Time to remain unchanged.

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)

Note: This parameter DOES NOT perform adjustments to UTC values based on time zone or Daylight Savings offsets. To enable such functionality, select "Universal" in the Coordinate System parameter and enter date and time using the UTCDate and UTCTime parameters.

Shown if: The Auto Time checkbox is "unchecked" AND "Coordinate System" is set to Local

Parm Name: Time

Requires:

  • MX: 4.1+
  • Android API: 8+

Set UTC Date

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

For more information, see the LTC Calculation Examples section of this guide.

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: The Auto Time checkbox is "unchecked" AND "Coordinate System" is set to Universal

Parm Name: UTCDate

Requires:

  • MX: 10.2+

Set UTC Time

Used to set the UTC Time for automatic calculation of the local time for the device. Date and Time values given to the Clock using this parameter must be represented as UTC (see Overview). Entering an empty value (or the absence of this parm from the XML) will retain any previously configured Time.

For more information, see the LTC Calculation Examples section of this guide.

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: The Auto Time checkbox is "unchecked" AND "Coordinate System" is set to Universal

Parm Name: UTCTime

Requires:

  • MX: 10.2+

Set Time Zone

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

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: The Auto Time Zone checkbox is "unchecked"

Parm Name: TimeZone

Requires:

  • MX: 4.1+

Auto Time Zone (checkbox)

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 Note Requires
false (unchecked) Disables Auto Time Zone, preventing the device from automatically acquiring the Time Zone from the carrier network.

OSX: 1.3+

MX: 6.0+

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

OSX: 1.3+

MX: 6.0+

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 Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no change to time display format; any previously selected setting is 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

The examples in this section apply only to UTCDate and UTCTime parameters, which accept values based on the Coordinated Universal Time (UTC) standard.

When using UTCDate and UTCTime parameters, values given to the Clock must be represented as UTC values. 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 the Local Time Coordinate (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 recalculates the value to arrive at the desired local time for display by the device and for use in applications.

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 also 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 recalculates 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>