EdsDcfNet

A comprehensive, easy-to-use C# .NET library for CANopen file formats: CiA DS 306 (EDS, DCF, CPJ) and CiA 311 (XDD, XDC).

Features

✨ Simple API - Intuitive, fluent API style for quick integration

📖 Read & Write EDS - Parse and generate Electronic Data Sheets

📝 Read & Write DCF - Process and create Device Configuration Files

🌐 Read & Write CPJ - Parse and create Nodelist Project files (CiA 306-3 network topologies)

🧩 Read & Write XDD/XDC - Parse and generate CiA 311 XML device descriptions/configurations

🔄 EDS to DCF Conversion - Easy conversion with configuration parameters

🎯 Type-Safe - Fully typed models for all CANopen objects

📦 Modular - Support for modular devices (bus couplers + modules)

✅ CiA DS 306 v1.4 / CiA 311 v1.1 Compliant - Implemented according to official specification

Quick Start

Reading an EDS File

using EdsDcfNet;

// Read EDS file
var eds = CanOpenFile.ReadEds("device.eds");

// Display device information
Console.WriteLine($"Device: {eds.DeviceInfo.ProductName}");
Console.WriteLine($"Vendor: {eds.DeviceInfo.VendorName}");
Console.WriteLine($"Product Number: 0x{eds.DeviceInfo.ProductNumber:X}");

Writing an EDS File

using EdsDcfNet;

var eds = CanOpenFile.ReadEds("device.eds");
eds.FileInfo.FileRevision++;
CanOpenFile.WriteEds(eds, "device_updated.eds");

Async File I/O (`async`/`await`)

using EdsDcfNet;
using System.Threading;

using var cts = new CancellationTokenSource();

var eds = await CanOpenFile.ReadEdsAsync("device.eds", cts.Token);
eds.FileInfo.FileRevision++;
await CanOpenFile.WriteEdsAsync(eds, "device_updated.eds", cts.Token);

Stream-based I/O

using EdsDcfNet;
using System.IO;

using var stream = File.OpenRead("device.eds");
var eds = CanOpenFile.ReadEds(stream);

using var outStream = new MemoryStream();
CanOpenFile.WriteEds(eds, outStream);

Stream ownership: stream overloads do not dispose input/output streams.
The caller remains responsible for stream lifetime.

Output Encoding Policy

All writer APIs that persist text (WriteEds*, WriteDcf*, WriteCpj*, WriteXdd*, WriteXdc*) write UTF-8 without BOM by default for file and stream output.

This is an intentional interoperability choice:

CiA DS 306 is historically ASCII-oriented.
UTF-8 keeps full ASCII compatibility for 7-bit content.
UTF-8 also preserves non-ASCII characters in names/comments instead of replacing them.

Guidance for strict ASCII toolchains

If a downstream tool only accepts strict ASCII, keep model text in 7-bit ASCII characters, or transcode explicitly to strict ASCII at your boundary and fail fast on non-ASCII content.

using EdsDcfNet;
using System.IO;
using System.Text;

var asciiStrict = Encoding.GetEncoding(
    "us-ascii",
    EncoderFallback.ExceptionFallback,
    DecoderFallback.ExceptionFallback);

var dcf = CanOpenFile.ReadDcf("device.dcf");
var text = CanOpenFile.WriteDcfToString(dcf);
File.WriteAllText("device_ascii.dcf", text, asciiStrict);

Reading an XDD File (CiA 311 XML)

using EdsDcfNet;

// Read XDD file
var xdd = CanOpenFile.ReadXdd("device.xdd");

Console.WriteLine($"Device: {xdd.DeviceInfo.ProductName}");
Console.WriteLine($"Vendor: {xdd.DeviceInfo.VendorName}");

Reading a DCF File

using EdsDcfNet;

// Read DCF file
var dcf = CanOpenFile.ReadDcf("configured_device.dcf");

Console.WriteLine($"Node ID: {dcf.DeviceCommissioning.NodeId}");
Console.WriteLine($"Baudrate: {dcf.DeviceCommissioning.Baudrate} kbit/s");

Reading an XDC File (CiA 311 XML)

using EdsDcfNet;

