Contribute

Thank you for your interest in contributing to the OpenECU Alliance! Learn how to contribute adapters, protocols, 3D models, and more.

What Would You Like to Contribute?

Adapters

Log file format definitions for ECU data parsing

Protocols

CAN Bus message definitions with DBC export

3D Models

Upload printable mounts and accessories directly

Ways to Contribute

Contribution Type	Description	Difficulty
Submit Adapters	Add support for new ECU log formats	Beginner
Submit Protocols	Define CAN Bus messages and signals	Intermediate
Upload 3D Models	Share printable mounts via our website	Beginner
Improve Content	Add source_names, fix issues	Beginner
Report Issues	Report bugs or missing features	Beginner
Documentation	Improve docs, add examples	Beginner
Review PRs	Help review submissions	Intermediate
Propose RFC	Suggest specification changes	Advanced
Build Tools	Validation tools, SDKs	Advanced

Contributing Adapters

Adapters are the primary way the community expands OpenECU Spec coverage.

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

Fork and Clone

Fork the OECUASpecs repository and clone it locally.

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

Create Vendor Directory

Create a directory for your vendor if it doesn't exist. Use lowercase names.

bash
mkdir -p adapters/vendorname

Create Adapter File

Create your adapter file following the naming convention: {vendor}-{format}.adapter.yaml

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

Write the Adapter

Fill in the adapter with your ECU's channel mappings.

Validate

Validate your adapter against the JSON Schema.

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

Submit Pull Request

Push your changes and create a pull request on GitHub.

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

Adapter Template

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"

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

Contributing Brand Assets

Help make the OpenECU Alliance visually cohesive by contributing vendor logos, icons, and brand assets.

Asset Requirements

Asset Type	Format	Size
Logo	SVG (preferred) or PNG	Min 400px wide
Icon	SVG (preferred) or PNG	256x256px
Banner	PNG or JPG	1200x630px

Approved Sources

Official vendor press kits / media pages
Direct written permission from vendor
Assets you have verified rights to use

Not Acceptable

Screenshots or low-quality captures
Modified third-party images
Assets without clear licensing

Proposing Specification Changes

For changes to the OpenECU Spec itself, use the RFC (Request for Comments) process.

Needs RFC

New fields in the adapter schema
New channel categories
Changes to existing field definitions
New canonical channel IDs
Breaking changes of any kind

No RFC Needed

Typo fixes
Clarifications that don't change meaning
Adding adapter examples

RFC Process

Discuss First - Open a GitHub Discussion to gauge interest

Write RFC - Create rfcs/0000-your-proposal.md using the template

Submit PR - Open PR for community review

Iterate - Incorporate feedback

FCP - Final Comment Period (14 days)

Decision - Steering Committee accepts or rejects

Reporting Issues

Bug Reports

For incorrect adapters, schema validation problems, or documentation errors. Include:

1. Which adapter/file is affected
2. What you expected
3. What actually happened
4. Sample log file (sanitize sensitive data)

Feature Requests

For new features:

1. Describe the use case
2. Explain why existing features don't suffice
3. Propose a solution (optional)

Development Setup

Prerequisites

Node.js 18+ (for validation tools)
Git
A text editor with YAML support

Install Validation Tools

bash
# Option 1: ajv-cli (Node.js)
npm install -g ajv-cli

# Option 2: check-jsonschema (Python)
pip install check-jsonschema

Validate All Adapters

bash
# Using ajv-cli
for f in adapters/**/*.adapter.yaml; do
  ajv validate -s schema/adapter.schema.json -d "$f"
done

Style Guidelines

YAML Style

Use 2-space indentation
Quote strings that might be ambiguous
Use lowercase for IDs and vendors
Use snake_case for channel IDs
Multi-line descriptions use |

Commit Message Types

adapter:Adding or updating adapters
protocol:Adding or updating CAN protocols
model:Adding or updating 3D models
spec:Specification changes
docs:Documentation only
schema:JSON Schema changes
chore:Maintenance, tooling

Getting Help

GitHub Discussions

Questions, ideas, general discussion

GitHub Issues

Bug reports, specific problems

Discord

Real-time chat (coming soon)

Recognition

All contributors are recognized in:

Adapter metadata.author fields
Repository CONTRIBUTORS.md file
Release notes for significant contributions

View on GitHub Adapter Guide Protocol Guide Upload 3D Model