🚗 Diagnostic Trouble Codes (Flutter)

A fully offline Diagnostic Trouble Code (DTC) database for Flutter.

This package provides a clean, asynchronous Flutter wrapper around the DTC Database created by Waleed Judah (Wal33D) — enabling fast local lookups of OBD-II fault codes without APIs, internet access, or custom SQL logic.

The original database and definitions are maintained by Wal33D. 📦 The dtc_codes_v0.1.0.db database is already bundled inside this package. No manual download or setup is required.

🔗 Original Repository: https://github.com/Wal33D/dtc-database

✨ What This Package Does

Most diagnostic apps need to:

Interpret OBD-II fault codes
Provide descriptions instantly
Work offline
Avoid maintaining their own database logic

This package provides:

✅ Offline SQLite DTC database ✅ Generic SAE J2012 coverage ✅ Manufacturer-specific definitions ✅ Zero CRUD required ✅ Built-in caching (LRU) ✅ Async Flutter-native API ✅ Asset-based database loading ✅ Production-safe singleton access

📱 Platform Support

Platform	Status
Android	✅ Supported
iOS	⚠️ Untested
macOS	⚠️ Untested
Windows	⚠️ Untested
Linux	⚠️ Untested
Web	❌ Not Supported (SQLite required)

📊 Database Overview

Dataset included via the original project:

Category	Count
Total Definitions	18,805
Unique DTC Codes	12,128
Generic Codes	9,415
Manufacturer Codes	9,390
Manufacturers	33
Powertrain (P)	14,821
Body (B)	1,465
Chassis (C)	985
Network (U)	1,534

🔗 Database Compatibility

This package follows the release lifecycle of the original Wal33D DTC Database project.

diagnostic_trouble_codes	Wal33D DTC Database
1.0.x	>= 0.1.0

The bundled database snapshot corresponds to Wal33D DTC Database v0.1.0.

Future package updates will primarily occur when:

The upstream database publishes a new release
Dependencies require updates
Wrapper code adapts to upstream structural changes

📊 Example Dashboard

🧠 Why Use This Package?

Typical implementations require:

❌ Remote API calls ❌ Manual SQLite queries ❌ Custom schema handling ❌ Code normalization logic ❌ Manufacturer fallback logic

Diagnostic Trouble Codes provides:

🚀 Instant local lookup
🧩 Simple Flutter integration
🧠 Correct fallback behavior (manufacturer → generic)
⚡ Cached repeated queries
🔒 Offline reliability

🚀 Getting Started

- Installation

dependencies:
  diagnostic_trouble_codes: ^1.0.0

- Initialize Database

final db = await DiagnosticTroubleCodeDatabase.instance;

Initialization automatically:

Copies database from assets
Stores it locally
Opens SQLite connection

No setup required.

🔍 Basic Usage

Lookup a Code

final diagnosticTroubleCode = await database.getDiagnosticTroubleCode('P0420');

print('${diagnosticTroubleCode?.code}: ${diagnosticTroubleCode?.description}');

Get Description Only

final description = await database.getDescription('P0171');

print(description);

Manufacturer-Specific Lookup

final fordSpecific = await database.getDescription(
  'P1690',
  manufacturer: 'FORD',
);

Automatically falls back to generic definitions if unavailable.

Search Codes

final diagnosticTroubleCodes = await database.search('oxygen', limit: 10);

for (final diagnosticTroubleCode in diagnosticTroubleCodes) {
  print('${diagnosticTroubleCode.code}: ${diagnosticTroubleCode.description}');
}

Batch Lookup

final results = await database.batchLookup([
  'P0171',
  'P0300',
  'B0001',
]);

print(results);

Filter by Type

final powertrainCodes = await database.getByType('P', limit: 20);

Types:

Code	Meaning
P	Powertrain
B	Body
C	Chassis
U	Network

Manufacturer Codes

final fordCodes = await database.getManufacturerCodes('FORD');

Database Statistics

final statistics = await database.getStatistics();

print(statistics['total']);
print(statistics['type_P']);

Change Locale

database.setLocale('en');

Changing locale automatically clears cache safely.

Close Database

await database.close();

🧩 Data Model

`DiagnosticTroubleCode`

diagnosticTroubleCode.code
diagnosticTroubleCode.description
diagnosticTroubleCode.type
diagnosticTroubleCode.typeName
diagnosticTroubleCode.manufacturer
diagnosticTroubleCode.isGeneric
diagnosticTroubleCode.locale

Example:

P0420 - Catalyst System Efficiency Below Threshold

⚡ Performance Features

Built-In LRU Cache

Repeated lookups avoid database queries:

Least Recently Used eviction
Locale-aware cache keys
Automatic invalidation

No configuration required.

🏗 Architecture Overview

Flutter App
      ↓
DiagnosticTroubleCodeDatabase
      ↓
sqflite (SQLite)
      ↓
dtc_codes_v0.1.0.db (Local Asset)

The database is:

Fully local
Read-only during runtime
Optimized with indexes

🔗 Relationship to Original Project

This package wraps the database created by:

👤 Waleed Judah (Wal33D)

Original repository:

👉 https://github.com/Wal33D/dtc-database

The original project provides:

Database generation
Source datasets
Python / Java / Android wrappers

This Flutter package provides:

✅ Native Flutter integration ✅ Asset initialization ✅ Async Dart API ✅ Mobile-friendly caching

All diagnostic definitions belong to the original project.

🧪 Testing

The package includes:

✅ Schema validation tests ✅ Runtime behavior tests ✅ Cache validation tests ✅ SQLite FFI testing support

Run tests:

flutter test

❌ What This Package Is Not

This package does not:

Communicate with vehicles
Read OBD adapters
Implement SAE J1979 protocols
Replace diagnostic SDKs

It is strictly a:

📚 Diagnostic Trouble Code reference database

Perfect companion to OBD libraries such as Flutter OBD2.

🎯 Ideal Use Cases

✅ OBD-II mobile apps ✅ Diagnostic scanners ✅ Fleet management tools ✅ Mechanic reference apps ✅ Offline automotive tools ✅ Insurance claim validation systems

🧭 Design Philosophy

This package prioritizes:

Simplicity over abstraction
Offline reliability
Correct diagnostic behavior
Minimal developer friction
API clarity

📄 License

Package: Licensed under the Mozilla Public License 2.0.

See original repository for dataset licensing details.

🙌 Credits

Database Author: Waleed Judah (Wal33D) https://github.com/Wal33D