// Read XDC file
var xdc = CanOpenFile.ReadXdc("configured_device.xdc");

Console.WriteLine($"Node ID: {xdc.DeviceCommissioning.NodeId}");
Console.WriteLine($"Baudrate: {xdc.DeviceCommissioning.Baudrate} kbit/s");

Working with ApplicationProcess (CiA 311 §6.4.5)

XDD/XDC files may include an ApplicationProcess element describing device parameters at the application level. The typed model gives full programmatic access to all sub-constructs.

using EdsDcfNet;

var xdd = CanOpenFile.ReadXdd("device.xdd");

if (xdd.ApplicationProcess is { } ap)
{
    // Iterate parameters
    foreach (var param in ap.ParameterList)
    {
        var displayName = param.LabelGroup.GetDisplayName() ?? param.UniqueId;
        Console.WriteLine($"Parameter: {displayName}");
    }

    // Inspect data type definitions
    if (ap.DataTypeList is { } dtl)
    {
        foreach (var enumType in dtl.Enums)
            Console.WriteLine($"Enum type: {enumType.Name}");
    }
}

Converting EDS to DCF

using EdsDcfNet;

// Read EDS
var eds = CanOpenFile.ReadEds("device.eds");

// Convert to DCF with node ID and baudrate
var dcf = CanOpenFile.EdsToDcf(eds, nodeId: 2, baudrate: 500, nodeName: "MyDevice");

// Save DCF
CanOpenFile.WriteDcf(dcf, "device_node2.dcf");

Validating models before write operations

Use the validation API to detect invalid commissioning values and inconsistent object-list definitions before serializing files.

using EdsDcfNet;
using EdsDcfNet.Validation;

var dcf = CanOpenFile.ReadDcf("configured_device.dcf");

IReadOnlyList<ValidationIssue> issues = CanOpenFile.Validate(dcf);
if (issues.Count > 0)
{
    foreach (var issue in issues)
        Console.WriteLine(issue);
}

CanOpenFile.Validate(...) is the recommended entry point and routes to the full model validator, returning path-based ValidationIssue entries. Current checks include:

commissioning constraints (Node-ID range 1..127 for commissioned nodes; NodeId == 0 is accepted only when commissioning is omitted, baudrate range with 0 accepted for that omitted state, key string limits)
device info constraints (name/order-code length, granularity limit)
object dictionary consistency (list membership, duplicates, missing entries)
object-level constraints (object type validity, parameter-name length, SubNumber mismatch)

Working with Nodelist Projects (CPJ)

using EdsDcfNet;
using EdsDcfNet.Models;

// Read a CPJ file describing the network topology
var cpj = CanOpenFile.ReadCpj("nodelist.cpj");

foreach (var network in cpj.Networks)
{
    Console.WriteLine($"Network: {network.NetName}");
    foreach (var node in network.Nodes.Values)
    {
        Console.WriteLine($"  Node {node.NodeId}: {node.Name} ({node.DcfFileName})");
    }
}

// Create a new CPJ
var project = new NodelistProject();
project.Networks.Add(new NetworkTopology
{
    NetName = "Production Line 1",
    Nodes =
    {
        [2] = new NetworkNode { NodeId = 2, Present = true, Name = "PLC", DcfFileName = "plc.dcf" },
        [3] = new NetworkNode { NodeId = 3, Present = true, Name = "IO Module", DcfFileName = "io.dcf" }
    }
});
CanOpenFile.WriteCpj(project, "network.cpj");

Working with Object Dictionary

using EdsDcfNet.Extensions;

var dcf = CanOpenFile.ReadDcf("device.dcf");

// Get object
var deviceType = dcf.ObjectDictionary.GetObject(0x1000);

// Set value (returns true if object exists, false if not found)
bool set = dcf.ObjectDictionary.SetParameterValue(0x1000, "0x00000191");

// Browse PDO objects
var tpdos = dcf.ObjectDictionary.GetPdoCommunicationParameters(transmit: true);

API Overview

Main Class: `CanOpenFile`

Writer encoding note: all file/stream Write* APIs use UTF-8 without BOM.

