PassThruOpen v4.04 v5.0

Verbindung zum Adapter herstellen

Letzte Änderung: 11. Januar 2026

Beschreibung

Die Funktion stellt die Verbindung zum ScanDoc-Adapter her. Die Verbindungsparameter (IP-Adresse oder Name des BLE-Geräts) werden aus der Konfigurationsdatei j2534.json gelesen.

long PassThruOpen(void* pName, unsigned long* pDeviceID)

Parameter

pName - Muss NULL oder ein Zeiger auf eine leere Zeichenkette sein. Die Verbindungsparameter werden aus der Konfigurationsdatei gelesen.
pDeviceID - Zeiger auf eine Variable, in die die Geräte-ID geschrieben wird. Diese ID wird in den Funktionen PassThruConnect(), PassThruClose() und anderen verwendet.

Konfigurationsdatei

Die Verbindungseinstellungen werden in der Datei j2534.json gespeichert. Der Speicherort der Datei hängt vom Betriebssystem ab:

Betriebssystem	Dateipfad
Windows	`%APPDATA%\Quantex\j2534.json` Beispiel: C:\Users\User\AppData\Roaming\Quantex\j2534.json
macOS	`~/Library/Application Support/Quantex/j2534.json`
Linux	`~/.config/quantex/j2534.json`

Wenn die Datei nicht vorhanden ist, wird sie automatisch mit den Standardeinstellungen erstellt.

Format der Konfigurationsdatei

{
    "current_device": 0,
    "devices": [
        {
            "name": "ScanDoc",
            "connection_type": "LAN",
            "device_ip": "192.168.1.3",
            "device_name": ""
        }
    ],
    "logs_directory": "",
    "debug": false
}

Beschreibung der Felder

Feld	Typ	Beschreibung
current_device	number	Index des aktiven Geräts im Array `devices` (beginnend bei 0)
devices	array	Array der Geräte. Für die API v04.04 wird nur ein Gerät mit dem Index `current_device` verwendet
name	string	Anzeigename des Geräts (zur besseren Übersicht für den Benutzer)
connection_type	string	`"LAN"` für WLAN/Ethernet oder `"BLE"` für BLE Low Energy
device_ip	string	IP-Adresse des Adapters (wird bei `connection_type = "LAN"` verwendet)
device_name	string	Seriennummer oder Name des BLE-Geräts (wird bei `connection_type = "BLE"` verwendet)
logs_directory	string	Ordner für Log-Dateien. Wenn leer, werden die Logs in `<config_dir>/sdlogs` gespeichert
debug	boolean	`true` - Protokollierung aktivieren, `false` - deaktivieren

Konfigurationsbeispiele

Verbindung über WLAN/LAN:

{
    "current_device": 0,
    "devices": [
        {
            "name": "ScanDoc FD",
            "connection_type": "LAN",
            "device_ip": "192.168.1.100",
            "device_name": ""
        }
    ],
    "debug": false
}

Verbindung über BLE:

{
    "current_device": 0,
    "devices": [
        {
            "name": "ScanDoc FD",
            "connection_type": "BLE",
            "device_ip": "",
            "device_name": "N4999"
        }
    ],
    "debug": true
}

Reihenfolge der Funktionsaufrufe

PassThruOpen()       → Verbindung zum Adapter herstellen
    ↓
PassThruConnect()    → Kommunikationskanal zum ECU öffnen
    ↓
PassThruReadMsg() / PassThruWriteMsg()  → Nachrichtenaustausch
    ↓
PassThruDisconnect() → Kanal schließen
    ↓
PassThruClose()      → Ressourcen des Adapters freigeben

Rufen Sie immer PassThruClose() auf, bevor Sie das Programm beenden. Andernfalls liefert die nächste Verbindung den Fehler ERR_DEVICE_IN_USE zurück.

Timeouts

Verbindungs-Timeout: 500 ms. Ist der Adapter nicht erreichbar, liefert die Funktion nach Ablauf des Timeouts ERR_DEVICE_NOT_CONNECTED zurück.

Rückgabe-Fehlercodes

