iOS Guides | Samples

MonoTouch.CoreBluetooth Namespace

APIs to interact with Bluetooth devices.

Remarks

The CoreBluetooth namespace allows developers to work with Bluetooth Low Energy (Bluetooth LE) devices.

The Bluetooth LE model revolves around CBPeer objects. There are two kinds of CBPeer: CBCentral objects that scan and consume data provided by CBPeripheral objects that correspond to data-providing Bluetooth LE devices.

Generally, the iOS device will be in the CBCentral role, but it is also possible to create apps in which the device is a CBPeripheral.

The following example shows the typical initialization behavior of an app that consumes data from external Bluetooth LE devices. Applications that have a CBCentral must have an associated CBCentralManagerDelegate delegate object and must override it's CBCentralManagerDelegate.UpdatedState method. The override must check the state of the CBCentralManager and confirm that it is CBCentralManagerState.PoweredOn.

Typically, applications will want to scan for Bluetooth LE peripherals. This is a high-energy function, so developers should call CBManager.StopScan after finding the CBPeripheral in which they are interested or after a certain amount of time.

C# Example

public class MySimpleCBCentralManagerDelegate : CBCentralManagerDelegate
{
		override public void UpdatedState (CBCentralManager mgr)
		{
			if (mgr.State == CBCentralManagerState.PoweredOn) {
				//Passing in null scans for all peripherals. Peripherals can be targeted by using CBUIIDs
				CBUUID[] cbuuids = null;
				mgr.ScanForPeripherals (cbuuids); //Initiates async calls of DiscoveredPeripheral
				//Timeout after 30 seconds
				var timer = new Timer (30 * 1000);
				timer.Elapsed += (sender, e) => mgr.StopScan();
			} else {
				//Invalid state -- Bluetooth powered down, unavailable, etc.
				System.Console.WriteLine ("Bluetooth is not available");
			}
		}

		public override void DiscoveredPeripheral (CBCentralManager central, CBPeripheral peripheral, NSDictionary advertisementData, NSNumber RSSI)
		{
			Console.WriteLine ("Discovered {0}, data {1}, RSSI {2}", peripheral.Name, advertisementData, RSSI);
		}
}    

public partial class HelloBluetoothCSharpViewController : UIViewController
{
    MySimpleCBCentralManagerDelegate myDel;

		public override void ViewDidLoad ()
		{
			base.ViewDidLoad ();
			
      //Important to retain reference, else will be GC'ed
			myDel = new MySimpleCBCentralManagerDelegate ();
			var myMgr = new CBCentralManager (myDel, DispatchQueue.CurrentQueue);

		}
//...etc... 
}

The CBCentralManagerDelegate.DiscoveredPeripheral method may be called multiple times for a single physical device. Once application developers have a reference to the CBPeripheral in which they are interested, they should maintain that reference for further work and call CBCentralManager.StopScan.

With a reference to a discovered CBPeripheral, developers can then connect to it, as shown in the following example.

A CBPeripheral has zero or more CBServices, each of which has zero or more CBCharacteristics. If the characteristic represents a measurement (such as a heartbeat, time, temperature, etc.), the value will be in the CBCharacteristic.Value property.

C# Example

public class SimplePeripheralDelegate : CBPeripheralDelegate
{
	public override void DiscoveredService (CBPeripheral peripheral, NSError error)
	{
		System.Console.WriteLine ("Discovered a service");
		foreach (var service in peripheral.Services) {
			Console.WriteLine (service.ToString ()); 
			peripheral.DiscoverCharacteristics (service);
		}
	}

	public override void DiscoveredCharacteristic (CBPeripheral peripheral, CBService service, NSError error)
	{
		System.Console.WriteLine ("Discovered characteristics of " + peripheral);
		foreach (var c in service.Characteristics) {
			Console.WriteLine (c.ToString ());
			peripheral.ReadValue (c);
		}
	}

	public override void UpdatedValue (CBPeripheral peripheral, CBDescriptor descriptor, NSError error)
	{
		Console.WriteLine ("Value of characteristic " + descriptor.Characteristic + " is " + descriptor.Value);
	}

	public override void UpdatedCharacterteristicValue (CBPeripheral peripheral, CBCharacteristic characteristic, NSError error)
	{
		Console.WriteLine ("Value of characteristic " + characteristic.ToString () + " is " + characteristic.Value);
	}
}

//...
mgr = new CBCentralManager (myCentralDelegate, DispatchQueue.CurrentQueue);

mgr.ConnectedPeripheral += (s, e) => {
	activePeripheral = e.Peripheral;
	System.Console.WriteLine ("Connected to " + activePeripheral.Name);

  
	if (activePeripheral.Delegate == null) {
		activePeripheral.Delegate = new SimplePeripheralDelegate ();
    //Begins asynchronous discovery of services
		activePeripheral.DiscoverServices ();
	}
};

//Connect to peripheral, triggering call to ConnectedPeripheral event handled above 
mgr.ConnectPeripheral (myPeripheral);

Classes

