btleServiceConnect()
This function connects to the given bluetooth service.
Synopsis
int btleServiceConnect(string address, string serviceUUID [, string|function_ptr callback]);
Parameters
| Parameter | Description |
|---|---|
| address | The device address. |
| serviceUUID | The uuid of the service |
| callback | The optional callback function that can be started. |
Return Value
The return value is an internal handler Id to this connection which must be used in the corresponding btleServiceDisconnect() call, or -1 on error.
Description
The function connects to the service given via the serviceUUID of the device at given address (which must have been opened via btleOpen()).
The optional callback function is started whenever a state change or error happens or when a characteristic of the service changes. The callback must have one argument of type mapping (e.g.: callback(mapping map) { ... } ) The mapping passed to the callback will have the following keys:
| callback mapping | |||
| "serviceId" (int) | the handle representing this service connection (the return value of btleServiceConnect()) | ||
| "reason" (string) |
This key is always present. It specifies why the callback has been started. It can be one of the following: |
||
| "stateChange" | An Error occurred. The type of error is available in the key "error"(see below). | ||
| "stateChange" | The state was changed. The state is available in the key "state" (see below). | ||
| "valueChanged" | This is triggered when the value of characteristic is changed by an event on the peripheral/device side. In that case, the value emission implies that change notifications must have been activated via the characteristic's ClientCharacteristicConfiguration descriptor prior to the change event on the peripheral. This is done by btleDescriptoeWrite() using the descriptor uuid with type == 0x2902, writing a value of 0x0100. See Bluetooth Characteristic Configuration The value of the characteristic is given in a mapping via the key "characteristic" (see below) | ||
| In case the callback was triggered by a state change, the key "state" is added: | |||
| "state" (string) | Can take one of the following values | ||
| "Invalid" | A service can become invalid when it looses the connection to the underlying device. Even though the connection may be lost it retains its last information. | ||
| "DiscoveryRequired" | The service details are yet to be discovered. | ||
| "DiscoveringServices" | The service details are being discovered. | ||
| "ServiceDiscovered" | The service details have been discovered. | ||
| When "state" is "ServiceDiscovered" the key "Characteristics" (dyn_mapping) will be available: | |||
| "Characteristics"/ (dyn_mapping) |
When "state" is "ServiceDiscovered" each entry of the dyn_mapping describes one of the discovered characteristics. Each mapping of a characteristic has the following keys: |
||
| "uuid" (string) | The UUID of the characteristic. | ||
| "name" (string) | The human-readable name of the characteristic. The name is based on the characteristic's uuid() which must have been standardized. The complete list of characteristic types can be found under Gatt Characteristics. The string is empty if the uuid is unknown. | ||
| "valid" (bool) | This is "false", if the associated service is no longer valid due to a disconnect from the underlying Bluetooth Low Energy device. | ||
| "value" (blob) | The cached value of the characteristic. always remains empty if the characteristic does not have read permission. | ||
| "properties" (uint) | A combination of the values found here. | ||
| "descriptors" (dyn_mapping) | A dyn_mapping which itself includes a list of descriptors belonging to this characteristic. Each mapping in this list has the following keys: | ||
| "name" (string) | The human-readable name of the descriptor. The name is based on the descriptor's type. The complete list of descriptor types can be found under Gatt Descriptors. | ||
| "valid" (bool) | This is "false", if the associated service is no longer valid due to a disconnect from the underlying Bluetooth Low Energy device. | ||
| "uuid" (string) | UUID of this descriptor in the format {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}. | ||
| "type" (uint) | A convienience type for descriptor class UUIDs. The detailed type specifications can be found under Gatt Descriptors. | ||
| "typeAsString" (string) | A human-readable and translated name for the descriptor type represented by uuid. | ||
| "value" (blob) | The cached value of the descriptor. | ||
| If "reason" is "valueChanged" the key "Characteristic" (mapping) will be available: | |||
| "Characteristic" (mapping) | In case that "reason" is "valueChanged" a single mapping containing the keys for the affected characteristic will be passed. This mapping will have the same keys as one mapping from the key "Characteristics" above. | ||
| The additional key "error" will be present only in the case of "reason" being "error": | |||
| "error" (string) | The error expressed in one of the following error codes: | ||
| "OperationError" | An operation was attempted while the service was not ready. An example might be the attempt to write to the service while it was not yet in the ServiceDiscovered state or the service is invalid due to a loss of connection to the peripheral device. | ||
| "CharacteristicReadError" | An attempt to read a characteristic value failed. | ||
| "CharacteristicWriteError" | An attempt to write a new value to a characteristic failed. | ||
| "DescriptorReadError" | An attempt to read a descriptor value failed. | ||
| "DescriptorWriteError" | An attempt to write a new value to a descriptor failed. | ||
| "Unknown" | An unknown error has occurred. | ||
Assignment
Mobile UI control functions
Availability
UI
See also
btleOpen(), btleServiceDisconnect()
