Suucha.Can.Core 0.1.0

Suucha.Can

⚠️ Preview Release: This is a 0.x version, indicating active development. The API is functional and tested, but may evolve based on user feedback. See CHANGELOG for details.

🚀 Modern, type-safe, and high-performance .NET wrapper for CAN devices

Suucha.Can is a production-grade open-source library that provides a clean, object-oriented API for CAN/CANFD devices. Built with modern .NET best practices, it replaces raw P/Invoke calls with safe, easy-to-use abstractions.

📖 Complete Documentation | 🚀 Quick Start | 📚 API Reference

🔌 Supported Manufacturers

• ZLG (Zhiyuan Electronics) - Full support for all ZLG CAN device families
• More manufacturers coming soon - Extensible architecture ready for additional vendors

✨ Features

• 🎯 Type-Safe API - No more IntPtr and manual marshaling
• 🔒 Resource Management - Automatic disposal with IDisposable pattern
• 🚀 High Performance - Zero-allocation receive paths
• 📦 Multi-Device Support - Extensible architecture for all ZLG device families
• 🧪 Well Tested - Comprehensive unit and integration tests
• 🔄 Async/Await - Modern asynchronous programming support
• 💻 Multi-Architecture - Supports both x86 (32-bit) and x64 (64-bit)

✅ Platform Support

Great News: This library supports both x86 and x64 architectures!

• ✅ x86 (32-bit) - Full support
• ✅ x64 (64-bit) - Full support
• ✅ AnyCPU - Automatically selects correct native DLLs at runtime

Your application can use any platform configuration:

<PropertyGroup>
  <PlatformTarget>AnyCPU</PlatformTarget>
</PropertyGroup>


<PropertyGroup>
  <PlatformTarget>x64</PlatformTarget>
</PropertyGroup>

📋 Prerequisites

System Requirements

• Operating System: Windows 10/11 (x86 or x64)
• .NET Runtime: .NET 8.0 or later

Required Software

1. ZLG Device Drivers (Required)

You must install ZLG device drivers before using this library.

📥 Download Links:

• Primary: ZLG Driver Manual & Downloads

Installation Steps:

1. Download the driver package for your specific device model
2. Extract and run the installer
3. Connect your ZLG device
4. Verify installation in Windows Device Manager (look for "ZLG USBCAN" or similar)
5. You may need to restart your computer after installation

Note: Different ZLG device families may require different driver packages:

• USBCAN series → USBCAN driver
• CANFDNET series → CANFDNET driver
• CANET series → CANET driver

Check ZLG's documentation for your specific device model.

2. Visual C++ Redistributable (Required)

Required for native DLL dependencies

• VC++ 2013 Redistributable (Primary requirement)
  • Download x64
  • Download x86
  • VC++ 2010 Redistributable (May be required for some devices)
    • Download x64
    • Download x86
  • VC++ 2008 Redistributable (May be required for older devices)
    • Download x64
    • Download x86

Note: ZLG's native DLLs are compiled with Visual Studio 2005-2013. Most Windows systems already have these runtimes installed. If you encounter a DllNotFoundException or missing DLL error, install VC++ 2013 Redistributable first, then try older versions if needed.

Quick Install (PowerShell)

Run this script to automatically check and install all prerequisites (VC++ only, ZLG drivers must be installed manually):

# Run from the project root
.\scripts\Install-Prerequisites.ps1

Important: This script only installs VC++ redistributables. You must download and install ZLG device drivers separately from ZLG's website.

Hardware Requirements

• ZLG CAN hardware device (USBCAN-II, CANET, USBCAN-E-U, etc.)
• ZLG device drivers installed - Download from:
  • 📥 Official Driver Download: ZLG Driver Manual & Downloads

Important: You must install the official ZLG device drivers before using this library. The driver package includes necessary kernel drivers and configuration tools for your specific device model.

📦 Packages

Package	Description	NuGet
Suucha.Can.Core	Core abstractions and interfaces
Suucha.Can.Zlg.Native	ZLG native runtime libraries (x86 & x64)
Suucha.Can.Zlg.Devices	Implementation for all ZLG devices

