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

No affiliation with Advantage Air or any of their products.

Supported Control Units:

• Confrimed:
  • e-zone
  • MyAir
  • MyAir3
  • MyAir4
  • zone10e
• Unconfirmed:
  • MyPlace
  • zone10

How It Looks:

Installation:

Raspbian/HOOBS:

1. Install Homebridge.
2. Install the homebridge-cmd4 plug-in through the Homebridge web UI or via terminal command:sudo npm install -g --unsafe-perm homebridge-cmd4. NOTE: you do not need to follow the extra installation steps on cmd4's page for this.
3. For users with only One Constant Zone (single storey home), the script is the same for users with or without Temperature Sensors. For users with Two Constant Zones you will have to navigate through 'Old Scripts' directory to find your relevant scripts (there will be two scripts for these users); upgrading the Two Constant Zones scripts is on the To-Do List.
4. Edit AdvAir.sh with the IP address of your Advantage Air controller. If you have two constant zones, then you will need to edit your IP Address and Constant Zones at the top of ezone.sh and zones.sh (you still need to use two scripts sorry!).
5. Copy AdvAir.sh (or ezone.sh and zones.sh for Two Constant Zone Users) to a subdirectory of your .homebridge directory; e.g. .homebridge/Cmd4Scripts/AdvAir.sh. I suggest doing this from the web UI terminal (... top, right hand corner). Mine file is located in /home/pi/AdvAir.sh.
6. OR if you are less savvy like me, you can create the script in your homedrive (type cd in your terminal and hit enter to get there) of your Raspberry Pi using sudo nano AdvAir.sh and pasting the contents inside, then saving. Its pathway in this case to be used in our config will be /home/pi/AdvAir.sh. For HOOBS users this would create your shell scripts at the lcation: /home/hoobs/.hoobs/AdvAir.sh.
7. Install jq; sudo apt-get install jq. Make sure curl is installed (it should already be installed).
8. Edit your homebridge config.json using the samples included in each directory for your appropriate setup; this should be completed from the Homebridge web UI. NOTE: Two devices cannot have the exact same name in your config. A switch and temperature sensor cannot both be named 'Kitchen' for example.
9. Restart Homebridge.

macOS

1. Install Homebridge.
2. Install the homebridge-cmd4 plug-in through the Homebridge web UI or via terminal command:sudo npm install -g --unsafe-perm homebridge-cmd4. NOTE: you do not need to follow the extra installation steps on cmd4's page for this.
3. For users with only One Constant Zone (single storey home), the script is the same for users with or without Temperature Sensors. For users with Two Constant Zones you will have to navigate through 'Old Scripts' directory to find your relevant scripts (there will be two scripts for these users); upgrading the Two Constant Zones scripts is on the To-Do List.
4. Edit AdvAir.sh with the IP address of your Advantage Air controller. If you have two constant zones, then you will need to edit your IP Address and Constant Zones at the top of ezone.sh and zones.sh (you still need to use two scripts sorry!).
5. Copy AdvAir.sh (or ezone.sh and zones.sh for Two Constant Zone Users) to a subdirectory of your .homebridge directory; e.g. .homebridge/Cmd4Scripts/AdvAir.sh. I suggest doing this from the macOS terminal like how you installed Homebridge. When I tested this on my wife's MacBook; mine was located in /Users/hername/AdvAir.sh.
6. OR if you are less savvy like me, you can create the script in your homedrive (type cd in your terminal and hit enter to get there) of your MacBook using sudo nano AdvAir.sh and pasting the contents inside, then saving. Its pathway in this case to be used in our config will be /Users/hername/AdvAir.sh.
7. Install jq; brew install jq (you may need to install brew first or you may use port).
8. Install curl; brew install curl
9. Edit your homebridge config.json using the samples included in each directory for your appropriate setup; this should be completed from the Homebridge web UI. NOTE: Two devices cannot have the exact same name in your config. A switch and temperature sensor cannot both be named 'Kitchen' for example.
10. Restart Homebridge.

Windows 10

I have not successfully set this up on Windows 10 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.

About:

Due to the current limitations in Homekit, multi-zoned ducted air conditioners are not represented as a single accessory. Our work around here is two create multiple accessories:

• A Thermostat with modes OFF/HEAT/COOL using the Advantage Air 'constant' zone (usually zone 1 in a one 'constant zone' setup) as the measured temperature for feedback. NOTE: AUTO mode in Homekit is not used in Advantage Air controllers, so it will set the controller to OFF. Setting DRY mode from the controller will then represent in Homekit as OFF.
• A simple Fan with modes OFF/ON (for the time being) for the controller's FAN mode. NOTE: Turning the Fan accessory on in Homekit will turn off the Thermostat accessory, and turning the Thermostat accessory on in homekit will turn off the Fan Accessory. When the Fan is turned on in Homekit, it will also execute the AUTO mode in the respective Advantage Air app; just to keep it simple for now.
• Temperature Sensors with feedback from each zone. These also include the FAULT status in the accessory, this is determined by the error codes produced by the controller. NOTE: According to the Advantage Air developers there is only one fault code; which is used for low battery, dead battery and loss of connection to sensor. I could not get any further information about this and have only seen one fault myself.
• A sample version of the config.json has been added for users who do not have the Temperature Sensors.
• Versions of the shell scripts have been added for users who have two 'constant zones' (two storey house typically). According to Advantage Air only one constant zone has to be on at any time; some logic has been added to the shell scripts for two 'constant zones' to either shut off the zone or turn off the entire controller based on if the other 'constant zone' is open or not; to make sure your air conditioner and ducting are protected.
• Switches with feedback to open and close each zone. NOTE: I do not recommend adding your 'constant zones' (usually zone 1, but there can be a second; represented as a 'C' in the app) as a Switch in Homekit as this zone is not meant to be turned off. I am not responsible for any damage to your ducting if you do manage to shut this zone (not sure it is possible, but just in case) and run the air conditioner.

How to Keep Up-To-Date:

As this is not a typical homebridge plug-in, you will not get prompted to update when I add improvements. The best way to keep up-to-date is to click the Watch button in the top right corner and select All Activity or Custom and then Releases. This will ensure you get an email everytime I push a new release with new features or improvements! Feel free to give me a Star as well if you are happy with the work.

How You Can Help:

• Open Issues/Tickets.
• Report Bugs/Errors.
• Suggest Improvements and Features you would like to see!
• 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 Homebridge.
• Feel free to let me know you are loving set up!

Further Notes:

• I have only tested this on my own E-zone Advantage Air controller, but the API is exactly the same for MyAir and the named devices at the begining of this README; that is actually where I was able to get the commands and learn how to structure them properly. The API can be found here once you have registered.
• I am not very savvy with all of this coding work and had a lot of help and direction as I 'learn as I go'; this was a learning curve for me but I plan to keep working on this and improving it.

Potential Device Limitations:

What we have discovered from over 8 months of trying to improve performance and reduce homebridge/cmd4 log warnings:

"The air conditioner controller returns successfully incomplete system data when it is in use by the operator and also incomplete system data if any 'Set' operation is in progress. The scripts that send/receive data from the air conditioner controller must not only retry on failures, but also check the validity of the data as the incomplete system data returned presents a successful return code. Even with these features built into the scripts, Cmd4 has implemented a queuing system such that any polling or queries from HomeKit would only send a setValue when no other operation was in progress. This feature in Cmd4 is the WoRM (Write once Read many) queue. While Cmd4 can then manage all traffic to the air conditioner controller, it cannot know if someone is actually interacting with the control tablet. When interacting with the control tablet and Cmd4 is trying to send/receive data simultaneously, errors are unavoidable. Cmd4 hides these unavoidable errors in debug mode as it retries the transaction and in this way presents a clean console that otherwise would cause panic to the operator." - John Talbot.

Special Thanks:

1. The evolution, improvements and continuously tireless work of John Talbot, who has not only improved these shell scripts beyond measure; but continues to improve homebridge-cmd4 to further cater to this work and my end users.
2. This would never have kicked off without the patience and kindness of TimofeyK helping out a new starter.
3. 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:

See LICENSE