Home

The FastyBird IoT HomeKit Connector is an extension of the FastyBird IoT ecosystem that enables effortless integration with Apple HomeKit. It provides users with a simple and user-friendly interface to connect FastyBird devices with Apple HomeKit, allowing easy control of the devices from the Apple Home app. This makes managing and monitoring your devices hassle-free.

Naming Convention

The connector uses the following naming convention for its entities:

Connector

A connector is an entity that manages communication with Apple HomeKit system. It needs to be configured for a specific interface.

Device

A device is an entity that represents a virtual Apple HomeKit device.

Device Service

A service is an entity that refers to a specific functionality or feature that a device provides. For example, a thermostat device might provide a "temperature control" service and a "humidity control" service.

Device Service Characteristic

A characteristic is an entity that refers to the individual attribute of a service that can be queried or manipulated. Characteristic represent specific data point that describe the state of a device or allow control over it. Examples of characteristic include temperature, humidity, on/off status, and brightness level.

Configuration

To integrate FastyBird IoT ecosystem devices with Apple HomeKit, you will need to configure at least one connector. The connector can be configured using the FastyBird IoT user interface or through the console.

Configuring the Connector through the Console

To configure the connector through the console, run the following command:

php bin/fb-console fb:homekit-connector:initialize

NOTE: The path to the console command may vary depending on your FastyBird application distribution. For more information, refer to the FastyBird documentation.

HomeKit connector - initialization
==================================

 ! [NOTE] This action will create|update|delete connector configuration

 Would you like to continue? (yes/no) [no]:
 > y

You will then be prompted to choose an action:

 What would you like to do?:
  [0] Create new connector configuration
  [1] Edit existing connector configuration
  [2] Delete existing connector configuration
 > 0

If you choose to create a new connector, you will be asked to provide basic connector configuration:

 Provide connector identifier:
 > my-homekit-server

 Provide connector name:
 > My HomeKit server

Now you can provide the communication port for the connector. If you don't provide a value, the default port will be used. If the port is not available, you can choose a different port.

 Provide server port [51827]:
 > 

After providing the necessary information, your new Apple HomeKit connector will be ready for use.

 [OK] Connector "My HomeKit server" was successfully created.

Configuring the Connector with the FastyBird User Interface

You can also configure the Apple HomeKit connector using the FastyBird IoT user interface. For more information on how to do this, please refer to the FastyBird IoT documentation.

Devices Configuration

With your new connector set up, you must now configure the devices with which the connector will communicate. This can be accomplished either through a console command or through the user interface of the FastyBird IoT.

Manual Console Command

To manually trigger device configuration, use the following command:

php bin/fb-console fb:homekit-connector:devices

NOTE: The path to the console command may vary depending on your FastyBird application distribution. For more information, refer to the FastyBird documentation.

The console will prompt for confirmation before proceeding with the devices configuration process.

HomeKit connector - devices management
======================================

 ! [NOTE] This action will create|update|delete connector device

 Would you like to continue? (yes/no) [no]:
 > y

You will then be prompted to select connector to manage devices.

 Please select connector under which you want to manage devices:
  [0] my-homekit-server [My HomeKit server]
 > 0

You will then be prompted to select device management action.

 What would you like to do?:
  [0] Create new connector device
  [1] Edit existing connector device
  [2] Delete existing connector device
 > 0

Now you will be asked to provide some device details:

 Provide device identifier:
 > living-room-thermostat

 Provide device name:
 > Living room thermostat

You are now required to select a device category, which will determine the specific services and characteristics of the device. If you are unable to find the appropriate category, you can choose the Other option.

 Please select device category [Other]:
  [0 ] Air Conditioner
  [1 ] Air Purifier
  [2 ] Alarm System
  [3 ] Camera
  [4 ] Dehumidifier
  [5 ] Door
  [6 ] Door Lock
  [7 ] Fan
  [8 ] Faucet
  [9 ] Garage Door Opener
  [10] Heater
  [11] Humidifier
  [12] Light Bulb
  [13] Other
  [14] Outlet
  [15] Programmable Switch
  [16] Range Extender
  [17] Remote Controller
  [18] Sensor
  [19] Shower Head
  [20] Speaker
  [21] Sprinkler
  [22] Switch
  [23] Television
  [24] Thermostat
  [25] Video Door Bell
  [26] Window
  [27] Window Covering
 > 24

If there are no errors, you will receive a success message.

 [OK] Device "Living room thermostat" was successfully created.

Each device have to have defined services. So in next steps you will be prompted to configure device's services.

NOTE: The list of items may vary depending on the device category.

 What type of device service you would like to add? [BatteryService]:
  [0] BatteryService
  [1] HeaterCooler
  [2] HumiditySensor
  [3] MotionSensor
  [4] OccupancySensor
  [5] TemperatureSensor
  [6] Thermostat
 > 6

Let's create Thermostat service:

 What type of service characteristic you would like to add? [CurrentHeatingCoolingState]:
  [0] CurrentHeatingCoolingState
  [1] TargetHeatingCoolingState
  [2] CurrentTemperature
  [3] TargetTemperature
  [4] TemperatureDisplayUnits
 > 4

These characteristics are mandatory and must be configured.

You have two options. Connect characteristics with FastyBird device or configure it as static value. Let's try static configuration value:

 Connect characteristics with device? (yes/no) [yes]:
 > n

Some characteristics have a defined set of allowed values, while others accept values from a range. Therefore, the next question will vary depending on the selected characteristic.

 Please select characteristic value:
  [0] Celsius
  [1] Fahrenheit
 > 0

And if you choose to connect characteristic with device:

 Connect characteristics with device? (yes/no) [yes]:
 > y

 Select device for mapping:
  [0] thermometer-living-room [Living room thermometer]
  [1] floor-heating-livin-room [Living room floor heating]
  [2] window-sensor-lifing-room [Living room window sensor]
 > 0

Now you have to choose type of the device property:

 What type of property you want to map? [Channel property]:
  [0] Device property
  [1] Channel property
 > 1

And select device channel:

 Select device channel for mapping:
  [0] temperature-humidity
 > 0

And channel's property:

 Select channel property for mapping:
  [0] temperature
  [1] humidity
 > 0

After all required characteristics are configured you will be prompted with question if you want to configure optional characteristics.

 What type of service characteristic you would like to add? (optional) [CurrentRelativeHumidity]:
  [0] CurrentRelativeHumidity
  [1] TargetRelativeHumidity
  [2] CoolingThresholdTemperature
  [3] HeatingThresholdTemperature
  [4] Name
  [5] None

The process is same as previous steps.

If there are no errors, you will receive a success message.

 [OK] Service "thermostat_1" was successfully created.

If you want to configure more device services you could repeat whole process:

 Would you like to configure another device service? (yes/no) [no]:
 > 

Known Issues and Limitations

Supported devices count

If you need to handle more devices than the maximum limit of 150 devices that can be handled by the connector and Apple HomeKit, you will need to create additional connectors using different ports.

Devices update

It is recommended to make configuration changes in smaller increments to avoid potential failure of device refresh when making multiple changes.