Note: Suucha.Can.Zlg.Devices is the unified package that supports all ZLG device types (USBCAN, CANET, USBCAN-E-U, CANFDNET, etc.) through a single API. Device selection is done via the DeviceType parameter.

🚀 Quick Start

Installation Checklist

Before you begin, make sure you have:

• ✅ Windows 10/11 (x86 or x64)
• ✅ .NET 8.0 SDK or Runtime installed
• ✅ ZLG device drivers installed (Download here)
• ✅ Visual C++ 2013 Redistributable installed (x64 / x86)
• ✅ ZLG CAN device connected and recognized in Device Manager

Installation

dotnet add package Suucha.Can.Zlg.Devices

This automatically includes the required dependencies:

• Suucha.Can.Core - Core abstractions
• Suucha.Can.Zlg.Native - Native DLLs (x86 + x64)

Basic Usage

using Suucha.Can.Core.Models;
using Suucha.Can.Zlg.Devices;

// Open device (supports all ZLG device types)
using var device = new ZlgCanDevice(DeviceType.USBCAN2, deviceIndex: 0);
device.Open();

// Configure and open channel
var config = ChannelConfig.Standard250K(); // 250 kbps preset
using var channel = device.OpenChannel(channelIndex: 0, config);

// Start receiving (event-driven)
channel.MessageReceived += (sender, frame) =>
{
    Console.WriteLine($"Received: ID=0x{frame.Id:X3}, Data={BitConverter.ToString(frame.Data)}");
};

channel.ErrorOccurred += (sender, e) =>
{
    Console.WriteLine($"Error: {e.ErrorInfo}");
};

channel.Start();

// Send a message
var message = new CanFrame
{
    Id = 0x123,
    Data = new byte[] { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 },
    IsExtended = false
};

await channel.SendAsync(message);

Multiple Device Support

The same API works for all ZLG device types:

// USBCAN-II
var usbcan = new ZlgCanDevice(DeviceType.USBCAN2, 0);

// CANET-TCP
var canet = new ZlgCanDevice(DeviceType.CANETTCP, 0);

// USBCAN-E-U
var usbcan_e = new ZlgCanDevice(DeviceType.USBCAN_E_U, 0);

// CANFDNET-800U
var canfdnet = new ZlgCanDevice(DeviceType.CANFDNET_800U_TCP, 0);

// All use the same ICanDevice interface!

🎯 Supported Devices

All ZLG CAN device types are supported through the unified ZlgCanDevice class:

✅ Fully Supported (85+ device types)

• USBCAN Series - USBCAN-I, USBCAN-II (Classic USB devices)
• USBCANFD Series - 100U, 200U, 400U, 800U (USB CANFD devices)
• CANET Series - CANET-TCP, CANET-UDP (Ethernet devices)
• CANFDNET Series - 200U-TCP, 400U-TCP, 800U-TCP (Ethernet CANFD)
• USBCAN-E-U Series - Enhanced USB devices
• PCI/PCIe Series - PCI-9840I, PCI-9820I, PCIE-9120I, PCIE-9110I, PCIE-9140I
• And 75+ more device types!

🔧 How It Works

All devices use the same ZLG native API (zlgcan.dll). The only difference is the DeviceType parameter:

// Select your device type from the DeviceType enum
public enum DeviceType : uint
{
    ZCAN_USBCAN1 = 3,
    ZCAN_USBCAN2 = 4,
    ZCAN_CANETTCP = 17,
    ZCAN_USBCAN_E_U = 20,
    ZCAN_CANFDNET_800U_TCP = 42,
    // ... 80+ more types
}

See the DeviceType enum in the source code for the complete list of supported device types.

🏗️ Architecture

┌─────────────────────────────────────────┐
│         Your Application                │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│      Suucha.Can.Core (Abstractions)     │
│   ICanDevice, ICanChannel, CanFrame     │
└──────────────┬──────────────────────────┘
               │
     ┌─────────┴─────────┬────────────┐
     │                   │            │
