Skip to content

NTP Sync Stage

Summary

  • Internal name: SyncNtp
  • Category: Time
  • Purpose: Synchronize device time with an NTP server to get accurate network time offset and round-trip time (RTT).
  • Task type: Normal

Compatibility

  • Minimum AndroMate version: 1.1.0
  • Maximum AndroMate version: 1.1.0
  • Minimum Android version: Android 13 (API 33)

  • Maximum Android version tested: Android 16 (API 36)

  • Supported manufacturers:

  • ✅ All manufacturers (tested on Samsung One UI 6.x / 7.x / 8.x and Google Pixel Android Stock)

  • Required permissions:

  • INTERNET

Detailed description

The NTP Sync task synchronizes the device with an NTP (Network Time Protocol) server to retrieve accurate time information.

It is used to:

  • Get accurate network time offset
  • Measure network round-trip time (RTT)
  • Synchronize device time with authoritative time servers
  • Validate system clock accuracy

Implementation details

  • RFC 5905 compliant: Full SNTP (Simple Network Time Protocol) implementation
  • Monotonic safe: Uses SystemClock.elapsedRealtime() for accurate timing
  • RTT filtering: Rejects responses with invalid RTT (> 1000 ms)
  • Timestamp validation: Validates originate timestamp to ensure response authenticity
  • Timeout handling: Configurable timeout for the NTP request

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
ntp_server String No Valid NTP server hostname Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 time.google.com

Output parameters

Field Type Trigger condition Android Compatibility AndroMate Compatibility Default
offset_ms_output Long When NTP sync succeeds Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>
rtt_ms_output Long When NTP sync succeeds Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>

Exceptions

Code Exception Name Description
SYNC-NTP-TASK-001 NTP Client Error Failed to communicate with NTP server (IOException) or received invalid response.

Execution flowchart

flowchart TD
    Start([Start NTP Sync]) --> ResolveParams[🔄 Resolve Parameters<br/>NTP server]

    ResolveParams --> SendRequest[📡 Send NTP Request<br/>Timeout: 5000ms]

    SendRequest -->|Success| Validate[✓ Validate Response<br/>RFC 5905 checks]
    SendRequest -->|Timeout/Error| E1[❌ SYNC-NTP-TASK-001]

    Validate -->|Valid| CalcMetrics[🔢 Calculate Offset & RTT<br/>Validate RTT &lt;= 1000ms]
    Validate -->|Invalid| E1

    CalcMetrics -->|RTT Invalid| E1
    CalcMetrics -->|Success| StoreResult[💾 Store Result<br/>NtpTaskResult]

    StoreResult --> LogReport[📋 Log Report<br/>Offset + RTT]

    LogReport --> Success([✅ Success])

    E1 --> Error([❌ Exception])

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style SendRequest fill:#f3e5f5
    style Validate fill:#fff9c4
    style CalcMetrics fill:#fff9c4
    style StoreResult fill:#c8e6c9

How it works:

  1. Resolve parameters: Resolves NTP server hostname
  2. Send NTP request: Sends SNTP request with 5-second timeout
  3. Validate response: Checks RFC 5905 compliance (LI, version, mode, stratum, timestamps)
  4. Calculate metrics: Computes time offset and RTT, validates RTT <= 1000ms
  5. Store result: Saves offset and RTT values
  6. Log report: Records execution details
  7. Result: Returns NtpTaskResult or exception

Input parameter details

1. Input parameter: ntp_server

NTP server hostname to synchronize with.

NTP server hostname to synchronize with.

Default value

time.google.com (Google Public NTP Server)

Possible values

  • time.google.com (Google)
  • pool.ntp.org (NTP Pool Project)
  • time.nist.gov (NIST)
  • Custom NTP server hostname

Example

"ntp_server": "pool.ntp.org"

Output parameter details

1. Result variable: offset_ms_output

Time offset between device and NTP server in milliseconds.

Example

"offset_ms_output": "$NTP_OFFSET"

