Essy.EssyBus

EssyBus .NET Library

EssyBus is a lightweight and robust communication library for interacting with devices over the EssyBus protocol.
It provides a clean abstraction between the underlying physical transport (UART, RS-485, USB, etc.) and your high-level device logic.

This package includes:

• EssyBus — Manages communication, framing, retries, and device orchestration.
• EssyBusClient — Base class for building device-specific drivers.
• IPhysicalLayer — Interface you implement to link EssyBus to your hardware or simulation layer.
• A structured exception hierarchy.

---

✨ Features

🔌 Pluggable Physical Layer

Implement IPhysicalLayer to make EssyBus work with:

• Serial ports
• USB bridges
• RS-485 interfaces
• Hardware simulators
• Unit-test stubs

🧱 High-Level Client Framework

Derive your device classes from EssyBusClient to automatically get:

• Typed request/response handling
• EncodeFunction / EncodeMethod helpers
• Async and sync APIs
• Built-in Ping & FirmwareVersion access
• Automatic casting to numeric, float, string types

🔁 Robust Error Handling

EssyBus includes:

• Automatic retry logic
• Bus reset on communication failures
• Checksum verification
• Timeout/error propagation
• Fatal-error protection

⚡ Interrupt Handling Support

Devices can signal interrupts using the physical layer interrupt line.
Implement:

• IEssyBusClientInterrupt
• IEssyBusClientResetable

EssyBus will automatically dispatch interrupts when detected.

🔧 Automatic Device Reset

If enabled, devices implementing IEssyBusClientResetable are automatically reset when added.

---

📦 Installation

dotnet add package EssyBus

---

🚀 Getting Started

1. Implement the Physical Layer

public class SerialPhysicalLayer : IPhysicalLayer
{
    // Implement WriteBytes, ReadBytes, interrupts, etc.
}

2. Create and Configure EssyBus

var bus = new EssyBus(new SerialPhysicalLayer());

3. Build Your Device Client

public class MyDevice : EssyBusClient
{
    public MyDevice(byte address) : base(address, "My Device") {}

    public int GetTemperature()
    {
        EncodeFunction(10, out int temp);
        return temp;
    }
}

4. Add Client and Communicate

var device = new MyDevice(1);
bus.AddClient(device);

Console.WriteLine(device.GetTemperature());

---

🧩 Architecture Overview

EssyBus

Handles communication, framing, retries, checksum, STX/ETX formatting, interrupt dispatch, and optional async operations.

EssyBusClient

Provides strongly typed access to device methods:

• EncodeFunction(...)
• EncodeMethod(...)
• Async equivalents
• Auto firmware retrieval
• Ping(), RebootDevice(), DisconnectedFromBus()

Exception Types

• EssyBusException
• PhysicalLayerException
• EssyBusClientException
• FatalEssyBusException

---

🛠 Protocol Details

EssyBus currently supports two protocol versions, selected transparently per device.

Protocol V1 (Legacy)

STX (255) | Address | Leader | Length | HEX(Data...) | Checksum | ETX (254) | EOT (253)

• Payload bytes are HEX-encoded (each byte → two nibbles)
• Maximum payload: 250 bytes
• Checksum = sum(payload) mod 250
• Simple framing, no escaping
• Used by default for legacy devices

Protocol V2 (Enhanced)

Protocol V2 removes HEX encoding and introduces binary framing with escaping and extended length support.

STX_V2 (251)
Address | Leader | Length (low, high) | Data (escaped) | Checksum | ETX (254) | EOT (253)

Key Improvements

• Binary payload (no HEX expansion)
• Escaping using ESC = 250 for any byte > 250
• 16-bit payload length (low + high byte)
• Higher throughput and lower latency
• Fully backward compatible at the bus level

Escaping Rules

Any byte with value > 250 is encoded as:

ESC, (byte - 250)

This applies to:

• Payload bytes
• Length bytes

Checksum is calculated on the unescaped payload:

checksum = sum(payload) % 250

Selecting Protocol Version

Protocol selection is per client:

public class MyDevice : EssyBusV2Client
{
    public MyDevice(byte address) : base(address, "My V2 Device") {}
}

• EssyBusClient → Protocol V1
• EssyBusV2Client → Protocol V2

The EssyBus automatically handles framing, retries, and decoding based on the client type.

---

📄 License

MIT License

---

🧯 Logging / Debugging

var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
var bus = new EssyBus(myPhysicalLayer, loggerFactory);