ThingConnect

From IoT
Jump to: navigation, search

Go Up to Main Page


The available ThingConnect devices use one of the following technologies:

Z-Wave

The Z-Wave protocol is an inter-operable, wireless, RF-based communications technology designed specifically for control, monitoring and status reading applications in residential and light commercial environments. For more information about the Z-Wave technology, see About Z-Wave Technology.

Z-Wave Overview

In order to use a Z-Wave device, you need to have a device that acts as a controller. We test our devices using the VeraLite Smart Home Controller, but you may use any compatible Z-Wave controller.

For instructions on how to set up a Z-Wave controller, see the official documentation of the manufacturer. For example, for VeraLite Smart Home Controller, see Vera User Guides.

Using Z-Wave IoT Framework

The Z-Wave IoT Framework is HTTP based and acts as a layer between the user and the device, making the interaction easier and transparent. Using the Z-Wave IoT Framework you can interact with devices by accessing properties. The properties are either readable, writable or both. See Working with ThingConnect Devices and Tutorial: Building a ThingConnect IoT Application for more details and examples.

Discovery Mechanism for Z-Wave Devices

To connect to a Z-Wave device, you need to do the following:

  • Provide the IP address of the Z-Wave controller: Set the IP address as the URL property of the component.
  • Provide the unique identifier of the device: Set the unique identifier of the device as the DeviceNum property of the component. You can find (and modify) this identifier in the web interface of your Z-Wave controller. For example, in VeraLite you can see it in the Advanced section of a device as the id field.

    AeonLightLedBulb-DeviceNum.png

  • Activate the component: Set the property Active of the component to True.

Delphi: 

IPAddress = '192.168.1.99'; //IP address of the Z-Wave controller
DeviceID = 1234;            //The unique identifier of the device
FVeraAeotecLEDBulb.URL := 'http://' + IPAddress + '/port_3480';
FVeraAeotecLEDBulb.DeviceNum := DeviceID;
FVeraAeotecLEDBulb.Active := True;

C++: 

IPAddress = "192.168.1.99"; //IP address of the Z-Wave controller
DeviceID = 1234;            //The unique identifier of the device
FVeraAeotecLEDBulb->URL = "http://" + IPAddress + "/port_3480";
FVeraAeotecLEDBulb->DeviceNum = DeviceID;
FVeraAeotecLEDBulb->Active = True;

Reading or Writing to a Characteristic

Reading or writing to a characteristic is simple, you use the available properties of the component. For example, to get the color of the Aeon Labs Light Bulb, use the following code:

Delphi: 

Value := FVeraAeotecLEDBulb.Color;

C++: 

Value = FVeraAeotecLEDBulb->Color;

Subscribing to a Characteristic

The Z-Wave technology does not provide a way to subscribe to a characteristic in the same way as BLE does. In order to simulate a "subscription", you can periodically query the controller to see if it received any alerts.

For example, if you want to "subscribe" to the temperature reading of the Honeywell thermostat, you can use the following code:

Delphi: 

procedure THoneywellThermostatApp.Timer1Timer(Sender: TObject);
begin
  InsideTempLabel.Text := FloatToStr(FVeraHoneywellThermostat.TemperatureValue) + '°F';
end;

C++: 

void __fastcall THoneywellThermostatApp::Timer1Timer(TObject *Sender)
{
	InsideTempLabel->Text = FloatToStr(FVeraHoneywellThermostat->TemperatureValue) + "F";
}

Receiving Alerts

Some Z-Wave device are able to trigger alerts. When those devices trigger an alert, the Z-Wave controller receives it. In order to "subscribe" to an alert, you can periodically query the controller (you can use a timer or a thread for that).

For example, if you want to "subscribe" to the alerts of the Fibaro window sensor, you can use the following code excerpt as a guide:

Delphi: 

var
  XMLNodeList: IXMLNodeList;
  XMLDocument: IXMLDocument;
...

...
XMLDocument := LoadXMLData(FibaroWindowSensorApp.FVeraFibaroWindowSensor.Xmlfile);
if XMLDocument <> nil then
begin
  XMLNodeList := XMLDocument.DocumentElement.ChildNodes['alerts'].ChildNodes;
  for I := XMLNodeList.Count - 1 downto 0 do
  if (XMLNodeList[I].Attributes['PK_Device']) = DeviceID then
    break;
  Date = '';
  Date := XMLNodeList[I].Attributes['LocalTimestamp'];
  ...
end;
...

C++: 

