POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

NAME
pobd_converter − a post−processor for csv log files written by pobd_logger
SYNOPSIS
pobd_converter −h
pobd_converter −V
pobd_converter [−f outfmt] [−o OUTFILE] [−p pidlist] [−s sepchar] [−t timefmt] [LOGFILE]
LOGFILE is the name of the pobd_logger csv log file to be converted
The available options are;
−f outfmt Convert log file to the output format given by outfmt
−h Display the help summary message to STDOUT and then exit
−o OUTFILE Output the converted data to the file named OUTFILE
−p pidlist Limit output data to PIDs in the comma delimited pidlist
−s sepchar The fields in output file(s) are separated by sepchar
−t timefmt Convert output timestamps into the time format timefmt
−V Display program version information to STDOUT and exit
OPTIONS
−f outfmt
The −f command line option controls the format of the output file(s). The option argument outfmt is of
the form format[:parameter], where the required format keyword identifies the desired output format,
and is followed by one or more optional, colon separated parameter keywords that specify additional
details of the output format. In the absence of the −f command line option, the default output format is
the statistics format.
The available output formats can be organized into two distinct categories; those where a simple
reorganization or reformatting of the input data is performed (multiple, single, and tabular), and
those that output some type of analysis of the input data, (economy, and statistics). The supported
format keywords are described below.
multiple or split
As the output format keyword suggests, this produces multiple output files. Each outfile file
contains the data for a given PID, (assuming at least one sample for that PID was present in the
input log file). The −p command line option can be used to limit the output to a specified set of
PIDs.
The optional parameters header and qheader specify that the first record contains header strings,
(or quoted header strings respectively), that describe the data in that field. The optional parameter
nopid can be used to produce output files that do not have a data field corresponding to the
hexadecimal PID number.
single
This output format produces a single output file. It is typically used in conjunction with the −s
and −t command line options to specify custom field separators and timestamps respectively.
The optional parameters header and qheader specify that the first record contains header strings,
(or quoted header strings respectively), that describe the data in that field. The optional
parameters sortbypid and sortbytime can be used to specify the ordering of output records. The
default ordering is to sort the output records by the sample time.
tabular or vector
Many data analysis and plotting programs that support multidimensional data assume that the
records in the input data are vectors, (a sample time followed by values for each dimension). At
any given sample time, it is assumed that data values for all dimensions are available, (and this is
not the case with OBD-II PID logging). This output format produces files where each record can

perl v5.14.4 2015-12-03 1

POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

be thought of as the row of a table, or a vector. The unknown PID values at any given sample time
are estimated using an interpolation algorithm. See the FILES section for a detailed description of
the data fields of the output file.
The optional parameters header and qheader specify that the first record contains header strings,
(or quoted header strings respectively), that describe the data in that field.
The optional parameters constant and linear can be used to specify the interpolation algorithm to
use, (either piecewise constant or linear interpolation respectively). The default is to use linear
interpolation. By default, some sample times near the start and end of the input log file, will not
appear in the tabular output file. (Any sample time where there is at least one other PID that has
not been sampled yet, or the data required for linear interpolation is no longer available). The
optional parameter extrapolate can be used to specify that records should be output for all
samples times in the input log file, and extrapolation will be used when needed at sample times
near the start and end of the input log file.
economy, fe, or fueleconomy
This output format produces a single file containing computed estimates of the vehicle fuel
economy. The input log file must contain data for PIDs 0x0d and 0x10 (vehicle speed and mass
air flow rate respectively). Data for PID 0x44, (fuel/air commanded equivalence ratio, or lambda)
will be used in the computation if it is present, but it is not required.
The optional parameters header and qheader specify that the first record contains header strings,
(or quoted header strings respectively), that describe the data in that field. The optional parameter
usunits specifies that the physical units in common use in the United States should be used in the
output, where the default is to use metric units. See the FILES section for a detailed description
of the data fields of the output file.
The optional parameter afr=value can be used to specify the stochiometric air to fuel ratio used
in the computation of the economy estimates. The optional parameter rho=value can be used to
specify the density of the fuel, in units of grams per liter. The default values are 14.7 for the
stochiometric ratio, and 755 grams per liter for the fuel density.
statistics, or stats
This output format produces a file that contains a variety of statistics (e.g. average sample rates
for each PID) computed from the PID data. It is in a self documenting, human readable format,
intended for printing or viewing with a file pager. The nature of the output statistics will vary
depending on the PID data in the input log file.
If you live in the United States, the optional usunits parameter can be used to produce output in
physical units that should be more familiar, the default physical units are metric. The optional
parameters gmt, local, or localtime can be used to specify the timezone to be used in the
formatting of the time of day. Since the output file is meant to be human readable, the −p, −s, and
−t command line options are silently ignored.
−o OUTFILE
The −o command line option can be used to specify the name of the output file(s). If the −o command
line option is absent, then pobd_converter will attempt to write the output to the STDOUT file unit.
The behavior of this option is slightly different in the special case of the multiple or split output
format. The argument OUTFILE can optionally contain a printf (3) format conversion specifier to
control how the PID is encoded into the PID specific filenames. A conversion specifier will be added to
OUTFILE if one was not present. Since multiple files can’t be written to the STDOUT file unit, the −o
command line option is required in this special case.
−p pidlist
The −p command line option can be used to restrict the data written to the output file(s) to a specific
set of PIDs. The argument pidlist is a comma delimited list of hexadecimal PIDs. A warning message
is written to the STDERR unit when a PID is listed, but no data for that PID is present in the input log
file. This option is silently ignored in the case of statistics output format.

