/homebridge-cmd4-AdvantageAir

Catered shell script to integrate air conditioner control units by Advantage Air into HomeKit using the plug-in homebridge-cmd4.

Primary LanguageShellMIT LicenseMIT

npm npm verified-by-homebridge

homebridge-cmd4-AdvantageAir

Catered shell script to integrate air conditioner control units by Advantage Air into Homekit using the plug-in homebridge-cmd4.

No affiliation with Advantage Air.

Supported Control Units:

Note: zone10 and MyAir3 do not appear to work with this plug-in.

  • Extras:
    • MyPlace
      • Lights
      • Garage Door
      • Gate
      • Motion Sensors
      • Blinds

Note: Config for these extras can be found here.

How It Looks:

Air Conditioning - Thermostat Mode (with Fan Speed) and Fan or FanSwitch Mode:

Air Conditioning - Zone Control and Temperature Sensors:

Air Conditioning - Zone Control without Temperature Sensors:

MyPlace Extras - Lights:

MyPlace Extras - Garage Door / Gate:

Note: Garage Door / Gate will appear in Apple CarPlay.

Installation:

Raspbian/HOOBS/macOS/NAS:

  1. Install Homebridge via these instructions for Raspbian, HOOBS or macOS.

  2. Install the homebridge-cmd4 plug-in via the Homebridge UI 'plugins' tab search function. Once installed, a pop-up box with a small config in it will appear. Do not edit anything and make sure you click SAVE.

  3. Install homebridge-cmd4-AdvantageAir plug-in via the Homebridge UI 'plugins' tab search function.

  4. Install jq via your Homebridge UI terminal or through ssh:

# Raspbian/Hoobs:
sudo apt-get install jq

# macOS:
brew install jq

# Synology NAS:
apt-get install jq

# QNAP NAS:
apk add jq
  1. Check if curl is installed (it should already be):
curl -V
  1. If curl does not return a version number, install via:
# Raspbian/Hoobs:
sudo apt-get install curl

# macOS:
brew install curl

# Synology NAS:
apt-get install curl

