mergBLE

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