syncWithHeadsetClock

This method lets you synchronize the monotonic clock of your application with the monotonic clock of Cortex. It is an important step if you want to inject markers with a high precision.

Cortex uses a different clock for each headset and it initializes this clock when the headset is connected by Bluetooth or USB dongle. This means that:

• You must call “syncWithHeadsetClock” after the headset is connected, not before.

• You must provide a headset id.

• If the headset is disconnected and connected again, then you must call this method again.

The simplest solution is to call this method just before creating a record.

Use Case

Cortex sets the timestamps of each EEG sample using the monotonic clock of the computer. It is more reliable than using the system clock, because the system clock is subject to unpredictable variations, notably because of the NTP synchronization.

When you add a marker to a record, Cortex uses the parameter "time" of your request to associate the marker with the EEG sample that has the closest timestamp. So if you want to have accurate markers, you should set the time of your markers using the monotonic clock, not the system clock.

Most programing languages provide a function to get a monotonic time. But in general, the point of origin of this time is undefined. So you need to synchronize the monotonic clock of your application with the monotonic clock used by Cortex. This is the purpose of this Cortex API method.

Parameters

This method takes 3 parameters:

Name	Type	Required	Description
headset	string	yes	The headset id. Use queryHeadset to list available headsets.
monotonicTime	number	yes	The monotonic time of your application. The unit is in seconds. The origin can be anything. You should get this time right before you call this API.
systemTime	number	yes	The system time of your application. It must be the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970 UTC. You should get this time right before you call this API.

Result

The result is a JSON object with these fields:

Name	Type	Description
headset	string	The headset id.
adjustment	number	The difference between the monotonic clock of your application and the monotonic clock of the headset. The unit is in seconds.

To synchronize your clock, you must add the “adjustment” to your monotonic times. If the “adjustment” is positive, then it means your clock is late compared to the Cortex clock. If the “adjustment” is negative, then your clock is ahead of the Cortex clock.

Example

Request

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "syncWithHeadsetClock",
  "params": {
    "headset": "INSIGHT-587XX4BB",
    "monotonicTime": 321.445,
    "systemTime": 1629978090.302
  }
}

Response

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "adjustment": 1629977768.86108,
    "headset": "INSIGHT-587XX4BB"
  }
}