Time Sync

A client for the time-sync service.

The time-sync service helps track the difference between the robot’s system clock and the system clock of clients, and sends an estimate of this difference to the client. The client uses this information when it needs to send a timestamp to the robot in a request proto. Timestamps in request protos generally need to be specified relative to the robot’s system clock.

exception bosdyn.client.time_sync.TimeSyncError

Bases: Error

General class of errors for TimeSync non-response / non-grpc errors.

exception bosdyn.client.time_sync.NotEstablishedError

Bases: TimeSyncError

Client has not established time-sync with the robot.

exception bosdyn.client.time_sync.TimedOutError

Bases: TimeSyncError

Exceeded deadline to achieve time-sync.

exception bosdyn.client.time_sync.InactiveThreadError

Bases: TimeSyncError

Time-sync thread is no longer running.

class bosdyn.client.time_sync.TimeSyncClient

Bases: BaseClient

A client for establishing time-sync with a server/robot.

default_service_name = 'time-sync'

service_type = 'bosdyn.api.TimeSyncService'

get_time_sync_update(previous_round_trip, clock_identifier, **kwargs)

Obtain an initial or updated timesync estimate with server.

Parameters:

• previous_round_trip (bosdyn.api.TimeSyncRoundTrip) – None on first rpc call, then fill out with previous response from server.

• clock_identifier (string) – Empty on first call, assigned by server in first response.

Raises:

RpcError – Problem communicating with the robot.

get_time_sync_update_async(previous_round_trip, clock_identifier, **kwargs)

Async version of get_time_sync_update()

bosdyn.client.time_sync.robot_time_range_from_nanoseconds(start_nsec, end_nsec, time_sync_endpoint=None)

Generate timespan as a TimeRange proto, in robot time.

If time_sync_endpoint is a TimeSyncEndpoint, the time_spec is in the local clock and will

be converted to robot_time.

If the input times are already in the robot clock, do not specify time_sync_endpoint and

the times will not be converted.

Parameters:

• None (end_nsec nanoseconds since the Unix epoch or) –

• None –

• None. (time_sync_endpoint Either TimeSyncEndpoint or) –

Returns:

return bosdyn.api.TimeRange time range in robot time

bosdyn.client.time_sync.robot_time_range_from_datetimes(start_datetime, end_datetime, time_sync_endpoint=None)

Generate timespan as a TimeRange proto, in robot time.

If time_sync_endpoint is a TimeSyncEndpoint, the time_spec is in the local clock and will

be converted to robot_time.

If the input times are already in the robot clock, do not specify time_sync_endpoint and

the times will not be converted.

Parameters:

• start_datetime – timestamp.timestamp or None

• end_datetime – timestamp.timestamp or None

• time_sync_endpoint – Either TimeSyncEndpoint or None.

Returns:

return bosdyn.api.TimeRange time range in robot time

bosdyn.client.time_sync.timespec_to_robot_timespan(timespan_spec, time_sync_endpoint=None)

Generate timespan as TimeRange proto, in robot time.

If time_sync_endpoint is a TimeSyncEndpoint, the time_spec is in the local clock and will

be converted to robot_time.

If the input times are already in the robot clock, do not specify time_sync_endpoint and

the times will not be converted.

Parameters:

• string (timespan_spec '{val}-{val}' or '{val}' time spec) –

• None. (time_sync_endpoint Either TimeSyncEndpoint or) –

Returns:

return bosdyn.api.TimeRange time range in robot time

bosdyn.client.time_sync.update_time_filter(client, timestamp, timesync_endpoint)

Set or convert fields of the proto that need timestamps in the robot’s clock.

Parameters:

• timestamp (float) – Client time, such as from time.time().

• timesync_endpoint (TimeSyncEndpoint) – A timesync endpoint associated with the robot object.

Raises:

bosdyn.client.robot_command.NoTimeSyncError – Could not find the timesync endpoint for the robot to convert the time.

bosdyn.client.time_sync.update_timestamp_filter(client, timestamp, timesync_endpoint)

Set or convert fields of the proto that need timestamps in the robot’s clock.

Parameters:

• timestamp (google.protobuf.Timestamp) – Client time.

• timesync_endpoint (TimeSyncEndpoint) – A timesync endpoint associated with the robot object.

Raises:

bosdyn.client.robot_command.NoTimeSyncError – Could not find the timesync endpoint for the robot to convert the time.

class bosdyn.client.time_sync.TimeSyncEndpoint(time_sync_client)

Bases: object

A wrapper that uses a TimeSyncClient object to establish and maintain timesync with a robot.

This class manages internal state, including a clock identifier and previous best time sync estimates. This class automatically builds requests passed to the TimeSyncClient, so users don’t have to worry about the details of establishing and maintaining timesync.