perl v5.14.4 2015-12-03 2

POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

−s sepchar
The −s command line option can be used to specify the field separator character (or character string),
that delimits the data fields in the output file(s). The option argument sepchar may contain Perl escape
sequences using the backslash character (e.g. ’\t’ translates to the tab character). If the argument
sepchar contains blank(s), it must be quoted for the shell to recognize it as an option argument. In the
absence of the −s command line option, the default value for the field separator is a single comma
character, producing CSV (Comma Separated Values) format output files. This option is silently
ignored in the case of statistics format output.
−t timefmt
The −t command line option controls the formatting of timestamps in the output file(s). The option
argument timefmt is of the form format[:parameter], where the required format keyword identifies the
desired timestamp format, and is followed by one or more optional, colon separated parameter
keywords for fine tuning of the format. In the absence of the −t command line option, the default
timestamp format is the unixtime format. The supported timestamp format keywords are described
below.
relative, shift, or zero
This format outputs timestamps as the number of floating point seconds elapsed since a given
time origin. By default, the new time origin is the time of the first sample in the input log file. An
arbitrary time origin value can be specified as an optional parameter. This timestamp format can
be useful when you want to create overlay plots using data from different logging sessions or
trips.
strftime
As the format keyword suggests, the timestamps produced are the output of the strftime (3)
function, as documented by the POSIX specification. The optional parameters gmt, local, or
localtime can be used to specify the time zone, followed by an optional strftime (3) format
specification. In the absence of an explicit format specification, the timestamp is formatted as in
this example: "10 Oct 2015 11:47:03.141592 PDT".
The non-standard conversion specification %.nf is available, and will be replaced by the
fractional portion of the seconds with n decimal places of precision following the decimal point.
If your format specification contains blanks (and it probably will), the option argument must be
quoted for the shell to parse it correctly. If you are unfamiliar with the strftime (3) function, see
the EXAMPLES section below for a quick tutorial. This timestamp format is useful when
generating output that is compatible with common spreadsheet programs.
unixtime
This is the default timestamp format, (it is the timestamp format used in CSV format log files
written by pobd_logger). It is a floating point number that represents the number of seconds
elapsed since the Epoch: 1970−01−01 00:00:00 +0000 (UTC). There are no optional parameters
for this timestamp format.
winnt
This specifies that the timestamps should be in Windows NT time format. It is an integer that
represents the number of ticks (where each tick is 100 nanoseconds in duration) since the Epoch:
1601−01−01 00:00:00 +0000 (UTC). There are no optional parameters for this timestamp format.
DESCRIPTION
The design philosophy of the pobd_converter application is to provide a mechanism for converting csv
format log files written by pobd_logger to formats that are compatible with third party data analysis or
plotting programs. Some commonly used conversions are to specify a custom field separator or a custom
formatted timestamp. It can also split the input log file into multiple output files, each one containing only
the data for a given PID.
The pobd_converter application also provides some rudimentary OBD-II data analysis capabilities. The
economy output format produces estimates of the vehicle fuel economy, while the statistics output format
produces a variety of useful statistics derived from the collected data.

