DIRIGERA

HSYCO integrates IKEA’s DIRIGERA hub, a smart home controller designed to unify control over IKEA smart devices such as lights, outlets, blinds, motion sensors, and more. Communication is conducted over the local network without requiring access to the IKEA cloud.

The integration enables HSYCO to monitor and control devices configured in the DIRIGERA hub, using a local API uncovered through reverse engineering. The HUB setup must be completed via the IKEA Home Smart App before use with HSYCO.

note

This I/O Server integrates with the IKEA DIRIGERA hub using a reverse-engineered and therefore unofficial network API. Please be aware that IKEA may, at any time and without notice, modify or even remove this network API in current or future versions of the DIRIGERA hub. Consequently, HSYCO expressly disclaims any guarantee that this I/O Server will continue to be available or functional in the future. Users acknowledge that utilizing this I/O Server carries potential risks, including but not limited to impacts on the functionality, reliability, security, and battery life of the DIRIGERA hub and connected devices. HSYCO shall not be held liable for any issues arising from the use of this unofficial integration.

Communication

Communication with the DIRIGERA hub is achieved through HTTPS and WebSocket protocols. HTTPS is used for device discovery and for writing attribute values to devices. As this is an unofficial API, there is no fixed list of writable attributes and their availability may vary depending on the device and firmware version.

In addition, once authenticated, HSYCO initiates a WebSocket connection to the hub and acts as a client to receive real-time updates about device states and events. Support for multiple HUBs is achieved by configuring one I/O Server for each hub.

HSYCO Configuration

Add a DIRIGERA I/O Server in the I/O Servers section of the Settings and set its parameters:

Communication

• IP Address: IP address of the DIRIGERA hub (fixed), or the broadcast address of the local network (e.g., 192.168.1.255) to scan for hubs or connect to a specific one using the code option.
• IP Port: TCP/IP port to use, always uses default port 8443.

High Availability

• Shutdown when inactive: defaults to false.

The dirigera.ini authentication tokens file (see below) is transferred from master to slave. The active HSYCO executes the authentication process, while the not active HSYCO only uses the authentication tokiens in the dirigera.ini file, if available.

Options

ID	Default	Values	Description
code		String	the 6-character code found on the bottom of the DIRIGERA hub. Required to identify a specific hub when using the broadcast address.
enableverbosedump	false	true	when verbose log is enabled, all decoded WebSocket packets are written to the log files
		false	when verbose log is enabled, don’t write packets dumps to the log files
refreshinterval	1440	>= 0	if > 0, the gateway is polled every n minutes to detect added or removed devices; if 0, no automatic polling is performed. Does not affect devices' attributes polling

Discovery Logic

When the IP Address is set to the local network broadcast address, the I/O Server operates in one of two modes based on the code option:

• Hub Code Mode (code is set): HSYCO scans the network for a specific hub matching the provided code. Once found, it automatically connects to that hub.

• Discovery Mode (code is empty): HSYCO scans the network and logs information about all DIRIGERA hubs found (Hub Code and IP). It will not connect to a hub in this mode; it is used only to identify available hubs on the network.

Device Discovery

When HSYCO starts, it attempts to connect to the DIRIGERA hub and generate an access token automatically.

To complete the initial authentication process, the user must press the Action button located on the bottom of the DIRIGERA hub when prompted. This must be done within 60 seconds of HSYCO’s initial connection attempt. 5 authentication attemps are done, after which the I/O Server will restart completely.

The authentication token is saved to a file named dirigera.ini in the root directory, and reused when HSYCO or the I/O Server restarts.

Once authenticated, HSYCO retrieves the list of devices paired with the DIRIGERA hub, including lights, outlets, blinds, and sensors.

Restart HSYCO or the I/O Server when devices are added or removed, or, if the 'refreshinterval' option is enabled, wait for the automatic polling.

Due to the unofficial nature of this integration, some devices may expose incomplete or unstable attributes. Always test thoroughly before deploying into production environments.

Device Control and Status

HSYCO allows basic interaction with supported devices, including turning lights on or off, adjusting brightness, operating blinds, and reading sensor data. However, the exact capabilities and exposed properties may vary by device model and firmware version.

note

No guarantee is given for device compatibility, channel consistency, or the stability of exposed endpoints. New firmware updates or changes from IKEA may break current functionality without notice.

Datapoints

Due to the unofficial and unstable nature of the integration, no fixed list of datapoints is provided. Each DIRIGERA device may expose different attributes and command formats, which may change over time. Therefore, users should explore and test datapoints dynamically based on the devices currently connected and available.

Additional datapoints

ID	Value	R/W	Description
connection	online	R	connection to the HUB established
	offline	R	HSYCO can't connect to the HUB
	authenticating	R	HSYCO is attempting to authenticate
	searching	R	HSYCO is scanning the network to find the specific hub defined by the code option
	discovery	R	HSYCO is scanning the network to discover and log all available DIRIGERA hubs

Release Notes

4.1.0

• new "code" option
• new automatic discovery mode
• support for dynamic IP addresses via hub code identification

4.0.0

• initial release

---

DIRIGERA is a trademark of Inter IKEA Systems B.V.