Back to Docs

Creating Adapters

Step-by-step guide to creating your own ECU adapter.

Before You Start

  • Check existing adapters - Ensure an adapter doesn't already exist for your format.
  • Gather sample files - You'll need real log files to test against.
  • Read the specification - Familiarize yourself with the full specification.

Step-by-Step Guide

1

Fork and Clone

bash
git clone https://github.com/YOUR-USERNAME/OECUASpecs.git
cd OECUASpecs
2

Create Vendor Directory

bash
mkdir -p adapters/vendorname

Use lowercase vendor names: haltech, link, motec, aem, etc.

3

Create Adapter File

bash
touch adapters/vendorname/vendorname-format.adapter.yaml

Naming convention: {vendor}-{format}.adapter.yaml

Examples: haltech-nsp.adapter.yaml, motec-csv.adapter.yaml
4

Write the Adapter

yaml
openecualliance: "1.0"
id: vendorname-format
name: "Vendor Name Format Description"
version: "1.0.0"
vendor: vendorname
description: |
  Brief description of this adapter.
  Include supported ECU models and export methods.
website: "https://vendor-website.com"

file_format:
  type: csv  # or binary
  extensions: [".csv", ".log"]
  delimiter: ","
  header_row: 0
  data_start_row: 1

channels:
  - id: rpm
    name: "Engine RPM"
    category: engine
    data_type: float
    unit: rpm
    min: 0
    max: 20000
    source_names:
      - "Engine RPM"
      - "RPM"
      # Add ALL variations you've seen in real log files

  - id: coolant_temp
    name: "Coolant Temperature"
    category: temperature
    data_type: float
    unit: celsius
    source_names:
      - "ECT"
      - "Coolant Temp"

metadata:
  author: "Your Name"
  tested_with:
    - "ECU Model 1"
    - "ECU Model 2"
  changelog:
    - version: "1.0.0"
      date: "2024-01-15"
      changes:
        - "Initial release"
5

Validate Your Adapter

bash
# Install validation tool (one-time)
npm install -g ajv-cli

# Validate
ajv validate -s schema/adapter.schema.json -d adapters/vendorname/vendorname-format.adapter.yaml
6

Submit Pull Request

bash
git checkout -b add-vendorname-adapter
git add adapters/vendorname/
git commit -m "Add adapter for VendorName Format"
git push origin add-vendorname-adapter

Then create a Pull Request on GitHub.

Quality Checklist

Before submitting, verify:

  • Adapter validates against JSON Schema
  • All required fields are present
  • id follows naming convention (vendor-format)
  • version follows semver (start with 1.0.0)
  • Each channel has at least one source_name
  • Channel IDs use canonical names where applicable
  • metadata.tested_with lists ECU models tested
  • Description explains what log files this adapter supports

Adding Source Names to Existing Adapters

If you discover additional channel name variations in log files:

  1. Find the channel in the existing adapter
  2. Add the new name to source_names array
  3. Increment the PATCH version
  4. Submit PR with explanation of where you found this variation
yaml
# Before
source_names:
  - "Engine RPM"

# After
source_names:
  - "Engine RPM"
  - "Eng RPM"  # Found in firmware v2.3 exports
View on GitHub Read the Full Spec