Question about the handy API getServerTime endpoint

devforxxx · January 23, 2021, 5:11pm

Hello All,

I’m building something that interacts with the handy but having issues understanding the explanation behind the getServerTime endpoint.

I undestand the first bit, that I need to first get an average of round trip time RTD, but then it mentions Ts_est = Ts + RTD/2 saying Ts is the “received value server time value” and from there until the end I’m lost.

I was wondering if anyone could provide a quick example in pseudo code or any language of how to do all that math, or at least another explanation about what each value is, cause I don’t understand the definitions.

Thanks!

Jupiter · January 23, 2021, 5:44pm

you may want to @defucilis and @Lucifie

Liquid · January 23, 2021, 7:16pm

There are two things to consider:

The delay between your pc and the handy api server (ping, roundtrip, whatever)
The time offset of your pc clock and the servers clock

The server send its timestamp in the response, so you might end up with an effective offset several seconds higher than the pure communication delay, or even a negative offset.

ScriptPlayer implementation for reference:

github.com

FredTungsten/ScriptPlayer/blob/7b1a7289908dad38bb51e22f2020996b5a85a94d/ScriptPlayer/ScriptPlayer.Shared/Devices/TheHandy/HandyController.cs#L680


      
          /// Ask server X times about the server time(Ts). A higher value results in longer syncing time but higher accuracy.A good value is to use 30 messages (X = 30).
          /// Each time a message is received track the Round Trip Delay(RTD) of the message by timing message send time(Tsend) and message receive time(Treceive). Calculate RTD = Treceive – Tsend.
          /// Calculate the estimated server time when the message is received(Ts_est) by adding half the RTD time to the received value server time value(Ts). Ts_est = Ts + RTD/2.
          /// Calculate the offset between estimated server time(Ts_est) and client time(Tc). Upon receive Tc == Treceive => offset = Ts_est - Treceive.Add the offset to the aggregated offset value(offset_agg). offset_agg = offset_agg + offset.
          /// When all messages are received calculate the average offset(offset_avg) by dividing aggregated offset(offset_agg) values by the number of messages sent(X). offset_avg = offset_agg / X
          /// 
          /// --Calculating server time
          /// When sending serverTime(Ts) to Handy calculate the Ts by using the average offset(offset_avg) and the current client time(Tc) when sending a message to Handy.Ts = Tc + offset_avg
          /// </summary>
          /// <remarks>/getServerTime</remarks>
          public void CalcServerTimeOffset()
          {
              // due too an api rate limit of I think 60 request per minute I chose just 10 attempts instead of 30...
              const int maxSyncAttempts = 20;
              const int warmupAttempts = 2;
          
          
    long offsetAggregated = 0;
          
          
    long minDelay = long.MaxValue;
              long maxDelay = long.MinValue;

In short:

To estimate what the time at the server is right now you take the serverTime from your response and add half your roundtrip (= time when you received the answer - time when you sent the request).

For a better result, do this 10-30 times and take the average.
(In my code there are 2 warmup requests because the first one might take a bit longer, which slightly skews the average)

This timespan is now your offset. So every time you send a message that requires a serverTime, you take the time of your PC and add that offset.

Lucifie · January 23, 2021, 7:17pm

This one is difficult…

I will send you a code example by DM that I got a while ago. I had to convert that and expanded it for my needs.

devforxxx · January 23, 2021, 7:22pm

Thanks for the easy to understand explanation

defucilis · January 23, 2021, 10:22pm

Also if you want another example, the HandyConnection script in my Handy Unity SDK on GitHub demonstrates how to do the synchronization stuff - might be helpful if you’re a C# programmer

github.com

defucilis/TheHandyUnity/blob/master/HandyConnection.cs

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using UnityEngine;


namespace Defucilis.TheHandyUnity
{
    /// <summary>
    /// Main class for accessing Handy functions
    /// </summary>
    public static class HandyConnection
    {
        /// <summary>
        /// The Handy connection key - required for all API functionality!
        /// </summary>
        public static string ConnectionKey { get; set; }

This file has been truncated. show original

system · February 6, 2022, 5:13pm

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.