AccordionQ2.WebApiClient 5.28.1

AccordionQ2.WebApiClient

A .NET HTTP client library for the AccordionQ2 Hardware Management REST API.
Provides a strongly-typed, async-first interface for reading/writing resource values, configuring channels, managing modules, and controlling application lifecycle over HTTP, as well as the event stream, value subscriptions, the control lease, the station's services and start-up configuration, its files, and signed firmware updates.

Installation

dotnet add package AccordionQ2.WebApiClient

Requirements

• .NET Standard 2.0 compatible runtime (.NET 5+, .NET Framework 4.6.1+)
• An AccordionQ2 WebApi host reachable over HTTP (e.g. http://raspberrypi:5000)

Quick Start

using AccordionQ2.WebApiClient;
using AccordionQ2.WebApiClient.Models;

using var client = new AccordionQ2Client("http://raspberrypi:5000");

// Check hardware manager connection
var status = await client.Connection.GetStatusAsync();

// Read a resource value
string voltage = await client.Resources.GetValueAsync("Voltage.VDD");

// Configure a channel
await client.Channels.ConfigureAsync(new ChannelConfigRequest
{
    NetName   = "MPIO00",
    Enabled   = true,
    Direction = DirectionTypes.IN
});

Documentation

Comprehensive API documentation is available in the docs/ folder:

• Getting Started / Installation
• Quick Start
• API Overview — all 18 operation groups at a glance
• Group pages: Resources, Channels, Modules, Application, Media, Connection, Comm, Numeric Results, Calibration, Audit, Instruments, Capabilities, Events and Subscriptions, Lease, System, Files, Firmware
• Error Handling
• Models Reference
• Enums Reference

API Reference

AccordionQ2Client exposes eighteen operation groups: Resources, Channels, Modules, Application, Media, Connection, Comm, NumericResults, Calibration, Audit, Instruments, Capabilities, Events, Subscriptions, Lease, System, Files and Firmware. The groups from Instruments on need a WebApi that has them; older firmware answers 404 (Capabilities.GetAsync returns CapabilitiesDto.None instead).

client.Resources — Hardware resource values

Resources are identified by name (e.g. "Voltage.VDD", "Temperature.Ambient").
Both NetName (e.g. "0.23.ESH10000517.READ_TEMPERATURE") and Alias (e.g. "FRONT_AIR READ TEMPERATURE") are accepted interchangeably by all methods.

// Batch read
var values = await client.Resources.GetValuesAsync(new[] { "Voltage.VDD", "Temperature.Ambient" });

// Write-then-read transaction
string response = await client.Resources.TransactAsync("Eeprom.Read", "0x0010");

client.Channels — Channel configuration

Channel configuration uses partial updates — only non-null properties in ChannelConfigRequest are applied; everything else is left unchanged.

// Set a single property without touching anything else
await client.Channels.ConfigureAsync(new ChannelConfigRequest
{
    NetName   = "MPIO00",
    Direction = DirectionTypes.OUT
});

// Batch configure
await client.Channels.ConfigureManyAsync(new List<ChannelConfigRequest>
{
    new() { NetName = "MPIO00", Enabled = true, Direction = DirectionTypes.IN },
    new() { NetName = "MPIO01", Enabled = true, Direction = DirectionTypes.OUT }
});

ChannelConfigRequest properties:

Each ChannelDto from Channels.GetAllAsync() has Details with the fields of its concrete type (null from firmware whose WebApi predates it). For example a multiplexer's choices:

var wave = (await client.Channels.GetAllAsync()).First(c => c.NetName == "0.2.ESH10000560.GEN1_WAVE");
Console.WriteLine(string.Join(", ", wave.Details?.DestinationNets ?? [])); // SINE, SQUARE, TRIANGLE, NOISE

client.Modules — Module management

client.Application — Application lifecycle & configuration files

// Download config, modify, re-upload
byte[] data = await client.Application.DownloadConfigFileAsync("default.cfg");
// ... modify data ...
await client.Application.UploadConfigFileAsync("default.cfg", data);
await client.Application.LoadConfigFileAsync("default.cfg");

client.Media — Media files

client.Connection — Connection status

client.Comm — Raw bus transactions (I2C, UART, SPI, Socket)

All byte data is hex-encoded (uppercase, no separator) on the wire. DataToSend and Received are plain hex strings (e.g. "AABB" = two bytes 0xAA 0xBB). The I2C Address and the Socket TerminationByte are two-digit hex strings (e.g. "50" for 0x50).

// I2C: scan the bus for connected devices
var scan = await client.Comm.I2cAsync(new I2cTransactionRequest
{
    DeviceName = "0.ESH10000597.I2C00",
    Address    = "00",
    Action     = BusActions.Scan,
});
foreach (var addr in Convert.FromHexString(scan.Received))
    Console.WriteLine($"Found device at 0x{addr:X2}");

// I2C: write two bytes to address 0x50
var write = await client.Comm.I2cAsync(new I2cTransactionRequest
{
    DeviceName = "0.ESH10000597.I2C00",
    Address    = "50",
    Action     = BusActions.Send,
    DataToSend = "0010",   // register 0x00, value 0x10
});

// I2C: read 4 bytes from address 0x50
var read = await client.Comm.I2cAsync(new I2cTransactionRequest
{
    DeviceName             = "0.ESH10000597.I2C00",
    Address                = "50",
    Action                 = BusActions.Receive,
    NumberOfBytesToReceive = 4,
});
byte[] bytes = Convert.FromHexString(read.Received);

// UART: send a SCPI query and read the response
var uart = await client.Comm.UartAsync(new UartTransactionRequest
{
    DeviceName             = "MyUartDevice",
    Action                 = BusActions.SendReceive,
    DataToSend             = Convert.ToHexString(System.Text.Encoding.ASCII.GetBytes("*IDN?\n")),
    NumberOfBytesToReceive = 64,
    TimeoutMs              = 2000,
});

client.NumericResults — Fast numeric sampling

client.Audit — WebApi audit log

client.Calibration — Calibration channel read/write

Calibration channels carry a CalibrationTable encoded as a Base64 binary payload. The server transparently decodes/encodes that payload, so you work with plain objects. Both NetName and Alias are accepted for the channel name.

// Read calibration data
var table = await client.Calibration.GetTableAsync("0.8.ESH10000590.CAL0");
foreach (var row in table.CalData)
    Console.WriteLine($"{row.Key}: gain={row.Gain:F6}, offset={row.Offset:F6}");

// Modify a row and write back
var updated = new CalibrationTableDto
{
    ProductId    = table.ProductId,
    Revision     = table.Revision,
    SerialNumber = table.SerialNumber,
    CalData      = table.CalData.Select(r =>
        r.Key == "ADC0" ? new CalibrationRowDto { Key = r.Key, Gain = 1.0012, Offset = 0.001 } : r
    ).ToList()
};
await client.Calibration.SetTableAsync("0.8.ESH10000590.CAL0", updated);

client.Instruments — Instrument channels

Instruments (power supplies, meters and others) are Instrument channels whose function map names the channel behind each capability, for example OUTPUT_VOLTAGE → 0.4.ESH10000662.VSET1. Channels.GetAllAsync() doesn't include the map; this does. Every key is optional. Needs firmware with GET /api/instruments; older firmware answers 404.

// Set a power-supply output to 12 V with a 100 mA limit, then turn it on
var supply = (await client.Instruments.GetAllAsync()).First(i => i.Type == "PowerSupply");
await client.Resources.SetValuesAsync(new Dictionary<string, string>
{
    [supply.FunctionMap["OUTPUT_VOLTAGE"]] = "12",
    [supply.FunctionMap["OUTPUT_CURRENTLIMIT"]] = "100",
});
await client.Resources.SetValueAsync(supply.FunctionMap["OUTPUT_ENABLE"], "True");

client.Capabilities — What the WebApi supports

var caps = await client.Capabilities.GetAsync();
if (caps.Has(CapabilitiesDto.Events)) { /* the event stream is available */ }

client.Events and client.Subscriptions — Event stream and pushed values

Events.ListenAsync(onEvent, ct) reads the server-sent event stream (hello, connection, configuration, values, lease) until cancelled; it throws TimeoutException or IOException when the stream dies, and reconnecting is the caller's. Subscriptions asks for channel values to arrive as values events on that stream.

See Events and Subscriptions for a reconnecting listener.

client.Lease — Control lease

One client at a time may change the station. While another client holds the lease, changes and forced reads get AccordionQ2ApiException with 423. The holder sends its lease id with every request automatically.

client.System — Services, reboot, clock and boot.config

boot.config changes apply at the hardware app's next start (alias files and modules also on reset).

client.Files — Files in the station's folders

client.Firmware — Firmware updates

The station installs only releases signed by E-Sharp, and nothing below 6.0.0. Installing restarts the hardware app and the WebApi, so poll GetUpdateAsync and expect connection errors for a minute or two.

See Firmware for a complete update with polling.

Error Handling

All methods throw AccordionQ2ApiException on non-success HTTP responses. The exception exposes the HTTP status code alongside the error message returned by the API.

try
{
    await client.Channels.ConfigureAsync(request);
}
catch (AccordionQ2ApiException ex) when (ex.StatusCode == 404)
{
    Console.WriteLine($"Channel not found: {ex.Message}");
}
catch (AccordionQ2ApiException ex)
{
    Console.WriteLine($"API error {ex.StatusCode}: {ex.Message}");
}

Dependency Injection (IHttpClientFactory)

For long-running applications, pass an externally managed HttpClient to avoid socket exhaustion:

// Program.cs
builder.Services.AddHttpClient("accordion", c =>
    c.BaseAddress = new Uri("http://raspberrypi:5000"));

builder.Services.AddSingleton<IAccordionService, AccordionService>();

// AccordionService.cs
public class AccordionService
{
    private readonly AccordionQ2Client _client;

    public AccordionService(IHttpClientFactory factory)
    {
        var http = factory.CreateClient("accordion");
        _client = new AccordionQ2Client("http://raspberrypi:5000", http);
    }
}

When using IHttpClientFactory, the caller owns the HttpClient lifetime — AccordionQ2Client.Dispose() will not dispose it.

License

Copyright © 2026 E-Sharp AB. See LICENSE for details.