This object is thread-safe.

property response

The last response message from the time-sync service.

Returns:

The bosdyn.api.TimeSyncResponse proto last returned by the server, or None if unset.

property has_established_time_sync

Checks if the client has successfully established time-sync with the robot.

Returns:

Boolean true if the previous time-sync update returned that time sync is OK.

property round_trip_time

The previous round trip time.

Returns:

Round trip time as google.protobuf.Duration proto if available, otherwise None.

property clock_identifier

The clock identifier for the instance of the time-sync client.

Returns:

A unique identifier for this client. Empty if get_new_estimate has not been called.

property clock_skew

The best current estimate of clock skew from the time-sync service.

Returns:

The google.protobuf.Duration representing the clock skew.

Raises:

NotEstablishedError – Time sync has not yet been established.

establish_timesync(max_samples=25, break_on_success=False)

Perform time-synchronization until time sync established.

Parameters:

• max_samples (int) – The maximum number of times to attempt to establish time-sync through time-synchronization.

• break_on_success (bool) – If true, stop performing the time-synchronization after time-sync is established.

Returns:

Boolean true if valid timesync has been established.

get_new_estimate()

Perform an update-cycle toward achieving time-synchronization.

Returns:

Boolean true if valid timesync has been established.

get_robot_time_converter()

Get a RobotTimeConverter for current estimate for robot clock skew from local time.

Returns:

An instance of RobotTimeConvertor for the time-sync client.

Raises:

NotEstablishedError – If time sync has not yet been established.

robot_timestamp_from_local_secs(local_time_secs)

Convert a local time in seconds to a timestamp proto in robot time.

Parameters:

local_time_secs (float) – Timestamp in seconds since the unix epoch (e.g., from time.time()).

Returns:

google.protobuf.Timestamp representing local_time_secs in robot clock, or None if

local_time_secs is None.

Raises:

NotEstablishedError – Time sync has not yet been established.

class bosdyn.client.time_sync.TimeSyncThread(time_sync_client, time_sync_endpoint=None)

Bases: object

Background thread for achieving and maintaining time-sync to the robot.

DEFAULT_TIME_SYNC_INTERVAL_SEC = 60

TIME_SYNC_SERVICE_NOT_READY_INTERVAL_SEC = 5

start()

Start the thread.

stop()

Shut down the thread if it is running.

property time_sync_interval_sec

Returns interval at which time-sync is updated in the thread.

property should_exit

Returns True if thread should stop iterating.

wait_for_sync(timeout_sec=3.0)

Wait for up to the given timeout for time-sync to be achieved

Parameters:

timeout_sec (float) – Maximum time (seconds) to wait for time-sync to be achieved.

Raises:

• InactiveThreadError – Thread is not running.

• time_sync.TimedOutError – Deadline to achieve time-sync is exceeded.

• Threading Exceptions – Errors from threading the processes.

property has_established_time_sync

Checks if the client has successfully established time-sync with the robot.

Returns:

Boolean true if the previous time-sync update returned that time sync is OK.

property stopped

Returns True if thread is no longer running.

property thread_exception

Return any exception which ended the time-sync thread.

property endpoint

Return the TimeSyncEndpoint used by this thread.

get_robot_clock_skew(timesync_timeout_sec=0)

Get current estimate for robot clock skew from local time.

Parameters:

timesync_timeout_sec (float) – Time to wait for timesync before doing conversion.

Returns:

Clock skew as a google.protobuf.Duration object

Raises:

• InactiveThreadError – Time-sync thread exits before time-sync.

• time_sync.TimedOutError – Deadline to achieve time-sync is exceeded.

• Threading Exceptions – Errors from threading the processes.

get_robot_time_converter(timesync_timeout_sec=0)

Get a RobotTimeConverter for current estimate for robot clock skew from local time.

Parameters:

timesync_timeout_sec (float) – Time to wait for timesync before doing conversion.

Raises:

• InactiveThreadError – Time-sync thread exits before time-sync.

• time_sync.TimedOutError – Deadline to achieve time-sync is exceeded.

• Threading Exceptions – Errors from threading the processes.

robot_timestamp_from_local_secs(local_time_secs, timesync_timeout_sec=0)

Convert a local time in seconds to a timestamp proto in robot time.

Parameters:

• local_time_secs (float) – Timestamp in seconds since the unix epoch (e.g., from time.time()).

• timesync_timeout_sec (float) – Time to wait for timesync before doing conversion.

Returns:

google.protobuf.Timestamp representing local_time_secs in robot clock, or None if local_time_secs is None.

Raises:

• InactiveThreadError – Time-sync thread exits before time-sync.

• time_sync.TimedOutError – Deadline to achieve time-sync is exceeded.

• Threading Exceptions – Errors from threading the processes.