Acting as a Central
In this section we describe how to operate as a central and scan, read, write and subscribe to peripherals.
Here you will be shown how to:
- Discovering Peripherals
- Connecting to a Peripheral
- Discovering Services and Characteristics of a Connected Peripheral
- Retrieving the Value of a Characteristic
- Subscribing to a Characteristic
- Unsubscribing from a Characteristic
- Writing the Value of a Characteristic
The most common first task for a central is to scan for advertising peripherals.
As advertising is the main way peripherals announce their presence. You can discover
any advertising peripherals by starting a scan using the
Then when peripherals are discovered you will receive the
Most likely in a real world situation you would provide the first parameter to the
scanForPeripherals function. This first parameter is an array of service uuids which
should be scanned for as generally you are wanting to discover devices with a certain feature
/ service. If you do not provide it (as in the above example) then all discovered peripherals
will be returned.
Connecting to a Peripheral
Once you have discovered a peripheral and made the decision to interact with it you will need
to connect to the peripheral. When connecting you need to use an object retrieved through a
discovered event, passing it to the
The connect function may then cause several events to be dispatched:
PeripheralEvent.CONNECT: when connection was successfully made
PeripheralEvent.CONNECT_FAIL: when the connection failed
PeripheralEvent.DISCONNECT: this may be dispatched later (after a connect event) if the connection is left idle.
Discovering Services and Characteristics of a Connected Peripheral
After you have established a connection to a peripheral, you can begin to explore its data.
The first step in exploring what a peripheral has to offer is discovering its available services.
To do this you add listeners to the
Peripheral object and call
scanForPeripherals the discovery process can take an array of uuids to limit the
services returned to be services of interest to your application. The following example uses
the default of an empty array to discover all avaliable services of the peripheral
When this process completes successfully the
PeripheralEvent.DISCOVER_SERVICES will be
dispatched with a Peripheral object that contains a populated
Peripheral.services array of
Each service contains a list of
Characteristics. You can consider a
Characteristic as a data value,
which has properties, permissions and a value represented as a
ByteArray. Similarly to services
you can discover the Characteristics of a
Service on a
Peripheral by calling the
discoverCharacteristics function. This function similarly dispatches the
PeripheralEvent.DISCOVER_CHARACTERISTICS event when completed.
In the following snippet we discover all of the available services on a previously connected Peripheral and then proceed to discover the characteristics of the first service.
Then in the event handler lets iterate through the services and discover the characteristics of the first available Service.
Retrieving the Value of a Characteristic
A characteristic contains a single value that represents more information about a peripheral's service. For example, a temperature measurement characteristic of a health thermometer service may have a value that indicates a temperature in Celsius. You can retrieve the value of a characteristic by reading it directly or by subscribing to it.
After you have found a characteristic of a service that you are interested in, you can read the
characteristic's value by calling the
readValueForCharacteristic and waiting for the
Subscribing to a Characteristic
Though reading the value of a characteristic using the
readValueForCharacteristic method can be
effective for some use cases, it is not the most efficient way to retrieve a value that changes.
For most characteristic values that change—for instance, your heart rate at any given time — you
should retrieve them by subscribing to them. When you subscribe to a characteristic's value, you
receive an event from the peripheral when the value changes.
You can subscribe to the value of a characteristic that you are interested in by calling the
subscribeToCharacteristic function and passing the characteristic you are interested in. When you
attempt to subscribe to a characteristic's value, the
CharacteristicEvent.SUBSCRIBE event will
be dispatched indicating you will now receive
CharacteristicEvent.UPDATE events whenever the
value of the Characteristic changes. If the subscription request fails for any reason the
CharacteristicEvent.SUBSCRIBE_ERROR will be dispatched.
After you have successfully subscribed to a characteristic's value, the peripheral device
notifies your app when the value has changed. Each time the value changes the
CharacteristicEvent.UPDATE event will be dispatched.
Once subscribed you will start receiving update events:
Unsubscribing from a Characteristic
If you wish to later unsubscribe from a characteristic you can call the
with the same
Characteristic and the
CharacteristicEvent.UNSUBSCRIBE will be dispatched when
this is completed.
Writing the Value of a Characteristic
For some use cases, it makes sense to write the value of a characteristic. If a characteristic's
value is writeable, you can write its value with some data (a ByteArray) by calling
writeValueForCharacteristic function on a
Peripheral and providing the
write and the new value.
You will receive either a success or an error event:
Characteristics may only allow certain types of writes to be performed on their value.
To determine which types of writes are permitted to a characteristic's value, you access
the relevant properties of the
Characteristic.properties array. The possible values are
defined in the