obd-ii-kit-pro-react

Developer-friendly React Native hooks for OBD-II Bluetooth and TCP adapters. Zero hex codes. Just describe what you want — and get real-time car data.

Features

• 🔌 Dual transport — Bluetooth (real car) or TCP Socket (simulator)
• 🎯 Selective polling — only request the PIDs you need
• ⏱️ Custom interval — set your own polling rate per hook call
• 🔄 Real-time updates — state updated automatically on every response
• 🔢 No PID codes — use OBD_PID.RPM instead of '010C'
• 🧩 Context provider — share OBD state across your whole app tree
• 🛠️ Simulator included — develop without a car using the bundled TCP simulator
• 💡 Full TypeScript — every hook, option, and data field is typed

Installation

npm install obd-ii-kit-pro-react

Install the transport peer dependency you need:

For Bluetooth (real device):

npm install react-native-bluetooth-classic

For Socket/Simulator:

npm install react-native-tcp-socket

You only need to install the transport(s) you actually use.

Quick Start

Bluetooth (real OBD-II adapter)

import { useOBD, OBD_PID } from 'obd-ii-kit-pro-react';

export default function Dashboard() {
  const { data, status, connectDevice, disconnectDevice } = useOBD({
    pids: [OBD_PID.RPM, OBD_PID.SPEED, OBD_PID.COOLANT_TEMP],
    interval: 500,      // poll every 500ms
    transport: 'bluetooth',
    debug: true,        // logs to console
  });

  return (
    <>
      <Text>Status: {status}</Text>
      <Text>RPM: {data.rpm}</Text>
      <Text>Speed: {data.speed} km/h</Text>
      <Text>Coolant: {data.coolantTemp} °C</Text>
      <Button title="Connect" onPress={() => connectDevice(myBluetoothDevice)} />
      <Button title="Disconnect" onPress={disconnectDevice} />
    </>
  );
}

Socket / Simulator

const { data, status, connectDevice } = useOBD({
  pids: [OBD_PID.RPM, OBD_PID.SPEED, OBD_PID.FUEL_LEVEL],
  interval: 1000,
  transport: 'socket',
  socket: { host: '192.168.1.100', port: 35000 },
  autoConnect: true,   // connects automatically on mount
});

Running the Simulator

The package ships with a realistic OBD-II simulator (physics-based car simulation with idle/accelerating/cruising/braking modes).

Start it:

# Default port 35000
npx obd-simulator

# Custom port
npx obd-simulator --port 9000

Then point your app at your machine's IP:

socket: { host: '192.168.1.100', port: 35000 }

Tip: Find your IP with ipconfig getifaddr en0 (Mac) or ipconfig (Windows).

All Available PIDs

import { OBD_PID } from 'obd-ii-kit-pro-react';

// Core
OBD_PID.RPM                   // Engine RPM
OBD_PID.SPEED                 // Vehicle speed (km/h)
OBD_PID.COOLANT_TEMP          // Coolant temperature (°C)
OBD_PID.THROTTLE              // Throttle position (%)
OBD_PID.ENGINE_LOAD           // Engine load (%)
OBD_PID.FUEL_LEVEL            // Fuel level (%)
OBD_PID.INTAKE_TEMP           // Intake air temperature (°C)
OBD_PID.INTAKE_PRESSURE       // Intake manifold pressure (kPa)
OBD_PID.MAF                   // Mass air flow (g/s)
OBD_PID.TIMING_ADVANCE        // Ignition timing advance (° BTDC)
OBD_PID.RUNTIME               // Engine runtime (seconds)
OBD_PID.AMBIENT_TEMP          // Ambient air temperature (°C)
OBD_PID.CONTROL_MODULE_VOLTAGE // ECU voltage (V)
OBD_PID.FUEL_RATE             // Fuel consumption rate (L/h)

// Hybrid / EV
OBD_PID.HYBRID_BATTERY_SOC      // HV Battery state of charge (%)
OBD_PID.HYBRID_BATTERY_CURRENT  // HV Battery current (A)
OBD_PID.HYBRID_BATTERY_VOLTAGE  // HV Battery voltage (V)
OBD_PID.HYBRID_BATTERY_TEMP_A   // HV Battery temp A (°C)
OBD_PID.HYBRID_BATTERY_TEMP_B   // HV Battery temp B (°C)
OBD_PID.HYBRID_INVERTER_TEMP    // Inverter temperature (°C)
OBD_PID.HYBRID_MOTOR_TEMP       // Motor temperature (°C)
OBD_PID.HYBRID_SYSTEM_POWER     // Hybrid system power (kW)

// Extended
OBD_PID.EVAP_PRESSURE         // EVAP system pressure
OBD_PID.OXYGEN_SENSOR_1       // O2 Bank 1, Sensor 1 (V)
OBD_PID.OXYGEN_SENSOR_2       // O2 Bank 1, Sensor 2 (V)
OBD_PID.OXYGEN_SENSOR_3       // O2 Bank 2, Sensor 1 (V)
OBD_PID.OXYGEN_SENSOR_4       // O2 Bank 2, Sensor 2 (V)
OBD_PID.FUEL_PRESSURE         // Fuel rail pressure (kPa)
OBD_PID.OIL_TEMP              // Engine oil temperature (°C)
OBD_PID.DISTANCE_MIL_ON       // Distance with MIL on (km)

Hooks API

useOBD(options) — Main hook

The all-in-one hook. Manages the connection, polling, and data parsing.