┌────▼─────────────┐ ┌──▼──────┐  ┌──▼───┐
│ Zlg.Devices      │ │ Other   │  │ ...  │
│(All ZLG types)   │ │ Vendors │  │      │
└────┬─────────────┘ └─────────┘  └──────┘
     │                   
┌────▼─────────────────────────────────────┐
│  Suucha.Can.Zlg.Native (Runtime DLLs)    │
│  x86: zlgcan.dll + kernel DLLs           │
│  x64: zlgcan.dll + kernel DLLs           │
└──────────────────────────────────────────┘

Key Design Decisions:

1. Vendor-Agnostic Core - Suucha.Can.Core provides common CAN abstractions (interfaces, CanFrame) that work across all manufacturers
2. Single Device Implementation Per Vendor - Suucha.Can.Zlg.Devices supports all 85+ ZLG device types through one unified API
3. Device Selection via Enum - Choose device type with DeviceType parameter (no separate packages per device)
4. Native Package Separation - Suucha.Can.Zlg.Native contains only runtime DLLs (x86 + x64), no managed code
5. Runtime Architecture Selection - Correct native DLLs automatically selected based on process architecture
6. Extensible for Other Vendors - Easy to add support for other CAN manufacturers (Kvaser, PEAK, Vector, etc.)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

git clone https://github.com/suucha/Suucha.Can.git
cd Suucha.Can
dotnet restore
dotnet build

📄 License

This project is dual-licensed:

• Suucha.Can Wrapper Code: MIT License - Our C# wrapper code
• ZLG Native Libraries (v20260414): Proprietary - ZLG's native DLLs

What This Means

✅ You CAN:

• Use commercially
• Modify and redistribute the wrapper code
• Use in closed-source projects
• Use with proper hardware

⚠️ You MUST:

• Include the license file when distributing
• Keep copyright notices intact
• Have valid hardware from respective manufacturers

❌ You CANNOT:

• Claim manufacturers endorse your product
• Remove copyright notices
• Hold us liable for issues

See LICENSE for full details, or LICENSE.zh-CN.md for Chinese version.

Note: The native DLLs (such as ZLG's zlgcan.dll) are proprietary software owned by their respective manufacturers. You need proper licensing to use their hardware and drivers.

🙏 Acknowledgments

• Thanks to ZLG (Zhiyuan Electronics) for their excellent CAN hardware and native libraries (version 20260414)
  • ZLG CAN API Documentation
  • ZLG Device Drivers
• Original USBCAN C# wrapper contributors

📞 Support

• � Complete Documentation - Full documentation with guides and examples
• �🐛 Report Issues
• 💬 Discussions
• 📋 Changelog

🔧 Troubleshooting

Common Issues

"Unable to load DLL 'zlgcan.dll'" or DllNotFoundException

Cause: Missing Visual C++ Redistributable runtime (2005-2013).

Solution:

1. Install VC++ 2013 Redistributable (most common):
   • VC++ 2013 x64 for 64-bit applications
   • VC++ 2013 x86 for 32-bit applications
2. If the issue persists, try installing older versions:
   • VC++ 2010 x64 / x86
   • VC++ 2008 x64 / x86
3. Restart your application after installation
4. Or use the automated installer: .\scripts\Install-Prerequisites.ps1

Tip: If you're unsure which version to install, install all three (2008, 2010, 2013) for both x86 and x64.

Device Not Found

Cause: ZLG device drivers not installed or device not connected.

Solution:

1. Download and install official ZLG drivers:
   • Primary: ZLG Driver Manual & Downloads
2. Install the driver package for your specific device model
3. Connect your ZLG device via USB or network
4. Verify the device appears in Windows Device Manager (should show as "ZLG USBCAN" or similar)
5. Check the device index and type in your code matches your hardware

Tip: Different device models may require different driver packages. Make sure you download the driver that matches your hardware (e.g., USBCAN-II driver, CANFDNET driver, etc.).

"BadImageFormatException"

Cause: Architecture mismatch between your application and the native DLL.

Solution:

• If using AnyCPU, ensure "Prefer 32-bit" is unchecked
• Verify your platform target matches your system architecture
• Rebuild your application after changing platform settings

Made with ❤️ by Suucha