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[source]¶

Bases: bosdyn.client.exceptions.Error

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

exception bosdyn.client.time_sync.NotEstablishedError[source]¶

Bases: bosdyn.client.time_sync.TimeSyncError

Client has not established time-sync with the robot.

exception bosdyn.client.time_sync.TimedOutError[source]¶

Bases: bosdyn.client.time_sync.TimeSyncError

Exceeded deadline to achieve time-sync.

exception bosdyn.client.time_sync.InactiveThreadError[source]¶

Bases: bosdyn.client.time_sync.TimeSyncError

Time-sync thread is no longer running.

class bosdyn.client.time_sync.TimeSyncClient[source]¶

Bases: bosdyn.client.common.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)[source]¶

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)[source]¶: Async version of get_time_sync_update()

bosdyn.client.time_sync.robot_time_range_from_nanoseconds(start_nsec, end_nsec, time_sync_endpoint=None)[source]¶

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

nanoseconds since the Unix epoch or None (end_nsec) –
nanoseconds since the Unix epoch or None –
Either TimeSyncEndpoint or None. (time_sync_endpoint) –

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)[source]¶

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)[source]¶

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

'{val}-{val}' or '{val}' time spec string (timespan_spec) –
Either TimeSyncEndpoint or None. (time_sync_endpoint) –

Returns

return bosdyn.api.TimeRange time range in robot time

class bosdyn.client.time_sync.TimeSyncEndpoint(time_sync_client)[source]¶

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)[source]¶

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()[source]¶

Perform an update-cycle toward achieving time-synchronization.

Returns: Boolean true if valid timesync has been established.

get_robot_time_converter()[source]¶

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)[source]¶

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)[source]¶

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()[source]¶: Start the thread.

stop()[source]¶: 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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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.