SharpCAT/Client/README.md

SharpCAT.Client

A .NET Standard 2.0 client library that provides a typed C# API for consuming the SharpCAT Server HTTP API endpoints. This library makes it easy to integrate CAT (Computer Aided Transceiver) control into your .NET applications.

Features

• Typed API: Strongly-typed C# methods for all SharpCAT Server endpoints
• Async/Await Support: Modern async programming with cancellation token support
• Error Handling: Comprehensive error handling with custom exceptions
• Cross-Platform: .NET Standard 2.0 compatible (works with .NET Core, .NET Framework, .NET 5+)
• HTTP Client Integration: Uses System.Net.Http.Json for JSON serialization
• Frequency Helpers: Convenient methods for getting/setting radio frequencies
• XML Documentation: Full IntelliSense support with comprehensive documentation

Installation

Add the SharpCAT.Client project reference to your application:

<ProjectReference Include="path/to/SharpCAT.Client/SharpCAT.Client.csproj" />

Quick Start

Basic Usage

using SharpCAT.Client;
using SharpCAT.Client.Models;

// Create client instance
using var client = new SharpCATClient("http://localhost:5188");

// Get available serial ports
var ports = await client.GetPortsAsync();
Console.WriteLine($"Available ports: {string.Join(", ", ports.Ports)}");

// Open a serial port
var openRequest = new OpenPortRequest
{
    PortName = "COM3",
    BaudRate = 9600
};
var openResult = await client.OpenPortAsync(openRequest);
Console.WriteLine($"Port opened: {openResult.Success}");

// Send a raw CAT command
var commandResult = await client.SendCommandAsync("FA;");
Console.WriteLine($"Command response: {commandResult.Response}");

// Use convenience methods for frequency operations
var frequency = await client.GetFrequencyAsync();
Console.WriteLine($"Current frequency: {frequency} Hz");

await client.SetFrequencyAsync(14074000); // Set to 14.074 MHz

Advanced Usage

// Use with dependency injection and HttpClientFactory
services.AddHttpClient<SharpCATClient>(client =>
{
    client.BaseAddress = new Uri("http://localhost:5188");
});

// Handle errors
try
{
    var result = await client.SendCommandAsync("invalid_command");
}
catch (SharpCATClientException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
    if (ex.Details != null)
        Console.WriteLine($"Details: {ex.Details}");
}

// Use cancellation tokens
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
var status = await client.GetStatusAsync(cts.Token);

API Reference

Core Methods

Port Management

• GetPortsAsync() - Get all available serial ports
• OpenPortAsync(request) - Open and configure a serial port
• ClosePortAsync() - Close the current serial port
• GetStatusAsync() - Get current port connection status

CAT Commands

• SendCommandAsync(command) - Send a raw CAT command string
• SendCommandAsync(request) - Send a CAT command with full request object

Frequency Operations (Convenience Methods)

• GetFrequencyAsync() - Get current frequency (VFO A)
• SetFrequencyAsync(frequencyHz) - Set frequency (VFO A)
• GetFrequencyBAsync() - Get current frequency (VFO B)
• SetFrequencyBAsync(frequencyHz) - Set frequency (VFO B)

Configuration Options

When opening a port, you can configure:

var request = new OpenPortRequest
{
    PortName = "COM3",           // Required
    BaudRate = 9600,             // Default: 9600
    Parity = Parity.None,        // Default: None
    StopBits = StopBits.One,     // Default: One
    Handshake = Handshake.None   // Default: None
};

Error Handling

The client throws SharpCATClientException for various error conditions:

• HTTP request failures
• Network timeouts
• API error responses
• Deserialization failures

try
{
    var result = await client.GetPortsAsync();
}
catch (SharpCATClientException ex)
{
    // Handle SharpCAT-specific errors
    Console.WriteLine($"SharpCAT Error: {ex.Message}");
}
catch (Exception ex)
{
    // Handle other errors
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

Common CAT Commands

Here are some common CAT commands you can send using SendCommandAsync():

Command	Description	Example Response
FA;	Get VFO A frequency	FA00014074000;
FB;	Get VFO B frequency	FB00007074000;
FA14074000;	Set VFO A frequency	No response or FA14074000;
MD;	Get operating mode	MD2; (USB)
MD2;	Set mode to USB	No response
IF;	Get radio information	IF00014074000...;

Note: The exact commands and responses depend on your radio model. Consult your radio's CAT documentation for complete command reference.

Thread Safety

The SharpCATClient class is thread-safe for concurrent read operations, but write operations (like sending commands) should be serialized to avoid conflicts at the radio level.

Disposal

The client implements IDisposable. When you create a client with a base address string or URI, it owns the internal HttpClient and will dispose it. If you pass in your own HttpClient, the client will not dispose it.

// Client owns HttpClient - will be disposed
using var client = new SharpCATClient("http://localhost:5188");

// You own HttpClient - manage disposal yourself
var httpClient = new HttpClient();
var client = new SharpCATClient(httpClient);
// Don't forget to dispose httpClient when done

Requirements

• .NET Standard 2.0 or later
• SharpCAT Server running and accessible
• Network connectivity to the server

Dependencies

• System.Net.Http.Json (5.0.0)
• System.Text.Json (5.0.2)
• System.ComponentModel.Annotations (5.0.0)

License

This project follows the same license as the parent SharpCAT project.

Contributing

Contributions are welcome! Please follow the existing code style and add appropriate documentation for new features.