# QNAP NAS:
apk add curl
  1. Automatically create your Homebridge config.json:
  • Homebridge users with access to the Homebridge web UI can jump ahead to Step 8.
  • Homebridge users without access to the Homebridge web UI can use the following terminal instructions.
  • HOOBS users do not have access to our Homebridge UI (for now!) and will have to use the following terminal instructions.

  1. Go to the 'plugins' tab in Homebridge UI and locate your newly installed homebridge-cmd4-AdvantageAir. Click SETTINGS > Config and it should launch the 'Advantage Air Configuration Creator'.

  2. Scroll down to the 'AdvantageAir Device Settings' area and fill out the Name, IP Address and PORT used fields (default PORT is 2025 for most users, Fujitsu anywAIR users set this to 10211 ). If you have more than one Advantage Air tablet, you can click Add new device to setup the others. Click SAVE when done editing, it will close the UI and you will need to open it once more as per Step 8 before proceding further.

  3. Check/uncheck the the following checkboxes/radio-buttons to select your preferred setup options, then press the CONFIG CREATOR button to create your Advantage Air config.

    • Use a "Switch" accessory as "On/Off" control for "Fan" state:

    "FanSwitch" setup allows the current fanSpeed to be displayed on Homekit tile when the Aircon is On and is in Cool, Heat or Dry (Auto) mode.

    • Include fancy timers to turn-on the Aircon in specific mode: Cool, Heat or Vent:

    This will generate extra timers to turn-on the Aircon in specidic mode: Heat, Cool or Vent.

    Zone Control setup options:

    • Use "Lightbulb/Switch" * accessory with standalone temperature and myZone switch (legacy):

      For systems with Temperature Sensors, this option will use the Switch accessory for Zone Control and a separate TemperatureSensor for the temperature info. If myZone is defined, a standalone myZone switch will also be configured.

      For systems without Temperature Sensors, this option will use the Lightbulb accessory for Zone Control.

    • Use "Lightbulb/Switch" * accessory with integrated temperature but standalone myZone switch:

      For systems with Temperature Sensors, this option will use the Switch accessory for Zone Control and integrate a linked TemperatureSensor for the temperature info. The advantage of this option is to be able to see the zone temperature displayed on the zone itself. If myZone is defined, a standalone myZone switch will also be configured.

      For systems without Temperature Sensors, this option will use the Lightbulb accessory for Zone Control.

    • Use "Lightbulb" accessory with integrated temperature but standalone myZone switch:

      For systems with Temperature Sensors, this option will use the Lightbulb accessory for Zone Control and integrate a linked TemperatureSensor for the temperature info. The advantage of this option is to have the temperature info and the "zone % open" displayed on the zone itself. Please note that the Brightness which is a proxy for "zone % open" is not user controllable as per AdvantageAir design. If myZone is defined, a standalone myZone switch will also be configured.

      For systems without Temperature Sensors, this option will use the Lightbulb accessory for Zone Control and the Brightness which is a proxy for "zone % open" is user controllable.

    • Use "Fan" accessory with integrated temperature and myZone switch (recommended):

      For systems with Temperature Sensors, this option will use the Fanv2 accessory for Zone Control with Fanv2's RotationDirection charateristic being repurposed as the myZone switch and integrate a linked TemperatureSensor for the temperature info. The advantage of this option is to have the temperature info & the "zone % open" displayed on the zone itself and able to set this zone as myZone if it hasn't been set yet. Please note that the Speed which is a proxy for "zone % open" is not user controllable as per AdvantageAir design. Please also note that once myZone is set, you cannot unset it. You have to set another zone as myZone to unset it.

    For systems with no Temperature Sensors, there will be no button switch and no temperature info but the Speed which is a proxy for "zone % open" is user controllable.

  4. Click CHECK CONFIGURATION. It will check over your installation and config to make sure you have everything correct. On a success it will say Passed; if something is incorrect, an error message will pop up telling you what it is that you have missed and need to fix.

  5. If you have Cmd4 v7.0.0-beta2 or v7.0.1 or v7.0.2 installed, an optimised version of Cmd4PriorityPollingQueue.js module which will give you some improvements in performance, will be installed as part of the ConfigCreator process at step 10.

    A feedback messages from ConfigCreator of "COPIED and DONE!" is an indication of sucessful installation.

    A feedback messages from ConfigCreator of "NOT COPIED but DONE!" is an indication of unsucessful installation of the optimised module but the config was generated sucesscully. If this happens, a script copyEnhancedCmd4PriorityPollingQueueJs.sh will be created in <config.json storage path> directory and you can run it to get it installed manually.

    The <config.json storage path> directory is the directory where "config.json" is stored. For Raspbian installation, it is typically /var/lib/homebridge. For Mac users, it is typically $HOME/.homebridge. For HOOBS users, it is typically /var/lib/hoobs/<bridge>.

    Restart homebridge for the change to take effect.

    Please note that if this optimised version of Cmd4PriorityPollingQueue.js module is not installed, this plugin will still work fine but slightly less efficient.

Windows OS

I have not successfully set this up on a Windows OS Homebridge server yet. If you have and want to contribute; please reach out and let me know how you did it. Otherwise I strongly suggest you buy a dedicated Raspberry Pi for Homebridge.

Further Notes

You can read more about this project and how to create your config on the Wiki page.

How You Can Help:

  • Open Issues/Tickets.
  • Report Bugs/Errors.
  • Suggest Improvements and Features you would like to see!
  • Help test the beta releases! See the Wiki to find out how to 'sign up'.
  • Create a fork, add or fix something yourself and create a Pull Request to be merged back into this project and released!
  • Let me know if you have a Control Unit or App that works that is not confirmed in my Supported List!
  • Let me know if you can figure out how to get this running on Windows 10/11 Homebridge.
  • Feel free to let me know you are loving the project by give me a Star! It is nice to have an idea how many people use this project!

Special Thanks:

  1. The evolution, improvements and continuously tireless work of John Talbot, who has not only improved these shell scripts beyond measure and created the Homebridge UI integration; but continues to improve homebridge-cmd4 to further cater to this work and my end users.
  2. The hard work and valued coding experince of Ung Sing Wong that has led to the many amazing features in a short space of time; and no doubt more to come in the future!
  3. This would never have kicked off without the patience and kindness of TimofeyK helping out a new starter find his feet.
  4. Lastly, but certainly not least, is my beautiful Wife who has put up with what has become an obsession of mine to get our air conditioner and many other devices into Homekit. May she forever be misunderstood by Siri for my amusement...

LICENSE:

This plugin is distributed under the MIT license. See LICENSE for details.