🚗 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 #

📊 Database Overview #

Dataset included via the original project:

🔗 Database Compatibility #

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

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:

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.

Database & Definitions: MIT License — © Waleed Judah (Wal33D)

See original repository for dataset licensing details.

🙌 Credits #

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