// Read EDS
ElectronicDataSheet ReadEds(string filePath)
ElectronicDataSheet ReadEds(string filePath, long maxInputSize)
Task<ElectronicDataSheet> ReadEdsAsync(string filePath, CancellationToken cancellationToken = default)
Task<ElectronicDataSheet> ReadEdsAsync(string filePath, long maxInputSize, CancellationToken cancellationToken = default)
ElectronicDataSheet ReadEdsFromString(string content)
ElectronicDataSheet ReadEdsFromString(string content, long maxInputSize)
ElectronicDataSheet ReadEds(Stream stream)
ElectronicDataSheet ReadEds(Stream stream, long maxInputSize)
Task<ElectronicDataSheet> ReadEdsAsync(Stream stream, CancellationToken cancellationToken = default)
Task<ElectronicDataSheet> ReadEdsAsync(Stream stream, long maxInputSize, CancellationToken cancellationToken = default)

// Write EDS
void WriteEds(ElectronicDataSheet eds, string filePath)
void WriteEds(ElectronicDataSheet eds, Stream stream)
Task WriteEdsAsync(ElectronicDataSheet eds, string filePath, CancellationToken cancellationToken = default)
Task WriteEdsAsync(ElectronicDataSheet eds, Stream stream, CancellationToken cancellationToken = default)
string WriteEdsToString(ElectronicDataSheet eds)

// Read DCF
DeviceConfigurationFile ReadDcf(string filePath)
DeviceConfigurationFile ReadDcf(string filePath, long maxInputSize)
Task<DeviceConfigurationFile> ReadDcfAsync(string filePath, CancellationToken cancellationToken = default)
Task<DeviceConfigurationFile> ReadDcfAsync(string filePath, long maxInputSize, CancellationToken cancellationToken = default)
DeviceConfigurationFile ReadDcfFromString(string content)
DeviceConfigurationFile ReadDcfFromString(string content, long maxInputSize)
DeviceConfigurationFile ReadDcf(Stream stream)
DeviceConfigurationFile ReadDcf(Stream stream, long maxInputSize)
Task<DeviceConfigurationFile> ReadDcfAsync(Stream stream, CancellationToken cancellationToken = default)
Task<DeviceConfigurationFile> ReadDcfAsync(Stream stream, long maxInputSize, CancellationToken cancellationToken = default)

// Write DCF
void WriteDcf(DeviceConfigurationFile dcf, string filePath)
void WriteDcf(DeviceConfigurationFile dcf, Stream stream)
Task WriteDcfAsync(DeviceConfigurationFile dcf, string filePath, CancellationToken cancellationToken = default)
Task WriteDcfAsync(DeviceConfigurationFile dcf, Stream stream, CancellationToken cancellationToken = default)
string WriteDcfToString(DeviceConfigurationFile dcf)

// Read CPJ (CiA 306-3 Nodelist Project)
NodelistProject ReadCpj(string filePath)
NodelistProject ReadCpj(string filePath, long maxInputSize)
Task<NodelistProject> ReadCpjAsync(string filePath, CancellationToken cancellationToken = default)
Task<NodelistProject> ReadCpjAsync(string filePath, long maxInputSize, CancellationToken cancellationToken = default)
NodelistProject ReadCpjFromString(string content)
NodelistProject ReadCpjFromString(string content, long maxInputSize)
NodelistProject ReadCpj(Stream stream)
NodelistProject ReadCpj(Stream stream, long maxInputSize)
Task<NodelistProject> ReadCpjAsync(Stream stream, CancellationToken cancellationToken = default)
Task<NodelistProject> ReadCpjAsync(Stream stream, long maxInputSize, CancellationToken cancellationToken = default)

// Write CPJ
void WriteCpj(NodelistProject cpj, string filePath)
void WriteCpj(NodelistProject cpj, Stream stream)
Task WriteCpjAsync(NodelistProject cpj, string filePath, CancellationToken cancellationToken = default)
Task WriteCpjAsync(NodelistProject cpj, Stream stream, CancellationToken cancellationToken = default)
string WriteCpjToString(NodelistProject cpj)

