Renode Sensor Data Format (RESD)¶

For an introduction and description of simple operations on your simulated sensors, such as assigning a constant value as a sensor readout, see the Sensors and virtual environment chapter.

What is the Renode Sensor Data format?¶

Renode Sensor Data (RESD) is a unified and portable way to provide sample data for sensor models implemented in Renode. Sensor data described in .resd files use standard units and fixed formats for all data types, so they can be used by any existing or future model.

The data stored in a .resd file is divided into independent channels, each of a given type (e.g. temperature or acceleration). This allows a single input file to be used for multiple sensors such as IMU. It is also possible to include multiple channels of the same type (each identified by a unique channel ID), e.g. two channels for temperature readings.

Each .resd file consists of a single file header followed by a variable number of data blocks:

00000000  52 45 53 44 01 00 00 00  02 01 00 00 00 a8 01 00  |RESD............|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 70 c9  |..............p.|
00000020  b2 8b 00 00 00 00 00 00  00 00 00 00 00 cc 9b 03  |................|
00000030  00 c4 95 03 00 79 9b 03  00 18 9a 03 00 75 a3 03  |.....y.......u..|
00000040  00 3b a1 03 00 b1 b4 03  00 8d 9d 03 00 41 a5 03  |.;...........A..|
00000050  00 4d 9b 03 00 21 af 03  00 6f 96 03 00 20 ba 03  |.M...!...o... ..|

You can easily create a binary file like the one shown above from a CSV file using the CSV - RESD parser.

The file header consists of a 4-byte magic string value RESD encoded in ASCII, followed by a single byte defining the version of the format the file uses (the code above uses version 0x1), followed by 3 bytes of reserved padding (currently defined as all zeros).

RESD Data Blocks¶

Each block header is structured in the following way:

RESD Block Types¶

Currently, you can use the following block types in your .resd files:

Arbitrary timestamp sample blocks¶

Arbitrary timestamp sample blocks contain a series of samples, each with its own timestamp. In this type of sample block, you do not specify a period between samples, but instead provide a specific timestamp for each sample to simulate irregular sensor readings.

Constant frequency sample blocks¶

In constant-frequency blocks, the block header is 16 bytes longer than the arbitrary timestamp block and includes an additional sub-header that provides information about the timestamp of the first sample in a series and a period between consecutive samples.

Timestamps¶

Timestamps in .resd are encoded as unsigned 8-byte values expressed in virtual nanoseconds counted from the beginning of the file.

RESD Sample Types¶

Your .resd files can contain the following sample types:

Keep in mind that sample types other than Custom do not utilize a metadata dictionary (metadata size set to 0).

Metadata¶

Metadata is a binary-encoded dictionary, where each entry consists of a key name, key type, and value. The first 8 bytes indicate the size of the metadata section and can be set to 0 to indicate that the given block contains no additional metadata.

The key name is a null-terminated string consisting of [a-z0-9_] characters. It’s followed by a byte that describes the type of the value for the given key:

For example, the encoding of a metadata section consisting of two entries: a description of type string and data of type blob would look like this:

Custom Sample Data Example - MAX86171 AFE¶

The following instructions show how to use RESD to create a custom sample data example based on a real sensor - MAX86171 AFE.

The measurements taken by the MAX86171 AFE sensor depend on the channel configuration, e.g. the LED exposure drive current value directly affects the photodiode output. Therefore, each MAX86171 AFE sample data block begins with a metadata section containing a dictionary of the following information:

MAX86171 AFE Sample Data¶

A single MAX86171 AFE sample is described as a one-byte unsigned value containing a number of active channels followed by a list of measurement frames, each encoded as a four-byte unsigned value:

An AFE sample in RESD corresponds to a single frame generated by the MAX86171 AFE: two tagged samples are required for each active measurement, as described in the FIFO Description section of the MAX86171 data sheet:

The tag section follows the specification from the FIFO Description section of the sensor’s data sheet:

A sample with data two measurement OC channel 1 would then look like this:

The frames can be decoded as:

RESD tooling¶

CSV - RESD parser usage¶

The CSV - RESD parser is a tool in the Renode repository that allows you to convert CSV files to the RESD file format.

To use the tool, follow this syntax:

./csv2resd.py [GROUP]... OUTPUT
GROUP ::= -i <csv-file> [-m <type>:<field(s)>:<target(s)>*:<channel>*]
          [-s <start-time>] [-f <frequency>] [-t <timestamp>] [-o <offset>] [-c <count>]

The syntax allows multiple group specifications, where –input is a separator between groups. You can specify multiple mappings (-map) for each --input.

The * in --map indicates that the given property is optional. For your --map argument to be correct, it must be structured in one of the following ways:

• --map <type>:<field(s)>

• --map <type>:<field(s)>:<target(s)>

• --map <type>:<field(s)>:<target(s)>:<channel>

• --map <type>:<field>::<channel>

See --help for more information.

If you wanted to extract the columns temp1 and temp2 from the file first.csv and first 3 samples temp from the file second.csv and then map them to the temperature channels 0, 1 and 2 in RESD, respectively, you would run the script with the following parameters:

