Skip to content

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 (C#/.NET,C++, Dart, Go, Java, Kotlin, Node,Objective-C, PHP, and Ruby). OpenOBD works on the basis of sessions. This page elaborates on its implementation and the steps required to start one.

Session creation

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.

SessionController

The SessionController controls the creation, listing and termination of sessions.

Session

The Session controls the communication and user interaction for one specific ticket. The life span of a Session is shorter than the life span of a ticket.

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

Connection

A Connection consists of a J-Rex and an openOBD server. It is the entity that allows 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 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);
  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.