Skip to main content
For the complete documentation index, see llms.txt.

Hubble Network developer documentation: integrate Bluetooth devices with terrestrial and satellite connectivity.

Timing Management

Proper time management is critical for ensuring accurate encryption and secure operations in the SDK. Below are the best practices for provisioning UTC time and accounting for drifts.

Provisioning UTC Time​

To ensure the SDK operates with accurate time, follow these steps to provision Coordinated Universal Time (UTC).

1. Obtain Accurate Time Source:

  • Use a reliable time source such as an NTP (Network Time Protocol) server or GPS.
  • Ensure the time source is synchronized and trusted to avoid tampering.

2. Set System Time: Use the Hubble API to set the obtained UTC time.

3. Validate Time Synchronization:

  • Periodically validate the system time against the trusted time source.
  • Log any discrepancies for debugging and auditing purposes.

Accounting for Time Drifts​

Time drifts can occur due to hardware clock inaccuracies. To mitigate this, follow these practices:

Periodic Time Synchronization​

  • Regularly synchronize the system clock with the trusted time source.
  • Use a configurable interval based on the expected drift rate of the hardware clock.

Monitor Drift​

  • Measure the drift rate of the hardware clock during testing.
  • Use this information to adjust the synchronization interval.

Apply Drift Compensation​

Implement drift compensation logic to adjust the system clock between synchronizations.

Time Persistence Across Power Cycles​

To accommodate a certain amount of drift and ensure time persistence across power cycles, you can use alternative methods such as storing the time in flash memory or other persistent storage. Below are recommendations, risks, and a workflow for managing time in such scenarios.

Alternatives for Time Persistence Across Reboots​

MethodApproachRisks
Store Time in Flash MemoryWrite the current UTC time to flash memory before a power cycle or periodically during operation.1. Flash Wear: Flash memory has a limited number of write cycles. Frequent writes can lead to premature wear.
2. Tearing: If a power failure occurs during a write operation, the data may become corrupted.
3. No Time Gap Information: Flash storage does not provide information about how long the device was powered off.
Store Time in Non-Volatile RAM (NVRAM)Use NVRAM or battery-backed RAM to store the current UTC time. This method avoids flash wear and allows faster read/write operations.1. Hardware Dependency: Requires specific hardware support for NVRAM.
2. Battery Depletion: If the battery backing the RAM depletes, the stored time will be lost.
Use an RTC DeviceIf the hardware includes an RTC, initialize it with the current UTC time and use it as a persistent time source. This is the most reliable method for time persistence across reboots.RTC Drift: The RTC may drift over time and require periodic synchronization.
Hybrid ApproachCombine flash storage and RTC. Use the RTC for short-term persistence and flash storage as a backup in case of RTC failure or battery depletion.Complexity: Increases system complexity and requires careful coordination between the two methods.

Below is a recommended workflow for managing time in the SDK:

1. Device Boots

  • Retrieve the last known time from persistent storage (e.g., flash, NVRAM, or RTC).
  • If no valid time is available, initialize the system to a default value (e.g., epoch time).

2. Wait to Sync Time

  • Attempt to synchronize the system clock with a trusted time source (e.g., NTP server or GPS).
  • Block critical operations that depend on accurate time until synchronization is complete.

3. Start Tracking Time

  • Once synchronized, start tracking time using the system clock.
  • Periodically log the current time for debugging and auditing purposes.

4. Retrieve A New Advertisement

  • You may retrieve a new advertising packet with an application-defined custom payload between 1 and 1,024 times per day.
  • This limit is imposed by the sequence number size in the advertising payload.
  • Make sure to retrieve at least 1 packet per day, to maintain encrypted transmissions on the network.

5. Monitor Drift

  • Continuously monitor the drift of the system clock.
  • If the drift exceeds a predefined threshold, trigger a resynchronization with the trusted time source.

6. Handle Resynchronization

  • During resynchronization, adjust the system clock to the correct UTC time.
  • Log the adjustment to maintain an audit trail.

Encryption and Time Dependency​

Encryption often relies on accurate time for operations such as generating time-based keys or validating timestamps.

Follow these implementation guidelines:

  1. Ensure the system clock is synchronized before performing encryption-related tasks.
  2. Log the UTC time used for encryption to facilitate debugging and auditing.

Implementation Recommendations​

By following these best practices, you can ensure accurate time management in the SDK, which is essential for secure and reliable encryption.

  • Use the log functionality to record time synchronization events and drift adjustments.
  • Test the SDK on hardware with varying clock drift rates to ensure robustness.
  • Consider implementing fallback mechanisms if the primary time source becomes unavailable.
  • Limit the number of unique advertising packets to betweeen 1 and 1,024 to avoid replay attacks with the same sequence number.