EKHO .RAW files

Version: 2.0

An EKHORAW file is a binary file format for storing recorded IV-information from Ekho. This file is recorded to an SD card on the Teensy, which is attached to the Ekho board. It will later be processed to create an IV surface.

All EKHORAW files should be named with a .RAW extension, to avoid confusion.

The EKHORAW file is binary. All multi-byte integers are unsigned (unless otherwise specified) and stored with little-endian byte order.

The file contains two parts:

• a header that describes how the data was recorded, and
• a list of recorded IV-pairs

The file header is 64 bytes long and contains the following elements:

• MAGIC (8 octets) — the first 8 octets contain the null-terminated ASCII characters, “EKHORAW”. Don't forget the null-terminating zero.
• FORMAT VERSION (2 octets - sequential. not a multi-byte integer) — Represents the version of the EKHORAW format. The first octet represents the major version, the second represents the minor version. So, for this document (version 2.0), these octets should be 0x0200.
• FIRMWARE VERSION (2 octets- unsigned integer) — represents the version of the firmware that created the file.
• FIRMWARE BUILD DATE (4 octets - two 1-octet integers, and one 2-octet unsigned integer) — the first octet stores the day. The second stores the month. The third and fourth store the year that the firmware was compiled. So, for April 3, 2020, these bytes should be 0x0304E407.
• TEENSY VERSION (2 octets- sequential. not a multi-byte integer) — the version of the teensy that produced the file. For v3.6, the octets should be 0x0306.
• BOARD VERSION (2 octets - unsigned integer) - the version of the Ekho recorder board used to record the data.
• SAMPLING RATE (4 octets - unsigned integer) — the number of samples per second.
• SAMPLING BATCH SIZE (2 octets - unsigned integer) — the number of samples per batch (explanation below).
• ERROR CHECKING MODE (1 octet) — specifies what error checking mode this file is using: supported values include 0x00 (None), 0x01 (PARITY BYTE), 0x02 (CHKSUM), 0x03 (CRC-8,poly=0x07)
• CURRENT AMPLIFICATION FACTORS (6 octets - unsigned integer) —consist of the following (2-octets each), FirstStageAmplificationFactor, SecondStageAmplificationFactor, and ThirdStageAmplificationFactor.
• VOLTAGE DIVISION FACTOR (2 octets - unsigned integer) - the voltage division factor on Ekho recorder board used to the data.
• RESERVED (29 octets) — Leaving space here in case we need to add something.

Samples are stored in batches. Each batch has the following format:

• TimeStamp (4 octets) — the time (in milliseconds) since the recording began. This allows for up to 49 days of continuous recording in one file. For longer recordings, multiple files can be generated. Frankly, if you're going longer than a day or two, you should probably generate multiple files anyway.
• Samples (10 octets/sample) — Samples consist of the following 5 integers (2-octets each), first 4 represent ADC values and the fifth value represents the the sense resistor that used to obtain the the ADC readings of the three amplification satges: FirstStageAmplificationCurrent, SecondStageAmplificationCurrent, ThirdStageAmplificationCurrent, Voltage, and SENSE RESISTOR VALUE.
• PADDING (1 octet) — a lot of microcontrollers like things to be aligned to even boundaries. So, we add single octet of padding. Should be set to 0x00.
• ERROR CORRECTION (1 octet) — this value depends on the error correction value specified in the header. If it is None, then this value should be 0x00. For, the Parity Byte setting, it should be a simple parity byte computed by XOR-ing all of the bytes in the batch. For CHKSUM, it should be the simple 8-bit sum of the bytes in the batch (initial value 0x00). For CRC8, it should be the CRC8 computed over the bytes of the batch (using polynomial 0x07). In all cases, except None, the checksum should be computed over all bytes in the batch (including the timestamp, but excluding the error correction and padding).