String XMLData, Date;
_di_IXMLNode XMLNodeList, XMLNodeListChild;
_di_IXMLDocument XMLDocument;
...
XMLDocument = LoadXMLData(FibaroWindowSensorApp->FVeraFibaroWindowSensor->Xmlfile);
if (XMLDocument)
{
	XMLNodeList = XMLDocument->DocumentElement->ChildNodes->FindNode("alerts");
	for (I = XMLNodeList->ChildNodes->Count - 1 ; I >= 0; I--)
	{
		XMLNodeListChild = XMLNodeList->ChildNodes->Get(I);
		if ((XMLNodeListChild->Attributes["PK_Device"]) == (DeviceID))
			break;
	}
	Date = "";
	Date = XMLNodeListChild->Attributes["LocalTimestamp"];
...

Z-Wave Android Uses Permissions

In order to use a Z-Wave device on android, you do not need to change the default settings for Uses Permissions.

Bluetooth Low Energy

Bluetooth Low Energy (Bluetooth LE) or Smart Bluetooth provides a new environment for devices with small amount of data to transfer and lower power consumption.

Bluetooth LE Overview

Generic Access Profile (GAP)

The Generic Access Profile controls the connections and the service advertising in Bluetooth. The Generic Access Profile of a Bluetooth LE device determines how the devices can interact with other devices.

The Generic Access Profile defines various roles for these devices:

  • Peripheral devices, with small amount of data to transfer and lower power consumption. Peripheral devices advertise their services and can connect to a powerful central device. Some samples of peripheral devices are a heart rate monitor, and a blood pressure monitor.
  • Central devices with more processing power and memory, and where the peripheral devices connect. The central device searches for devices and establishes connection with one peripheral device.

Platform Support

Platform Bluetooth Low Energy
Central Peripheral

Windows*

8+

Mac OS X

10.7+

10.9+

iOS

5+

6+

Android

4.3+

*Windows Server does not support Bluetooth (see: General Bluetooth Support in Windows).

GATT (Generic Attribute Profile) Profiles

Profiles are high level definitions that define how to use standard services in your applications. For example, there is a Heart Rate profile that is used for fitness or health applications. The server device with a Heart Rate Sensor exposes the standard Heart Rate Service so that the Bluetooth LE client discovers the service and starts collecting data, for example the bpm (beats per minute).

The GATT profile is the combination of service and characteristics.

The official page with the GATT Profiles is GATT Specifications for Standard Profiles.

Bluetooth LE Services

Services are collections of characteristics and relationships to other services that encapsulate the behavior of part of a device.

A GATT profile includes one or more standard services that are identified by a number. For example, the Heart Rate has an official number assigned: "0x180D".

The official page with Standard Services information is Standard Bluetooth LE Services.

Bluetooth LE Characteristics

A characteristic defines an attribute type that contains a single logical value.

One service can contain one or more characteristics that provide information for the particular service. Each characteristic is identified by an official number. For example, the Heart Rate service has a characteristic to measure the heart rate, Heart Rate Measurement.

The official page with adopted Characteristic information is Standard Bluetooth LE Characteristics.

Using Bluetooth LE IoT Framework

The IoT framework for Bluetooth LE based device uses TBluetoothDeviceDiscoveryManager to manage the connection with an IoT device as a general Bluetooth LE based connection mechanism and wraps each device as a component. For instance, the TWahooTICKRHeartRateMonitor component wraps the Wahoo TICKR Heart Rate Monitor.

The TBluetoothDeviceDiscoveryManager component provides the basic mechanism for connecting to Bluetooth LE based devices. In the TBluetoothDeviceDiscoveryManager component, you can define timeout and a number of re-tries to connect for these devices.

Discovery Mechanism for Bluetooth LE Devices

Discovery Mechanism Methods in the Bluetooth LE Device Discovery Manager

The TBluetoothDeviceDiscoveryManager component supports several options for the discovery mechanism (DiscoveryMethod property):

Discovery Method Type Description
Connect The central device connects directly to a given peripheral device.
ScanResponse The central device uses the advertised data from the peripheral device to connect to it faster.
ScanResponseAllDevices The central device searches for all peripheral devices with the same primary service in their advertised data.


Note:
  • For 32-bit Windows and 64-bit Windows platforms applications, you need to set Connect as the discovery method type.
  • Some devices do not broadcast their name or services in the advertised data. You need to use the Connect discovery method instead, and set manually the name of the device you want to connect to.
  • The ScanResponse method connects to the first ThingConnect device found that has a given primary service.

ThingConnect Component Discovery Mechanism Events

All Bluetooth LE components provide the following events for any of discovery methods set in the TBluetoothDeviceDiscoveryManager:

Name of Event Description
OnDeviceConnected When the component finds a device and connects to it.
OnDeviceDisconnect When the component detects that the device is disconnected.
OnDeviceDiscovered When the component finds new device (it can be raised several times).


If the discovery method of the TBluetoothDeviceDiscoveryManager is set to ScanResponseAllDevices, the following events can be raised before connecting to the ThingConnect device:

Name of Event Description
OnDeviceListDiscovered When the component finishes listing all the discovered devices.

When the component finishes listing all the discovered devices (and the OnDeviceListDiscovered event is fired), the following component properties are updated and you can use them to connect to a device:

  • DiscoveredDeviceCount: Contains the total amount of discovered devices that contains the list.
  • DiscoveredDevice: Returns a specific device from the list of discovered devices.

For more information about these properties, see Using the ScanResponseAllDevices Discovery Mechanism Method.

Connecting to a ThingConnect Device

Depending on the Discovery Mechanism, you can connect to the ThingConnect device by using:

  • For the Connect method, set the DeviceName property of the component to the name of your own component.
  • For the ScanResponseAllDevices method, use the ConnectDevice method to connect to a given DiscoveredDevice. Fore more details, see Using the ScanResponseAllDevices Discovery Mechanism Method.

Bluetooth LE Device Discovery Manager Error Event

The TBluetoothDeviceDiscoveryManager provides the following event:

Name of Event Description
OnGeneralDiscoveryError

When the device manager does not find any device to connect to.

The procedure also has an additional parameter, Handled. If you want to handle the exception yourself, set set Handled to True. 

TGeneralDiscoveryErrorEvent = procedure(const Sender: TObject; const AException: Exception; var Handled: Boolean) of object;

ThingConnect Component Error Events

All Bluetooth LE components provide the following events:

Name of Event Description
OnDeviceConnectionError When the component cannot retrieve the services from the device (the device is now disconnected).

You need to implement the corresponding event handlers when the events are fired.

Reading or Subscribing to a Characteristic

Once the application connects to a device, you can read the information contained in the characteristics of a service or subscribe to a characteristic to get the information each time it changes.

Only read-only characteristic has its corresponding Property in the Bluetooth LE components.

Note: Subscription-characteristics also have a PropertyName value but only for documentation purposes. The property name values of subscription-characteristics are not properties of the component.

Every characteristic has an event. All the names of the events conform to On<PropertyName>Update. The event handler is fired after reading the property value.

  • To read the data of a read-only characteristic, call the Refresh<PropertyName> method.
  • To subscribe to a characteristic and to start receiving data updates, call the Subscribe<PropertyName> method.
  • To unsubscribe from a characteristic and stop receiving data updates, call the Unsubscribe<PropertyName> method.

The following table shows an example of method names in the Zephyr Heart Rate Monitor for reading the BatteryLevel property, and subscribing and unsubscribing to the Heart Rate Measurement characteristic (HeartRateMeasurement).

Service Characteristic Property EventName Read Method Subscribe Method Unsubscribe Method
Battery Service Battery Level BatteryLevel OnBatteryLevelUpdate RefreshBatteryLevel
Heart Rate Heart Rate Measurement HeartRateMeasurement OnHeartRateMeasurementUpdate SubscribeHeartRateMeasurement UnsubscribeHeartRateMeasurement

To work with, you need to add the following units to the Uses clause of the application:

  • Iot.Family.BluetoothLE.GattTypes
  • The custom Types unit (if the component defines custom data types).

Writing a Characteristic

You can send data to the device by writing the corresponding characteristics of a service.

  • The names of the events conform to On<PropertyName>WriteStatus. The event handler is fired after sending the order to the device to write in a characteristic.
  • To write to a characteristic, assign to the property the correct value. For more information on how to write to a characteristic, see Writing to a Characteristic.

To check if the characteristic in the device has been updated, you need to subscribe to a notification of another data type or to read the current value of the property (this depends on the device you are using).

Bluetooth LE Application Troubleshooting

Standard Bluetooth LE Services Not Shown in Mac OS X and iOS Applications

The Generic Attribute Profile Service and the Generic Access Profile Service Bluetooth LE standards services are not shown for Mac OS X and iOS applications.

Mac OS X and iOS operating systems use the information on these services internally and filter out from the list of discovered services the Generic Attribute Service and the Generic Access Service.

Windows Bluetooth LE Applications Cannot Connect

In 32-bit Windows and 64-bit Windows Bluetooth LE applications, you need to pair the devices before trying to connect them.

Windows does not support ScanResponse or the ScanResponseAllDevices as the discovery mechanism to find peripheral devices. Instead, you need to use Connect as the discovery mechanism in the TBluetoothDeviceDiscoveryManager component and set the DeviceName property with the name of your own device.

Bluetooth LE Android Uses Permissions

For Android Bluetooth LE applications, you need to enable the required Uses Permissions in the appropriate project configuration (Project > Options > Uses Permissions):

  • Bluetooth
  • Bluetooth admin

Topics

See Also

Retrieved from "https://docwiki.embarcadero.com/IoT/e/index.php?title=ThingConnect&oldid=3555"