rostime

Access ROS time functionality

Description

A ROS Time message represents an instance of time in seconds and nanoseconds. This time can be based on your system time, the ROS simulation time, or an arbitrary time.

Creation

Syntax

time = rostime(totalSecs)

time = rostime(secs,nsecs)

time = rostime("now")

[time,issimtime] = rostime("now")

time = rostime("now","system")

time = rostime(___,"DataFormat","struct")

Description

time = rostime(totalSecs) initializes the time values for seconds and nanoseconds based on totalSecs, which represents the time in seconds as a floating-point number.

Note

In a future release, ROS Toolbox will use message structures instead of objects for ROS messages.

To use message structures now, set the "DataFormat" name-value argument to "struct". For more information, see ROS Message Structures.

time = rostime(secs,nsecs) initializes the time values for seconds and nanoseconds individually. Both inputs must be integers. Large values for nsecs are wrapped automatically with the remainder added to secs.

time = rostime("now") returns the current ROS time. If the use_sim_time ROS parameter is set to true, the rostime returns the simulation time published on the clock topic. Otherwise, the function returns the system time of your machine. The time is a ROS Time object. If no output argument is given, the current time (in seconds) is printed to the screen.

The rostime can be used to timestamp messages or to measure time in the ROS network.

[time,issimtime] = rostime("now") also returns a Boolean that indicates if time is in simulation time (true) or system time (false).

time = rostime("now","system") always returns the system time of your machine, even if ROS publishes simulation time on the clock topic. If no output argument is given, the system time (in seconds) is printed to the screen.

The system time in ROS follows the UNIX^® or POSIX^® time standard. POSIX time is defined as the time that has elapsed since 00:00:00 Coordinated Universal Time (UTC), 1 January 1970, not counting leap seconds.

time = rostime(___,"DataFormat","struct") uses message structures instead of objects with any of the arguments in previous syntaxes. For more information, see ROS Message Structures.

Properties

totalSecs — Total time

0 (default) | scalar

Total time, specified as a floating-point scalar. The integer portion is set to the Sec property with the remainder applied to Nsec property of the Time object.

Sec — Whole seconds

0 (default) | positive integer

Whole seconds, specified as a positive integer.

Note

The maximum and minimum values for secs are [0, 4294967294].

Nsec — Nanoseconds

0 (default) | positive integer

Nanoseconds, specified as a positive integer. It this value is greater than or equal to 10⁹, then the value is wrapped and the remainders are added to the value of Sec.

DataFormat — Message format

"object" (default) | "struct"

Message format, specified as "object" or "struct". You must set this property on creation using the name-value input. For more information, see ROS Message Structures.

Examples

Get Current ROS Time

Connect to a ROS network.

rosinit

Launching ROS Core...
Done in 0.70998 seconds.
Initializing ROS master on http://172.20.145.92:58534.
Initializing global node /matlab_global_node_59040 with NodeURI http://dcc496324glnxa64:44695/ and MasterURI http://localhost:58534.

Get the current ROS Time as a ROS message structure. You can also check whether is it system time by getting the issim output.

[t,issim] = rostime('now','DataFormat','struct')

t = struct with fields:
     Sec: 1737612496
    Nsec: 47372093

issim = logical
   0

Shutdown the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_59040 with NodeURI http://dcc496324glnxa64:44695/ and MasterURI http://localhost:58534.
Shutting down ROS master on http://172.20.145.92:58534.

Timestamp ROS Message Data

Initialize a ROS network.

rosinit

Launching ROS Core...
Done in 0.47424 seconds.
Initializing ROS master on http://172.20.224.220:59819.
Initializing global node /matlab_global_node_10039 with NodeURI http://dcc194700glnxa64:38605/ and MasterURI http://localhost:59819.

Create a stamped ROS message using structures. Specify the Header.Stamp property with the current system time.

point = rosmessage('geometry_msgs/PointStamped','DataFormat','struct');
point.Header.Stamp = rostime('now','system','DataFormat','struct');

Shut down the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_10039 with NodeURI http://dcc194700glnxa64:38605/ and MasterURI http://localhost:59819.
Shutting down ROS master on http://172.20.224.220:59819.

ROS Time to MATLAB Time Example

This example shows how to convert current ROS time into a MATLAB® standard time. The ROS Time object is first converted to a double in seconds, then to the specified MATLAB time.

Set up ROS network and store the ROS time as a structure message.

rosinit

Launching ROS Core...
Done in 0.74908 seconds.
Initializing ROS master on http://172.20.146.75:56569.
Initializing global node /matlab_global_node_80326 with NodeURI http://dcc554194glnxa64:37047/ and MasterURI http://localhost:56569.

t = rostime('now','DataFormat','struct');

Convert ROS Time to double using the seconds function and set time to a specified MATLAB format, datetime.

time = datetime(t.Sec + 10^-9*t.Nsec,'ConvertFrom','posixtime')

time = datetime
   23-Jan-2025 06:07:49

Shut down ROS network.

rosshutdown

Shutting down global node /matlab_global_node_80326 with NodeURI http://dcc554194glnxa64:37047/ and MasterURI http://localhost:56569.
Shutting down ROS master on http://172.20.146.75:56569.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2019b

R2021a: ROS Message Structures

You can now create messages as structures with fields matching the message object properties. Using structures typically improves performance of creating, updating, and using ROS messages, but message fields are no longer validated when set. Message types and corresponding field values from the structures are validated when sent across the network.

To use ROS messages as structures, use the "DataFormat" name-value argument when creating your publishers, subscribers, or other ROS objects. Any messages generated from these objects will utilize structures.

pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")
msg = rosmessage(pub)

You can also create messages as structures directly, but make sure to specify the data format as "struct" for the publisher, subscriber, or other ROS objects as well. ROS objects still use message objects by default.

msg = rosmessage("/scan","sensor_msgs/LaserScan","DataFormat","struct")
...
pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")

In a future release, ROS messages will use structures by default and ROS message objects will be removed.

For more information, see Improve Performance of ROS Using Message Structures.