This page is part of archived documentation for openHAB 2.5. Go to the current stable version
# iCloud Binding
The Apple iCloud (opens new window) is used to retrieve data such as the battery level or current location of one or multiple Apple devices connected to an iCloud account. Updates are quick and accurate without significant battery time impact. The Binding also offers access to the "Find My iPhone" function.
An Apple account is required. Two factor authentication is supported.
Please note: Application specific passwords are not supported. You will need to provide the account password to the Binding.
# Discovery
An iCloud account can be added as a Thing and needs to be configured with your ID and password. The devices registered to this account will then be automatically discovered.
# Binding Configuration
The Binding has no configuration options, all configuration is done at Thing level.
# Thing Configuration
The Binding provides two Thing types.
# Account Thing
The account Thing, more precisely the account Bridge, represents one Apple iCloud account. The account can be connected to multiple Apple devices which are represented as Things below the Bridge, see the example below. You may create multiple account Things for multiple accounts.
# Device Thing
A device is identified by the device ID provided by Apple.
If a device is removed or disconnects from the account the respective openHAB device Thing status will change to OFFLINE.
All Things are updated according to the configured refresh time of their shared account Bridge.
You may force an update by sending the REFRESH command to any channel of the Bridge Things.
However this REFRESH command will not request data directly from the phone, but it will only make a query to the server.
# Channels
# Account Thing
The account Thing does not provide any channels.
# Device Thing
The following channels are available (if supported by the device):
| Channel ID | Type | Description |
|---|---|---|
| batteryStatus | String | Current battery status (Charging, NotCharging, Charged, Unknown) |
| batteryLevel | Number | Battery charge in percent |
| findMyPhone | Switch | Triggers the "Find My Phone" (opens new window) functionality of the device (if available). |
| location | Location | GPS coordinates of the devices current/last known location |
| locationAccuracy | Number | Accuracy of the last position report |
| locationLastUpdate | DateTime | Timestamp of the last location update |
# Full Example
# icloud.things
Bridge icloud:account:myaccount [appleId="[email protected]", password="secure", refreshTimeInMinutes=5]
{
Thing device myiPhone8 "iPhone 8" @ "World" [deviceId="VIRG9FsrvXfE90ewVBA1H5swtwEQePdXVjHq3Si6pdJY2Cjro8QlreHYVGSUzuWV"]
}
The device ID can be found in the Paper UI inbox. The information @ "World" is optional.
# icloud.items
Group iCloud_Group "iPhone"
String iPhone_BatteryStatus "Battery Status [%s]" <battery> (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:batteryStatus"}
Number iPhone_BatteryLevel "Battery Level [%d %%]" <battery> (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:batteryLevel"}
Switch iPhone_FindMyPhone "Trigger Find My iPhone" (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:findMyPhone", autoupdate="false"}
Switch iPhone_Refresh "Force iPhone Refresh" (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:location", autoupdate="false"}
Location iPhone_Location "Coordinates" (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:location"}
Number iPhone_LocationAccuracy "Coordinates Accuracy [%.0f m]" (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:locationAccuracy"}
DateTime iPhone_LocationLastUpdate "Last Update [%1$td.%1$tm.%1$tY, %1$tH:%1$tM]" <time> (iCloud_Group) {channel="icloud:device:myaccount:myiPhone8:locationLastUpdate"}
Switch iPhone_Home "Phone Home" <presence> (iCloud_Group)
# icloud.sitemap
sitemap icloud label="iCloud" {
Frame item=iCloud_Group {
Text item=iPhone_BatteryStatus
Text item=iPhone_BatteryLevel
Text item=iPhone_Home
Text item=iPhone_LocationAccuracy
Text item=iPhone_LocationLastUpdate
Switch item=iPhone_FindMyPhone mappings=[ ON="Find!" ]
Switch item=iPhone_Refresh mappings=[ REFRESH='Refresh now' ]
// Mapview for Basic UI and Applications (Android/iOS)
Mapview item=iPhone_Location height=10
}
}
# icloud.rules
rule "iPhone Home"
when
Item iPhone_Location changed
then
// specify your home location
val PointType home_location = new PointType(new DecimalType(51.0), new DecimalType(4.0))
val PointType phone_location = iPhone_Location.state as PointType
val int distance = phone_location.distanceFrom(home_location).intValue()
// specify your preferred radius (in meters)
if ( distance < 200) {
iPhone_Home.postUpdate(ON)
logInfo("iPhone Home", "iPhone is at home.")
} else {
iPhone_Home.postUpdate(OFF)
logInfo("iPhone Home", "iPhone is away.")
}
end
Apple, iPhone, and iCloud are registered trademarks of Apple Inc., registered in the U.S. and other countries.