Timestamp is a feature that enables you to track the date at which an event occurs. You can track as many events as you want, timing information is saved in the system with the value associated to events.
How to timestamp data
Let's take an example with a button driver: each time we read the button state, we want to timestamp this event. First, we must create a global variable called a token, used to track our event in the system:
Then, we can tag the data related to the button event with this token:
The function Timestamp_Tag links the token to the data. This enables several features:
- If you use
button.statein an another function in your service, you can check if there is a timestamp linked to the data and get it from the token with Timestamp_GetToken and Timestamp_GetTimeFromToken functions.
- If you send
button.statethrough a Luos message, the timestamp will be copied into the message. Then you can get it from the message in the receiving service with the Timestamp_DecodeMsg function.
How to create a timestamped event
Timestamp API also allows you to tag an event instead of data. The idea is to create a command, attach a timestamp information to it, and send it to a service.
The service which receives this information can execute the command at the date specified by the timestamp. This is a really interesting feature if you want to execute actions at precise dates. It also releases the constraints on messages exchanged on the network, as you can send them by batch: each message carries a timestamped event which will be processed at the defined date.
In the API, Timestamp_CreateEvent enables you to use this feature. You have to give to this function the same arguments that you give to timestamp_tag, plus an argument called relative_date. This last one carries information about when the event has to be processed, with unit in nanoseconds. If you want your event to be processed in 1 second, put 1000000000 in this argument.
All timestamp API's functions can be found in Luos/Robus/inc/timestamp.h. You can also find examples that are using this feature. For now, the examples using timestamp are the following:
- light sensor
|Tag data with a token|
|Get a token from data|
|Check if a message is timestamped|
|Update the timestamp in a message|
|Encode a message with the timestamp protocol|
|Decode a timestamped message|
|Create a timestamped event|