BLEClient Component

Properties   Methods   Events   Config Settings   Errors  

An easy-to-use Bluetooth Low Energy (BLE) GATT Client component.

Syntax

nsoftware.IPWorksBLE.BLEClient

Remarks

The BLEClient component provides a simple but flexible BLE GATT client implementation, making it easy to work with the services, characteristics, and descriptors exposed by BLE GATT servers on remote devices.

Prerequisites

Important: Please note that the BLEClient component is only supported by Windows 10 Creator's Update (10.0.15063.0) and later. Additionally .NET Version 4.5 or higher is required.

Scanning and Connecting

The Advertisement event provides a wealth of information about the remote device, such as its Id and local name, whether or not you can connect to it, the list of service UUIDs it's advertising, and much more.

Once you've determined what device you wish to connect to, call the Connect method and pass its server Id, obtained from the Advertisement event. The component will stop scanning, then attempt to connect to the device. The Connected event is fired when the connection attempt finishes, and will contain error information in case of a failure.

// StartScan, StopScan, and Advertisement event handlers. bleclient1.OnStartScan += (s, e) => Console.WriteLine("Scanning has started"); bleclient1.OnStopScan += (s, e) => Console.WriteLine("Scanning has stopped"); bleclient1.OnAdvertisement += (s, e) => { // Your application should make every effort to handle the Advertisement event quickly. // BLEClient fires it as often as necessary, often multiple times per second. Console.WriteLine("Advertisement Received:\r\n\tServerId: " + e.ServerId + "\r\n\tName: " + e.Name + "\r\n\tServiceUuids: " + e.ServiceUuids + "\r\n\tManufacturerCompanyId: " + e.ManufacturerCompanyId + "\r\n\tIsConnectable: " + e.IsConnectable); }; // Scan for all devices. bleclient1.StartScanning(""); // Alternatively, you can scan for devices advertising specific service UUIDs. You can use a // mixture of 16-, 32-, and 128-bit UUID strings, they'll be converted to 128-bit internally. bleclient1.StartScanning("180A,0000180F,00001801-0000-1000-8000-00805F9B34FB"); // ...Once you find a device you wish to connect to... bleclient1.Connect("SERVER_ID");

Refer the StartScanning for more detailed code examples.

Service, Characteristic, and Descriptor Discovery

After you've discovered the services you're interested in, you have to discover those services' characteristics. This is done with the DiscoverCharacteristics method, passing the Id of the service you wish to discover characteristics for, and optionally passing a list of characteristic UUIDs to limit the discovery process. For each characteristic discovered, an object will be added to the Characteristics collection, and the Discovered event will fire.

Finally, you can discover descriptors for the discovered characteristics. To do this, you use the DiscoverDescriptors method, passing the Id of a characteristic, as well as the Id of the service which owns it. For each descriptor discovered, an object will be added to the Descriptors collection, and the Discovered event will fire.

If you would prefer to do multiple discovery steps with a single call, you can use the Discover method rather than the individual DiscoverServices, DiscoverCharacteristics, and DiscoverDescriptors methods. However, keep in mind that doing so will consume more power up front. Discovering services, characteristics, and descriptors as you need them is more energy-efficient.

// Discovered event handler. bleclient1.OnDiscovered += (s, e) => { string gattType = e.GattType == 0 ? "Service" : (e.GattType == 1 ? "Characteristic" : "Descriptor"); Console.WriteLine(gattType + " discovered:" + // The 128-bit UUID string, "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX". "\r\n\tUUID: " + e.Uuid + // For standard GATT objects whose UUIDs are defined by the Bluetooth // SIG, the Description event parameter will contain their name. "\r\n\tDescription: " + e.Description); }; string serviceIds = "180A,F000AA70-0451-4000-B000-000000000000,F000AA20-0451-4000-B000-000000000000"; // Discover specific root services. bleclient1.DiscoverServices(serviceIds, ""); foreach (Service s in bleclient1.Services) { // Discover all characteristics for this service. bleclient1.DiscoverCharacteristics(s.Id, ""); bleclient1.Service = s.Id; foreach (Characteristic c in bleclient1) { // Discover all descriptors for this characteristic. bleclient1.DiscoverDescriptors(s.Id, c.Id); } }

Refer to DiscoverServices, DiscoverCharacteristics, DiscoverDescriptors, and Discover for more detailed code examples.

Working with Discovered Data

Set the Service property to a specific service's Id to have the component populate the Characteristics collection based on the characteristics discovered for that service. You can then iterate over the characteristic objects to inspect the details of each characteristic. Depending on what flags a characteristic has, you may also be able to directly manipulate some of its information.

Set the Characteristic property to a specific characteristic's Id to have the component populate the Descriptors collection based on the descriptors discovered for that characteristic. You can then iterate over the descriptor objects to inspect the details of each descriptor.

// Loop through all discovered GATT objects and print out their UUIDs and descriptions. foreach (Service s in bleclient1.Services) { Console.WriteLine("Service: " + s.Description + " (" + s.Uuid + ")"); // Select this service and loop through its characteristics. bleclient1.Service = s.Id; foreach (Characteristic c in bleclient1.Characteristics) { Console.WriteLine("\tCharacteristic: " + c.Description + " (" + c.Uuid + ")"); // Select this characteristic and loop through its descriptors. bleclient1.Characteristic = c.Id; foreach (Descriptor d in bleclient1.Descriptors) { Console.WriteLine("\t\tDescriptor: " + d.Description + " (" + d.Uuid + ")"); } } }

Reading and Writing Values

// Print the cached value for a characteristic (which you can assume // we've already found and assigned to a variable called "c"). Console.WriteLine("Characteristic Value: " + BitConverter.ToUInt16(c.CachedValueB, 0)); // Print the cached value for a descriptor (again, assume it's stored in "d"). Console.WriteLine("Descriptor Value: " + BitConverter.ToString(d.CachedValueB));

To read a value directly from the remote device's GATT server, use the ReadValue method. For characteristics, you'll need to pass the Ids of the characteristic and the service which owns it. For descriptors, you'll pass both of those, as well as the Id of the descriptor. If the read succeeds, the method will return the value read from the device, and the Value event will be fired. If the read fails, the Error event is fired and the component throws an exception.

// Value event handler. bleclient1.OnValue += (s, e) => { Console.WriteLine("Read value {" + BitConverter.ToString(e.ValueB) + "} for " + (string.IsNullOrEmpty(e.DescriptorId) ? "characteristic" : "descriptor") + " with UUID " + e.Uuid); }; // Prints the live value for a characteristic. bleclient1.ReadValue("001C00000000", "001C001D0000", ""); // Prints the live value for a descriptor. bleclient1.ReadValue("001C00000000", "001C001D0000", "001C001D0021");

To write a characteristic or descriptor value, call the WriteValue method, passing the appropriate Ids and the value to be written. If the write succeeds, the method will return and the WriteResponse event will fire. If the write fails, the Error event is fired and the component throws an exception.

// WriteResponse event handler. bleclient1.OnWriteResponse += (s, e) => { string gattType = string.IsNullOrEmpty(e.DescriptorId) ? "characteristic" : "descriptor"; Console.WriteLine("Successfully wrote to " + gattType + " with UUID " + e.Uuid); }; // Write to a characteristic. bleclient1.WriteValue("004200000000", "004200460000", "", new byte[] { 0x1 }); // Write to a descriptor. bleclient1.WriteValue("004200000000", "004200430000", "004200430045", new byte[] { 0x1 });

You can also use the PostValue method to write values to characteristics that have the "Write Without Response" flag. Posting a value to a characteristic is more energy-efficient since the remote device's GATT server won't send back an acknowledgement, even if the write fails.

// Write without response to a characteristic. bleclient1.PostValue("00AA00000000", "00AA00BB0000", new byte[] { 0x1, 0x2, 0x3 });

Keep in mind that not all characteristics and descriptors support value writes, and some might not even support value reads. If you attempt to perform an operation that a characteristic or descriptor doesn't support, the component throws an exception.

