mergBLE is a LiveCode external for iOS and OS X that enables CoreBluetooth (BLE) functionality. You can use the external to discover and interact with peripherals or advertise your app as a peripheral for others to interact with.
command mergBLEInitialize
command mergBLEScanForPeripheralsWithServices [pUUIDs]
Scans for peripherals that are advertising services. Apps that have specified the bluetooth-central background mode are allowed to scan while in the background. That said, they must explicitly scan for one or more services by specifying them in the pUUIDs parameter. When a peripheral is discovered the mergBLE the mergBLEDidDiscoverPeripheral message is sent.
Parameters:
- pUUIDs - (optional with "" default) An list of service UUIDs that the app is interested in. If empty all discovered peripherals are returned regardless of their supported services (not recommended).
message mergBLEDidDiscoverPeripheral pUUID,pName,pRSSI
Sent when a peripheral is discovered
Parameters:
- pUUID - The peripheral UUID
- pName - The name of the peripheral
- pRSSI - A number, in decibels, that indicates the RSSI of the peripheral while it is currently connected. You can use a connected peripheral’s RSSI property to determine the peripheral’s proximity.
command mergBLEStopScanningForPeripherals
Stop the scan begun by mergBLEScanForPeripheralsWithServices
command mergBLEConnectPeripheral pUUID
Establishes a local connection to a peripheral. When successfully connected the mergBLEDidConnectPeripheral message is sent. If a connection couldn't be made the mergBLEDidFailToConnectPeripheral is sent. When a peripheral connection is lost the mergBLEDidDisconnectPeripheral is sent.
Parameters:
- pUUID - A peripheral UUID as returned bu the mergBLEDidDiscoverPeripheral message
message mergBLEDidConnectPeripheral pUUID
Sent when a peripheral connected
Parameters:
- pUUID - The peripheral UUID
message mergBLEDidFailToConnectPeripheral pUUID,pError
Sent when a peripheral connection failed
Parameters:
- pUUID - The peripheral UUID
- pError - An error message
message mergBLEDidDisconnectPeripheral pUUID
Sent when a peripheral is disconnected
Parameters:
- pUUID - The peripheral UUID
command mergBLECancelConnectionToPeripheral pUUID
Cancel a pending or active connection to a peripheral. When disconnected the mergBLEDidDisconnectPeripheral message is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
Services
command mergBLEPeripheralDiscoverServices pUUID,[pServiceUUIDs]
Discover the services offered by a peripheral. When discovered the mergBLEPeripheralDidDiscoverServices is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pServiceUUIDs - (optional with "" default) A list of service UUIDs that your app is interested in. If empty all discovered services are returned (not recommended).
message mergBLEPeripheralDidDiscoverServices pUUID,pServices
Sent when services are discovered
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pServices - A list of service UUIDs
command mergBLEPeripheralDiscoverIncludedServicesForService pUUID,pService,[pServiceUUIDs]
When discovered the mergBLEPeripheralDidDiscoverIncludedServices is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pServiceUUIDs - (optional with "" default) A list of service UUIDs that your app is interested in. If empty all discovered services are returned (not recommended).
message mergBLEPeripheralDidDiscoverIncludedServices pUUID,pService,pServices
Sent when services included in a service are discovered
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pServices - A list of service UUIDs
Characteristics
command mergBLEPeripheralDiscoverCharacteristicsForService pUUID,pService,[pCharacteristicUUIDs]
Discover the characteristics of a service. When discovered the mergBLEPeripheralDidDiscoverCharacteristicsForService is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristicUUIDs - (optional with "" default) A list of characteristic UUIDs that your app is interested in. If empty all discovered characteristics are returned (not recommended).
message mergBLEPeripheralDidDiscoverCharacteristicsForService pUUID,pService,pCharacteristic
Sent when characteristics of a service are discovered
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A list of characteristic UUIDs
command mergBLEPeripheralReadValueForCharacteristic pUUID,pService,pCharacteristic
Read the value of a service characteristic. When read the mergBLEPeripheralDidUpdateValueForCharacteristic is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A characteristic UUID.
message mergBLEPeripheralDidUpdateValueForCharacteristic pUUID,pCharacteristic,pValue,pError
Sent when a characteristic value is read
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pCharacteristic - A characteristic UUID as returned by the mergBLEPeripheralDidDiscoverCharacteristicsForService message
- pValue - The value of the characteristic
- pError - An error message if an error occured otherwise empty
command mergBLEPeripheralWriteValueForCharacteristic pUUID,pService,pCharacteristic,pValue
Write the value for a service characteristic. When written the mergBLEPeripheralDidWriteValueForCharacteristic is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A characteristic UUID.
- pValue - The value to write
message mergBLEPeripheralDidWriteValueForCharacteristic pUUID,pCharacteristic,pError
Sent when a characteristic value is written
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pCharacteristic - A characteristic UUID as returned by the mergBLEPeripheralDidDiscoverCharacteristicsForService message
- pError - An error message if an error occured otherwise empty
command mergBLEPeripheralSetNotificationsForCharacteristic pUUID,pService,pCharacteristic,pNotify
Set notifications to service characteristic value changes. When successful the mergBLEPeripheralDidUpdateNotificationStateForCharacteristic is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A characteristic UUID.
- pNotify - If true then set you will be notified of changes to the characteristic value
message mergBLEPeripheralDidUpdateNotificationStateForCharacteristic pUUID,pCharacteristic,pError
Sent when the update notification state is set for a characterisitc
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pCharacteristic - A characteristic UUID as returned by the mergBLEPeripheralDidDiscoverCharacteristicsForService message
- pError - An error message if an error occured otherwise empty
Descriptors
command mergBLEPeripheralDiscoverDescriptorsForCharacteristic pUUID,pService,pCharacteristic
Discover the descriptors of a service characteristic. When discovered the mergBLEPeripheralDidDiscoverDescriptorsForCharacteristic is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A characteristic UUID.
message mergBLEPeripheralDidDiscoverDescriptorsForCharacteristic pUUID,pCharacteristic,pDescriptors
Sent when the descriptors of a characteristic of a service are discovered
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pCharacteristic - A descriptor UUID as returned by the mergBLEPeripheralDidDiscoverCharacteristicsForService message
- pDescriptors - A list of descriptor UUIDs
command mergBLEPeripheralReadValueForDescriptor pUUID,pService,pCharacteristic,pDescriptor
Read the value of a descriptor of a service characteristic. When read the mergBLEPeripheralDidUpdateValueForDescriptor is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A characteristic UUID.
- pDescriptor - A descriptor UUID.
message mergBLEPeripheralDidUpdateValueForDescriptor pUUID,pDescriptor,pValue,pError
Sent when a descriptor value is read
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pDescriptor - A descriptor UUID as returned by the mergBLEPeripheralDidDiscoverDescriptorsForCharacteristic message
- pValue - The value of the descriptor
- pError - An error message if an error occured otherwise empty
command mergBLEPeripheralWriteValueForDescriptor pUUID,pService,pCharacteristic,pDescriptor,pValue
Write the value of a descriptor of a service characteristic. When written the mergBLEPeripheralDidWriteValueForDescriptor is sent.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pService - A service UUID as returned by the mergBLEPeripheralDidDiscoverServices message
- pCharacteristic - A characteristic UUID.
- pDescriptor - A descriptor UUID.
- pValue - The value to write
message mergBLEPeripheralDidWriteValueForDescriptor pUUID,pDescriptor,pError
Sent when a descriptor value is written
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pDescriptor - A descriptor UUID as returned by the mergBLEPeripheralDidDiscoverDescriptorsForCharacteristic message
- pError - An error message if an error occured otherwise empty
message mergBLECentralManagerDidUpdateState pState
Sent when the central manager updates state.
Parameters:
- pState - One of:|unknown|resetting|unsupported|unauthorized|powered off|powered on
Peripheral Properties
command mergBLEPeripheralReadRSSI pUUID
Read the RSSI value which is returned via the mergBLEPeripheralDidUpdateRSSI message.
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
message mergBLEPeripheralDidUpdateRSSI pUUID,pRSSI,pError
Sent when the RSSI value is read
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pRSSI - The RSSI value of the peripheral
- pError - An error message if an error occured otherwise empty
message mergBLEPeripheralDidModifyServices pUUID,pInvalidatedServices
Sent when the peripheral adds or invalidates services
Parameters:
- pUUID - A peripheral UUID as returned by the mergBLEDidDiscoverPeripheral message
- pInvalidatedServices - If any services were invalidated then their UUIDs are listed here otherwise this parameter will be empty. To determine any new services available you need to discover services again.
Advertising As A Peripheral
command mergBLECreateService pUUID
Create a service to advertise
Parameters:
- pUUID - A service UUID being advertised by the device
command mergBLEDeleteService pUUID
Delete a service
Parameters:
- pUUID - A service UUID being advertised by the device
command mergBLEAddCharacteristicToService pUUID,pCharacteristic,pRead,pWriteWithoutResponse,pWrite,pNotify,pIndicate,pAuthenticatedSignedWrites,pNotifyEncryptionRequired,pIndicateEncryptionRequired,[pValue]
Add a characteristic to a previously created service
Parameters:
- pUUID - A service UUID being advertised by the device
- pCharacteristic - A characteristic UUID.
- pRead - The characteristic’s value can be read.
- pWriteWithoutResponse - The characteristic’s value can be written, without a response from the peripheral to indicate that the write was successful.
- pWrite - The characteristic’s value can be written, with a response from the peripheral to indicate that the write was successful.
- pNotify - Notifications of the characteristic’s value are permitted, without a response from the central to indicate that the notification was received.
- pIndicate - Indications of the characteristic’s value are permitted, with a response from the central to indicate that the indication was received.
- pAuthenticatedSignedWrites - Signed writes of the characteristic’s value are permitted, without a response from the peripheral to indicate that the write was successful.
- pNotifyEncryptionRequired - Only trusted devices can enable notifications of the characteristic’s value.
- pIndicateEncryptionRequired - Only trusted devices can enable indications of the characteristic’s value.
- pValue - (optional with The default) The value of the characteristic. Only set for readable characteristics.
command mergBLEUpdateValueForCharacteristicOfService pUUID,pCharacteristic,pValue
Parameters:
- pUUID - A service UUID being advertised by the device
- pCharacteristic - A characteristic UUID.
- pValue - The value of the characteristic. Subscribed centrals will be notified.
command mergBLERemoveCharacteristicFromService pUUID,pCharacteristic
Parameters:
- pUUID - A service UUID being advertised by the device
- pCharacteristic - A characteristic UUID.
command mergBLEStartAdvertising [pName]
Parameters:
- pName - (optional with "" default) The name to advertise the peripheral as. If empty on iOS then the device name is used. For example "Monte's iPhone"
message mergBLEPeripheralManagerDidStartAdvertising pError
Sent when the device starts advertising as a peripheral
Parameters:
- pError - An error message if an error occured otherwise empty
message mergBLECentralDidSubscribeToCharacteristic pUUID,pCharacteristic
Sent when a central subscribes to one of the advertised service characteristics
Parameters:
- pUUID - A service UUID being advertised by the device
- pCharacteristic - A characteristic UUID.
message mergBLECentralDidUnsubscribeToCharacteristic pUUID,pCharacteristic
Sent when a central unsubscribes from one of the advertised service characteristics
Parameters:
- pUUID - A service UUID being advertised by the device
- pCharacteristic - A characteristic UUID.
message mergBLECentralDidUpdateValueForCharacteristic pUUID,pCharacteristic,pValue
Sent when a central writes the value of a characteristic
Parameters:
- pUUID - A service UUID being advertised by the device
- pCharacteristic - A characteristic UUID.
- pValue - The new value of the characteristic.
command mergBLEStopAdvertising
message mergBLEPeripheralManagerDidUpdateState pState
Sent when the peripheral manager updates state.
Parameters:
- pState - One of:|unknown|resetting|unsupported|unauthorized|powered off|powered on