./csv2resd.py \
    -i first.csv \
        -m temperature:temp1::0 \
        -m temperature:temp2::1 \
        -s 0 \
        -f 1 \
    -i second.csv \
        -m temperature:temp::2 \
        -s 0 \
        -f 1 \
        -c 3 \
    output.resd

CSV Field Types¶

All fields of a single column must be of the same type. Below is a description of how values in CSV will be interpreted:

RESD introspection¶

Renode comes with a command for inspecting RESD files without a need to load them to any particular sensor model.

To analyze the content of a RESD file, first load it with:

(monitor) resd load r1 @my_samples.resd
RESD file from 'my_samples.resd' loaded under identifier 'r1'

Now, you can print information about sample blocks with:

(monitor) resd list-blocks r1
Blocks in r1:
1. [00:00:00.000000..00:00:02.000000] Acceleration:0
2. [00:00:02.000000..00:01:05.500000] Acceleration:0
(monitor) resd describe-block r1 1
Index: 1
Sample type: Acceleration
Channel ID: 0
Start Time: 00:00:00.000000
End Time: 00:00:02.000000
Duration: 00:00:02.000000
Samples count: 2
Period: 00:00:01.000000
Frequency: 1Hz

You can also dump selected samples (e.g., between timestamps of 2.2 and 2.3 seconds) with:

(monitor) resd get-samples-range r1 2 "2.2" "2.3"
00:00:02.203125: [0, 0, 0.1] g
00:00:02.218750: [0, 0, 0.2] g
00:00:02.234375: [0, 0, 0.3] g
00:00:02.250000: [0, 0, 0.2] g
00:00:02.265625: [0, 0, 0.2] g
00:00:02.281250: [0, 0, 0.1] g
00:00:02.296875: [0, 0, 0.0] g

For more details, see the command’s help output:

(monitor) help resd
resd
introspection for RESD files

You can use the following commands:
'resd load NAME PATH'   loads RESD file under identifier NAME
'resd unload NAME'      unloads RESD file with identifier NAME
'resd list-blocks NAME' list data blocks from RESD file with identifier NAME
'resd describe-block NAME INDEX'        show information about INDEXth block from RESD with identifier NAME
'resd get-samples NAME INDEX "START_TIME" COUNT'        lists COUNT samples starting at START_TIME from INDEXth block of RESD with identifier NAME
'resd get-samples-range NAME INDEX "START_TIME" "DURATION"'     lists DURATION samples starting at START_TIME from INDEXth block of RESD with identifier NAME
'resd get-samples-range NAME INDEX "START_TIME..END_TIME"'      lists samples between START_TIME and END_TIME from INDEXth block of RESD with identifier NAME
'resd get-prop NAME INDEX PROP' read property PROP from INDEXth block of RESD with identifier NAME
  possible values for PROP are: SampleType, ChannelID, StartTime, EndTime, Duration, SamplesCount

UART RESD Feeder¶

The UARTRESDFeeder is a special peripheral designed for feeding UART data to emulated UART buses. It’s based on Virtual Console therefore it inherits and extends the Python scripting capability.

An instance of the feeder can be created with a Monitor command:

(machine-0) machine CreateUARTRESDFeeder "feeder"

or in a .repl file:

feeder: UART.UARTRESDFeeder @ sysbus

Usage¶

This peripheral uses Binary Data samples from .resd files as a source of data to be inject into the emulation. Such file can be loaded using FeedDataFromRESD method.

(machine-0) feeder FeedDataFromRESD @hci.resd mode=Normal channelId=1 sampleOffsetTime=2500000000

Timing of the data transmission depends on the mode selected while loading a file. Every block should also specify the intended mode to be used with. A feeding_mode metadata can have one of the string values specified for each mode. If the metadata is not set to a legal value than a warning will be logged and the block will be used, but if a mismatch with the current mode is detected then the block will be skipped.

Normal mode¶

Normal mode follows the standard RESD behaviour.

The feeding_mode metadata should be set to normal with this mode.

Trigger mode¶

Trigger mode relays on the Trigger method to be called. This action can be interactive as the methods can be called from the Monitor, or scripted with Python. Also, before the sample is enqueued, it can be retrieved to be inspected with TryGetNextTriggerSample method and skipped with SkipTriggerSample method.

When the Trigger is called the next sample will be transmitted after a delay. The interpretation of the sample’s timestamp is changed in this mode and it’s used as the delay.

This means that the arbitrary timestamp type of RESD blocks is preferred. With such interpretation the fixed frequency based block type is unlikely to be useful due to the accumulation of the period in the samples’ timestamp. That is, the delay since the trigger would be (n-1) * period + start_time for the nth sample.

The feeding_mode metadata should be set to trigger with this mode.

Scripting¶

The UART RESD Feeder extends Virtual Console’s API and changes the echoing behaviour. The unchanged parts of the API are not listed here, but rather can be checked in Virtual Console documentation.

A more detailed description can be found in the source file: UARTRESDFeeder.cs.