For characteristics, you can inspect the Characteristic.Flags field to determine what operations the characteristic supports. For descriptors, you'll either need to know in advance what operations are supported, or be ready to handle exceptions which may occur.

Refer to ReadValue, WriteValue, and PostValue for more detailed code examples.

Subscribing to Characteristics

When you want to subscribe to a characteristic, start by checking the Characteristic.CanSubscribe field to determine if it supports subscriptions.

For characteristics which do support subscriptions, you can subscribe and unsubscribe by using either the Characteristic.Subscribed field or the Subscribe and Unsubscribe methods. The Subscribed and Unsubscribed events are fired whenever a characteristic's subscription state changes, and the Value event is fired whenever a value update is received.

Note that characteristics do not have to support both subscription types, or even one of them. For characteristics which do support both, the component will subscribe for notifications by default. If you'd prefer that it subscribe for indications instead, enable the PreferIndications configuration setting.

// Subscribed, Unsubscribed, and Value event handlers. bleclient1.OnSubscribed += (s, e) => { Console.WriteLine("Subscribed to characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; bleclient1.OnUnsubscribed += (s, e) => { Console.WriteLine("Unsubscribed from characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; bleclient1.OnValue += (s, e) => { Console.WriteLine("Value update received for characteristic: " + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description + "\r\n\tValue: " + BitConverter.ToString(e.ValueB)); }; // Assume that we've already found a characteristic, its owning service, // and a descriptor on it; and we've stored them in variables called "c", // "s", and "d", respectively. You can subscribe to and unsubscribe from // the characteristic using any, or all, of the three methods below. // Subscribe and unsubscribe using methods. bleclient1.Subscribe(s.Id, c.Id); // ... bleclient1.Unsubscribe(s.Id, c.Id); // Subscribe and unsubscribe using the "Subscribed" field. c.Subscribed = true; // ... c.Subscribed = false; // Subscribe and unsubscribe by writing directly to the CCCD. bleclient1.WriteValue(s.Id, c.Id, d.Id, new byte[] { 1, 0 }); // ... bleclient1.WriteValue(s.Id, c.Id, d.Id, new byte[] { 0, 0 });

Usage Notes

Most platforms will in some way limit the use of Bluetooth APIs when your application is in the background. Be aware of the limitations your platform places on the usage of BLE APIs while in the background, and be ready to act accordingly.

Be sure to disconnect from a remote device by calling Disconnect when you're finished using it. When you're completely finished using the BLEClient component, be sure that you've called StopScanning and Disconnect before disposing of the instance. (Calling the component's Dispose() method will automatically take care of this for you.)

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

ActiveScanning Property (BLEClient Component)

Whether to use active scanning.

Syntax

• C#
• VB.NET

public bool ActiveScanning { get; set; }

Public Property ActiveScanning As Boolean

Default Value

False

Remarks

When enabled, the component will instruct the system to use active scanning rather than passive scanning, at the cost of higher power consumption.

Active scanning causes the system's BLE API to request a scan response packet for each advertisement received, which in turn means that you will be able to get more information from devices without connecting to them.

The tradeoff is that enabling this feature increases power consumption for both the client and server, but if your use-case doesn't call for ever actually connecting to the devices (which itself can be a power-intensive operation), then that tradeoff might be mitigated.

Note that you cannot change the value of the ActiveScanning property if the component is already scanning.

Active Scanning // Enable active scanning. bleclient1.ActiveScanning = true; bleclient1.StartScanning(""); // ... bleclient1.StopScanning();

This property is not available at design time.

Characteristic Property (BLEClient Component)

The currently selected characteristic's Id.

Syntax

• C#
• VB.NET

public string Characteristic { get; set; }

Public Property Characteristic As String

Default Value

""

Remarks

Setting the Characteristic property to the Id of a discovered characteristic allows you to inspect the descriptors which have been discovered for it using the Descriptors collection.

Characteristic can either be set to the Id of a characteristic which has been discovered for the service currently selected by Service, or to empty string.

This property is automatically set when you call the Select method; and it is reset to empty string when you set Service.

This property is not available at design time.

Characteristics Property (BLEClient Component)

The characteristics which have been discovered for the currently selected service.

Syntax

• C#
• VB.NET

public CharacteristicList Characteristics { get; }

Public Property Characteristics As CharacteristicList

Remarks

The characteristics which have been discovered for the service currently selected with Service. This collection is populated when characteristics are discovered for a service, which may occur due to a call to the Discover or DiscoverCharacteristics methods, or at the time when a service is discovered (if you have the AutoDiscoverCharacteristics configuration setting enabled).

Characteristics do not all have to be discovered at one time, and additional characteristics discovered for a service will automatically be added to this collection upon discovery. This collection is cleared when the component disconnects from the server.

If Service is set to empty string, or if no characteristics have been discovered for the currently selected service, this collection will be empty.

This property is not available at design time.

Descriptors Property (BLEClient Component)

The descriptors which have been discovered for the currently selected characteristic.

Syntax

• C#
• VB.NET

public DescriptorList Descriptors { get; }

Public ReadOnly Property Descriptors As DescriptorList

Remarks

The descriptors which have been discovered for the characteristic currently selected with Characteristic. This collection is populated when descriptors are discovered for a characteristic, which may occur due to a call to the Discover or DiscoverDescriptors methods, or at the time when a characteristic is discovered (if you have the AutoDiscoverDescriptors configuration setting enabled).

Descriptors do not all have to be discovered at one time, and additional descriptors discovered for a characteristic will automatically be added to this collection upon discovery. This collection is cleared when the component disconnects from the server.

If Characteristic is set to empty string, or if no descriptors have been discovered for the currently selected characteristic, this collection will be empty.

This property is read-only and not available at design time.

Scanning Property (BLEClient Component)

Whether or not the component is currently scanning for servers.

Syntax

• C#
• VB.NET

public bool Scanning { get; }

Public ReadOnly Property Scanning As Boolean

Default Value

False

Remarks

This property indicates whether or not the component is currently scanning for servers. While the component is scanning, the Advertisement event will be fired whenever an advertisement from a remote device is received.

Refer to the StartScanning method for more information.

This property is read-only and not available at design time.

ServerId Property (BLEClient Component)

Platform-specific string identifying the currently connected server.

Syntax

• C#
• VB.NET

public string ServerId { get; }

Public ReadOnly Property ServerId As String

Default Value

""

Remarks

When the component is connected to a server, this property contains the platform-specific server identification string.

Note that this value is not guaranteed to be the same at any point in time for a specific server device.

This property is read-only and not available at design time.

ServerName Property (BLEClient Component)

Local name of the currently connected server.

Syntax

• C#
• VB.NET

public string ServerName { get; }

Public ReadOnly Property ServerName As String

Default Value

""

Remarks

When the component is connected to a server, this property contains the server's local name.

If the server's name changes while you're connected to it, the ServerUpdate event will fire with the Name parameter populated, and the new value will be reflected here.

This property is read-only and not available at design time.

Service Property (BLEClient Component)

The currently selected service's Id.

Syntax

• C#
• VB.NET

public string Service { get; set; }

Public Property Service As String

Default Value

""

Remarks

Setting the Service property to the Id of a discovered service allows you to inspect the characteristics which have been discovered for it using the Characteristics collection.

Service can either be set to the Id of a service which has been discovered for the currently connected server, or to empty string. Setting Service will automatically reset Characteristic to empty string.

This property is automatically set when you call the Select method.

This property is not available at design time.

Services Property (BLEClient Component)

The services which have been discovered on the currently connected server.

Syntax

• C#
• VB.NET

public ServiceList Services { get; }

Public ReadOnly Property Services As ServiceList

Remarks

The services which have been discovered for the currently connected server. This collection is populated when services are discovered, which may occur due to a call to the Discover or DiscoverServices methods, or at the time when a service with included services is discovered (if you have the AutoDiscoverIncludedServices configuration setting enabled).

Included services are represented in this collection just like root ones are.

Services do not all have to be discovered at one time, and additional services discovered will automatically be added to this collection upon discovery. This collection is cleared when the component disconnects from the server.

