OSF4 – Specific documentation

This document describes all aspects of Open Streaming Format Version 4 (OSF4) that go beyond the general OSF description.
It supplements the file osf_general.md, which explains all structures common to OSF4 and OSF5.

OSF4 is the classic version of the format. It uses only XML for the meta block and forms the basis for backward compatibility in OSF5.

Magic header in OSF4

• Allowed identifiers:
  • OSF4
  • OCEAN_STREAM_FORMAT4 (historical identifier)
• Format:

  OSF4 173762\n

• Properties:
  • Always XML metablock directly after the header.
  • No JSON support.
  • OSF5 parsers can read OSF4 files completely.

Metablock in OSF4 (XML)

OSF4 uses only XML for the metablock.
It contains all file and channel information and begins with a standard prologue:

<?xml version="1.0" encoding="UTF-8"?>

Root element <osf>

Example:

<osf version="4"
     created_utc="2019-08-12T12:23:01+02:00"
     creator="smartdevice:14001000078"
     created_at_longitude="50.2"
     created_at_latitude="8.65"
     created_at_altitude="193"
     reason="BOOT"
     total_seq_no="0"
     triggered_seq_no="0"
     namespacesep="."
     tag="preview"
     comment="">

Attributes:

• version: Version of the OSF4 format (default: "1").
• created_utc: Date and time of file creation in ISO 8601 format (UTC).
• creator: Identification of the creating device or program.
• created_at_longitude / latitude / altitude: Optional geographic position.
• reason: Reason for file creation (BOOT, SEQUENCE, TRIGGERED).
• total_seq_no: Absolute sequence number since system startup.
• triggered_seq_no: Relative sequence number since last trigger.
• namespacesep: Separator for hierarchical channel names (default: ".").
• tag: Free tag for classifying the file (default: "preview").
• comment: Optional comment.

Channel list <channels>

Contains all channels in the file.

<channels count="8">
    <channel index="0"
             name="Sensor/Temperature"
             channeltype="scalar"
             datatype="double"
             timeincrement="1000000"
             sizeoflengthvalue="2"
             physicalunit="°C"
             reference="uuid"
             physicaldimension="temperature"/>
</channels>

• count: Number of channels in the file.

Channel description <channel>

All parameters as described in the general OSF documentation; the following applies to OSF4:

• Metablock: Always XML
• Supported channeltype: scalar, vector, matrix, binary
• Vector and matrix parameters: In the channel definition via rows, columns, and associated attributes
• sizeoflengthvalue: Required field (2 or 4 bytes)
• No new pair and triple types – these will only be available in OSF5.

Supported data types in OSF4

Data type	Size	Description
bool	1 byte	True/False
int8	1 byte	Signed integer
int16	2 bytes	Signed integer
int32	4 bytes	Signed integer
int64	8 bytes	Signed integer
float	4 bytes	IEEE 754 single precision
double	8 bytes	IEEE 754 double precision
string	variable	UTF-8, length determined by block
candata	16 bytes	Structure for CAN frames
gpsdata	24 bytes	Structure for GPS positions

Note: pair and triple are not defined in OSF4.

Data blocks in OSF4

OSF4 uses the data block structures described in the general specification.
Specific to OSF4:

• Control byte: All original block types 0–8 are supported.
• bcContinuedRelStampData: Still used in OSF4 (removed in OSF5).
• bcStatusEvent and bcMessageEvent: Present, but no longer recommended in new implementations.
• Metadata: Always in XML format.

Restrictions:

• Equidistant channels (bcStartData, bcContinuedData): Numeric types only (int*, float, double).
• Timestamped channels (bcAbsTimeStampData, bcContinuedRelStampData): All types allowed.

XML trailers and Magic trailers

OSF4 optionally supports an XML info block with channel statistics and a magic trailer.

XML trailer example:

<trailer finalized_utc="2019-08-12T12:23:01+02:00" reason="fileStartGrid_min">
    <channels count="8">
        <channel index="0" samples="29452" last_ns="1384899599997800000"/>
        <channel index="1" samples="29452" last_ns="1384899599997800000"/>
    </channels>
</trailer>

Magic Trailer:

OSF_STREAM_END 321316454==============

• 40 bytes long, number = position of the 0xFFFF block.

Special features and limitations of OSF4

• Only XML metablocks, no JSON support.
• Control byte more complex, more block types than OSF5.
• No native pair/triple data types.
• Vector and matrix channels via XML parameters (rows, columns).
• bcContinuedRelStampData is supported but is no longer included in OSF5.

Example of an OSF4 file

OSF4 30269
<?xml version="1.0" encoding="UTF-8"?>
<osf version="4" created_utc="2019-08-12T12:23:01+02:00" creator="smartdevice:14001000021">
  <channels count="2">
    <channel index="0" name="Sensor/Temperature" channeltype="scalar" datatype="double" timeincrement="1000000"/>
    <channel index="1" name="Sensor/Pressure" channeltype="scalar" datatype="double" timeincrement="1000000"/>
  </channels>
</osf>
[BEGIN OF BINARY DATA]