This repository contains a web-based viewer for exploring automotive diagnostic data description files based on the file format described by ISO 22901. It consists of a frontend and a backend server. The backend provides the underlying data via a RESTfull HTTP API, whilst the frontend visualizes said data within a web browser using web technologies.
This README.md provides a quick overview of the project; further details are given by the respective README.md files for the user interface and the backend server.
For deployment in stand-alone mode, odex.viewer currently only requires Python version 3.10 or later to be available on the system.
To build the project from scratch, the following software packages are required as well:
- Node.js version 22.0.0 or later
- Python version 3.10 or later
- Java version 21.0.5 or later (only required for OpenAPI-based code generation)
First, clone this repository, and after all system prerequisites for development have been satisfied, all python and node.js modules required by odex.viewer must be installed:
# ODEX_VIEWER_DIR is the top-level directory of your local clone of the
# odex.viewer repository
cd $ODEX_VIEWER_DIR/server; pip install -r requirements.txt
cd $ODEX_VIEWER_DIR/viewer; npm installOnce the depencencies have been installed, the files required for stand-alone mode can be generated:
cd $ODEX_VIEWER_DIR/viewer; npm run build(This is not required if you intend to exclusively run odex.viewer in development mode, i.e., using separate web servers for the user interface and the backend functionality.)
Using a single "all-in-one" web server for the user interface requires the static files for the UI to be generated (see previous section). The server can then be started via
cd $ODEX_VIEWER_DIR/server; python -m diag_server.openapi_serverAt this point, the odex.viewer user interface ought to be available on [http://localhost:8080/].
To start separate front- and backend servers for development, run the following in two speparate terminal windows:
# start backend server
cd $ODEX_VIEWER_DIR/server; python -m diag_server.openapi_serverand
# start frontend server
cd $ODEX_VIEWER_DIR/viewer; npm run devAs an alternative, one of the provided Visual Studio Code launch configurations can be used for starting and debugging the viewer and/or the backend server.
After this, you should be able to open the following URLs in your web browser:
- http://localhost:3000: User interface
- http://localhost:8080/v1/ui: Low-level user interface of backend server
The respository contains a collection of Visual Studio Code launch configurations which can be used for automation of tasks such as code generation steps or ODX test data provisioning on server startup.
The following sections provide a list of all launch configurations with a short description, grouped by their underlying use cases.
- "Start Viewer and Server": Starts the server and viewer together and loads the viewer directly in a new browser window.
- "Start Server via Uvicorn": Starts a new instance of the backend server using uvicorn ASGI server.
- "Start Server": Starts a new instance of the backend server.
- "Start Server/Open Browser": Starts a new instance of the backend server and opens a browser with the OpenAPI of the server in Swagger-UI.
- "Start Server with Data": Starts a new instance of the backend server, uploads all PDX files contained in the
$ODEX_VIEWER_DIR/server/pdx-input/input directory to the server and opens a browser with the OpenAPI of the server in Swagger-UI. - "Start Viewer": Starts a new instance of the user interface server via
npm run dev. - "Start Viewer/Open Browser": Starts a new instance of the user interface server and opens it in a new browser window.
- "Upload PDX files": Uploads all PDX files contained in the
$ODEX_VIEWER_DIR/server/pdx-input/directory to a running instance of the backend server.
- "Generate JSON Schemas and OpenAPI code": Generates and updates all JSON schema definitions for odxtools dataclasses in [
odxtools-types.json] (see Generate JSON Schema Definitions for odxtools Data Model Classes) and triggers the OpenAPI server code generation described in Server Stub Code Generation from OpenAPI Specification. - "Cleanup and regenerate OpenAPI code": Deletes all existing - potentially outdated - generated models and controllers and retriggers the OpenAPI generator to produce up-to-date code reflecting the definitions in
diag-server.yml. This is necessary, for example, if schema names have changed since this introduces new classes during generation while the deprecated previous class definitions will still be present, if not deleted.
To build and bundle a respective Docker container for odex.viewer, open a terminal and run:
cd $ODEX_VIEWER_DIR; docker build -t odex.viewer .After successful creation of the Docker image, odex.viewer can be started using:
cd $ODEX_VIEWER_DIR; docker run -d -p 8080:8080 odex.viewerYou can then open the viewer in your browser with the following URL: [http://localhost:8080]. The low-level user interface of backend server uses Swagger and is provided with the server at [http://localhost:8080/v1/ui].
Hint: An overview of all docker CLI commands can be found in the Docker documentation.
Any contributions to odex.viewer are highly welcome. If you want to contribute to the odex.viewer project, please read our contributing guide.
Please read our Code of Conduct as it is our base for interaction.
Please visit https://group.mercedes-benz.com/provider/ for more information on the provider Mercedes-Benz AG.
Notice: Before you use the odex.viewer program in productive use, please take all necessary precautions such as testing and verifying the program with regard to your specific use. The source code has been tested solely for our own use cases, which might differ from yours.
This project is licensed under the GNU Affero General Public License v3.0.