This property is read-only and not available at design time.

Timeout Property (BLEClient Component)

A timeout for the component

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered (except the PostValue method, which always returns immediately).

If Timeout is set to a positive value, the component will wait for a maximum of Timeout seconds since the beginning of the operation. If Timeout expires, and the operation is not yet complete, the component throws an exception.

The default value for the Timeout property is 60 (seconds).

CheckCharacteristicSubscribed Method (BLEClient Component)

Checks to see if the component is subscribed to a characteristic.

Syntax

• C#
• VB.NET

public bool CheckCharacteristicSubscribed(int index);

Async Version
public async Task<bool> CheckCharacteristicSubscribed(int index);
public async Task<bool> CheckCharacteristicSubscribed(int index, CancellationToken cancellationToken);

Public Function CheckCharacteristicSubscribed(ByVal index As Integer) As Boolean

Async Version
Public Function CheckCharacteristicSubscribed(ByVal index As Integer) As Task(Of Boolean)
Public Function CheckCharacteristicSubscribed(ByVal index As Integer, cancellationToken As CancellationToken) As Task(Of Boolean)

Remarks

This method is used to see if the component is subscribed to a characteristic. The method uses the given index parameter to find the characteristic at the index of the Characteristics property. The method will then return a bool value based on whether the client is currently subscribed to that characteristic.

Config Method (BLEClient Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Connect Method (BLEClient Component)

Connect to a BLE GATT server based on its identifier.

Syntax

• C#
• VB.NET

public void Connect(string serverId);

Async Version
public async Task Connect(string serverId);
public async Task Connect(string serverId, CancellationToken cancellationToken);

Public Sub Connect(ByVal ServerId As String)

Async Version
Public Sub Connect(ByVal ServerId As String) As Task
Public Sub Connect(ByVal ServerId As String, cancellationToken As CancellationToken) As Task

Remarks

This method will attempt to connect to the BLE GATT server represented by the platform-specific identifier supplied in the ServerId parameter. The Connected event will be fired when the connection attempt finishes, and will contain additional information if the attempt failed.

If the component is connected to a server already when Connect is called, and the given ServerId is different than the currently connected server's ServerId, it will attempt to gracefully disconnect prior to initiating a new connection.

Calling Connect does nothing if ServerId is empty or matches the currently connected server's ServerId.

If Connect is called while the component is Scanning, the component will stop scanning prior to attempting to initiate a connection.

Note that there are a variety of reasons that a connection to a server may fail, not the least of which includes the server device being out of range of the client device. For the best results, it is recommended that you scan for devices before attempting a connection. Also note that the device identifier is a platform-specific value which is not guaranteed to be the same at any given point in time for any specific server device.

Connecting and Disconnecting // Connect to our TI SensorTag device. bleclient1.Connect("546C0E795800"); // Use BLEClient... // Disconnect from the device. bleclient1.Disconnect();

Disconnect Method (BLEClient Component)

Disconnects from the remote server.

Syntax

• C#
• VB.NET

public void Disconnect();

Async Version
public async Task Disconnect();
public async Task Disconnect(CancellationToken cancellationToken);

Public Sub Disconnect()

Async Version
Public Sub Disconnect() As Task
Public Sub Disconnect(cancellationToken As CancellationToken) As Task

Remarks

This method disconnects from the remote server and clears all service, characteristic, and descriptor data from the component. The Disconnected event will be fired when the component has disconnected from the remote device.

Refer to the Connect method for more information.

Discover Method (BLEClient Component)

Convenience method to discover multiple levels of the GATT object hierarchy at once.

Syntax

• C#
• VB.NET

public void Discover(string serviceUuids, string characteristicUuids, bool discoverDescriptors, string includedByServiceId);

Async Version
public async Task Discover(string serviceUuids, string characteristicUuids, bool discoverDescriptors, string includedByServiceId);
public async Task Discover(string serviceUuids, string characteristicUuids, bool discoverDescriptors, string includedByServiceId, CancellationToken cancellationToken);

Public Sub Discover(ByVal ServiceUuids As String, ByVal CharacteristicUuids As String, ByVal DiscoverDescriptors As Boolean, ByVal IncludedByServiceId As String)

Async Version
Public Sub Discover(ByVal ServiceUuids As String, ByVal CharacteristicUuids As String, ByVal DiscoverDescriptors As Boolean, ByVal IncludedByServiceId As String) As Task
Public Sub Discover(ByVal ServiceUuids As String, ByVal CharacteristicUuids As String, ByVal DiscoverDescriptors As Boolean, ByVal IncludedByServiceId As String, cancellationToken As CancellationToken) As Task

Remarks

This method can be used in place of individual calls to the DiscoverServices, DiscoverCharacteristics, and DiscoverDescriptors methods in order to discover GATT objects from multiple levels of the GATT hierarchy at once.

To discover root services, their characteristics, and those characteristics' descriptors, you can:

• Pass a comma-separated list of service UUIDs for the services which you are interested in to the ServiceUuids parameter.
• Pass a comma-separated list of characteristic UUIDs for the characteristics which you are interested in (for any and all services which could be discovered) to the CharacteristicUuids parameter.
• Pass either true or false to the DiscoverDescriptors parameter, based on whether or not you wish to discover descriptors for discovered characteristics.
• Pass the empty string to the IncludedByServiceId parameter.

If you wish to discover included services, their characteristics, and those characteristics' descriptors, the above still applies, but you should pass the Id of an already discovered service to the IncludedByServiceId parameter.

You have the option of passing the empty string to either, or both, of the ServiceUuids and CharacteristicUuids parameters if you do not wish to limit your discovery to specific services and/or characteristics, but doing so is strongly discouraged due to the additional power consumption that will result.

During the discovery process, the Discovered event will fire once for each GATT object discovered. You may control whether it fires when a GATT object is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Multi-Level Discovery string serviceUUIDs = "180A,F000AA70-0451-4000-B000-000000000000,F000AA20-0451-4000-B000-000000000000"; string characteristicUUIDs = ""; //All Characteristics bool discoverDescriptors = true; string includedByServiceId = ""; //No included services // This will discover all characteristics and descriptors for specific services. bleclient1.Discover(serviceUUIDs, characteristicUUIDs, discoverDescriptors, includedByServiceId); // This will discover everything on the server, but won't discover // the "includes"/"included by" service relationships. bleclient1.Discover("", "", true, "");

DiscoverCharacteristics Method (BLEClient Component)

Used to discover characteristics for a specific service.

Syntax

• C#
• VB.NET

public void DiscoverCharacteristics(string serviceId, string characteristicUuids);

Async Version
public async Task DiscoverCharacteristics(string serviceId, string characteristicUuids);
public async Task DiscoverCharacteristics(string serviceId, string characteristicUuids, CancellationToken cancellationToken);

Public Sub DiscoverCharacteristics(ByVal ServiceId As String, ByVal CharacteristicUuids As String)

Async Version
Public Sub DiscoverCharacteristics(ByVal ServiceId As String, ByVal CharacteristicUuids As String) As Task
Public Sub DiscoverCharacteristics(ByVal ServiceId As String, ByVal CharacteristicUuids As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to discover characteristics that belong to the service represented by ServiceId. Discovered characteristics' data will be used to populate the Characteristics collection property when the Service property is set to the applicable service Id.

It is recommended that you pass a comma-separated list of characteristic UUIDs for the CharacteristicUuids parameter in order to limit discovery to just the characteristics that you are interested in. You may also pass the empty string to discover all of the service's characteristics, but doing so will result in higher power consumption.

During the discovery process, the Discovered event will fire once for each characteristic discovered. You may control whether it fires when a characteristic is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Characteristic Discovery // Discovered event handler. bleclient1.OnDiscovered += (s, e) => { Console.WriteLine("Characteristic discovered:" + "\r\n\tOwning Service Id: " + e.ServiceId + "\r\n\tCharacteristic Id: " + e.CharacteristicId + // The discovered characteristic's 128-bit UUID string, in the format // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" "\r\n\tUUID: " + e.Uuid + // For standard characteristics whose UUIDs are defined by the Bluetooth SIG, // the Description event parameter will contain the name of the characteristic. "\r\n\tDescription: " + e.Description); }; // Discover all characteristics for the service whose Id is "000900000000". // (On our CC2650STK TI SensorTag, this is the Device Information Service.) bleclient1.DiscoverCharacteristics("000900000000", "");

Filtered Characteristic Discovery // Discover specific characteristics for the service whose Id is "000900000000". // (On our CC2650STK TI SensorTag, this is the Device Information Service.) // This will cause the System Id, Model Number String, and Manufacturer Name String // characteristics to be discovered, respectively. bleclient1.DiscoverCharacteristics("000900000000", "2A23,2A24,2A29");

DiscoverDescriptors Method (BLEClient Component)

Used to discover all descriptors for a specific characteristic.

Syntax

• C#
• VB.NET

public void DiscoverDescriptors(string serviceId, string characteristicId);

Async Version
public async Task DiscoverDescriptors(string serviceId, string characteristicId);
public async Task DiscoverDescriptors(string serviceId, string characteristicId, CancellationToken cancellationToken);

Public Sub DiscoverDescriptors(ByVal ServiceId As String, ByVal CharacteristicId As String)

Async Version
Public Sub DiscoverDescriptors(ByVal ServiceId As String, ByVal CharacteristicId As String) As Task
Public Sub DiscoverDescriptors(ByVal ServiceId As String, ByVal CharacteristicId As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to discover all descriptors that belong to the characteristic represented by CharacteristicId (which is owned by the service represented by ServiceId). Discovered descriptors' data will be used to populate the Descriptors collection property when the Characteristic property is set to the applicable characteristic Id.

During the discovery process, the Discovered event will fire once for each descriptor discovered. You may control whether it fires when a descriptor is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Descriptor Discovery // Discovered event handler. bleclient1.OnDiscovered += (s, e) => { Console.WriteLine("Descriptor discovered:" + "\r\n\tOwning Service Id: " + e.ServiceId + "\r\n\tOwning Characteristic Id: " + e.CharacteristicId + "\r\n\tDescriptor Id: " + e.DescriptorId + // The discovered descriptor's 128-bit UUID string, in the format // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" "\r\n\tUUID: " + e.Uuid + // For standard descriptors whose UUIDs are defined by the Bluetooth SIG, // the Description event parameter will contain the name of the descriptor. "\r\n\tDescription: " + e.Description); }; // Discover all descriptors for characteristic Id "001C001D0000", owned by // service Id "001C00000000". (On our CC2650STK TI SensorTag, this is the // Battery Level characteristic, which is owned by the Battery Service.) bleclient1.DiscoverDescriptors("001C00000000", "001C001D0000");

DiscoverServices Method (BLEClient Component)

Used to discover services for the currently connected server.

Syntax

• C#
• VB.NET

public void DiscoverServices(string serviceUuids, string includedByServiceId);

Async Version
public async Task DiscoverServices(string serviceUuids, string includedByServiceId);
public async Task DiscoverServices(string serviceUuids, string includedByServiceId, CancellationToken cancellationToken);

Public Sub DiscoverServices(ByVal ServiceUuids As String, ByVal IncludedByServiceId As String)

Async Version
Public Sub DiscoverServices(ByVal ServiceUuids As String, ByVal IncludedByServiceId As String) As Task
Public Sub DiscoverServices(ByVal ServiceUuids As String, ByVal IncludedByServiceId As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to discover root services on the currently connected server when empty string is passed for the IncludedByServiceId parameter. Passing the Id of an already-discovered service instead will cause the component to discover services included by that service.

All discovered services, root or otherwise, are added to the Services collection property.

It is recommended that you pass a comma-separated list of service UUIDs for the ServiceUuids parameter in order to limit discovery to just the services that you are interested in. You may also pass the empty string to discover all of the server's services (or all of a service's included services), but doing so will result in much higher power consumption.

During the discovery process, the Discovered event will fire once for each service discovered. You may control whether it fires when a service is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Service Discovery // Discovered event handler. bleclient1.OnDiscovered += (s, e) => { Console.WriteLine("Service discovered:" + "\r\n\tService Id: " + e.ServiceId + // The discovered service's 128-bit UUID string, in the format // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" "\r\n\tUUID: " + e.Uuid + // For standard services whose UUIDs are defined by the Bluetooth SIG, // the Description event parameter will contain the name of the service. "\r\n\tDescription: " + e.Description); }; // Discover all root services. bleclient1.DiscoverServices("", ""); // Discover all services included by a discovered service whose Id is "000100000000". bleclient1.DiscoverServices("", "000100000000");

Filtered Service Discovery // Discover specific root services. These three UUIDs will cause the Device Information, // Luxometer, and Humidity services to be discovered on our CC2650STK TI SensorTag. // (Since the latter two are non-standard, you have to use their full UUIDs.) bleclient1.DiscoverServices("180A,F000AA70-0451-4000-B000-000000000000,F000AA20-0451-4000-B000-000000000000", ""); // Discover specific services included by a discovered service whose Id is "000100000000". // (The TI SensorTag doesn't have any included services, this is just an example.) bleclient1.DiscoverServices("FFFFFFFF-9000-4000-B000-000000000000", "000100000000")

DoEvents Method (BLEClient Component)

This method processes events from the internal message queue.

Syntax

• C#
• VB.NET

public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);

Public Sub DoEvents()

Async Version
Public Sub DoEvents() As Task
Public Sub DoEvents(cancellationToken As CancellationToken) As Task

Remarks

When DoEvents is called, the component processes any available events. If no events are available, it waits for a preset period of time, and then returns.

PostValue Method (BLEClient Component)

Write the value of a characteristic without expecting a response.

Syntax

• C#
• VB.NET

public void PostValue(string serviceId, string characteristicId, byte[] value);

Async Version
public async Task PostValue(string serviceId, string characteristicId, byte[] value);
public async Task PostValue(string serviceId, string characteristicId, byte[] value, CancellationToken cancellationToken);

Public Sub PostValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal Value As String)

Async Version
Public Sub PostValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal Value As String) As Task
Public Sub PostValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to write the value of a characteristic, but unlike WriteValue it instructs the server not to send a response, even if the write request fails. This method will return immediately after the request is sent, regardless of the current Timeout value.

