# Getting Started

> **Library 2.0.0.213** · SAE J2534 v04.04 API

## 1. Loading the library

### Windows

Third-party applications locate the DLL through the standard J2534 registry
mechanism (see [CONFIGURATION.md](CONFIGURATION.md#windows-registry)):

```text
HKLM\SOFTWARE\PassThruSupport.04.04\Quantex - ScanDoc
    "Name"            = "ScanDoc"
    "Vendor"          = "Quantex"
    "FunctionLibrary" = "C:\Program Files\Quantex\J2534\j2534sd_v04_04_x64.dll"
```

Enumerate the subkeys of `PassThruSupport.04.04`, read `FunctionLibrary`, load
it with `LoadLibrary` and resolve the `PassThru*` exports with `GetProcAddress`.
32-bit applications on 64-bit Windows read the same path under
`HKLM\SOFTWARE\Wow6432Node\`.

### macOS / Linux

Link against (or `dlopen`) the shared library and resolve the `PassThru*`
symbols:

```c
void *lib = dlopen("libj2534_v04_04.dylib", RTLD_NOW); // .so on Linux
int32_t (*PassThruOpen)(char *, uint32_t *) = dlsym(lib, "PassThruOpen");
```

All functions use C linkage. On Windows the calling convention is `__stdcall`;
on other platforms it is the default C convention.

### Android

See [ANDROID.md](ANDROID.md) — the library ships with a Kotlin JNI wrapper.

## 2. Connection strings

`PassThruOpen` accepts a device name string:

```text
<device_name>;<type><value>
```

The value starts **immediately after the type letter** (no separator):

| Type | Transport | Example |
|------|-----------|---------|
| `n` | LAN / Wi-Fi (TCP) | `sd0;n192.168.12.3` |
| `b` | BLE by device name | `sd0;bN49999` |
| `m` | BLE by MAC address (Android, Linux) | `sd0;m12:34:56:78:9A:BC` |
| `u` | BLE by UUID (macOS) | `sd0;u8E64...` |
| `c` | USB serial port (macOS) | `sd0;c/dev/tty.usbserial-DP04XHM7` |

If `name` is `NULL`, empty, or contains no `;`, the library opens the device
selected in `j2534.json` (`current_device` / `current_interface`) — this is how
devices are switched without touching application code. See
[CONFIGURATION.md](CONFIGURATION.md).

Notes:

- Default device IP addresses: ScanDoc Nano/SDMax `192.168.12.3`,
  ScanDoc Classic `192.168.1.3`. The device's TCP port is fixed (53983) and is
  not part of the connection string.
- BLE device names equal the device serial number (e.g. `N49999`).

## 3. Minimal session (C)

```c
#include "j2534.h"

uint32_t device_id = 0, channel_id = 0, filter_id = 0, num = 1;

// 1. Open (here: explicit LAN address; pass NULL to use j2534.json)
if (PassThruOpen("sd0;n192.168.12.3", &device_id) != STATUS_NOERROR) {
    char err[256];
    PassThruGetLastError(err);
    printf("open failed: %s\n", err);
    return 1;
}

// 2. Connect ISO 15765 @ 500 kbit/s
PassThruConnect(device_id, ISO15765, 0, 500000, &channel_id);

// 3. Flow-control filter for 11-bit OBD-II request/response pair 7E0/7E8
pt_msg_t mask = {0}, pattern = {0}, flow = {0};
mask.protocol_id = pattern.protocol_id = flow.protocol_id = ISO15765;
mask.tx_flags = pattern.tx_flags = flow.tx_flags = ISO15765_FRAME_PAD_TF;
mask.data_size = pattern.data_size = flow.data_size = 4;
memcpy(mask.data,    "\xFF\xFF\xFF\xFF", 4);
memcpy(pattern.data, "\x00\x00\x07\xE8", 4);
memcpy(flow.data,    "\x00\x00\x07\xE0", 4);
PassThruStartMsgFilter(channel_id, FLOW_CONTROL_FILTER, &mask, &pattern, &flow, &filter_id);

// 4. UDS/OBD request: Mode 09 PID 02 (VIN), functional address 7DF
pt_msg_t tx = {0};
tx.protocol_id = ISO15765;
tx.tx_flags = ISO15765_FRAME_PAD_TF;
tx.data_size = 6;
memcpy(tx.data, "\x00\x00\x07\xDF\x09\x02", 6);
num = 1;
PassThruWriteMsgs(channel_id, &tx, &num, 200);

// 5. Read the response (first messages may be TX confirmation / segmentation markers)
for (int i = 0; i < 10; i++) {
    pt_msg_t rx = {0};
    num = 1;
    int32_t ret = PassThruReadMsgs(channel_id, &rx, &num, 1000);
    if (ret != STATUS_NOERROR || num == 0) continue;
    if (rx.rx_status & TX_MSG_TYPE) continue;       // loopback/echo
    if (rx.rx_status & START_OF_MESSAGE) continue;  // segmented msg start marker
    // rx.data: [4-byte CAN ID][0x49 0x02 0x01][VIN...]
    break;
}

// 6. Tear down
PassThruDisconnect(channel_id);
PassThruClose(device_id);
```

## 4. Device discovery (J2534-2)

```c
uint32_t count = 0;
PassThruScanForDevices(&count);         // scans BLE/network, blocks for a few seconds
for (uint32_t i = 0; i < count; i++) {
    pt_device_t dev;
    if (PassThruGetNextDevice(&dev) != STATUS_NOERROR) break;
    printf("%s\n", dev.device_name);    // e.g. "N49999;m12:34:56:78:9A:BC"
}
```

The returned `device_name` is ready to be passed to `PassThruOpen`.

## 5. Where to go next

- Full function list and structures: [API_REFERENCE.md](API_REFERENCE.md)
- Error codes and diagnostics: [ERROR_HANDLING.md](ERROR_HANDLING.md)
- DoIP / ISO 13400: [DOIP.md](DOIP.md)
- Library logs (`.qlog`): [LOG_FORMAT.md](LOG_FORMAT.md)
