A Recorder is a type of implementation that records a specific Dataflow upon query of the Heex Agent. A Recorder produces an Event Recording.

Any Recorder you are using shall be a customized implementation based on the Recorder class.

​
Building your Recorder

To integrate recorders in your project you have to build them with Heex SDK and libraries. See HeexSDK integration for more details.

​
Recorder main APIs

You need to create a class that inherits from the Recorder class. Don’t forget to include the required files as seen previously with the monitor implementation.

class myRecorder : public Recorder

The first thing needed is to call the Recorder class’ constructor :

Recorder(const std::string& id, const std::string& serverIp, const unsigned int& serverPort)

After that, it is necessary to overridde two methods of the Recorder class.

virtual bool generateRequestedLabels(const Heex::RecorderArgs::EventRecordingLabelsQuery& query, HeexMessages::RecorderArgs::RecorderLabels& labels)

virtual bool generateRequestedFilePaths(const Heex::RecorderArgs::RecorderEventRecordingPartArgs& query, std::string& filepath)

​
Overriding generateRequestedLabels method to provide labels

Labels are a set of customer defined keys and values picked by the recorders from the data flows to contextualize events.

It takes the form of a short string that will be sent to be visible on the event page of the Heex Cloud.

On this example, you can see we contextualized our event with the GNSS coordinates of where the event occured. But we could have added external temperature, speed, tire pressure, etc.

Note that there are several special label keys that trigger behaviors when received by our Heex Cloud:

  • position key with a value set to the latitude and longitude in decimal degrees, separated by a comma and space character, for example "48.8580644, 2.3850982".

    ℹ️ Info:

    This will add a map to the event page on the Heex Cloud pointing the event location.

  • tag key will add the value to the event tags on the Heex Cloud. You can add multiple tags at once by separating them with the pipe character like so : "Tag 1|Tag 2|Tag 3".

  • sessionId key with a free text value that could be used to group events by session or drive. In the near future, the Heex Cloud will allow you to filter events by this value.

​
Add Labels

In the generateRequestedLabels() method of your recorder’s implementation, you can use the structure labels to add labels as keys and values.

labels.addLabel(key, value);

↳ Is used to assign the value to the key. Key and value are added to the RecorderLabels structure.

labels.addLabel(HeexGps(latitude, longitude))

↳ Is an overload of the addLabel method that takes a HeexGps type as an input. It is used to quickly assign separate latitude and longitude to the key "position" key.


You have access to all info about the query such as Recorder id (query.id), Event id (query.eventId) and requested timestamp (query.timestamp)…
See the EventRecordingLabelsQuery structure in the Query content for Labels for more details.

Finally, you shall return true after adding all the labels.

⚠️ Warning: error

Returning false signals an error and stops the entire event process.

​
Overriding generateRequestedFilePaths method to provide Event Recordings

An event recording is a file or directory produced by the recorder on demand of the Heex Agent, to add substance to the event.

The query is timed around the timestamp provided by the monitor that created the event.

It can be videos, log files, rosbags and more, and of any type or format. Every Event Recording Part will be available for download in the event page on the Heex Cloud.

​
Add Event Recording

In the generateRequestedFilePaths() method of your recorder, you need to access query informations:

  • Event id (query.eventId)
  • Requested timestamp (query.timestamp)
  • Event id and timestamp (query.timestampedEventUuid)
  • Interval of time before the timestamp (query.recordIntervalStart)
  • Interval of time after the timestamp (query.recordIntervalEnd)

See the RecorderEventRecordingPartArgs structure in the Query content for Event Recordings Parts for more details.

With this information you can generate a file (or collection of files) that represents the data you want to retreive for your events.

After that, you just need to fill the filepath variable with your filepath value, pointing to your generated event recording part (filepath variable being passed by reference to the function).

You have different options in how you provide the desired filepath, each of which has a specific synthax depending on the use case:

  1. Send only the file. Return the direct path to file.
  2. Send the folder and all its content. Return the direct path to folder.
  3. Send only the content of the folder. Return the path to the folder with /* as an extra suffix (wildcard at the end to include only files within the parent directory).

⚠️ Warning:

The event recording parts should have different names. Otherwise, some files may be overriden by your recorder before being fully uploaded.

Your data generation may differ from what is resquested by the query. The SDK provides methods to run inside your generateRequestedFilePaths() implementation to integrate these changes per field.

ℹ️ Note:

Returning false signals an error and stops the entire event process.