If your use-case doesn't require confirmation of characteristic value writes, this method is preferred; it allows both devices (but especially the server) to save power by keeping the BLE radio hardware turned off.

If you do require confirmation of characteristic value writes, or need to write a descriptor's value, use the WriteValue method.

Posting Values // The CC2650STK TI SensorTag doesn't have any characteristics which support // write without response, so this is just an example. bleclient1.PostValue("00AA00000000", "00AA00BB0000", new byte[] { 0x1, 0x2, 0x3 });

QueryCharacteristicCachedVal Method (BLEClient Component)

Reads and returns a characteristic value from the value cache.

Syntax

• C#
• VB.NET

public byte[] QueryCharacteristicCachedVal(int index);

Async Version
public async Task<byte[]> QueryCharacteristicCachedVal(int index);
public async Task<byte[]> QueryCharacteristicCachedVal(int index, CancellationToken cancellationToken);

Public Function QueryCharacteristicCachedVal(ByVal index As Integer) As String

Async Version
Public Function QueryCharacteristicCachedVal(ByVal index As Integer) As Task(Of String)
Public Function QueryCharacteristicCachedVal(ByVal index As Integer, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method will return the cached value for the characteristic. The method uses the given index parameter to find the characteristic at the index of the Characteristics property. The method then uses that characteristic to retrieve information from the value cache. 

QueryDescriptorCachedVal Method (BLEClient Component)

Reads and returns a descriptor value from the value cache.

Syntax

• C#
• VB.NET

public byte[] QueryDescriptorCachedVal(int index);

Async Version
public async Task<byte[]> QueryDescriptorCachedVal(int index);
public async Task<byte[]> QueryDescriptorCachedVal(int index, CancellationToken cancellationToken);

Public Function QueryDescriptorCachedVal(ByVal index As Integer) As String

Async Version
Public Function QueryDescriptorCachedVal(ByVal index As Integer) As Task(Of String)
Public Function QueryDescriptorCachedVal(ByVal index As Integer, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method will return the cached value for the descriptor. The method uses the given index parameter to find the descriptor at the index of the Descriptors property. The method then uses that descriptor to retrieve information from the value cache. 

ReadValue Method (BLEClient Component)

Read the value of a characteristic or descriptor from the server.

Syntax

• C#
• VB.NET

public byte[] ReadValue(string serviceId, string characteristicId, string descriptorId);

Async Version
public async Task<byte[]> ReadValue(string serviceId, string characteristicId, string descriptorId);
public async Task<byte[]> ReadValue(string serviceId, string characteristicId, string descriptorId, CancellationToken cancellationToken);

Public Function ReadValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal DescriptorId As String) As String

Async Version
Public Function ReadValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal DescriptorId As String) As Task(Of String)
Public Function ReadValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal DescriptorId As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to read the value of a characteristic or a descriptor directly from the server, bypassing the platform's cache in the process.

