Time Measurement

Table of Contents

• Accuracy
• Resolution
• Time Domain

CAN messages are time stamped as they arrive. This time stamping is, depending on your hardware platform, done either by the CAN interface hardware or by CANlib.

In the former case, the accuracy is pretty good, in the order of 1 - 10 microseconds; when CANlib does the job, the accuracy is more like 100 microseconds to 10 milliseconds and you may experience a rather large jitter. This is because Windows is not a real-time operating system.

The resolution of the time stamps is, by default, 1 ms. It can be changed to a better resolution if desired.

Use canReadTimer() to read the current time. You must pass the handle of an open channel to this API call; the return value is the current time using the clock of that channel.

Use canIoCtl() with a function code of canIOCTL_SET_TIMER_SCALE to change the resolution of the time stamps, if desired. This will not affect the accuracy of the time stamps.

Accuracy

The accuracy of the time stamps depends on the hardware.

The members of the Kvaser Leaf family have an onboard CPU. The time stamp accuracy varies (check the hardware manual) but the high-end members have very precise time stamping. The accuracy can be as good as one microsecond depending on the hardware. If more than one Leaf is used, their clocks are automatically kept in sync by the Kvaser MagiSync™ technology.

Other CAN interfaces, like the Kvaser Leaf, LAPcan and USBcan II, have an on-board CPU and clock and provide very accurate time stamps for incoming CAN messages. The accuracy is typically 10-20 microseconds.

Certain interfaces, like the PCIcan (PCI) series of boards, don't have an on-board CPU so the driver relies on the clock in the PC to timestamp the incoming messages. As Windows is not a real-time operating system, this gives an accuracy which is in the order of one millisecond.

Resolution

The resolution of the time stamps is, by default, 1 ms. It can be changed by calling canIoCtl() with the canIOCTL_SET_TIMER_SCALE function code.

Time Domain

The time domain is a system to group a set of devices to a common time which can be useful for time synchronised applications between multiple devices.

While all kvaser devices supports the use of time domains they can get out of sync over time, to avoid this some devices have support for MagiSync™ which will continuously apply an offset to their clocks to compensate for any drifting that may occur.

After creating a time domain and adding handles to it, use kvTimeDomainResetTime() to reset the time of the domain.

Note

For the time domain to function properly all devices that are part of it should be connected to the same root usb hub.

• kvTimeDomainCreate()
• kvTimeDomainDelete()
• kvTimeDomainResetTime()
• kvTimeDomainGetData()
• kvTimeDomainAddHandle()
• kvTimeDomainRemoveHandle()

Example. The following code fragment resets the time for some already opened channels. It also collects and interprets some data from a domain.

#define NUMBER_OF_CHANNELS 3
CanHandle hnd[NUMBER_OF_CHANNELS];
canStatus stat;
int i;
kvTimeDomain tDomain;
kvTimeDomainData tData;

...

// Create a time domain for my handles.
stat = kvTimeDomainCreate(&tDomain);
if (stat < 0) {
    printf("Failed, status == %d\n", stat);
}

// Add the handles to the domain.
for (i = 0; i < NUMBER_OF_CHANNELS; i++) {
  stat = kvTimeDomainAddHandle(tDomain, hnd[i]);
  if (stat < 0) {
      printf("Failed to add handle %u to tDomain, ", i);
      printf("status == %d\n", stat);
  }
}

// Request some data from the domain and try to interpret it.
stat = kvTimeDomainGetData(tDomain, &tData; sizeof(tData));
if (stat < 0) {
    printf("Failed, status == %d\n", stat);
}

if (tData.nMagiSyncGroups > 1) {
  printf("Consider connecting the Kvaser MagiSync&tm; enabled ");
  printf("interfaces through the same USB root hub!");
}

if (tData.nMagiSyncGroups == 1) {
  printf("All my Kvaser MagiSync&tm; enabled interfaces are ");
  printf("connected through the same USB root hub and hence ");
  printf("perfectly synchronized!");
}

if (tData.nMagiSyncedMembers == NUMBER_OF_CHANNELS) {
  printf("All handles have the Kvaser MagiSync&tm; feature enabled!");
}

// Reset the time on all handles in tDomain.
stat = kvTimeDomainResetTime(tDomain);
if (stat < 0) {
  printf("Failed, status == %d\n", stat);
}

...

// Final cleanup
stat = kvTimeDomainDelete(tDomain);
if (stat < 0) {
  printf("Failed, status == %d\n", stat);
}
else {
  printf("All resources used by tDomain and its members ");
  printf("returned to system");
}