observe

Observes changes to the specified Characteristic.

If characteristic was created via characteristicOf then the first found characteristic with a property of notify or indicate and matching service UUID and characteristic UUID will be used. If multiple characteristics with the same UUID and either notify or indicate property exist in the GATT profile, then a discovered characteristic from services should be used instead.

When using characteristicOf, observations can be setup (observe can be called) prior to a connection being established. Once connected, the observation will automatically start emitting changes. If connection is lost, Flow will remain active, once reconnected characteristic changes will begin emitting again.

If characteristic has a Client Characteristic Configuration descriptor (CCCD), then based on bits in the characteristic properties, observe will be configured (CCCD will be written to) as notification or indication (if characteristic supports both notifications and indications, then only notification is used).

While the peripheral is fully connected, failures related to observations are propagated via the returned observe, for example, if the specified characteristic is invalid or cannot be found then returned Flow terminates with a NoSuchElementException. An ObservationExceptionHandler may be registered with the Peripheral to control which failures are propagated through (and terminate) the observation Flow. When registered, only exceptions thrown from the ObservationExceptionHandler are propagated (and terminate) the returned observation Flow. See PeripheralBuilder.observationExceptionHandler for more details.

However, failures related to observations that occur during connection are treated differently. Instead of propagating through the Flow or the ObservationExceptionHandler, the exception is thrown from connect and the connection attempt fails, leaving this peripheral in the disconnected state.

The optional onSubscription parameter is functionally identical to using the onSubscription operator on the returned Flow except it has the following special properties:

• It will be executed whenever connection is established (while the returned Flow is active); and

• It will be executed after the observation is spun up (i.e. after enabling notifications or indications)

The onSubscription action is useful in situations where an initial operation is needed when starting an observation (such as writing a configuration to the peripheral and expecting the response to come back in the form of a characteristic change). The onSubscription is invoked for every new subscriber; if it is desirable to only invoke the onSubscription once per connection (for the specified characteristic) then you can either use the shareIn Flow operator on the returned Flow, or call observe again with the same characteristic and without specifying an onSubscription action.

If multiple observations are created for the same characteristic but with different onSubscription actions, then the onSubscription actions will be executed in the order in which the returned Flows are subscribed to.