To read the value of a characteristic, pass the Ids of it and its owning service for the CharacteristicId and ServiceId parameters, and pass empty string for the DescriptorId parameter. To read the value of a descriptor, do the same thing, but pass the descriptor's Id for the DescriptorId parameter too.

If the read request is successful, the read value will be returned and the Value event will be fired. In addition, the platform will cache the value; you can retrieve the cached for a characteristic using CachedValue or for a descriptor using CachedValue.

If the read request fails, the Error event will be fired and the component throws an exception.

If the value of a characteristic changes often, prefer subscribing to the characteristic over polling in order to prevent unnecessary power consumption. Refer to the Subscribe method for more information.

Reading Live Values // Value event handler. bleclient1.OnValue += (s, e) => { if (string.IsNullOrEmpty(e.DescriptorId)) { Console.WriteLine("Read value {" + BitConverter.ToString(e.ValueB) + "} for characteristic with UUID " + e.Uuid); } else { Console.WriteLine("Read value {" + BitConverter.ToString(e.ValueB) + "} for descriptor with UUID " + e.Uuid); } }; // Print the live value for the Battery Level characteristic. These Ids // are correct for our CC2650STK TI SensorTag, but yours might differ. byte[] rawBatteryVal = bleclient1.ReadValue("001C00000000", "001C001D0000", ""); Console.WriteLine("Battery Level Value: " + (int)rawBatteryVal[0]); // Print the live value for the Characteristic Presentation Format descriptor on // the Battery Level characteristic. Again, your Ids might differ. byte[] rawBatteryPF = bleclient1.ReadValue("001C00000000", "001C001D0000", "001C001D0021"); Console.WriteLine("Battery Level Presentation Format bytes: " + BitConverter.ToString(rawBatteryPF));

Reading Cached Values // Print the cached value for the Luxometer Data characteristic (which you can // assume we've already found and assigned to a variable called "luxChara"). byte[] rawLuxVal = luxChara.CachedValueB; ushort luxVal = BitConverter.ToUInt16(rawLuxVal, 0); Console.WriteLine("Luxometer Value: " + luxVal); // Print the cached value for the Client Characteristic Configuration descriptor on // the Luxometer Data characteristic (again, assume it's stored in "luxCCCD"). byte[] rawLuxCCCD = luxCCCD.CachedValueB; Console.WriteLine("Luxometer CCCD bytes: " + BitConverter.ToString(rawLuxCCCD));

Select Method (BLEClient Component)

Used to set the currently selected service and characteristic by their Ids.

Syntax

• C#
• VB.NET

public void Select(string serviceId, string characteristicId);

Async Version
public async Task Select(string serviceId, string characteristicId);
public async Task Select(string serviceId, string characteristicId, CancellationToken cancellationToken);

Public Sub Select(ByVal ServiceId As String, ByVal CharacteristicId As String)

Async Version
Public Sub Select(ByVal ServiceId As String, ByVal CharacteristicId As String) As Task
Public Sub Select(ByVal ServiceId As String, ByVal CharacteristicId As String, cancellationToken As CancellationToken) As Task

Remarks

This is a convenience method used to select a specific service and/or characteristic.

To select just a service, only pass the desired service Id for ServiceId; pass empty string for CharacteristicId. To select a characteristic, pass both of the Ids.

