A Recorder is a software component of a System that records a specific Dataflow upon query of the Heex Agents. A Recorder produces an Event Recording Part.

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

class myRecorder : public Recorder

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

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

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

virtual bool generateRequestedValues(const Heex::RecorderArgs::RecorderContextValueArgs& query, std::vector<Heex::RecorderArgs::ContextValue>& contextValues)

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

You can also set the real recording range by using the following method :

bool setRealRecordIntervalRange(const Heex::RecorderArgs::RecorderEventRecordingPartArgs& query,const std::string& realRecordIntervalStart,const std::string& realRecordIntervalEnd)

​
Overriding generateRequestedValues API to provide Context Values

Context values 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 with the metadata to be visible on the event page of the Heex Cloud, in the Metadata information card.

On that 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 context value 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 Context Values

In the generateRequestedValues() method of your recorder’s implementation, you need to fill the variable contextValues. When you receive it, it contains all the keys your recorder has to fill. You can extend the list with new keys and values.

The following useful methods facilitate the process.

this->getContextValueKeys(contextValues);

↳ Is used to obtain all required keys from the query (optional check).

this->addContextValue(contextValues, key, value);

↳ Is used to assign the value to the key. If contextValues does not contain key, key and value are added at the end of contextValues. Values are defaulted to an empty string.

this->addGNSSContextValue(contextValues, "position", latitude, longitude)

↳ Is used to quickly assign separate latitude and longitude to the key "position".


You have access to all info about the query such as Recorder uuid (query.uuid), Event uuid (query.eventUuid) and requested timestamp (query.timestamp)…
See the RecorderContextValueArgs structure in the Query content for Context Values for more details.

Finally, you shall return true when all the context keys have their values added in contextValues.

⚠️ Warning: error

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

​
Overriding generateRequestedFilePaths API to provide Event Recordings

An event recording is a file or directory produced by the recorder on demand of the Heex Agents, 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:

  • Recorder uuid (query.uuid)
  • Event uuid (query.eventUuid)
  • Requested timestamp (query.timestamp)
  • Intervals of time before the timestamp (query.recordIntervalStart)
  • Intervals 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.

Modify RecordIntervalStart and RecordIntervalEnd fields:

this->setRealRecordIntervalRange(query, realRecordIntervalStart, realRecordIntervalEnd);

Finally, you shall return true when the path to the event recording part have been replaced in filepath. File(s) shall have been completely generated.

ℹ️ Note:

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

​
Recorder Samples

You can check them here samples