const {
  data,              // OBDData — parsed values for requested PIDs
  status,            // 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error'
  isConnected,       // boolean shorthand for status === 'connected'
  error,             // Error | null
  connectDevice,     // (device?: BluetoothDevice) => Promise<void>
  disconnectDevice,  // () => Promise<void>
  sendCommand,       // (cmd: string) => void — raw escape hatch
} = useOBD(options);

Options

| Option | Type | Default | Description | |---|---|---|---| | pids | OBDPidKey[] | — | Required. Which PIDs to poll. | | transport | 'bluetooth' \| 'socket' | 'bluetooth' | Transport to use. | | socket | { host, port } | — | Required when transport='socket'. | | interval | number | 1000 | Poll cycle in milliseconds. | | autoConnect | boolean | false | Auto-connect on mount (socket only). | | debug | boolean | false | Enable verbose console logging. | | onData | (data: OBDData) => void | — | Callback on each data update. | | onConnect | () => void | — | Callback when connected. | | onDisconnect | () => void | — | Callback when disconnected. | | onError | (err: Error) => void | — | Callback on error. |

useOBDConnect(options) — Connection only

For when you just need connection lifecycle without polling.

const { connectDevice, disconnectDevice, status, isConnected, error } =
  useOBDConnect({
    transport: 'bluetooth',
    debug: true,
    onData: (raw) => console.log('Raw frame:', raw),
    onError: (err) => Alert.alert('OBD Error', err.message),
  });

useOBDPid(pid) — Single PID widget

Subscribe to a single PID value with display metadata. Requires <OBDProvider> ancestor.

const { value, unit, label } = useOBDPid(OBD_PID.RPM);
// → { value: 1450, unit: 'rpm', label: 'Engine RPM' }

return <Text>{label}: {value} {unit}</Text>;

OBDProvider + useOBDContext — App-wide sharing

Set up once at the top of your app and access OBD data anywhere.

// App.tsx
import { OBDProvider, OBD_PID } from 'obd-ii-kit-pro-react';

export default function App() {
  return (
    <OBDProvider
      transport="socket"
      socket={{ host: '192.168.1.100', port: 35000 }}
      pids={[OBD_PID.RPM, OBD_PID.SPEED, OBD_PID.COOLANT_TEMP]}
      interval={500}
      autoConnect
      debug
    >
      <MainNavigator />
    </OBDProvider>
  );
}

// SpeedWidget.tsx — anywhere in the tree
import { useOBDPid, OBD_PID } from 'obd-ii-kit-pro-react';

export function SpeedWidget() {
  const { value, unit } = useOBDPid(OBD_PID.SPEED);
  return <Text>{value} {unit}</Text>;
}

// ConnectButton.tsx
import { useOBDContext } from 'obd-ii-kit-pro-react';

export function ConnectButton() {
  const { connectDevice, disconnectDevice, isConnected } = useOBDContext();
  return (
    <Button
      title={isConnected ? 'Disconnect' : 'Connect'}
      onPress={isConnected ? disconnectDevice : () => connectDevice()}
    />
  );
}

Switching Between Simulator and Bluetooth

Change a single line:

// Development — point at the simulator
transport: 'socket',
socket: { host: '192.168.1.100', port: 35000 },

// Production — real Bluetooth OBD-II adapter
transport: 'bluetooth',

Or drive it from an env variable / config file:

const isDev = __DEV__;

useOBD({
  pids: [...],
  transport: isDev ? 'socket' : 'bluetooth',
  socket: isDev ? { host: '192.168.1.100', port: 35000 } : undefined,
});

Advanced Usage

Sending raw commands

const { sendCommand } = useOBD({ ... });

// Reset adapter
sendCommand('ATZ');

// Disable echo
sendCommand('ATE0');

// Request a specific PID manually
sendCommand('010C');

Custom polling logic with useOBDConnect

const { connectDevice, disconnectDevice } = useOBDConnect({
  transport: 'socket',
  socket: { host: '192.168.1.100', port: 35000 },
  onData: (raw) => {
    // Handle raw OBD frames yourself
    const updates = parseOBDResponse(raw);
    if (updates) myStore.update(updates);
  },
});

Using the parser standalone

import { parseOBDResponse, OBD_PID } from 'obd-ii-kit-pro-react';

const raw = '41 0C 1A F8\r'; // Example raw RPM response
const updates = parseOBDResponse(raw, new Set([OBD_PID.RPM]));
// → { rpm: 1726 }

OBDData Reference

All fields returned in data:

| Field | Type | Unit | Description | |---|---|---|---| | rpm | number | rpm | Engine RPM | | speed | number | km/h | Vehicle speed | | gear | number \| '-' | — | Estimated gear (1–5) | | coolantTemp | number | °C | Coolant temperature | | throttle | number | % | Throttle position | | fuelLevel | number | % | Fuel tank level | | range | number | km | Estimated range | | engineLoad | number | % | Engine load | | intakeTemp | number | °C | Intake air temp | | maf | number | g/s | Mass air flow | | intakePressure | number | kPa | Intake manifold pressure | | timingAdvance | number | ° | Timing advance | | runtime | number | s | Engine runtime | | controlModuleVoltage | number | V | ECU voltage | | fuelRate | number | L/h | Fuel consumption rate | | hybridBatterySOC | number | % | HV Battery SOC | | ... | ... | ... | (see types.ts for full list) |

License

MIT