As long as both of the Ids are valid, the Service and Characteristic properties will be set accordingly (Characteristic is cleared if a characteristic Id isn't given).

An error will be thrown if any of the Ids aren't valid, or if an invalid combination of Ids is passed.

StartScanning Method (BLEClient Component)

Causes the component to begin scanning for BLE GATT servers.

Syntax

• C#
• VB.NET

public void StartScanning(string serviceUuids);

Async Version
public async Task StartScanning(string serviceUuids);
public async Task StartScanning(string serviceUuids, CancellationToken cancellationToken);

Public Sub StartScanning(ByVal ServiceUuids As String)

Async Version
Public Sub StartScanning(ByVal ServiceUuids As String) As Task
Public Sub StartScanning(ByVal ServiceUuids As String, cancellationToken As CancellationToken) As Task

Remarks

This method causes the component to start scanning for BLE GATT servers, optionally filtered to include only servers which are advertising one or more services of interest.

To scan for all servers, pass empty string as the ServiceUuids parameter.

To scan for only servers advertising specific services, pass a comma-separated list of service UUIDs as the ServiceUuids parameter. (Only servers advertising all of the given services will be detected. Be aware that, due to the limited space in an advertisement packet, it's common for servers to support more services than they advertise.)

The StartScan event will be fired when the scanning has begun, after which the Advertisement event is fired whenever an advertisement from a server is received; the Error event is fired if an error occurs.

If you wish to use active scanning, enable the ActiveScanning property before you call StartScanning (refer to its documentation for more information).

You may start scanning while already connected to a server, but the component will stop scanning automatically if you attempt to initiate a new server connection (regardless of whether or not that connection attempt ends up succeeding).

Please be aware that scanning is a power-intensive activity, and you should call the StopScanning method as soon as is appropriate in order to prevent unnecessary power consumption.

Calling StartScanning when the component is already scanning does nothing.

Basic Scanning and Advertisement Handling Example // StartScan event handler. bleclient1.OnStartScan += (s, e) => Console.WriteLine("Scanning has started"); // StopScan event handler. bleclient1.OnStopScan += (s, e) => Console.WriteLine("Scanning has stopped"); // Advertisement event handler. bleclient1.OnAdvertisement += (s, e) => { // Your application should make every effort to handle the Advertisement event quickly. // BLEClient fires it as often as necessary, often multiple times per second. Console.WriteLine("Advertisement Received:" + "\r\n\tServerId: " + e.ServerId + "\r\n\tName: " + e.Name + "\r\n\tRSSI: " + e.RSSI + "\r\n\tTxPower: " + e.TxPower + "\r\n\tServiceUuids: " + e.ServiceUuids + "\r\n\tServicesWithData: " + e.ServicesWithData + "\r\n\tSolicitedServiceUuids: " + e.SolicitedServiceUuids + "\r\n\tManufacturerCompanyId: " + e.ManufacturerCompanyId + // We use BitConverter.ToString() to print data as hex bytes; this also prevents // an issue where the string could be cut off early if the data has a 0 byte in it. "\r\n\tManufacturerCompanyData: " + BitConverter.ToString(e.ManufacturerDataB) + "\r\n\tIsConnectable: " + e.IsConnectable + "\r\n\tIsScanResponse: " + e.IsScanResponse); }; // Scan for all devices. bleclient1.StartScanning(""); // Wait a while... bleclient1.StopScanning();

Filtered Scanning Example // Scan for devices which are advertising at least these UUIDs. You can use a mixture // of 16-, 32-, and 128-bit UUID strings, they'll be converted to 128-bit internally. bleclient1.StartScanning("180A,0000180F,00001801-0000-1000-8000-00805F9B34FB"); // ... bleclient1.StopScanning();

StopScanning Method (BLEClient Component)

Causes the component to stop scanning for BLE GATT servers.

Syntax

• C#
• VB.NET

public void StopScanning();

Async Version
public async Task StopScanning();
public async Task StopScanning(CancellationToken cancellationToken);

Public Sub StopScanning()

Async Version
Public Sub StopScanning() As Task
Public Sub StopScanning(cancellationToken As CancellationToken) As Task

Remarks

This method will request that the component stop scanning for BLE GATT servers if it is currently doing so, otherwise it will do nothing. The StopScan event will fire when the scanning has stopped.

Note that scanning may be stopped automatically by the platform under certain conditions; the StopScan event will contain the error code and description if applicable.

You can check the Scanning property to determine whether or not the component is currently scanning.

Subscribe Method (BLEClient Component)

Subscribes to value updates for the specified characteristic.

Syntax

• C#
• VB.NET

public void Subscribe(string serviceId, string characteristicId);

Async Version
public async Task Subscribe(string serviceId, string characteristicId);
public async Task Subscribe(string serviceId, string characteristicId, CancellationToken cancellationToken);

Public Sub Subscribe(ByVal ServiceId As String, ByVal CharacteristicId As String)

Async Version
Public Sub Subscribe(ByVal ServiceId As String, ByVal CharacteristicId As String) As Task
Public Sub Subscribe(ByVal ServiceId As String, ByVal CharacteristicId As String, cancellationToken As CancellationToken) As Task

Remarks

This method will subscribe the component to value updates for the characteristic whose Id is passed to CharacteristicId (which is owned by the service specified by ServiceId), as long as the characteristic supports it.

You can check a characteristic's CanSubscribe field to determine whether or not it supports subscriptions.

The Subscribed event will fire whenever you subscribe to a characteristic. While subscribed to a characteristic, the Value event will be fired each time the server sends an updated value for it (and its cached value will be updated as well).

The characteristic's Subscribed field can be used to determine whether or not the component is currently subscribed to a characteristic. You can also set it to true or false, which will automatically call Subscribe or Unsubscribe.

An error will be thrown if either of the given Ids are invalid, if the characteristic does not support subscribing for updates, or if there is an issue while trying to subscribe. Trying to subscribe to an already-subscribed characteristic does nothing.

Subscriptions // Subscribed event handler. bleclient1.OnSubscribed += (s, e) => { Console.WriteLine("Subscribed to characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; // Unsubscribed event handler. bleclient1.OnUnsubscribed += (s, e) => { Console.WriteLine("Unsubscribed from characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; // Value event handler. bleclient1.OnValue += (s, e) => { Console.WriteLine("Value update received for characteristic: " + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description + "\r\n\tValue: " + BitConverter.ToString(e.ValueB)); }; // Assume that we've already found the Luxometer Data characteristic, // its owning service, and the Client Characteristic Configuration // descriptor on it; and we've stored them in variables called "luxSvc", // "luxData", and "luxCCCD". // Subscribe and unsubscribe using methods. bleclient1.Subscribe(luxSvc.Id, luxData.Id); // ... bleclient1.Unsubscribe(luxSvc.Id, luxData.Id); // Subscribe and unsubscribe using the "Subscribed" field. luxData.Subscribed = true; // ... luxData.Subscribed = false; // Subscribe and unsubscribe by writing directly to the CCCD. bleclient1.WriteValue(luxSvc.Id, luxData.Id, luxCCCD.Id, new byte[] { 1, 0 }); // ... bleclient1.WriteValue(luxSvc.Id, luxData.Id, luxCCCD.Id, new byte[] { 0, 0 });

Unsubscribe Method (BLEClient Component)

Unsubscribes from value updates for one or more characteristics.

Syntax

• C#
• VB.NET

public void Unsubscribe(string serviceId, string characteristicId);

Async Version
public async Task Unsubscribe(string serviceId, string characteristicId);
public async Task Unsubscribe(string serviceId, string characteristicId, CancellationToken cancellationToken);

Public Sub Unsubscribe(ByVal ServiceId As String, ByVal CharacteristicId As String)

Async Version
Public Sub Unsubscribe(ByVal ServiceId As String, ByVal CharacteristicId As String) As Task
Public Sub Unsubscribe(ByVal ServiceId As String, ByVal CharacteristicId As String, cancellationToken As CancellationToken) As Task

Remarks

This method will unsubscribe from value updates for the characteristic represented by CharacteristicId (which is owned by the service specified by ServiceId). The Unsubscribed event will fire each time you unsubscribe from a characteristic.

Passing empty string for CharacteristicId will cause the component to unsubscribe from any characteristic it is subscribed to in the specified service. Passing empty string for both parameters does the same, but for all services. (Unsubscribing en masse may take time since every subscribe/unsubscribe operation requires a write request and response behind the scenes.)

An error will be thrown if either of the given Ids are invalid (when both are passed), if only CharacteristicId is passed, if the characteristic does not support subscribing for updates, or if there is an issue while trying to unsubscribe.

Refer to the Subscribe method for more information.

WriteValue Method (BLEClient Component)

Write the value of a characteristic or descriptor.

Syntax

• C#
• VB.NET

public void WriteValue(string serviceId, string characteristicId, string descriptorId, byte[] value);

Async Version
public async Task WriteValue(string serviceId, string characteristicId, string descriptorId, byte[] value);
public async Task WriteValue(string serviceId, string characteristicId, string descriptorId, byte[] value, CancellationToken cancellationToken);

Public Sub WriteValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal DescriptorId As String, ByVal Value As String)

Async Version
Public Sub WriteValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal DescriptorId As String, ByVal Value As String) As Task
Public Sub WriteValue(ByVal ServiceId As String, ByVal CharacteristicId As String, ByVal DescriptorId As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to write the value of a characteristic or descriptor. The method will return and the WriteResponse event will fire if the write is a success. If the write fails, the Error event will fire and the component throws an exception.

To write the value of a characteristic, pass the Ids of it and its owning service for the CharacteristicId and ServiceId parameters, and pass empty string for the DescriptorId parameter. To write the value of a descriptor, do the same thing, but pass the descriptor's Id for the DescriptorId parameter too.

If your use-case doesn't require confirmation of characteristic value writes, prefer the PostValue method in order to reduce power consumption.

Writing Values // WriteResponse event handler. bleclient1.OnWriteResponse += (s, e) => { if (string.IsNullOrEmpty(e.DescriptorId)) { Console.WriteLine("Successfully wrote to characteristic with UUID " + e.Uuid); } else { Console.WriteLine("Successfully wrote to descriptor with UUID " + e.Uuid); } }; // Write to the Luxometer Config characteristic. These Ids are correct // for our CC2650STK TI SensorTag, but yours might differ. bleclient1.WriteValue("004200000000", "004200460000", "", new byte[] { 0x1 }); // Write to the Client Characteristic Configuration descriptor on the // Luxometer Data characteristic. Again, your Ids might differ. bleclient1.WriteValue("004200000000", "004200430000", "004200430045", new byte[] { 0x1 });

Advertisement Event (BLEClient Component)

Fired when an advertisement packet is received during scanning.

Syntax

• C#
• VB.NET

public event OnAdvertisementHandler OnAdvertisement;

public delegate void OnAdvertisementHandler(object sender, BLEClientAdvertisementEventArgs e);

public class BLEClientAdvertisementEventArgs : EventArgs {
  public string ServerId { get; }
  public string Name { get; }
  public int RSSI { get; }
  public int TxPower { get; }
  public string ServiceUuids { get; }
  public string ServicesWithData { get; }
  public string SolicitedServiceUuids { get; }
  public int ManufacturerCompanyId { get; }
  public string ManufacturerData { get; }
  public byte[] ManufacturerDataB { get; }
  public bool IsConnectable { get; }
  public bool IsScanResponse { get; }
}

Public Event OnAdvertisement As OnAdvertisementHandler

Public Delegate Sub OnAdvertisementHandler(sender As Object, e As BLEClientAdvertisementEventArgs)

Public Class BLEClientAdvertisementEventArgs Inherits EventArgs
  Public ReadOnly Property ServerId As String
  Public ReadOnly Property Name As String
  Public ReadOnly Property RSSI As Integer
  Public ReadOnly Property TxPower As Integer
  Public ReadOnly Property ServiceUuids As String
  Public ReadOnly Property ServicesWithData As String
  Public ReadOnly Property SolicitedServiceUuids As String
  Public ReadOnly Property ManufacturerCompanyId As Integer
  Public ReadOnly Property ManufacturerData As String
  Public ReadOnly Property ManufacturerDataB As Byte()
  Public ReadOnly Property IsConnectable As Boolean
  Public ReadOnly Property IsScanResponse As Boolean
End Class

Remarks

The Advertisement event is fired each time an advertisement is received while the component is Scanning for servers to connect to. Based on the information in the advertisement, you can decide whether or not you wish to connect to the associated device (if it is connectable).

Not all of the parameters are relevant for all platforms. Additionally, since advertisement packets are somewhat flexible in their contents, it is not guaranteed that every parameter relevant to your platform will be populated for every advertisement. Please refer to the following table for descriptions of the parameters:

Setting the ServiceData configuration setting to any of the service UUIDs in the ServicesWithData parameter will return the associated data.

You can use the ManufacturerDataCount configuration setting to determine whether the advertisement contains multiple manufacturer data sections; if it does, the ManufacturerData and ManufacturerCompanyId configuration settings can be used to iterate over them.

Note that all of the configuration settings mentioned above are only valid while you are within the Advertisement event handler.

Please refer to the following table to determine which parameters are relevant for your platform:

Note: IsConnectable will always be false when IsScanResponse is true.

Refer to the StartScanning method for more information.

Connected Event (BLEClient Component)

Fired immediately after a connection to a remote device completes (or fails).

Syntax

• C#
• VB.NET

public event OnConnectedHandler OnConnected;

public delegate void OnConnectedHandler(object sender, BLEClientConnectedEventArgs e);

public class BLEClientConnectedEventArgs : EventArgs {
  public int StatusCode { get; }
  public string Description { get; }
}

Public Event OnConnected As OnConnectedHandler

Public Delegate Sub OnConnectedHandler(sender As Object, e As BLEClientConnectedEventArgs)

Public Class BLEClientConnectedEventArgs Inherits EventArgs
  Public ReadOnly Property StatusCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

If the connection is made successfully, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Bluetooth stack. Description contains a description of this code.

Refer to the Connect method for more information.

Disconnected Event (BLEClient Component)

Fired when the component has been disconnected from the remote device.

Syntax

• C#
• VB.NET

public event OnDisconnectedHandler OnDisconnected;

public delegate void OnDisconnectedHandler(object sender, BLEClientDisconnectedEventArgs e);

public class BLEClientDisconnectedEventArgs : EventArgs {
  public int StatusCode { get; }
  public string Description { get; }
}

Public Event OnDisconnected As OnDisconnectedHandler

Public Delegate Sub OnDisconnectedHandler(sender As Object, e As BLEClientDisconnectedEventArgs)

Public Class BLEClientDisconnectedEventArgs Inherits EventArgs
  Public ReadOnly Property StatusCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the Bluetooth stack. Description contains a description of this code.

Refer to the Disconnect section for more information.

Discovered Event (BLEClient Component)

Fired when the component discovers a service, characteristic, or descriptor.

Syntax

• C#
• VB.NET

public event OnDiscoveredHandler OnDiscovered;

public delegate void OnDiscoveredHandler(object sender, BLEClientDiscoveredEventArgs e);

public class BLEClientDiscoveredEventArgs : EventArgs {
  public int GattType { get; }
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string DescriptorId { get; }
  public string Uuid { get; }
  public string Description { get; }
}

Public Event OnDiscovered As OnDiscoveredHandler

Public Delegate Sub OnDiscoveredHandler(sender As Object, e As BLEClientDiscoveredEventArgs)

Public Class BLEClientDiscoveredEventArgs Inherits EventArgs
  Public ReadOnly Property GattType As Integer
  Public ReadOnly Property ServiceId As String
  Public ReadOnly Property CharacteristicId As String
  Public ReadOnly Property DescriptorId As String
  Public ReadOnly Property Uuid As String
  Public ReadOnly Property Description As String
End Class

Remarks

This event is fired during any discovery process to indicate that the component has discovered a service, characteristic, or descriptor. Discovery processes take place whenever Discover, DiscoverServices, DiscoverCharacteristics, or DiscoverDescriptors is called.

GattType indicates what type of GATT object was discovered:

• 0 - Service
• 1 - Characteristic
• 2 - Descriptor

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the discovered service, characteristic, or descriptor.

When a service is discovered:

• ServiceId is the Id of the newly discovered service.
• CharacteristicId is empty.
• DescriptorId is empty.

When a characteristic is discovered:

• ServiceId is the Id of the previously discovered service which owns the newly discovered characteristic.
• CharacteristicId is the Id of the newly discovered characteristic.
• DescriptorId is empty.

When a descriptor is discovered:

• ServiceId is the Id of the previously discovered service which owns the previously discovered characteristic.
• CharacteristicId is the Id of the previously discovered characteristic which owns the newly discovered descriptor.
• DescriptorId is the Id of the newly discovered descriptor.

Error Event (BLEClient Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, BLEClientErrorEventArgs e);

public class BLEClientErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As BLEClientErrorEventArgs)

