OBD Metrics is a Java OBD2 framework that is intended to simplify communication with OBD2 adapters like ELM327/STNxxx clones.
The goal behind the implementation is to provide the extensionable framework which covers selected aspects of communication with the OBD2 adapters like reading OBD telemetry data and can be a foundation for the future OBD2 oriented applications.
- Collecting vehicle telemetry data (Metrics)
- Reading Vehicle Metadata, e.g: VIN
- Reading Diagnostic Trouble Codes (DTC)
- The framework supports
ELM327based adapters- The framework is compatible with the
ELM327AT command set
- The framework is compatible with the
- The framework supports
STNxxxxbased adapters. More here: https://www.scantool.net/- The framework is able to utilize
STcommand set available in theSTNxxxxdevice family. More here: https://www.scantool.net/
- The framework is able to utilize
OBD2 PIDs hereinafter referred to as PIDs or OBD2 PIDs processed by the framework are defined in the external resource files and are described by the JSON schema.
Through this design decision PIDs does not need to be necessarily part of the framework and might be supplied by external party.
Within single resource file PIDs are divided into distinct groups, following categories are available:
capabilities- Supported PIDs categorydtcRead- Diagnostic trouble code categorydtcClear- Diagnostic trouble code categorymetadata- Metadata PIDs category. PIDs which are read just once during session with the Adapterlivedata- Livedata PIDs category. PIDs which are read frequently during session with the Adapterroutine- Routines PIDs category. PIDs which are executed on demand and might alter vehicle component behavior, e.g:Turn dashboard illumination on.
During single session the framework is able to work with multiple resource files which might be specific for different automotive manufacturers.
Generic list of PIDs can be found here
Configuration might looks like the one below example.
{
"capabilities": [
{
"id": "21000",
"mode": "01",
"pid": "00",
"description": "Supported PIDs 00",
"codecClass": "org.obd.metrics.command.SupportedPIDsCodec"
}
],
"dtcRead": [
{
"id": "27000",
"mode": "19",
"pid": "020D",
"description": "DTC Read",
"successCode": "5902CF",
"codecClass": "org.obd.metrics.command.dtc.DiagnosticTroubleCodeCodec"
}
],
"dtcClear": [
{
"id": "37000",
"mode": "14",
"pid": "FFFFFF",
"description": "DTC Clear",
"successCode": "54",
"codecClass": "org.obd.metrics.command.dtc.DiagnosticTroubleCodeClearCodec"
}
],
"metadata": [
{
"id": "17001",
"mode": "22",
"pid": "F190",
"description": "Vehicle Identification Number"
"codecClass": "org.obd.metrics.command.meta.HexCodec"
},
],
"livedata": [
{
"priority": 0,
"id": "7001",
"mode": "22",
"pid": "195A",
"length": 2,
"description": "Boost\nPressure",
"min": 0,
"max": 2800,
"units": "mbar",
"formula": "(A*256+B)"
},
],
"routine": [
{
"id": "10002",
"mode": "2F",
"pid": "55720308",
"description":"Turn dashboard illumination on",
"overrides" : {
"canMode": "INSTRUMENT_PANEL"
}
}
],
}The framework is able to calculate PID's value from the RAW data using dynamic formulas written in JavaScipt.
The formula can include additional JavaScript functions like Math.floor .
This feature dramatically decrease time to delivering new PIDs and reduces need to write dedicated java based decoders.
Example for Measured Boost Pressure PID
{
"pid": "195A",
"length": 2,
"formula": "(A*256+B) | 0",
}Given that 62195A09AA hex data is received from the ECU for above PID, FW implementation converts it (splitting by two characters) into decimal numbers identified by two parameters A and B (PID length here is equal 2).
Received data 62195A 09AA is later passed to the formula as follows:
A=09=9B=AA=170
Finally this results as 9 * 256 + 170 = 2474. The value 2474 is what FW emits for later processing.
By default framework interprets all hex as unsigned numbers.
In order to process negative numbers, property signed=true must be set true within the PID definition.
This property tells framework to decoded hex value using special rules.
Moreover, calculation formula must contains dedicated statement: if (typeof X === 'undefined')... to handle negative number which might be received under X parameter, see example bellow:
Definition
{
"description": "Measured Intake\nValve Crossing",
"signed": true,
"formula": "if (typeof X === 'undefined') X =(A*256+B); parseFloat((X * 0.0078125).toFixed(3))"
},
Framework allows to pass external parameters into PID formula. Through this calculation formula can be modified dynamically based on external factors. One of the example is calculation of the fuel level based on tank size, which might have different size in different vehicles.
In this example unit_tank_size is passed as the external parameter.
{
"priority": 3,
"id": "7040",
"mode": "22",
"pid": "1001",
"length": 1,
"description": "Fuel Level\n(Liters)",
"min": "0",
"max": "100",
"units": "L",
"formula": "parseFloat(((A*0.3921568)/100 * unit_tank_size).toFixed(1))"
},final Adjustments optional = Adjustments.builder()
.formuilaExternalParams(FormulaExternalParams.builder().param("unit_tank_size",tankSize).build())
.build();The framework is able to speak with multiple ECU with the same communication session.
Once sessions established ObdMetrics queries different modules like TCU, ECU without additional overhead.
Moreover FW it's able to work either with CAN 11 bit or CAN 29 bit headers.
final Pids pids = Pids
.builder()
.resource(contextClassLoader.getResource("mode01.json"))
.resource(contextClassLoader).getResource("alfa.json")).build();
.build();
final Init init = Init.builder()
.delay(1000)
.header(Header.builder().mode("22").header("DA10F1").build())
.header(Header.builder().mode("01").header("DB33F1").build())
.protocol(Protocol.CAN_29)
.sequence(DefaultCommandGroup.INIT).build();
final Workflow workflow = Workflow
.pids(pids)
workflow.start(BluetoothConnection.openConnection(), query, init, optional);The framework allows to override CAN headers just for specific PID's, and adjust it at runtime.
{
"priority": 0,
"id": "7029",
"mode": "22",
"pid": "051A",
"length": 1,
"description": "Gear Engaged",
"min": "-1",
"max": "10",
"units": "",
"type": "INT",
"formula": "x=A; if (x==221) {x=0 } else if (x==238) {x=-1} else { x=A/17} x",
"overrides" : {
"canMode": "555",
"batchEnabled": false
}
},
final Init init = Init.builder()
.header(Header.builder().mode("22").header("DA10F1").build())
.header(Header.builder().mode("01").header("DB33F1").build())
//overrides CAN mode
.header(Header.builder().mode("555").header("DA18F1").build())
.protocol(Protocol.CAN_29)
.build();As part of the solution there is available dedicated module name ObdMetricsTest which exposes set of interfaces like: CodecTest which allows to write clean PIDs tests with the focus on business aspects of its development.
interface MultiJet_2_2_Test extends CodecTest {
final String RESOURCE_NAME = "giulia_2_2_multijet.json";
@Override
default String getPidFile() {
return RESOURCE_NAME;
}
}
public class AirTempMafTest implements MultiJet_2_2_Test {
@ParameterizedTest
@CsvSource(value = {
"62193F0000=-40",
"62193F1100=47",
}, delimiter = '=')
public void test(String input, Integer expected) {
assertEquals(input, expected);
}
}The framework provides couple of ways of decoding ECU messages. One and the default way is through the formula definition, and second way is by using custom decoders which can read and transform ECU message. This section depicts how to use custom decoders.
import org.obd.metrics.codec.Codec;
import org.obd.metrics.pid.PidDefinition;
import org.obd.metrics.transport.Characters;
import org.obd.metrics.transport.message.ConnectorResponse;
public final class TestCodec implements Codec<String> {
@Override
public String decode(PidDefinition pid, ConnectorResponse connectorResponse) {
final String rawMessage = connectorResponse.getRawValue(pid);
....
return ....
}
}{
"id": "1111",
"mode": "22",
"pid": "1921",
"length": 9,
"description": "Custom decoder PID",
"codecClass": "org.obd.metrics.codec.custom.TestCodec"
}
The framework collects metadata about commands processing, you can easily get information about max, min, mean, value for the current session with ECU.
Example
final Workflow workflow = Workflow
.instance()
.pids(pids)
.initialize();
workflow.start(connection, query, init, optional);
final PidDefinitionRegistry pidRegistry = workflow.getPidRegistry();
final PidDefinition rpm = pidRegistry.findBy(13l);
final Diagnostics diagnostics = workflow.getDiagnostics();
final Histogram rpmHist = diagnostics.histogram().findBy(rpm);
Assertions.assertThat(rpmHist.getMin()).isGreaterThan(500);You can add multiple decoders for single PID. In the example bellow there are 2 decoders for PID 0115. One that calculates AFR, and second one shows Oxygen sensor voltage.
{
"id": "22",
"mode": "01",
"pid": 15,
"length": 2,
"description": "Calculated AFR",
"min": "0",
"max": "20",
"units": "Volts %",
"formula": "parseFloat( ((0.680413+((0.00488*(A / 200))*0.201356))*14.7).toFixed(2) )"
},
{
"id": "23",
"mode": "01",
"pid": 15,
"length": 2,
"description": "Oxygen sensor voltage",
"min": "0",
"max": "5",
"units": "Volts %",
"formula": "parseFloat(A / 200)"
}
The framework is able to calculate number of lines Adapter should return for the given query. This optimization speedup communication with the ECU.
Request:
01 0C 0B 11 0D 04 06 3
Last digit in the query: 3 indicates that Adapter should back to the caller as soon as it gets 3 lines from the ECU.
The framework supports batch queries and allows to query for up to 6 PID's in a single request for the mode 01.
For the mode 22 its allowed to query up to 11 PID's in the single call.
Request:
01 01 03 04 05 06 07
Response:
0110:4101000771611:0300000400051c2:06800781000000
It's possible to set priority for some of the PID's so they are pulled from the Adapter more frequently than others.
Intention of this feature is to get more accurate result for dynamic PID's.
A good example here, is a RPM or Boost pressure PID's that should be queried more often because of their characteristics over the time than Engine Coolant Temperature has (less frequent changes).
There is not necessary to have physical ECU device to play with the framework.
In the pre-integration tests where the FW API is verified its possible to use MockAdapterConnection that simulates behavior of the real OBD adapter.
MockAdapterConnection connection = MockAdapterConnection.builder()
.requestResponse("22F191", "00E0:62F1913532301:353533323020202:20")
.requestResponse("22F192", "00E0:62F1924D4D311:304A41485732332:32")
.requestResponse("22F187", "00E0:62F1873530351:353938353220202:20")
.requestResponse("22F190", "0140:62F1905A41521:454145424E394B2:37363137323839")
.requestResponse("22F18C", "0120:62F18C5444341:313930393539452:3031343430")
.requestResponse("22F194", "00E0:62F1945031341:315641304520202:20")
.build();The framework consists of multiple components that are intended to exchange the messages with the Adapter (Request-Response model) and propagate decoded metrics to the target application using a non-blocking manner (Pub-Sub model). All the internal details like managing multiple threads are hidden and the target application that includes FW must provide just a few interfaces that are required for establishing the connection with the Adapter and receiving the OBD metrics.
API of the framework is exposed through Workflow interface which centralize all features in the single place, see: Workflow.
Particular workflow implementations can be instantiated by calling Workflow.instance().initialize()
Workflow interface
/**
* {@link Workflow} is the main interface that expose the API of the framework.
* It contains typical operations that allows to play with the OBD adapters
* like:
* <ul>
* <li>Connecting to the Adapter</li>
* <li>Disconnecting from the Adapter</li>
* <li>Collecting OBD2 metrics</li>
* <li>Obtaining statistics registry</li>
* <li>Obtaining OBD2 PIDs/Sensor registry</li>
* <li>Gets notifications about errors that appears during interaction with the
* device.</li>
*
* </ul>
*
* @version 9.2.0
* @see Adjustments
* @see AdapterConnection
*
* @since 0.0.1
* @author tomasz.zebrowski
*/
public interface Workflow {
/**
* Execute routine for already running workflow
*
* @param id id of routine
* @param init init settings of the Adapter
*/
WorkflowExecutionStatus executeRoutine(@NonNull Long id, @NonNull Init init);
/**
* Updates query for already running workflow
*
* @param query queried PID's (parameter is mandatory)
* @param init init settings of the Adapter
* @param adjustments additional settings for process of collection the data
*/
WorkflowExecutionStatus updateQuery(@NonNull Query query, @NonNull Init init, @NonNull Adjustments adjustments);
/**
* It starts the process of collecting the OBD metrics
*
* @param connection the connection to the Adapter (parameter is mandatory)
* @param query queried PID's (parameter is mandatory)
*/
default WorkflowExecutionStatus start(@NonNull AdapterConnection connection, @NonNull Query query) {
return start(connection, query, Init.DEFAULT, Adjustments.DEFAULT);
}
/**
* It starts the process of collecting the OBD metrics
*
* @param connection the connection to the Adapter (parameter is mandatory)
* @param query queried PID's (parameter is mandatory)
* @param adjustments additional settings for process of collection the data
*/
default WorkflowExecutionStatus start(@NonNull AdapterConnection connection, @NonNull Query query,
Adjustments adjustments) {
return start(connection, query, Init.DEFAULT, adjustments);
}
/**
* It starts the process of collecting the OBD metrics
*
* @param adjustements additional settings for process of collection the data
* @param connection the connection to the Adapter (parameter is mandatory)
* @param query queried PID's (parameter is mandatory)
* @param init init settings of the Adapter
*/
WorkflowExecutionStatus start(@NonNull AdapterConnection connection, @NonNull Query query, @NonNull Init init,
Adjustments adjustements);
/**
* Stops the current workflow.
*/
default void stop() {
stop(true);
}
/**
* Stops the current workflow.
*
* @param gracefulStop indicates whether workflow should be gracefully stopped.
*/
void stop(boolean gracefulStop);
/**
* Informs whether {@link Workflow} process is already running.
*
* @return true when process is already running.
*/
boolean isRunning();
/**
* Rebuild {@link PidDefinitionRegistry} with new resources
*
* @param pids new resources
*/
void updatePidRegistry(Pids pids);
/**
* Gets the current pid registry for the workflow.
*
* @return instance of {@link PidDefinitionRegistry}
*/
PidDefinitionRegistry getPidRegistry();
/**
* Gets diagnostics collected during the session.
*
* @return instance of {@link Diagnostics}
*/
Diagnostics getDiagnostics();
/**
* Gets allerts collected during the session.
*
* @return instance of {@link Alerts}
*/
Alerts getAlerts();
/**
* It creates default {@link Workflow} implementation.
*
* @param pids PID's configuration
* @param formulaEvaluatorConfig the instance of {@link FormulaEvaluatorConfig}.
* Might be null.
* @param observer the instance of {@link ReplyObserver}
* @param lifecycleList the instance of {@link Lifecycle}
* @return instance of {@link Workflow}
*/
@Builder(builderMethodName = "instance", buildMethodName = "initialize")
static Workflow newInstance(Pids pids, FormulaEvaluatorConfig formulaEvaluatorConfig,
@NonNull ReplyObserver<Reply<?>> observer, @Singular("lifecycle") List<Lifecycle> lifecycleList) {
return new DefaultWorkflow(pids, formulaEvaluatorConfig, observer, lifecycleList);
}
}Quality of the project is ensured by junit and integration tests. In order to ensure that coverage is on the right level since 0.0.3-SNAPTHOST jacoco check plugin is part of the build. Minimum coverage ratio is set to 80%, build fails if not meet.
Framework has been verified against following ECU.
- Marelli MM10JA
- MED 17.3.1
- MED 17.5.5
- EDC 15.x
The framework was verified on the following versions of Android
- 7
- 8
- 9
- 10
- 11