PassThruOpen v4.04 v5.0

Nawiązanie połączenia z adapterem

Ostatnia zmiana: 11 stycznia 2026 r.

Opis

Funkcja nawiązuje połączenie z adapterem ScanDoc. Parametry połączenia (adres IP lub nazwa urządzenia BLE) są odczytywane z pliku konfiguracyjnego j2534.json.

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

Parametry

pName - Musi być NULL lub wskaźnikiem na pusty ciąg znaków. Parametry połączenia są odczytywane z pliku konfiguracyjnego.
pDeviceID - Wskaźnik na zmienną, do której zostanie zapisany identyfikator urządzenia. Ten identyfikator jest używany w funkcjach PassThruConnect(), PassThruClose() i innych.

Plik konfiguracyjny

Ustawienia połączenia są przechowywane w pliku j2534.json. Lokalizacja pliku zależy od systemu operacyjnego:

System operacyjny	Ścieżka do pliku
Windows	`%APPDATA%\Quantex\j2534.json` Na przykład: C:\Users\User\AppData\Roaming\Quantex\j2534.json
macOS	`~/Library/Application Support/Quantex/j2534.json`
Linux	`~/.config/quantex/j2534.json`

Jeśli plik nie istnieje, zostanie utworzony automatycznie z ustawieniami domyślnymi.

Format pliku konfiguracyjnego

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

Opis pól

Pole	Typ	Opis
current_device	number	Indeks aktywnego urządzenia w tablicy `devices` (licząc od 0)
devices	array	Tablica urządzeń. Dla API v04.04 używane jest tylko jedno urządzenie o indeksie `current_device`
name	string	Wyświetlana nazwa urządzenia (dla wygody użytkownika)
connection_type	string	`"LAN"` dla WLAN/Ethernet lub `"BLE"` dla BLE Low Energy
device_ip	string	Adres IP adaptera (używany przy `connection_type = "LAN"`)
device_name	string	Numer seryjny lub nazwa urządzenia BLE (używane przy `connection_type = "BLE"`)
logs_directory	string	Katalog plików dziennika. Jeśli pusty, dzienniki są zapisywane w `<config_dir>/sdlogs`
debug	boolean	`true` - włączyć zapis dzienników, `false` - wyłączyć

Przykłady konfiguracji

Połączenie przez WLAN/LAN:

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

Połączenie przez BLE:

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

Kolejność wywoływania funkcji

PassThruOpen()       → Nawiązanie połączenia z adapterem
    ↓
PassThruConnect()    → Otwarcie kanału komunikacji z ECU
    ↓
PassThruReadMsg() / PassThruWriteMsg()  → Wymiana komunikatów
    ↓
PassThruDisconnect() → Zamknięcie kanału
    ↓
PassThruClose()      → Zwolnienie zasobów adaptera

Zawsze wywołuj PassThruClose() przed zakończeniem programu. W przeciwnym razie następne połączenie zwróci błąd ERR_DEVICE_IN_USE.

Limity czasu

Limit czasu połączenia: 500 ms. Gdy adapter jest niedostępny, funkcja zwróci ERR_DEVICE_NOT_CONNECTED po upływie limitu czasu.

Zwracane kody błędów

Kod	Opis	Możliwe przyczyny i rozwiązania
STATUS_NOERROR	Funkcja wykonana pomyślnie	-
ERR_DEVICE_NOT_CONNECTED	Brak połączenia z adapterem	Adapter jest wyłączony Brak połączenia sieciowego Nieprawidłowy adres IP w konfiguracji Rozwiązanie: sprawdź zasilanie adaptera, wykonaj `ping` na adres IP
ERR_DEVICE_IN_USE	Urządzenie jest już używane	W poprzedniej sesji nie wywołano `PassThruClose()` Inny program używa adaptera Rozwiązanie: uruchom ponownie program lub adapter
ERR_NULL_PARAMETER	Nie podano wskaźnika pDeviceID	Przekaż prawidłowy wskaźnik na zmienną
ERR_FAILED	Błąd wewnętrzny	Błąd odczytu pliku konfiguracyjnego Błąd alokacji pamięci Rozwiązanie: użyj `PassThruGetLastError()`, aby uzyskać szczegóły

Przykłady

Przykład w C/C++

#include "j2534_dll.hpp"

unsigned long DeviceID;
long ret;

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

// Praca z urządzeniem...

// Obowiązkowo zamykamy połączenie
PassThruClose(DeviceID);

Przykład w Kotlin (Android)

W tym przykładzie używana jest nakładka JNI J2534JNI do wywoływania natywnych funkcji J2534 z Kotlina.

// J2534JNI - to klasa-nakładka dla JNI
val j2534 = J2534JNI(context)

// Przekazujemy null - ustawienia są odczytywane z j2534.json
val deviceResult = j2534.ptOpen(null)

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

    // Praca z urządzeniem...

    // Obowiązkowo zamykamy połączenie
    j2534.ptClose(deviceID)
} else {
    Log.e("J2534", "Błąd: ${deviceResult.status}")
}

Przykład w Python (ctypes)

from ctypes import *
import platform

# Ładowanie biblioteki w zależności od systemu operacyjnego
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 - ustawienia są odczytywane z j2534.json
ret = j2534.PassThruOpen(None, byref(device_id))

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

    # Praca z urządzeniem...

    # Obowiązkowo zamykamy połączenie
    j2534.PassThruClose(device_id)
else:
    error = create_string_buffer(256)
    j2534.PassThruGetLastError(error)
    print(f"Błąd: {error.value.decode()}")

Przykład w 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);
}

// Użycie:
uint deviceId;
// IntPtr.Zero = NULL - ustawienia są odczytywane z j2534.json
int ret = J2534.PassThruOpen(IntPtr.Zero, out deviceId);

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

    // Praca z urządzeniem...

    // Obowiązkowo zamykamy połączenie
    J2534.PassThruClose(deviceId);
}
else
{
    var error = new System.Text.StringBuilder(256);
    J2534.PassThruGetLastError(error);
    Console.WriteLine($"Błąd: {error}");
}