Public Class BLEClientErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (BLEClient Component)

Fires once for each log message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, BLEClientLogEventArgs e);

public class BLEClientLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As BLEClientLogEventArgs)

Public Class BLEClientLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This events fires once for each log message generated by the component. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the Message. Possible values are:

The default log level, Info, provides information when most BLE operations begin and end, and should be sufficient to get a good idea of what the component is doing at a high level.

The Verbose log level adds a few extra operation timing messages, and adds more detail to some messages logged at the Info level.

The Debug log level causes the component to output as much information as possible about what it is doing at all times. All BLE communications, even those which are typically abstracted away by the API, are logged in full detail. Typically the additional information added by this log level is not helpful to the end user, and would only be necessary to capture if you wish to report an issue to the support team.

LogType identifies the type of log entry. Possible values are:

• Scanning: Messages relating to scanning and advertisements.
• Connection: Messages relating to connecting, disconnecting, and connection failures.
• Discovery: Messages relating to any service, characteristic, or descriptor discovery process.
• Read: Messages relating to reading values from the remote device.
• Write: Messages relating to writing values to the remote device.
• Subscriptions: Messages relating to subscribing to and unsubscribing from characteristics.
• Info, Verbose, and Debug: Miscellaneous messages fired at the applicable log level concerning internal component operations.

PairingRequest Event (BLEClient Component)

TBD.

Syntax

• C#
• VB.NET

public event OnPairingRequestHandler OnPairingRequest;

public delegate void OnPairingRequestHandler(object sender, BLEClientPairingRequestEventArgs e);

public class BLEClientPairingRequestEventArgs : EventArgs {
  public string ServerId { get; }
  public int PairingKind { get; }
  public string Pin { get; set; }
  public bool Accept { get; set; }
}

Public Event OnPairingRequest As OnPairingRequestHandler

Public Delegate Sub OnPairingRequestHandler(sender As Object, e As BLEClientPairingRequestEventArgs)

Public Class BLEClientPairingRequestEventArgs Inherits EventArgs
  Public ReadOnly Property ServerId As String
  Public ReadOnly Property PairingKind As Integer
  Public Property Pin As String
  Public Property Accept As Boolean
End Class

Remarks

TBD.

ServerUpdate Event (BLEClient Component)

Fired when the currently connected server updates its name or available services.

Syntax

• C#
• VB.NET

public event OnServerUpdateHandler OnServerUpdate;

public delegate void OnServerUpdateHandler(object sender, BLEClientServerUpdateEventArgs e);

