Converting from Geoff's version, and why new fork vs. upstreaming changes?

[rkboni]

Hello,

I just found this repo and see there are a lot of exciting changes from https://github.com/geoffdavis/esphome-mitsubishiheatpump. I do have some questions:

1. For the changes to the SwiCago, why not upstream them so other projects can also benefit?
2. I guess I could ask the same about trying to upstream the component's changes vs. creating a separate fork of https://github.com/geoffdavis/esphome-mitsubishiheatpump.
3. And finally, is there a guide for upgrading from https://github.com/geoffdavis/esphome-mitsubishiheatpump to this component? I guess if I just update the YAML for one of my devices that should do it, correct? Any other caveats for that process?

Sorry if I sounds critical, but am curious why we can't have one great library and one great ESPHome component.. but this does look like a great set of cleanups, so thanks for all the work!

[sjwright]

As a layperson—

1. It appears that the person who wrote this significantly refactored the HeatPump.cpp code from SwiCago. I can only assume they had a good reason to do this, as it would have been pointless drudge work otherwise. I am not a C++ programmer or an embedded programmer so I'm not able to pass judgement on the choices made, or the quality of anyone's code. However it seems the LGPL 2.1 license notice from SwiCago hasn't been retained. Unless this is a clean room reimplementation (seems unlikely) this repo needs to be licensed under LGPL 2.1 or a compatible license.

2. Being a separate repo is reasonable because it's a significant, breaking change.

3. Worked for me. No harm in trying. If it doesn't work, you can always roll back.

[echavet]

Hey everyone,

I’ll try to keep this brief.

The idea of starting a new repository came from a fundamental difference in the integration of the SwiCago library. This library heavily relies on delay instructions to give the air conditioner time to respond to requests. Aside from the reliability issues linked to this approach in the context of a communication protocol, this method doesn’t meet the requirements of the esphome framework.

The changes were so significant that a traditional fork wasn’t an option. A merge wouldn’t have been possible at all! Moreover, this firmware is compatible with ESP32 chips, which wasn’t the case with Geoff Davis’s version.

Geoff and I considered merging our projects, but the amount of work involved is substantial, and the benefits remain questionable.

So, it’s indeed a fundamental paradigm shift that led to this project.

As for the LGPL license, I must admit I have no knowledge of it and no desire to delve into these considerations. Any help on the topic would be appreciated!

[sjwright]

The license for the SwiCago library is in a comment at the top of the source files:
https://github.com/SwiCago/HeatPump/blob/master/src/HeatPump.h

/*
  HeatPump.h - Mitsubishi Heat Pump control library for Arduino
  Copyright (c) 2017 Al Betschart. All right reserved.
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

First, notice this—

Copyright (c) 2017 Al Betschart. All right reserved.

Software licensed under GPL / LGPL is still the copyright property of its author. The license is what allows you to use and modify their code.

Second, this—

you can redistribute it and/or
modify it under the terms of the
[LGPL version 2.1]

The LGPL says "if you accept this license, you may to do anything you want in private, but distributed copies or modifications or derivative works must all be similarly licensed." Put simply, you must license any code derived from HeatPump.h/cpp under the same license. (Or a compatible license, but for the sake of simplicity, just stick with LGPL 2.1 because it's a great fit for this kind of project.)

You should declare copyrights at the top of all source files. Any files derived from HeatPump.h/cpp should include Al Betschart's copyright statement along with your own, e.g.:

/*
  MitsubishiCN105ESPHome
  Copyright (c) 2024 Eric Chavet. All right reserved.
  Portions of this code were derived from SwiCago/HeatPump
  Copyright (c) 2017 Al Betschart. All right reserved.

  ...etc
*/

The same applies if you copied anything from esphome-mitsubishiheatpump. Geoff Davis licensed his work under a very simple "BSD two clause" license. It is legally permissible to treat Geoff's BSD-licensed work as though it was LGPL, which is my suggestion because it keep things simple for you. (It's complicated enough as it is!)

Acknowledging Geoff's contribution with a copyright line is sufficient and respectful. For any files where Geoff's work can be found, the statement could read:

/*
  MitsubishiCN105ESPHome
  Copyright (c) 2024 Eric Chavet. All right reserved.
  Portions of this code were derived from esphome-mitsubishiheatpump
  Copyright (c) 2020 Geoff Davis. All right reserved.

  ...etc
*/

For any source files which are entirely your own work, you're free to do (or not do) anything you like. My suggestion is to license it all under LGPL because it makes things as simple as they can be. It's a very permissive license which won't inconvenience anyone who wishes to use it, fork it, or do whatever, so long as it's done in the spirit of open source. It doesn't even stop someone from using this code as the basis of a commercial AC controller product—the LGPL merely requires them to release source code alongside binaries.

As for how to go about tagging this properly in GitHub, this seems to be a relevant guide:
https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository

[sjwright]

By the way, I'd like to offer my gratitude for the work you've done Eric, and to Geoff and especially to Al for getting the protocol working in the first place. I'm currently building a new home and my rental has a Mitsubishi Electric MSZ-AP. I've been so impressed by the robust nature of the SwiCago library running inside ESPHome that I amended my building plans to specify Mitsubishi Electric instead of Daikin.

(I had even bought a couple of Faikin controllers in preparation, and set them up in my parents' house. It works, but it's not perfect. It feels like the code is fighting Daikin whereas SwiCago and its derivatives seem to work perfectly for me 100 percent of the time.)

[echavet]

Thanks for the feedback. It's good to read!
I will refactor the code to integrate the license terms like you mentioned.

[rkboni]

Thanks @echavet and @sjwright and I'd like to second the tanks to Geoff and Al for the work done there -- even with the timer-based original code, the functionality this enabled for the cost of a ESP8266 or an ESP32 and a few other components was fabulous!

Eric, thanks for describing the rationale for the forks (vs upstreaming) and for working with Geoff to see what could be done there, makes me doubly glad I asked 😁

Most of all, thanks for inspiring a new community to hack on this, development seems to be quite active, so I can't wait until I have some time to convert my units over to running this component!

Cheers!