openOBD protocol

This page explains protocol implementation of openOBD. The aim is to help developers implement the openOBD protocol in their desired language. Currently, Jifeline supports the openOBD protocol implementation only in Python but the possibility exists to implement in a wide range of languages (1). openOBD works on the basis of sessions. This page elaborates on the implementation steps that are required to create, run and finish a session.

C#/.NET,C++, Dart, Go, Java, Kotlin, Node,Objective-C, PHP, and Ruby.

openOBD setup

Session Handling — fig 1. Jifeline Networks passthrough setup

openOBD session

An openOBD session always exists in the context of a connection. By the term 'connection' we mean a connection on a server that routes OBD2 traffic to and from a remote connector (J-ReX). Figure 1 shows how an openOBD session relates to a connection, First, we would like to introduce some terminology. In figure 2 the timeline is depicted.

openOBD session management

In the openOBD protocol there are two main services that have different responsibilities. The first one is the SessionController and the second one is the Session . First, we will introduce the entities that take part in the creation of an openOBD session. In figure 2 we depict schematically how an openOBD session is created.

The gRPC client is the client implementation by a 3rd party (e.g. Jifeline Partner / Diagnostic service provider).

The gRPC server contains the services that allow the creation and management of openOBD sessions. These sessions integrate seamlessly within the Jifeline Networks infrastructure.

Process A is the client application that creates and manages an openODB session from the clients perspective (3^rd party)

Process B is the client application that runs the diagnostic procedure on an openOBD session (3^rd party)

Session Controller is a server side controller that manages authentication and session control (creation, listing and termination). The client (Process A) needs Jifeline Partner API credentials to access this service.

Session Session is an openOBD session that acts as a gateway for the client (Process B) to a remote vehicle. It controls the communication and user interaction for one specific ticket. The life span of an openOBD session is shorter than the life span of a ticket.

Client process separation

Process A and B can be implemented in the same client code. This is the case in our examples throughout this website. However, in a production environment there are some great benefits of separating the client in two separate processes:

Privilege separation
The context where the diagnostic procedure (Process B) is running does not have more privileges than needed. Its only rights are directly related to the openOBD session and end when the openOBD session is finished. This limits the chances of accidental (or intentional) mistakes. Additionally, the master credentials, that need to be carefully protected, are only needed by Process A.
Parallelization
The software that creates the session (Process A) has a clear designated task and can trigger multiple diagnostic procedures (Process B) in parallel.
Delegation
The diagnostic procedures (Process B) can run in a different environment, even a different data center, as long as Process B receives a message envelope with the {SessionInfo} of Process A (see step in figure 2) through a secure channel.

This separation of Process A and Process B enable Jifeline Partners to create an openOBD session on their ticket and hand over the control to a different party (e.g. a diagnostic service provider), just by providing them with the {SessionInfo}. This control is only enabled for the duration of this particular session and does not give the diagnostic service provider more authorization than needed.

Sequence diagram

An overview of how a Session is created through the SessionController is shown in the sequence diagram below.

sequenceDiagram
    autonumber

    rect var(--openobd-session-controller-color)
    Client->>SessionController: startSessionOnTicket(TicketId)
    create participant Session
    SessionController-->>Session: create session
    SessionController->>Client: SessionInfo
    end
    rect var(--openobd-session-color)
    Client->>Session: authenticate() using SessionInfo
    loop
        Client->>Session: Request x
        Session-->>Connection: Request x
        note over Client,Connection: Data communication
        Connection-->>Session: Response y
        Session->>Client: Response y
    end
    destroy Session 
    Client->>Session: finish(ServiceResult)
    end

Connection

A Connection is defined as a J-Rex device that is connected to a vehicle's OBD2 port and an openOBD server. It is the entity that facilitates communication over the cloud from the openOBD server to the vehicle.

An overview of what role the Connection plays and its relation between server and the vehicle.