public class BLEClientServerUpdateEventArgs : EventArgs {
  public string Name { get; }
  public string ChangedServices { get; }
}

Public Event OnServerUpdate As OnServerUpdateHandler

Public Delegate Sub OnServerUpdateHandler(sender As Object, e As BLEClientServerUpdateEventArgs)

Public Class BLEClientServerUpdateEventArgs Inherits EventArgs
  Public ReadOnly Property Name As String
  Public ReadOnly Property ChangedServices As String
End Class

Remarks

This event is fired under one of two conditions, both of which involve some sort of server-side change other than the value of a subscribed characteristic having changed (subscribed characteristic value updates are delivered through the Value event).

If the server's name has changed, this event is fired with the new name in the Name parameter, and the ServerName property is updated as well.

If the server's services have changed, this event is fired with a non-empty value in the ChangedServices parameter.

StartScan Event (BLEClient Component)

Fired when the component starts scanning.

Syntax

• C#
• VB.NET

public event OnStartScanHandler OnStartScan;

public delegate void OnStartScanHandler(object sender, BLEClientStartScanEventArgs e);

public class BLEClientStartScanEventArgs : EventArgs {
  public string ServiceUuids { get; }
}

Public Event OnStartScan As OnStartScanHandler

Public Delegate Sub OnStartScanHandler(sender As Object, e As BLEClientStartScanEventArgs)

Public Class BLEClientStartScanEventArgs Inherits EventArgs
  Public ReadOnly Property ServiceUuids As String
End Class

Remarks

This event is fired when the component starts scanning. ServiceUuids is a comma-separated list of 128-bit service UUIDs that the scan is being filtered by. Refer to the StartScanning method for more information.

StopScan Event (BLEClient Component)

Fired when the component stops scanning.

Syntax

• C#
• VB.NET

public event OnStopScanHandler OnStopScan;

public delegate void OnStopScanHandler(object sender, BLEClientStopScanEventArgs e);

public class BLEClientStopScanEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string ErrorDescription { get; }
}

Public Event OnStopScan As OnStopScanHandler

Public Delegate Sub OnStopScanHandler(sender As Object, e As BLEClientStopScanEventArgs)

Public Class BLEClientStopScanEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property ErrorDescription As String
End Class

Remarks

This event is fired when the component stops scanning. If the scanning stopped due to an error, the ErrorCode and ErrorDescription parameters will be set accordingly; otherwise they will be 0 and empty string. Refer to the StopScanning method for more information.

Subscribed Event (BLEClient Component)

Fired when the component has successfully subscribed to a characteristic.

Syntax

• C#
• VB.NET

public event OnSubscribedHandler OnSubscribed;

public delegate void OnSubscribedHandler(object sender, BLEClientSubscribedEventArgs e);

public class BLEClientSubscribedEventArgs : EventArgs {
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string Uuid { get; }
  public string Description { get; }
}

Public Event OnSubscribed As OnSubscribedHandler

Public Delegate Sub OnSubscribedHandler(sender As Object, e As BLEClientSubscribedEventArgs)

Public Class BLEClientSubscribedEventArgs Inherits EventArgs
  Public ReadOnly Property ServiceId As String
  Public ReadOnly Property CharacteristicId As String
  Public ReadOnly Property Uuid As String
  Public ReadOnly Property Description As String
End Class

Remarks

This event is fired when the component has successfully subscribed to a characteristic.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic.

Refer to the Subscribe method for more information.

Unsubscribed Event (BLEClient Component)

Fired when the component has successfully unsubscribed from a characteristic.

Syntax

• C#
• VB.NET

public event OnUnsubscribedHandler OnUnsubscribed;

public delegate void OnUnsubscribedHandler(object sender, BLEClientUnsubscribedEventArgs e);

public class BLEClientUnsubscribedEventArgs : EventArgs {
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string Uuid { get; }
  public string Description { get; }
}

Public Event OnUnsubscribed As OnUnsubscribedHandler

Public Delegate Sub OnUnsubscribedHandler(sender As Object, e As BLEClientUnsubscribedEventArgs)

Public Class BLEClientUnsubscribedEventArgs Inherits EventArgs
  Public ReadOnly Property ServiceId As String
  Public ReadOnly Property CharacteristicId As String
  Public ReadOnly Property Uuid As String
  Public ReadOnly Property Description As String
End Class

Remarks

This event is fired when the component has successfully unsubscribed from a characteristic.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic

Refer to the Unsubscribe method for more information.

Value Event (BLEClient Component)

Fired when a characteristic or descriptor value is received from the server.

Syntax

• C#
• VB.NET

public event OnValueHandler OnValue;

public delegate void OnValueHandler(object sender, BLEClientValueEventArgs e);

public class BLEClientValueEventArgs : EventArgs {
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string DescriptorId { get; }
  public string Uuid { get; }
  public string Description { get; }
  public string Value { get; }
  public byte[] ValueB { get; }
}

Public Event OnValue As OnValueHandler

Public Delegate Sub OnValueHandler(sender As Object, e As BLEClientValueEventArgs)

Public Class BLEClientValueEventArgs Inherits EventArgs
  Public ReadOnly Property ServiceId As String
  Public ReadOnly Property CharacteristicId As String
  Public ReadOnly Property DescriptorId As String
  Public ReadOnly Property Uuid As String
  Public ReadOnly Property Description As String
  Public ReadOnly Property Value As String
  Public ReadOnly Property ValueB As Byte()
End Class

Remarks

This event is fired to signify that a value has been received for a characteristic or descriptor. The DescriptorId parameter will be empty string if the value is for a characteristic.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic or descriptor.

There are three scenarios which can cause this event to fire:

• The server has responded to a read request for a characteristic.
• The server has responded to a read request for a descriptor.
• The server has sent an updated value for a subscribed characteristic.

Whenever a value is received for a characteristic or descriptor, the value that the platform has cached for it is updated as well. You can read the cached value for a characteristic using CachedValue, or for a descriptor using CachedValue.

Refer to the ReadValue and/or Subscribe methods for more information.

WriteResponse Event (BLEClient Component)

Fired when the server acknowledges a successful value write request.

Syntax

• C#
• VB.NET

public event OnWriteResponseHandler OnWriteResponse;

public delegate void OnWriteResponseHandler(object sender, BLEClientWriteResponseEventArgs e);

public class BLEClientWriteResponseEventArgs : EventArgs {
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string DescriptorId { get; }
  public string Uuid { get; }
  public string Description { get; }
}

Public Event OnWriteResponse As OnWriteResponseHandler

Public Delegate Sub OnWriteResponseHandler(sender As Object, e As BLEClientWriteResponseEventArgs)

Public Class BLEClientWriteResponseEventArgs Inherits EventArgs
  Public ReadOnly Property ServiceId As String
  Public ReadOnly Property CharacteristicId As String
  Public ReadOnly Property DescriptorId As String
  Public ReadOnly Property Uuid As String
  Public ReadOnly Property Description As String
End Class

Remarks

This event is fired when the server acknowledges a successful value write request for a characteristic or descriptor.

ServiceId holds the Id of the service.

CharacteristicId holds the Id of the characteristic.

DescriptorId holds the Id of the descriptor. This is only populated when a descriptor value is written.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic or descriptor.

Note that this event is not fired if the write request was sent using PostValue, regardless of the outcome.

Refer to the WriteValue method for more information.

Characteristic Type

A GATT characteristic.

Remarks

This type represents a GATT characteristic.

Fields

Constructors

• C#
• VB.NET

public Characteristic();

Public Characteristic()

Descriptor Type

A GATT descriptor.

Remarks

This type represents a GATT descriptor.

Fields

Constructors

• C#
• VB.NET

public Descriptor();

Public Descriptor()

Service Type

A GATT service.

Remarks

This type represents a GATT service.

Fields

Constructors

• C#
• VB.NET

public Service();

Public Service()

Config Settings (BLEClient Component)

BLEClient Config Settings

Base Config Settings

Trappable Errors (BLEClient Component)

BLEClient Errors