Class BleNusTransport

BLE transport backed by the Nordic UART Service (NUS).

Inheritance

object

BleNusTransport

Implements

ITransport

Namespace: HFI.Wss

Assembly: WSS.Transport.BLE.dll

Syntax

public sealed class BleNusTransport : ITransport

Remarks

This is a low-level byte transport only. Outbound messages are written with response to the NUS RX characteristic, inbound messages arrive as notifications from the NUS TX characteristic, and writes are serialized so only one GATT write is in flight at a time. Device selection follows AutoSelectDevice: when enabled, the transport scans for compatible BLE devices and chooses the best valid candidate; otherwise it requires an explicit DeviceId or DeviceName.

Constructors

BleNusTransport(BleNusTransportOptions)

Creates a BLE transport from a fully specified options object.

Declaration

public BleNusTransport(BleNusTransportOptions options)

Parameters

Type	Name	Description
BleNusTransportOptions	options	BLE transport configuration including device selection and required UUIDs.

Exceptions

Type	Condition
ArgumentNullException	Thrown when options is null.
ArgumentException	Thrown when the supplied options are invalid.

BleNusTransport(string)

Creates a BLE transport that connects to a device with the specified advertised name.

Declaration

public BleNusTransport(string deviceName)

Parameters

Type	Name	Description
string	deviceName	Exact BLE device name to scan for.

Fields

DefaultNotifyCharacteristicUuid

Gets the default Nordic UART Service notification characteristic UUID used for inbound bytes.

Declaration

public static readonly Guid DefaultNotifyCharacteristicUuid

Field Value

Type	Description
Guid

DefaultServiceUuid

Gets the default Nordic UART Service UUID used to discover compatible BLE devices.

Declaration

public static readonly Guid DefaultServiceUuid

Field Value

Type	Description
Guid

DefaultWriteCharacteristicUuid

Gets the default Nordic UART Service write characteristic UUID used for outbound bytes.

Declaration

public static readonly Guid DefaultWriteCharacteristicUuid

Field Value

Type	Description
Guid

Properties

IsConnected

Gets whether the transport currently has an active BLE session and both required GATT characteristics.

Declaration

public bool IsConnected { get; }

Property Value

Type	Description
bool

Methods

ConnectAsync(CancellationToken)

Asynchronously scans for and connects to the configured BLE device.

Declaration

public Task ConnectAsync(CancellationToken ct = default)

Parameters

Type	Name	Description
CancellationToken	ct	Cancellation token.

Returns

Type	Description
Task	A task that completes when the BLE session and required characteristics are ready.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the transport has been disposed.
InvalidOperationException	Thrown when no compatible BLE device can be resolved or the required service and characteristics are unavailable.
OperationCanceledException	Thrown when the operation is canceled.

CreateDefaultOptions(string)

Creates a default options object that resolves a BLE device by advertised name.

Declaration

public static BleNusTransportOptions CreateDefaultOptions(string deviceName)

Parameters

Type	Name	Description
string	deviceName	Exact BLE device name to scan for.

Returns

Type	Description
BleNusTransportOptions	A new options object with DeviceName set.

DisconnectAsync(CancellationToken)

Asynchronously disconnects the active BLE session and stops inbound notifications.

Declaration

public Task DisconnectAsync(CancellationToken ct = default)

Parameters

Type	Name	Description
CancellationToken	ct	Cancellation token.

Returns

Type	Description
Task	A task that completes when platform-specific BLE resources have been released.

Exceptions

Type	Condition
OperationCanceledException	Thrown when the operation is canceled.

Dispose()

Disconnects the transport and releases managed resources.

Declaration

public void Dispose()

Remarks

This method performs a best-effort synchronous disconnect and logs disconnect failures instead of rethrowing them.

SendAsync(byte[], CancellationToken)

Sends a block of raw bytes over the BLE write characteristic.

Declaration

public Task SendAsync(byte[] data, CancellationToken ct = default)

Parameters

Type	Name	Description
byte[]	data	Raw payload bytes to write.
CancellationToken	ct	Cancellation token.

Returns

Type	Description
Task	A task that completes when the write has been handed off to the platform BLE stack.

Remarks

Writes are serialized so only one GATT write is in flight at a time.

Exceptions

Type	Condition
ArgumentNullException	Thrown when data is null.
ObjectDisposedException	Thrown when the transport has been disposed.
InvalidOperationException	Thrown when the transport is not connected.
OperationCanceledException	Thrown when the operation is canceled.

Events

BytesReceived

Raised when raw bytes are received from the BLE notification characteristic.

Declaration

public event Action<byte[]>? BytesReceived

Event Type

Type	Description
Action<byte[]>

Remarks

Handlers may be invoked on a background thread supplied by the underlying BLE stack. Marshal to the required context before touching thread-affine state.

Implements

ITransport