// Read XDD (CiA 311 XML Device Description)
ElectronicDataSheet ReadXdd(string filePath)
ElectronicDataSheet ReadXdd(string filePath, long maxInputSize)
Task<ElectronicDataSheet> ReadXddAsync(string filePath, CancellationToken cancellationToken = default)
Task<ElectronicDataSheet> ReadXddAsync(string filePath, long maxInputSize, CancellationToken cancellationToken = default)
ElectronicDataSheet ReadXddFromString(string content)
ElectronicDataSheet ReadXddFromString(string content, long maxInputSize)
ElectronicDataSheet ReadXdd(Stream stream)
ElectronicDataSheet ReadXdd(Stream stream, long maxInputSize)
Task<ElectronicDataSheet> ReadXddAsync(Stream stream, CancellationToken cancellationToken = default)
Task<ElectronicDataSheet> ReadXddAsync(Stream stream, long maxInputSize, CancellationToken cancellationToken = default)

// Write XDD
void WriteXdd(ElectronicDataSheet xdd, string filePath)
void WriteXdd(ElectronicDataSheet xdd, Stream stream)
Task WriteXddAsync(ElectronicDataSheet xdd, string filePath, CancellationToken cancellationToken = default)
Task WriteXddAsync(ElectronicDataSheet xdd, Stream stream, CancellationToken cancellationToken = default)
string WriteXddToString(ElectronicDataSheet xdd)

// Read XDC (CiA 311 XML Device Configuration)
DeviceConfigurationFile ReadXdc(string filePath)
DeviceConfigurationFile ReadXdc(string filePath, long maxInputSize)
Task<DeviceConfigurationFile> ReadXdcAsync(string filePath, CancellationToken cancellationToken = default)
Task<DeviceConfigurationFile> ReadXdcAsync(string filePath, long maxInputSize, CancellationToken cancellationToken = default)
DeviceConfigurationFile ReadXdcFromString(string content)
DeviceConfigurationFile ReadXdcFromString(string content, long maxInputSize)
DeviceConfigurationFile ReadXdc(Stream stream)
DeviceConfigurationFile ReadXdc(Stream stream, long maxInputSize)
Task<DeviceConfigurationFile> ReadXdcAsync(Stream stream, CancellationToken cancellationToken = default)
Task<DeviceConfigurationFile> ReadXdcAsync(Stream stream, long maxInputSize, CancellationToken cancellationToken = default)

// Write XDC
void WriteXdc(DeviceConfigurationFile xdc, string filePath)
void WriteXdc(DeviceConfigurationFile xdc, Stream stream)
Task WriteXdcAsync(DeviceConfigurationFile xdc, string filePath, CancellationToken cancellationToken = default)
Task WriteXdcAsync(DeviceConfigurationFile xdc, Stream stream, CancellationToken cancellationToken = default)
string WriteXdcToString(DeviceConfigurationFile xdc)

// Validate models
IReadOnlyList<ValidationIssue> Validate(ElectronicDataSheet eds)
IReadOnlyList<ValidationIssue> Validate(DeviceConfigurationFile dcf)

// Convert EDS to DCF
DeviceConfigurationFile EdsToDcf(ElectronicDataSheet eds, byte nodeId,
                                  ushort baudrate = 250, string? nodeName = null)

Input Size Limits and Tuning

All read APIs apply a safe default input-size limit of 10 MB (IniParser.DefaultMaxInputSize) to reduce denial-of-service risk from unexpectedly large payloads.

You can override this limit per operation when you need to process larger files:

var xdd = CanOpenFile.ReadXdd("large-device.xdd", maxInputSize: 50L * 1024 * 1024);

Guidance:

Keep the default whenever possible.
Increase limits only for trusted sources and known use cases.
Set the limit just high enough for your expected maximum file size.

Supported Features

✅ Complete EDS parsing and writing
✅ Complete DCF parsing and writing
✅ CPJ nodelist project parsing and writing (CiA 306-3 network topologies)
✅ XDD parsing and writing (CiA 311 XML device description)
✅ XDC parsing and writing (CiA 311 XML device configuration)
✅ All Object Types (NULL, DOMAIN, DEFTYPE, DEFSTRUCT, VAR, ARRAY, RECORD)
✅ Sub-objects and sub-indexes
✅ Compact Storage (CompactSubObj, CompactPDO)
✅ Object Links
✅ Modular device concept
✅ Hexadecimal, decimal, and octal numbers
✅ $NODEID formula evaluation (e.g., $NODEID+0x200)
✅ CANopen Safety (EN 50325-5) - SRDOMapping, InvertedSRAD
✅ Comments and additional sections