sequenceDiagram
    create participant Server
    create participant Connection
    Server ->> Connection: create <br/> connection
    rect var(--openobd-pink-light)
    loop perform requested service
        Server ->> Connection: request x
        Connection -->> Vehicle: request x
        Note over Server, Vehicle: The connection behaves as the middle man <br/> forwarding and receiving messages.
        Vehicle -->> Connection: response y
        Connection ->> Server: response y
    end
    end
    destroy Connection
    Server ->> Connection: close <br/> connection

Info

Every openOBD session is linked to its dedicated resource allowing for communication with a vehicle to perform diagnostic procedures via openOBD.

Sessions

The information required to start an openOBD session can be found in Credentials. Using this information, it is required to authenticate to the openOBD server to be able to start a session.

Authentication

Before starting a new session authentication must be carried out between client and server. This is done via getSessionControllerToken. The diagram shows the Authenticate message being sent and the SessionControllerToken message being received. After this step it is possible to start a session using startSessionOnTicket or startSessionOnConnector.

sequenceDiagram
    participant Client
    participant Server
    Note over Client, Server: getSessionControllerToken
    Client->>Server: Authenticate
    Server->>Client: sessionControllerToken

Note

Whenever using sessionController for e.g. starting or interrupting a session. The sessionControllerToken must be sent by the client via gRPC metadata to prove current session validity.

Starting a session

After authentication is carried out, it is possible to start a new session and start communicating with the server to send diagnostic commands to the connected vehicle. The diagram shows starting a session using startSessionOnTicket where the TicketId message is sent and a SessionInfo message is received. This message contains details about the session and can be used as reference to identify between multiple sessions.

sequenceDiagram
    participant Client
    participant Server
    Note over Client, Server: startSessionOnTicket
    Client->>Server: TicketId
    Server->>Client: SessionInfo

Session states

An openOBD session can exist in one of five possible states. The five states, and the possible transitions between these states, are shown in the diagram below.

When creating a new openOBD session, the session's state will be available. The moment any communication occurs, authentication will first take place, and the session will transition to active. From either of these states, it is possible for a session to become either interrupted or failed. interrupted means that a session hasn't been gracefully stopped through gRPC, but has been stopped by other means, for example by a call made through the Partner API, or by calling interruptSession. failed means that a session has been stopped because of a server-side error. The finished state can only be reached when an active session has been gracefully closed by a gRPC call.

When a session has transitioned to one of the final states (interrupted, finished, or failed) it is not possible to use the session anymore, and the session's info will remain retrievable for two more minutes. A new session will have to be started if further communication is desired.

graph TB
  START[ ] --> |Start| S(available)
  S --> |Authenticate| A(active);
  A --> |Release| S;
  S --> I(interrupted);
  A --> I;
  A --> F(finished)
  A --> E;
  S --> E(failed);

  style START fill-opacity:0, stroke-opacity:0;

Session management

An openOBD session can be managed by making calls through the Partner API or by functions in SessionController. An example python client implementation in Session Management shows how to start, stop, retrieve and interrupt sessions. The diagram shows an example of retrieving a session using SessionId.

sequenceDiagram
    participant Client
    participant Server
    Note over Client, Server: getSession
    Client->>Server: SessionId
    Server->>Client: SessionInfo

Services

openOBD offers a multitude of services making it possible to communicate with a vehicle and helping in carrying out a diagnostic procedure smoothly. openOBD grpc shows all available services.

When starting communication services, the session claims its resource by authentication. This sets the session state from available to active ensuring that no one else can claim this session and its resource. Now, communication services between client and server can be carried out to perform the desired diagnostic service.

sequenceDiagram
    participant Client
    participant Server 
    Note over Client, Server: authenticate
    Client->>Server: EmptyMessage
    Server->>Client: SessionToken

Note

The SessionToken mentioned here differs from that mentioned in the sessionController i.e.,
sessionControllerToken. This token is used to lock in the session and activate it. It required to be included in the gRPC metadata for following calls to the server.

Following the above-mentioned procedure, it is required ensure the validity of the SessionToken when carrying out services. This is done using openSessionTokenStream. It keeps the session authenticated which in turn ensure services to be carried out.