Migrating from v1.x.x to v2.x.x

Table of Contents

• Overview
  • Understanding the Architectural Change
  • From Accessory Plugin to Dynamic Platform Plugin
  • Why this Complicated Change is Necessary
• Step-by-Step Migration Process
  • 1. Take a Homebridge Backup
  • 2. Uninstall the Old Plugin
  • 3. Hard Restart Homebridge
    • Power Options
    • Can't Find Power Options?
  • 4. Install the New Plugin Version
  • 5. Configure the New Plugin

Overview

Direct migration between the two versions is not supported. To upgrade, you will need to first remove the old plugin and its configuration, then install and configure the new version. This process requires a hard restart of Homebridge, which is more than just using the "Restart" button in the UI.

Understanding the Architectural Change

The migration from version 1.x.x to version 2.x.x of the Homebridge Winix Purifiers plugin is not just a simple update; it involves a fundamental change in the underlying architecture of the plugin. This section aims to shed light on why this transition, albeit complex, is essential for enhanced functionality and user experience.

From Accessory Plugin to Dynamic Platform Plugin

The original version of the plugin was built on the Accessory plugin architecture. While functional, this architecture had its limitations, particularly in flexibility and scalability. Each device had to be manually configured and added to Homebridge, and any changes or additions of devices required editing the configuration file and restarting Homebridge.

The new version 2.x.x transitions to the Dynamic Platform Plugin architecture. This architectural shift brings significant improvements:

• Dynamic Discovery and Addition of Devices: With the dynamic platform plugin architecture, the plugin can now automatically discover and add Winix air purifiers to Homebridge without needing to manually edit the configuration file or restart Homebridge. This means that as soon as you add a new purifier to your Winix account, it can be automatically reflected in your Homebridge setup.

• Enhanced Scalability: This architecture makes it easier to manage multiple devices, as the platform can dynamically handle device additions, removals, and updates. It's particularly beneficial for users with multiple air purifiers, simplifying the overall management and integration process.

Why this Complicated Change is Necessary

The transition to a dynamic platform plugin architecture necessitates a clean slate due to the differences in how the two architectures manage devices and configurations. This is why the migration process involves uninstalling the old plugin, including its configuration, and setting up the new version from scratch. While this process may seem cumbersome initially, the long-term benefits of a more flexible, scalable, and stable integration make it a worthwhile effort.

Step-by-Step Migration Process

1. Take a Homebridge Backup

Follow the Homebridge Backup and Restore instructions to take a backup of your current settings and plugins. It is always important to take a backup before performing large changes or migrations.

If there are any issues during this migration, you can always follow the guide to restore from your backup you just took.

2. Uninstall the Old Plugin

Instead of manually editing the config.json file to remove the old plugin's configuration, it's recommended to uninstall the plugin through the Homebridge UI. This method is more straightforward and helps prevent potential configuration errors.

1. Go to the Plugins section in the Homebridge UI.
2. Find the homebridge-winix-purifiers plugin.
3. Click the three dots menu and select Uninstall.
4. Ensure that the "Remove Plugin Config?" option is checked. This will clean up the old plugin configuration from your system.

3. Hard Restart Homebridge

After uninstalling the old plugin and before installing the new version, a hard restart of the Homebridge service is necessary to ensure that all changes are correctly applied. A hard restart is crucial in this migration process because it ensures that all components of Homebridge, including any residual configurations or processes from the old plugin, are completely reset. This process can be easily done through the Homebridge UI with the following steps:

Power Options

1. In the Homebridge UI, locate the three-dots menu in the top right corner.
2. From the dropdown menu, select Power Options.
3. In the Power Options menu, choose "Restart HB Service & UI". This action will restart both the Homebridge service and the UI, ensuring that all backend processes are fully refreshed.

Can't Find Power Options?

In older versions of Homebridge, the Power Options might not be in the three-dots menu. If this occurs, you can still perform a hard restart by accessing a more hidden setting:

1. In the Homebridge UI, locate the three-dots menu in the top right corner.
2. From the dropdown menu, select Settings.
3. Scroll to the bottom of the Settings page to find the Actions section.
4. Select Force Service Restart. This function forces the Homebridge service to restart, similar to the "Restart HB Service & UI" option but accessible through a different path.

  

4. Install the New Plugin Version

After successfully uninstalling the old plugin and performing a hard restart, you can proceed to install the new version of the plugin:

1. Go to the Plugins section in the Homebridge UI.
2. Search for homebridge-winix-purifiers.
3. Click Install next to the plugin to install the latest version.

5. Configure the New Plugin

With the new plugin version installed, you'll need to configure it to connect to your Winix purifiers. Please follow the steps in the README to properly setup your new plugin version