perl v5.14.4 2015-12-03 3

POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

There are many open source licensed applications that are suited to the analysis and plotting of the output
files written by pobd_converter. Some that you might find useful (given in alphabetical order); DataMelt
(formerly called SCaViS), Freemat, GGobi, Gnuplot, Grace (formerly called xmgr), kst, LabPlot, MayaVi,
Octave, ploticus, PyLab (ipython with the −−pylab command line option), QtiPlot, R (sometimes called
GNU S), SciDAVis, and Veusz. Spreadsheet programs such as Calc from LibreOffice or Excel can be also
be used, but their capabilities are rather limited when compared to any of the afore mentioned programs.
ERRORS
When problems are encountered, pobd_converter will write any associated warning or fatal error messages
to the STDERR file unit. It also tries to provide some suggestions on possible remedies when the situation
permits.
EXAMPLES
This section presents some examples of invoking the pobd_converter application with various command
line options.
This example demonstrates the multiple or split output format. The −s command line option is used to
produce output files with a single space character as the field separator, (making it compatible with the
Gnuplot application). Because more than one output file will be written, the −o option is required for this
output format. The filename argument contains a printf (3) conversion specifier to control how the PID is
encoded into the output filenames.
$ pobd_converter −f split −o 'output_0x%02x.dat' −s ' ' log_20150822.csv
The following example demonstrates the single output format. The −t option is used to produce custom
strftime (3) formatted timestamps that are compatible with many spreadsheet programs. Because the
argument of the −t option contains blanks, it must be enclosed in quotes for the shell to parse it correctly.
$ pobd_converter −f single \
−t 'strftime:local:"%y/%m/%d %H:%M:%S%.6f %Z"' \
< log_20150829.csv > converted_log_20150829.csv
The following example demonstrates the tabular output format, with the optional qheader parameter to
produce quoted descriptive header strings. The −p option is used to restrict the output data to the comma
delimited list of PIDs, (which helps reduce the size of the output and minimize errors introduced by
interpolation).
$ pobd_converter −f tabular:qheader −p 0x0d,0x10,0x11,0x44 \
< log_20150914.csv > table_20150914.csv
This example demonstrates the economy output format. Two optional parameters are included in the
argument of the −f option to fine tune the output; the afr parameter specifies the stochiometric air to fuel
ratio to be 14.13 (representative of E10 gasahol), and the usunits parameter specifies the units of the output
quantities are to be those in common use in the United States. The −t option is used to shift the origin of the
output timestamps to the start of the log file (giving relative, or trip time).
$ pobd_converter −f economy:afr=14.13:usunits −s ' ' −t zero \
< sedan_20150921.csv > sedan_20150921.dat
FILES
The pobd_converter program interacts with an input CSV (Comma Separated Values) format log file, as
written by pobd_logger and one or more output files. The specific contents of the output file(s) will depend
on which output format was selected, which can be controlled with the −f command line option. The
available output formats can be organized into two distinct categories; those where a simple reorganization
or reformatting of the input data is performed, and those that output some type of analysis of the input data.
Input File
The input to the pobd_converter program is a log file written by the pobd_logger program in the default
CSV format. If the input log file is not specified at the end of the command line, then pobd_converter will
attempt to read it from the STDIN file unit.
The pobd_converter program currently supports only pobd_logger log files written in the CSV (Comma

perl v5.14.4 2015-12-03 4

POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

Separated Values) format. If you have log files written in SQLite database format, you can always use
something like the freely available sqlite3 application to convert them into CSV format.
Common Features of the Output Files
By default, the data fields in the output file(s) will be separated by the comma character, producing CSV
(Comma Separated Values) formatted output files. The exception is statistics format output files, which are
meant to be human readable. The −s command line option can be used to specify a user customized field
separator character or character string. By default, sample times will be output in UNIX time, the number of
floating seconds since the Epoch: 1970−01−01 00:00:00 +0000 (UTC). The −t command line option can be
used to produce user customized timestamp formats.
The Output File for Multiple Format
Each record of a multiple format output file consists of three (sometimes four) columns or fields; the time
of the sample, the hexadecimal PID, and the PID values. Most PIDs have a single column or field for the PID
value, but some of them have two. The optional parameter nopid can be used to specify that the second
column, the hexadecimal PID, be eliminated from the output (as the output filenames have the associated
hexadecimal PID embedded in them).
The Output File for Single Format
Each record of a single format output file consists of three (or sometimes four) columns or fields; the time
of the sample, the hexadecimal PID, and the PID values. Most PIDs have a single column or field for the PID
value, while some have two.
The Output File for Tabular Format
Each record of a tabular format output file consists of N+1 columns or fields; the time of the sample,
followed by N fields containing PID values. By default, the value of N is the number of PIDs that where
sampled at least once in the input log file. The −p command line option can be used to limit the output to a
specified set of PIDs. The PID value fields are in ascending order with respect to the associated
hexadecimal PID number.
The Output File for Economy Format
Each record of the economy format output file consists of seven columns or fields; the time of the sample,
followed by six data fields. By default, the physical units associated with the data fields use the metric
system. The optional usunits parameter can be used to override the default, in which case physical units
commonly used in the United States will be used instead. The quantities associated with each field are
described here.
Field 1
The timestamp associated with this sample. The default format of the timestamp is UNIX time, the
number of floating seconds since the Epoch: 1970−01−01 00:00:00 +0000 (UTC). The −t command
line option can be used to produce custom formatted timestamps.
Field 2
The total distance traveled by the vehicle since the start of the log file. The physical units are in
kilometers for the metric system, and statute miles when using units for the United States. This
quantity is found by integrating the instantaneous vehicle speed with respect to time.
Field 3
The estimate of the volume of fuel consumed by the engine since the start of the log file. The physical
units are in liters for the metric system, and usgallons when using units for the United States. This
quantity is found by integrating the instantaneous fuel flow rate with respect to time.
Field 4
The instantaneous speed of the vehicle. The physical units are in kilometers per hour for the metric
system, and statute miles per hour when using units for the United States.
Field 5
The instantaneous fuel flow rate. The physical units are in liters per hour for the metric system, and
usgallons per hour when using units for the United States. This quantity is computed by dividing the
value of instantaneous mass air flow rate by the stochiometric air to fuel ratio for the fuel being used,

