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.
-
-
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.
-
property
-
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¶
-
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.
-