Code	Beschreibung	Mögliche Ursachen und Lösungen
STATUS_NOERROR	Funktion erfolgreich ausgeführt	-
ERR_DEVICE_NOT_CONNECTED	Keine Verbindung zum Adapter	Adapter ist ausgeschaltet Keine Netzwerkverbindung Falsche IP-Adresse in der Konfiguration Lösung: Prüfen Sie die Stromversorgung des Adapters und führen Sie einen `ping` auf die IP-Adresse aus
ERR_DEVICE_IN_USE	Gerät wird bereits verwendet	`PassThruClose()` wurde in der vorherigen Sitzung nicht aufgerufen Ein anderes Programm verwendet den Adapter Lösung: Starten Sie das Programm oder den Adapter neu
ERR_NULL_PARAMETER	Der Zeiger pDeviceID wurde nicht angegeben	Übergeben Sie einen gültigen Zeiger auf eine Variable
ERR_FAILED	Interner Fehler	Fehler beim Lesen der Konfigurationsdatei Fehler bei der Speicherzuweisung Lösung: Verwenden Sie `PassThruGetLastError()`, um Details zu erhalten

Beispiele

Beispiel in C/C++

#include "j2534_dll.hpp"

unsigned long DeviceID;
long ret;

// pName = NULL - Einstellungen werden aus j2534.json gelesen
ret = PassThruOpen(NULL, &DeviceID);
if (ret != STATUS_NOERROR)
{
    char error[256];
    PassThruGetLastError(error);
    printf("Error: %s\n", error);
    return;
}

// Arbeit mit dem Gerät...

// Verbindung unbedingt schließen
PassThruClose(DeviceID);

Beispiel in Kotlin (Android)

In diesem Beispiel wird der JNI-Wrapper J2534JNI verwendet, um die nativen J2534-Funktionen aus Kotlin aufzurufen.

// J2534JNI - das ist eine Wrapper-Klasse für JNI
val j2534 = J2534JNI(context)

// Wir übergeben null - Einstellungen werden aus j2534.json gelesen
val deviceResult = j2534.ptOpen(null)

if (deviceResult.status == STATUS_NOERROR) {
    val deviceID = deviceResult.deviceId
    Log.i("J2534", "Adapter geöffnet, DeviceID: $deviceID")

    // Arbeit mit dem Gerät...

    // Verbindung unbedingt schließen
    j2534.ptClose(deviceID)
} else {
    Log.e("J2534", "Fehler: ${deviceResult.status}")
}

Beispiel in Python (ctypes)

from ctypes import *
import platform

# Laden der Bibliothek je nach Betriebssystem
if platform.system() == "Windows":
    j2534 = windll.LoadLibrary("j2534sd_v04_04_x64.dll")
elif platform.system() == "Darwin":
    j2534 = cdll.LoadLibrary("libj2534_v04_04.dylib")
else:
    j2534 = cdll.LoadLibrary("libj2534_v04_04.so")

device_id = c_ulong()

# pName = None - Einstellungen werden aus j2534.json gelesen
ret = j2534.PassThruOpen(None, byref(device_id))

if ret == 0:  # STATUS_NOERROR
    print(f"Adapter geöffnet, DeviceID: {device_id.value}")

    # Arbeit mit dem Gerät...

    # Verbindung unbedingt schließen
    j2534.PassThruClose(device_id)
else:
    error = create_string_buffer(256)
    j2534.PassThruGetLastError(error)
    print(f"Fehler: {error.value.decode()}")

Beispiel in C# (P/Invoke)

using System;
using System.Runtime.InteropServices;

class J2534
{
    [DllImport("j2534sd_v04_04_x64.dll", CallingConvention = CallingConvention.StdCall)]
    public static extern int PassThruOpen(IntPtr pName, out uint pDeviceID);

    [DllImport("j2534sd_v04_04_x64.dll", CallingConvention = CallingConvention.StdCall)]
    public static extern int PassThruClose(uint DeviceID);

    [DllImport("j2534sd_v04_04_x64.dll", CallingConvention = CallingConvention.StdCall)]
    public static extern int PassThruGetLastError(
        [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pErrorDescription);
}

// Verwendung:
uint deviceId;
// IntPtr.Zero = NULL - Einstellungen werden aus j2534.json gelesen
int ret = J2534.PassThruOpen(IntPtr.Zero, out deviceId);

if (ret == 0) // STATUS_NOERROR
{
    Console.WriteLine($"Adapter geöffnet, DeviceID: {deviceId}");

    // Arbeit mit dem Gerät...

    // Verbindung unbedingt schließen
    J2534.PassThruClose(deviceId);
}
else
{
    var error = new System.Text.StringBuilder(256);
    J2534.PassThruGetLastError(error);
    Console.WriteLine($"Fehler: {error}");
}