Notes

  • Positive value: Device time is ahead of NTP server
  • Negative value: Device time is behind NTP server
  • Value represents milliseconds

2. Result variable: rtt_ms_output

Round-trip time (RTT) for NTP request in milliseconds.

Example

"rtt_ms_output": "$NTP_RTT"

Notes

  • Lower values indicate faster network connection
  • Maximum accepted value: 1000 ms
  • Requests with RTT > 1000 ms are rejected

Complete JSON example

{
  "SyncNtp": [
    {
      "id": "-1",
      "title": "NTP Sync",
      "ntp_server": "time.google.com",
      "offset_ms_output": "$OFFSET_MS",
      "rtt_ms_output": "$RTT_MS"
    }
  ]
}

NTP Schema and Formulas

Timestamps Diagram

         t'₂         t'₃
          ↑           ↑
    ------|-----------|------  SERVER
          |           |
         δ₁          δ₂
         ↙            ↘
    ----•----•-----------•---- CLIENT
       t₁   δ₁          δ₂   t₄

Schema Explanation: - t₁ : Client request send time - t'₂ : Server request receive time - t'₃ : Server response send time - t₄ : Client response receive time - δ₁ : Network delay (client → server) - δ₂ : Network delay (server → client)

Timestamps

Timestamp Description Source
t₁ Client request send time Client (wall-clock)
t'₂ Server request receive time Server (NTP)
t'₃ Server response send time Server (NTP)
t₄ Client response receive time Client (wall-clock)
δ₁ Network delay (client → server) Network delay
δ₂ Network delay (server → client) Network delay

Calculation Formulas

Round-Trip Time (RTT)

RTT = (t₄ - t₁) - (t'₃ - t'₂)
    = δ₁ + δ₂

Explanation: - (t₄ - t₁) : Total elapsed time on client side - (t'₃ - t'₂) : Server processing time - Result : Pure network latency (sum of both delays)

Time Offset

Offset = ((t'₂ - t₁) + (t'₃ - t₄)) / 2
       = (δ₁ - δ₂) / 2

Explanation: - (t'₂ - t₁) : Offset at reception - (t'₃ - t₄) : Offset at transmission - Division by 2 : Average of both measurements - Result : Difference between server time and client time

Concrete Example

Network delays: δ₁ = 50 ms, δ₂ = 50 ms
Time offset: -100 ms

t₁ = 1000 ms (client sends)
t'₂ = 1050 ms (server receives) = t₁ + δ₁
t'₃ = 1100 ms (server sends) = t'₂ + 50 ms (processing)
t₄ = 1150 ms (client receives) = t'₃ + δ₂

RTT = (1150 - 1000) - (1100 - 1050)
    = 150 - 50
    = 100 ms ✓ (δ₁ + δ₂ = 50 + 50 = 100)

Offset = ((1050 - 1000) + (1100 - 1150)) / 2
       = (50 + (-50)) / 2
       = 0 / 2
       = 0 ms

Validations Performed

Check Condition Description
Valid RTT 0 < RTT ≤ 1000 ms Rejects responses with invalid latency
Originate timestamp |originate - t1| ≤ 5 ms Validates that response is authentic
Transmit timestamp t3 ≠ 0 Verifies server sent a response
Server mode mode = 4 or 5 Accepts server or broadcast responses
Stratum 0 < stratum ≤ 15 Validates quality of time source
Leap Indicator LI ≠ 3 Rejects if server not synchronized
NTP Version 3 ≤ version ≤ 4 Accepts NTP v3 and v4
  • SNTP Client: RFC 5905 compliant implementation
  • Timeout: Fixed 5-second timeout for NTP request
  • RTT Filter: Responses with RTT > 1000 ms are rejected for mobile safety
  • Timestamp Validation: Originate timestamp must match within 5 ms tolerance
  • Monotonic Timing: Uses SystemClock.elapsedRealtime() for accurate timing calculations
  • No Permissions Cache: Internet permission required for NTP communication