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

IPhysicalLayer

Your implementation provides:

• WriteBytes
• ReadBytes / ReadBytesAsync
• ResetInterface
• Interrupt events
• EEPROM read/write support

---

📘 Example: Read Firmware Version

var version = device.FirmwareVersion;
Console.WriteLine(version);

Firmware is fetched using method token 254.

---

🛠 Protocol Details

EssyBus uses a framed HEX-encoded protocol:

STX | Address | Leader | Length | HEX(Data...) | Checksum | ETX

• Each byte is encoded as two HEX nibbles
• Max payload: 250 bytes
• Transmission ends with EOT

---

📄 License

MIT License

---

🧯 Logging / Debugging

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