Error Handling

Writer APIs expose format-specific exceptions with context:

EdsWriter / CanOpenFile.WriteEds*: EdsWriteException
DcfWriter / CanOpenFile.WriteDcf*: DcfWriteException
CpjWriter / CanOpenFile.WriteCpj*: CpjWriteException
XddWriter / CanOpenFile.WriteXdd*: XddWriteException
XdcWriter / CanOpenFile.WriteXdc*: XdcWriteException

When a failure can be attributed to a concrete generated section/element, the exception contains a SectionName value (for example DeviceInfo, Topology, DeviceProfile, or deviceCommissioning).

Examples

Complete examples can be found in the examples/EdsDcfNet.Examples project.

Performance Benchmarks

A dedicated BenchmarkDotNet project is available at:

benchmarks/EdsDcfNet.Benchmarks

Run all benchmarks:

dotnet run -c Release -p benchmarks/EdsDcfNet.Benchmarks -- --filter "*"

Baseline scenario definitions and artifact locations are documented in:

benchmarks/EdsDcfNet.Benchmarks/BASELINE.md

Project Structure

eds-dcf-net/
├── src/
│   └── EdsDcfNet/              # Main library
│       ├── Models/             # Data models
│       ├── Parsers/            # EDS/DCF/CPJ/XDD/XDC parsers
│       ├── Writers/            # EDS/DCF/CPJ/XDD/XDC writers
│       ├── Utilities/          # Helper classes
│       ├── Exceptions/         # Custom exceptions
│       └── Extensions/         # Extension methods
├── benchmarks/
│   └── EdsDcfNet.Benchmarks/   # BenchmarkDotNet throughput/memory benchmarks
├── examples/
│   └── EdsDcfNet.Examples/     # Example application
└── docs/
    ├── architecture/           # ARC42 software architecture
    └── cia/                    # CiA DS 306 specification

Requirements

For consuming the NuGet package:

Any .NET implementation compatible with .NET Standard 2.0 (e.g., .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+, Unity, Xamarin)

For building this repository (library, tests, examples):

.NET SDK 10.0 or higher
C# 13.0 (as provided by the .NET 10 SDK)

License

MIT License - see LICENSE file

Specification

Based on:

CiA DS 306 Version 1.4.0 (December 15, 2021)
CiA 311 XML device description/configuration concepts (XDD/XDC)

Support

For questions or issues:

GitHub Issues: https://github.com/dborgards/eds-dcf-net/issues

EdsDcfNet - Professional CANopen EDS/DCF/CPJ/XDD/XDC processing in C# .NET

Name		Name	Last commit message	Last commit date
Latest commit History 233 Commits
.github		.github
benchmarks/EdsDcfNet.Benchmarks		benchmarks/EdsDcfNet.Benchmarks
docs		docs
examples		examples
src/EdsDcfNet		src/EdsDcfNet
tests		tests
tools		tools
.editorconfig		.editorconfig
.gitignore		.gitignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Build.props		Directory.Build.props
EdsDcfNet.sln		EdsDcfNet.sln
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
codecov.yml		codecov.yml
global.json		global.json
package-lock.json		package-lock.json
package.json		package.json
renovate.json		renovate.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

EdsDcfNet

Features

Quick Start

Reading an EDS File

Writing an EDS File

Async File I/O (async/await)

Stream-based I/O

Output Encoding Policy

Guidance for strict ASCII toolchains

Reading an XDD File (CiA 311 XML)

Reading a DCF File

Reading an XDC File (CiA 311 XML)

Working with ApplicationProcess (CiA 311 §6.4.5)

Converting EDS to DCF

Validating models before write operations

Working with Nodelist Projects (CPJ)

Working with Object Dictionary

API Overview

Main Class: CanOpenFile

Input Size Limits and Tuning

Supported Features

Error Handling

Examples

Performance Benchmarks

Project Structure

Requirements

License

Specification

Support

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 39

Sponsor this project

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Async File I/O (`async`/`await`)

Main Class: `CanOpenFile`