perl v5.14.4 2015-12-03 5

POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

and then multiplying by the appropriate conversion constants to get the desired physical units. When
data for PID 0x44 (lambda) is available, the air to fuel ratio is the product of lamdba times the
stochiometric ratio, otherwise the stochiometric ratio is used without any further adjustment.
Field 6
The instantaneous fuel economy estimate. The physical units are in kilometers per liter for the metric
system, and statute miles per usgallon when using units for the United States.
Field 7
The trip average fuel economy estimate, from the start of the log file to the present time. The physical
units are in kilometers per liter for the metric system, and statute miles per usgallon when using units
for the United States.
The Output File for Statistics Format
The output file for statistics format contains a variety of statistics (e.g. computed average sample rates for
each PID) that is in a self documenting, human readable format, intended for printing or viewing with a file
pager. The output file is not intended to be used as input to a data analysis or plotting program. The nature
of the output statistics will depend on the PID data contained in the input log file.
CAVEATS
The fuel economy statistics in the economy output format are referred to as estimates to reflect the fact that
several simplifying assumptions are required in the calculation of them, and these assumptions will
introduce a bit of error. The most significant assumption is that the engine will operate using a constant and
known air to fuel ratio (in terms of mass). The problem with this assumption is that virtually all modern
engines will dynamically adjust the air to fuel ratio based on exhaust gas emission (anti-pollution), engine
durability and performance, and numerous other considerations. Most contemporary gasoline engines try to
run at the stochiometric ratio most of the time, namely the air to fuel ratio where all available oxygen and
fuel are both consumed. The value of the stochiometric ratio depends on the fuel used and also on
environmental factors such as the moisture content of the ambient air (hence it is not a constant over time,
even for a given fuel).
The default stochiometric ratio used by pobd_converter is 14.7 to 1, which is the value for dry air and
gasoline composed of pure octane. The stochiometric ratio for gasoline containing oxygenators (such as
ethanol, methanol, or MTBE) will be somewhat less. For example, the stochiometric ratio for E10 gasahol,
is about 14.13 to 1, and 9 to 1 for pure ethanol. The stochiometric ratio used in computing the fuel economy
estimates can be explicitly specified as an optional parameter that follows the economy keyword in the
argument of the −f command line option.
As noted above, there are inherent limits to the accuracy of the fuel economy estimates. The accuracy will
be further degraded if the PIDs used in calculating the estimates (0x0d and 0x10) are sampled at rates that
are too slow relative to the time scales with which they actually fluctuate.
BUGS
The pobd_converter program reads all the data from the input log file into dynamic or RAM memory. This
should not be a practical problem on contemporary desktop or laptop systems. However, it could cause
problems with very large log files on embedded or older systems with limited dynamic memory. This
problem could be fixed, but it’s quite messy and would further obfuscate the code.
RESTRICTIONS
As noted above, the economy output format relies on the presence of data for PIDs 0x0d and 0x10
(vehicle speed and mass air flow rate respectively). Data for PID 0x44, (fuel/air commanded equivalence
ratio, or lambda) will be used in the computation of fuel economy estimates if it is present, but it is not
required. Be sure to instrument your pobd_logger.cfg configuration file to collect data for these PIDs. If
your vehicle does not support these PIDs, you are out of luck.
NOTES
Measures of fuel economy
Outside of the United States, fuel economy is frequently quoted in units of liters of fuel used for a 100
kilometer trip. While it is acknowledged that this convention is common place, it presents some problems
when computing the instantaneous fuel economy. Whenever the vehicle comes to rest, (which will happen

perl v5.14.4 2015-12-03 6

POBD_CONVERTER(1) User Contributed Perl Documentation POBD_CONVERTER(1)

at stop signs and stop lights, assuming you are a law abiding driver), the final step in the computation of the
instantaneous fuel economy involves a division by zero, and this is an undefined operation.
When measured in units of distance traveled per unit volume of fuel, the instantaneous fuel economy
becomes zero whenever the vehicle is at rest. This measure is undefined for the same reason as noted above
whenever the engine is not running, but this issue is easier to deal with.
Evaluating the economy of different routes
The pobd_converter program can be used to evaluate the economy of different routes or trips that share a
common departure and destination point. When factors such as stop lights, reduced speed due to traffic
congestion are given consideration, the shortest route may not be the most economical one. The total mass
of air ingested by the engine as output in the statistics format, or the total volume of fuel consumed by the
engine as output in the economy format can be used to compare different routes or trips. Just be consistent
in what measure you use.
A parametric plot of all the available data can help provide insight into the pros and cons of different routes
or trips. Using the economy format output, plot the total distance traveled (dependent variable, y axis)
versus the total volume of fuel consumed by the engine (independent variable, x axis). The slope of the line
that is tangent to the curve is the instantaneous fuel economy in distance per unit volume of fuel at that
point in time. The slope of the secant line from the origin to any given point on the curve is the trip
averaged fuel economy at that point in time (steeper slope being better fuel economy).
If you prefer to measure fuel economy in fuel used per unit distance, then plot the total volume of fuel
consumed (dependent variable, y axis) verses the total distance traveled (independent variable, x axis). In
this case, the slope of the tangent and secant lines will be proportional to the fuel economy in fuel used per
unit distance (shallower slope being better fuel economy).
AUTHOR
Written by John C. Peterson <jcp@eskimo.com>
COPYRIGHT AND LICENSE
Copyright 2014−2015 by John C. Peterson <jcp@eskimo.com>.
Perl OBD-II Logger is free software: you can redistribute it and/or modify it under the terms of the Artistic
License 2.0 as published by the Perl Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
Artistic License 2.0 for more details.
SEE ALSO
pobd_logger (1)

perl v5.14.4 2015-12-03 7