TypeReason
CBAdvertisementKeys used to lookup dictionary values from the NSDictionary received as a parameter in CBCentralManagerDelegate.DiscoveredPeripheral.
CBATTErrorErrors returned by a GATT server.
CBATTRequestAn Attribute Protocol request for reading or writing.
CBATTRequestEventArgsProvides data for the CBATTRequestEventArgs.ReadRequestReceived event.
CBATTRequestsEventArgsProvides data for the CBATTRequestsEventArgs.WriteRequestsReceived event.
CBAttributeClass that uniquely identifies a Bluetooth device.
CBAttributePermissionsEnumerates the read, write, and encryption permissions for a characteristic's values.
CBCentralUsed to identify centrals (that are not the current device).
CBCentralInitOptionsContains options for initializing a Bluetooth central manager.
CBCentralManagerRepresents the local central device in Bluetooth LE.  Use the CBCentralManager to scan, discover and connect to remote peripherals.
CBCentralManagerDelegateDelegate objects for CBCentralManager objects.
CBCentralManagerDelegate_ExtensionsExtension methods to the ICBCentralManagerDelegate interface to support all the methods from the CBCentralManagerDelegate protocol.
CBCentralManagerStateEnumerates possible states of a CBCentralManager.
CBCharacteristicCharacteristics of a remote peripheral.
CBCharacteristicEventArgsProvides data for the CBCharacteristicEventArgs.DiscoveredDescriptor, CBCharacteristicEventArgs.UpdatedCharacterteristicValue, CBCharacteristicEventArgs.UpdatedNotificationState and CBCharacteristicEventArgs.WroteCharacteristicValue events.
CBCharacteristicPropertiesThe possible properties of a characteristic. A characteristic may have multiple properties.
CBCharacteristicWriteTypeEnumerates the possible types of writes to a characteristic's value.
CBDescriptorAn immutable description of a peripheral's characteristic. See also CBMutableDescriptor.
CBDescriptorEventArgsProvides data for the CBDescriptorEventArgs.UpdatedValue and CBDescriptorEventArgs.WroteDescriptorValue events.
CBDiscoveredPeripheralEventArgsProvides data for the CBDiscoveredPeripheralEventArgs.DiscoveredPeripheral event.
CBErrorErrors possible during Bluetooth LE transactions.
CBMutableCharacteristicA mutable CBCharacteristic.
CBMutableDescriptorA mutable CBDescriptor.
CBMutableServiceA mutable CBService.
CBPeerClass that represents a central or perhipheral Bluetooth device.
CBPeripheralRepresents a CoreBluetooth peripheral.
CBPeripheralDelegateDelegate object for CBPeripheral. Provides methods called on events relating to discovery, exploration, and interaction with a remote peripheral.
CBPeripheralDelegate_ExtensionsExtension methods to the ICBPeripheralDelegate interface to support all the methods from the CBPeripheralDelegate protocol.
CBPeripheralErrorEventArgsProvides data for the CBPeripheralErrorEventArgs.DisconnectedPeripheral and CBPeripheralErrorEventArgs.FailedToConnectPeripheral events.
CBPeripheralEventArgsProvides data for the CBPeripheralEventArgs.ConnectedPeripheral event.
CBPeripheralManagerManages published services per the CBPeripheral device's GATT database.
CBPeripheralManagerAuthorizationStatusEnumerates the possible states of the CBPeripheralManager.
CBPeripheralManagerConnectionLatencyThe connection latency of the CBPeripheralManager.
CBPeripheralManagerDelegateDelegate object for CBPeripheralManager. Adds methods for events relating to availability, publishing, advertising, and subscription.
CBPeripheralManagerDelegate_ExtensionsExtension methods to the ICBPeripheralManagerDelegate interface to support all the methods from the CBPeripheralManagerDelegate protocol.
CBPeripheralManagerServiceEventArgsProvides data for the CBPeripheralManagerServiceEventArgs.ServiceAdded event.
CBPeripheralManagerStateEnumerates the possible states of the CBPeripheralManager.
CBPeripheralManagerSubscriptionEventArgsProvides data for the CBPeripheralManagerSubscriptionEventArgs.CharacteristicSubscribed and CBPeripheralManagerSubscriptionEventArgs.CharacteristicUnsubscribed events.
CBPeripheralServicesEventArgsProvides data for the CBPeripheralServicesEventArgs.ModifiedServices event.
CBPeripheralsEventArgsProvides data for the CBPeripheralsEventArgs.RetrievedConnectedPeripherals and CBPeripheralsEventArgs.RetrievedPeripherals events.
CBPeripheralStateEnumerates the possible connection states of a CBPeripheral.
CBRssiEventArgsProvides data for the CBRssiEventArgs.RssiRead event.
CBServiceRepresents the services of a remote peripheral.
CBServiceEventArgsProvides data for the CBServiceEventArgs.DiscoverCharacteristic, CBServiceEventArgs.DiscoveredCharacteristic and CBServiceEventArgs.DiscoveredIncludedService events.
CBUUIDUniversal Unique Identifiers for the Bluetooth stack.
CBWillRestoreEventArgsProvides data for the CBWillRestoreEventArgs.WillRestoreState and CBWillRestoreEventArgs.WillRestoreState events.
ICBCentralManagerDelegateInterface representing the required methods (if any) of the protocol CBCentralManagerDelegate.
ICBPeripheralDelegateInterface representing the required methods (if any) of the protocol CBPeripheralDelegate.
ICBPeripheralManagerDelegateInterface representing the required methods (if any) of the protocol CBPeripheralManagerDelegate.
PeripheralConnectionOptionsPeripheral connection options.
PeripheralScanningOptionsPossible values for the options parameter in calls to CBCentralManager.ScanForPeripherals.
StartAdvertisingOptionsManages access to options used by CoreBluetooth.StartAdvertising method.