openOBD session management

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 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 that make it possible to communicate with a vehicle and help in smoothly carrying out diagnostic procedures. The openOBD gRPC page 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.