Migration Notes
Update to version 15.0.0
Database improved
With this major update the database logic has been extended. This was necessairy to allow storage of cached service tables (see below). To keep compatibility with existing applications multiple formats for the database are supported now.
| Database Format | Bond Data | Attribute Caching in Bondings | Hash based Attribute Caching | Description |
|---|---|---|---|---|
| Record | Yes | No | No | Old format of Arendi.Bluetooth libraries based on key value lines |
| Bond | Yes | No | No | Old format of Arendi.BleLibrary libraries based on json records |
| Json | Yes | Yes | Yes | New format that should replace both old formats |
Databases now need to be cretaed by the new DatabaseFactory. There the format and database options can be passed. The options also allow enabling the convertion of old files into the new file format (only supported for the new format).
It is still possible to create a database implementation without storage backend by a dedicated method of the DatabaseFactory. In that case all data types are aupported, but not stored permanently.
GATTC Attribute Caching
This release brings support for attribute caching. When the database supports it a read service table is stored in the device data or in database hash records.
If a device has a bonding for the connected peer the read service table is stored in the device data (if supported by the database).
When there is no bonding, but the peer device has the Database Hash characteristic in the Generic Attribute service the service table can be stored hash based service table cache. On discovery a dedicated read to the database hash is made. If the read database hash is found in the database the service table can be restored from cache.
The method IGattc.ServiceDiscovery was extended with a variant that allows providing the allows sources for the discovery. The old method will allow discovery from any supported source.
The service discovery sources are (in descending priority):
| Service Discovery Source | Description |
|---|---|
| Bonding Data | Service table is loaded from device data. |
| Service Table Cache | Service table is loaded from hash based service table cache. |
| Full Discovery | Service table is read out from peer device. |
Optional GATTS Robust Caching support (HCI adapter only)
For HCI adapters it is now possible to activate robust caching. This adds the Database Hash characteristic and the Client Supported Features characteristic to the Generic Attribute service. The database hash value will be updated on every change of the GATT server attributes. The bonded client can activate "Robust Caching" by writing the corresponding bit to the Client Supported Features characteristic.
The robust caching is enabled by default.
16-bit UUID's from Assigned Numbers provided
The Bluetooth Assigned Numbers document defines a lot of 16-bit UUID's. To prevent the need to create all these UUID objects the AssignedNumbers class now provides various of these UUID's to you. For example the Generic Attribute service UUID can be found at AssignedNumbers.Uuids.Services.GenericAttribute.
Dropped .NET Framework 4.5 support
As .NET Framework ist out of support by Microsoft since years we decided to lift up the minimal .NET framework version to 4.7.2.
API Changes
Arendi.Bluetooth.Adapter.IAdapter
Old |
New |
|---|---|
DeviceDatabase: IDeviceDatabase |
Database: IDatabase |
AdvertisingTimeout |
AdvertisingTerminated |
Arendi.Bluetooth.Adapter.IConnection
Old |
New |
|---|---|
AuthenticationRequestAccept(bool bond, bool mitm, bool lesc, IoCapabilities ioCaps, AuthenticationOptions options): void |
AuthenticationRequestAccept(bool bond, bool mitm, bool lesc, IoCapabilities ioCaps): void |
- |
Encrypt(IDeviceRecord deviceRecord, CancellationToken cancellationToken): void |
- |
EncryptAsync(IDeviceRecord deviceRecord, CancellationToken cancellationToken) : Task |
Arendi.Bluetooth.Adapter.IGattc
Old |
New |
|---|---|
- |
ServiceDiscovery(ServiceDiscoverySources sources, CancellationToken cancellationToken): IGattcServiceTable |
- |
ServiceDiscoveryAsync(ServiceDiscoverySources sources, CancellationToken cancellationToken): Task<IGattcServiceTable> |
- |
Indication: EventHandler<GattcCharacteristicIndicationEventArgs> |
- |
Notification: EventHandler<GattcCharacteristicNotificationEventArgs> |
Arendi.Bluetooth.Adapter.IGattcServiceTable
Old |
New |
|---|---|
Find(Uuid uuid): IGattcService |
FindService(Uuid uuid): IGattcService |
- |
FindService(string uuid): IGattcService |
Arendi.Bluetooth.Adapter.IGattcService
Old |
New |
|---|---|
Find(Uuid uuid): IGattcCharacteristic |
FindCharacteristic(Uuid uuid): IGattcCharacteristic |
- |
FindCharacteristic(string uuid): IGattcCharacteristic |
Arendi.Bluetooth.Adapter.IGattcCharacteristic
Old |
New |
|---|---|
Find(Uuid uuid): IGattcDescriptor |
FindDescriptor(Uuid uuid): IGattcDescriptor |
- |
FindDescriptor(string uuid): IGattcDescriptor |
Arendi.Bluetooth.Adapter.IGatts
Old |
New |
|---|---|
Add(Uuid uuid): IGattsService |
AddService(Uuid uuid): IGattsService |
Find(Uuid uuid): IGattsService |
FindService(Uuid uuid): IGattsService |
- |
FindService(string uuid): IGattsService |
Arendi.Bluetooth.Adapter.IGattsService
Old |
New |
|---|---|
Add(Uuid uuid, CharacteristicProperties properties, ConnectionSecurity readPermission, ConnectionSecurity writePermission, byte[] initialValue, int maxValueLength): IGattsCharacteristic |
- |
Add(Uuid uuid, CharacteristicProperties properties, ConnectionSecurity readPermission, ConnectionSecurity writePermission, string userDescription, CharacteristicPresentationFormat presentationFormat, byte[] initialValue, bool isVariableLength, int maxValueLength): IGattsCharacteristic |
AddCharacteristic(Uuid uuid, CharacteristicProperties properties, AttPermissions permissions, string userDescription, CharacteristicPresentationFormat presentationFormat, byte[] initialValue, bool isVariableLength, int maxValueLength): IGattsCharacteristic |
- |
AddIncludedService(IGattsService service): IGattsIncludedService |
Find(Uuid uuid): IGattsCharacteristic |
FindCharacteristic(Uuid uuid): IGattsCharacteristic |
- |
FindCharacteristic(string uuid): IGattsCharacteristic |
- |
HandleDeclaration: UInt16 |
- |
LastHandle: UInt16 |
Arendi.Bluetooth.Adapter.IGattsCharacteristic
Old |
New |
|---|---|
Add(Uuid uuid, CharacteristicProperties properties, ConnectionSecurity readPermission, ConnectionSecurity writePermission, byte[] initialValue, bool isVariableLength, int maxValueLength): IGattsDescriptor |
AddDescriptor(Uuid uuid, CharacteristicProperties properties, AttPermissions permissions, byte[] initialValue, bool isVariableLength, int maxValueLength): IGattsDescriptor |
Find(Uuid uuid): IGattsDescriptor |
FindDescriptor(Uuid uuid): IGattsDescriptor |
- |
FindDescriptor(string uuid): IGattsDescriptor |
- |
HandleDeclaration: UInt16 |
ReadPermission: ConnectionSecurity |
Permissions: AttPermissions |
Arendi.Bluetooth.Adapter.IGattsDescriptor
Old |
New |
|---|---|
- |
GetValue(IConnection connection): byte[] |
- |
HandleDeclaration: UInt16 |
ReadPermission: ConnectionSecurity |
Permissions: AttPermissions |
Update to version 14.0.0
Adapter API changes for advertising
Because of the new support for extended advertising a change in the API of the adapter was necessairy.
To initiat an advertisng the SetAdvertisingParameter method must be called first. Then the advertising data and/or scan data may be set with SetAdvertsingData method. Be aware that depending on the advertising type not both data types are allowed. With StartAdvertising/StopAdvertising the advertising can be started and stopped. It is allowed to change the data while the advertising is enabled.
Adapter API changes for scan
A new variant of the method StartScan has ben added. It allows to set new options that have been added by the support for extended scanning.
Adapter API changes for connect
To support connect of extended advertisings on other phys than the 1Mbps phy a new Connect method is added. It has an additional parameter that allows to set the initiating phys.
The previously available retires parameter has been removed. The connect logic will do retries till the given connect timeout elapses when acknowledger is activated.
Update to version 13.0.0
Full .NET8 support
With the release 13.0.0 the Nuget packages contain builds for "net8.0" (and sometimes "net8.0-windows"). These new builds come in addition to the existing ones.
Update to version 12.2.0
Full .NET7 support
With the release 12.2.0 the Nuget packages contain builds for "net7.0" (and sometimes "net7.0-windows"). These new builds come in addition to the existing ones.
Update to version 12.0.0
The release 12.0.0 brings a lot of improvements that shows up in Bluetooth PTS tests. May tests showed that some aspects of the full specification where not fully covered by the current adapter API. These new changes come as breaking changes and are not compatible with the version 11.x anymore.
Adapter Scan API changes
The scan for devices has new support to set the discovery mode. The previous implementation was allways scanning in an inofficial 'Observation' mode without any filtering. To get the same behavior as before the new StartScan method may be used with the discovery mode 'Observation'. By using the official modes 'General' and 'Limited' the results are filted based on the flags in the advertising of the devices.
GATT server API changes
The GATT server API now supports descriptors in the characteristics. The new Add method of the GATT server provides already an option to set the most common descriptors as user description and presentation format.
GATT client API changes
Also on the GATT client API the descriptors have been added.
Authentication API changes
The mechanic for authentication has changed to fit for more use cases.
As central previously the ServiceRequest was expcected to be answered with a call of Authenticate oder Encrypt. New this has been changed and the ServiceRequest event needs to be answered by calling SecurityRequestAccept to authenticate or encrypt or SecurityRequestReject to reject the request by the peripheral.
As peripheral the event AuthenticationParameterRequest has been renamed to AuthenticationRequest. To respond to this event the method AuthenticationRequestAccept or AuthenticationRequestReject needs to be called.
The API new also supports some options for the authentication. With these options currently the requirement for MITM or LESC can be configured to an authentication process. These options need to be provided as argument of AuthenticationRequestAccept (peripheral role), Authenticate (master role) or SecurityRequestAccept (master role).
Adapter Constructor and AdapterFactory changed
The adapter implementations for Connectivity and HCI have a changed constructor that takes an option object for configuration values. Therefor the initialization code needs to be adapted to thes changes.
Update to version 11.0.0
Full .NET6 support
With the release 11.0.0 the Nuget packages contain builds for "net6.0" (and sometimes "net6.0-windows"). These new builds come in addition to the existing ones. Till now it was also possible to use the libraries on .NET6 projects with the "netstandard 2.0" builds, but the "net6.0" packages make sense as they are more optimized and often faster by using .NET6 enhancements.
Suggested default data length must now be set manually
The HCI adapter previously set the suggested data length in the HCI controller to the maximal supported value. As this is not always the wanted behavior the suggested data length must since version 11.0.0 be set manually. To reach the same behavior as before you may add the following line after the HCI adapter was generated.
hciAdapter.SetSuggestedDefaultDataLength(hciAdapter.MaximumDataLength.MaxSupportedTxOctets);
Even if the method SetSuggestedDefaultDataLength is part of the IAdapter interface it must be kept in mind that not all adapter or controller support this feature:
- Nordic adapter don't support a default data length. They will throw a NotSupportedException if the method is called.
- The HCI adapter supports this method if the controller has data length extension, but some controllers ignore the setting that is provided and don't initiate the suggested data length after connection establish.
Update to version 10.0.0
Enhanced Connectivity Classes Removed
The Enhanced classes from the Namespace Arendi.Bluetooth.Connectivity.SXXvY.Enhanced have been removed with this release. Since the introduction of the Connectivity Adapter library these classes have been obsolete as the new library provides the same functions in a more general way. The API is a bit different, but is built based on the same logic. The advantage of the adapter libraries is that this library is tested by a SystemTest and the interface is shared between the adapter for HCI adapters.
For a migration from the Enhanced classes to the Adapter classes the most important thing to know is that the Device class is now the Adapter class. For more information a closer look to the examples is recommended.
Update to version 9.4.0
Toolbox Package
AdapterFactory The creation for the adapters have always be a complex thing as there are many layers that have to be initialized one by one. The new introduced Arendi.Bluetooth.Toolbox package provides an AdapterFactory with methods to create the adapter with one call. All create functions have optional options that can be provided to cusomize the behavior of the adapter. The examples have to be modified to use the AdapterFactory to show a simple initialisation.
KeyManager To simplify the unlock of the libaries if you own a license key that includes multiple adapters a new method has been added that unlocks all libraries at once:
- Arendi.Bluetooth.Toolbox.KeyManager.Unlock
HID library changed
With this release we replaced the previously used HID library HidSharp with the Hid.Net library. The reason for this change is that the HidSharp project is abandoned quite a long time. Even proposed bugfixes have not been integrated. The tests with the newly used Hid.Net library have all passed and also the performance looked equal to the HidSharp library.
Update to version 9.1.0
API-Changes
In the API there have been made some changes to get a more consistent naming scheme.
- RemoteParameterUpdateRequestNegativeReply changes to RemoteParameterUpdateRequestReject
- RemoteParameterUpdateRequestReply changes to RemoteParameterUpdateRequestAccept
Update to version 9.0.0
License Check
With the update to the version 9.0.0 of the Bluetooth.Net libraries a license is required for continuous use of the Hci and/or Connectivity libraries. Without a valid key the libraries runs for two minutes in evaluation mode.
Note: Owner of a valid license for the Connectivity/Hci variant of the BleLibrary may use the same license key to unlock these libraries.
Note: Using the BLT2450 Tester is still possible without a valid license as it has a hardware bundled license.
To unlock call the corresponding functions with a valid key:
- Arendi.Bluetooth.Hci.KeyManager.Unlock
- Arendi.Bluetooth.Connectivity.S132v5.KeyManager.Unlock
- Arendi.Bluetooth.Connectivity.S132v7.KeyManager.Unlock
- Arendi.Bluetooth.Connectivity.S140v7.KeyManager.Unlock
To obtain a license contact the sales department of Arendi AG (www.arendi.ch).
.NET Standard 2.0 Support
With this release we start to provide the libraries also as .NET Standard 2.0 build. If you are using the NuGet packages you shouldn't need to be aware of what version you need. It will automatically take the right one for you.
Update Hci to version 3.0.0 (Hci Libraries)
Transport Packages
With the update to version 3.0.0 the library was split up into the core component and the transport components for HCI over USB and HCI over UART. You may need to add a reference for the new Arendi.Bluetooth.Hci.Usb or Arendi.Bluetooth.Hci.Uart libraries.
Update to version 8.0.0 (Connectivity Libraries)
Changed References
With the update to version 8.0.0 the referenced library Arendi.DotNETLibrary was updated to version 5.x. As the Arendi.DotNETLibrary 4.x is not compatible with the Arendi.DotNETLibrary 5.x some references need to be updated in libraries and applications using the connectivity library.
| Current Reference | New Reference |
|---|---|
| Arendi.DotNETLibrary 4.x | Arendi.DotNETLibrary 5.x |
| Arendi.DotNETLibrary.Windows 4.x | Arendi.DotNETLibrary.Log.log4net 5.x *Arendi.DotNETLibrary.Serial.Comport 5.x *Arendi.DotNETLibrary.Serial.HidSharp 5.x *Arendi.DotNETLibrary.Console 5.x *only if required |
| Arendi.DotNETLibrary.Android 4.x | Arendi.DotNETLibrary.Log.Android 5.x |
| Arendi.DotNETLibrary.iOS 4.x | Arendi.DotNETLibrary.Log.iOS 5.x |