Merge pull request #22 from krahabb/dev

Add HTTP protocol mode and support for MSL120 MSH300 MS100 MTS100

.devcontainer/devcontainer.json

@@ -4,7 +4,8 @@
 	"name": "Blueprint integration development",
 	"context": "..",
 	"appPort": [
-		"9123:8123"
+		"9123:8123",
+		"67:67/udp"
 	],
 	"postCreateCommand": "container install",
 	"extensions": [

README.md

@@ -5,9 +5,11 @@
 
 # Meross LAN
 
-This [homeassistant](https://www.home-assistant.io/) integration allows you to control your *Meross* plugs all over your LAN without any need for cloud connectivity. It works through your own MQTT broker (or any other configured through the homeassistant mqtt integration).
+This [homeassistant](https://www.home-assistant.io/) integration allows you to control your *Meross* devices all over your LAN without any need for cloud connectivity. It supports communication through your own MQTT broker (or any other configured through the homeassistant mqtt integration) or directly via HTTP.
 
-In order for this to work you need to bind your *Meross* appliances to this same MQTT broker. Follow the guide at https://github.com/bytespider/Meross/wiki/MQTT to re-configure your devices and start integrating them locally from the HA Integrations page
+These are the two main use cases:
+- Keep your devices paired with the offical Meross App (and cloud infrastructure) and communicate directly to them via HTTP. This will allow for greater flexibility and less configuration pain since you don't have to setup and configure the MQTT pairing of these devices. The integration will just 'side-communicate' over HTTP to the devices and poll them for status updates. (This is different from https://github.com/albertogeniola/meross-homeassistant since my componenent does not talk to the Meross Cloud service so it doesn't use credentials or any)
+- Bind your devices to your 'private' MQTT broker so to completely disconnect them from the Meross infrastructure and interact only locally (The procedure for MQTT binding is here: https://github.com/bytespider/Meross/wiki/MQTT or better, you can use the pairer app from @albertogeniola at https://github.com/albertogeniola/meross_pair )
 
 HAVE FUN! 😎
 
@@ -30,45 +32,51 @@ Restart HA to let it play
 
 ## Setup
 
-Make sure your *Meross* plugs are correctly connected to the MQTT broker by checking they are effectively publishing state updates. 
+Once installed and restarted your Meross devices should be automatically discovered by the 'dhcp' integration and will then pop-up in your integrations panel ready to be configured (the exact timing will depend since the dhcp discovery has different strategies but a simple boot of the device should be sufficient even if not necessary)
 
-The best test here is to enter the mqtt integration configuration in HA and subscribe to all topics to see if your HA instance is receiving the relevant messages by listening to the `/appliance/#` topic since *Meross* devices will publish to a subdomain of this one. 
+If you are using the 'MQTT way' you can help the discovery process by adding the 'MQTT Hub' feature of this integration (This was needed in the previous versions while you should be able to skip this step if the dhcp discovery works fine). If you need, just go to your homeassistant `Configuration -> Integrations` and add the Meross LAN by looking through the list of available ones. Here you can configure the device key used to sign the messages exchanged: this need to be the same key used when re-binding your hardware else the integration will not be able to discover new devices (dhcp discovery should instead work anyway: the key will be asked and set when configuring every single appliance)
 
-Manually switch your plug and check if you received any message in your MQTT configuration pane. The topic should be something in the form `appliance/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/publish/` where the `XXX...` is the device identifier which is unique for every appliance.
+You can also manually add your device by adding a new integration entry and providing the host address.
 
-Once you are set up with the MQTT integration and device pairing, you can go to your homeassistant `Configuration -> Integrations` and add the Meross LAN by looking through the list of available ones.
-
-When you add it the first time, it will setup a 'software hub' (you will see the 'MQTT Hub' name on the configured integration) for the devices so it can start listening for MQTT messages from your Meross devices. If you configured your device to use a *key* different than *''* you can configure the 'MQTT Hub' accordingly by setting a key in the 'Options' pane for the configuration entry of the integration
-
-You can now start adding devices by manually toggling them so they *push* a status message to the broker and then to HA: you will receive a notification for a discovered integration and you will be able to set it up by clicking 'Configure' on the related panel in the Integrations page. Confirm and you are all done. In case of bulbs just plug/unplug them so they'll broadcast some status to the mqtt when my hub is listening
-
-If everything goes the way should, the component will be able to auto detect the device and nothing need to be done. The optional device *key* you configured for the hub will be propagated to the discovered entry and 'fixed' in it's own configuration so you can eventually manage to change the key when discovering other appliances
-
-If your device is not discovered then it is probably my fault since I currently do not have many of them to test
+When configuring a device entry you'll have the option to set:
+- host address: this is available when manually adding a device or when a device is discovered via DHCP: provide the ip address or a valid network host name. When you set the ip address, ensure it is 'stable' and not changing between re-boots else the integration will 'loose' access to the device
+- device key: this is used to sign messages according to the official Meross protocol behaviour. Provide the same key you used to re-configure your appliance or, in case you're side-communicating and/or don't know the key leave it empty: this way the HTTP stack will be instructed to 'hack' the protocol by using a simple trick
 
 
 ## Supported hardware
 
-At the moment this software has been developed and tested on the Meross MSS310 plug and MSL100 bulb. I have tried to make it the more optimistic and generalistic as possible based on the work from [@albertogeniola] and [@bytespider] so it should work with most of the plugs out there but I did not test anything other than mines
+Most of this software has been developed and tested on my owned Meross devices which, over the time, are slowly expanding. I have tried to make it the more optimistic and generalistic as possible based on the work from [@albertogeniola] and [@bytespider] so it should work with most of the hardware out there but I did not test anything other than mines. There are some user reports confirming it works with other devices and the 'official' complete list is here:
 
 - Switches
   - [MSS310R](https://www.meross.com/product/38/article/): power plug with metering capabilties
   - [MSS425](https://www.meross.com/product/16/article/): Smart WiFi Surge Protector (multiple sockets power strip)
 - Lights
-  - [MSL100R](https://www.meross.com/product/4/article/): Smart bulb with dimmable light
+  - [MSL100](https://www.meross.com/product/4/article/): Smart bulb with dimmable light
+  - [MSL120](https://www.meross.com/product/28/article/): Smart RGB bulb with dimmable light
+- Hub
+  - [MSH300](https://www.meross.com/Detail/50/Smart%20Wi-Fi%20Hub): Smart WiFi Hub
+- Sensors
+  - [MS100](https://www.meross.com/Detail/46/Smart%20Temperature%20and%20Humidity%20Sensor): Smart Temperature/Humidity Sensor
+- Thermostats
+  - [MTS100](https://www.meross.com/Detail/30/Smart%20Thermostat%20Valve): Smart Thermostat Valve
 - Covers
   - Support for garage door opener and roller shutter is implemented by guess-work so I'm not expecting flawless behaviour but...could work
 
 
 ## Features
 
-The component exposes the basic functionality of the underlying device (toggle on/off, dimm, report consumption through sensors) without any other effort, It should be able to detect if the device goes offline suddenly by using a periodic heartbeat on the mqtt channel (actually 5 min). The detection works faster for plugs with power metering since they're also polled every 30 second or so for the power values.
+The component exposes the basic functionality of the underlying device (toggle on/off, dimm, report consumption through sensors) without any other effort, It should be able to detect if the device goes offline suddenly by using a periodic heartbeat.
+It also features an automatic protocol switching capability so, if you have your MQTT setup and your broker dies or whatever, the integration will try to fallback to HTTP communication and keep the device available returning automatically to MQTT mode as soon as the MQTT infrastructure returns online. The same works for HTTP mode: when the device is not reachable it will try to use MQTT (provided it is available!). This feature is enabled by default for every new configuration entry and you can control it by setting the 'Protocol' field in the configration panel of the integration: setting 'AUTO' (or empty) will do the automatic switch. Setting any fixed protocol 'MQTT' or 'HTTP' will force the use of that option (useful if you're in trouble and want to isolate or investigate inconsistent behaviours). I'd say: leave it empty or 'AUTO' it works good in my tests.
+
+If you have the MSH300 Hub working with this integration, every new subdevice (thermostat or sensor) can be automatically discovered once the subdevice is paired with the hub. When the hub is configured in this integration you don't need to switch back and forth to/from the Meross app in order to 'bind' new devices: just pair the thermostat or sensor to the hub by using the subdevice pairing procedure (fast double press on the hub)
 
+I'm sorry to not be able to write a complete wiki at the moment in order to better explain some procedures or share my knwoledge about the devices but time is constrained and writing knwoledge bases is always consuming (and sligthly boring I admit). I'm still working on some features and I've put a big effort trying to ensure a frictionless working of this software so I hope you can make use of it without deeper explanations. Something will come, slowly, but if you have any urgent issue or question I will be happy to help (and maybe this will speed up the documentation :)
 
 ## Service
 
-There is a service (since version 0.0.4) exposed to simplify communication with the device and play with it a bit. It basically requires the needed informations to setup a command request and send it over MQTT without the hassle of signatures and timestamps computations. You can check it in the 'Developer Tools' of the HA instance, everything should be enough self-explanatory there. 
+There is a service (since version 0.0.4) exposed to simplify communication with the device and play with it a bit. It basically requires the needed informations to setup a command request and send it over MQTT or HTTP without the hassle of signatures and timestamps computations. You can check it in the 'Developer Tools' of the HA instance, everything should be enough self-explanatory there. 
 I find it a bit frustrating that the HA service infrastructure does not allow to return anything from a service invocation so, the eventual reply from the device will get 'lost' in the mqtt flow. I've personally played a bit with the MQTT integration configuration pane to listen and see the mqtt responses from my devices but it's somewhat a pain unless you have a big screen to play with (or multiple monitors for the matter). Nevertheless you can use the service wherever you like to maybe invoke features at the device level or dig into it's configuration
+*WARNING*: the service name has changed from 'mqtt_publish' to 'request' to accomodate the more general protocol support
 
 
 ## References