Merge pull request #614 from iranl/auth-enhance

Duo Push MFA, Coredump saving to flash, remove last_action_authorization and keypad_status from HA, improve HA availability topics

DUOAUTH.md

@@ -0,0 +1 @@
+## Duo Push authenticationNuki Hub supports the use of the [Cisco Duo Auth API](https://duo.com/docs/authapi) for Multi-factor authentication (MFA).Cisco Duo can be used for free with unlimited pushes using Duo Push authentication with the Duo application running on an Android device or iPhone.## Setup- Signup for a [free Duo account](https://duo.com/editions-and-pricing/duo-free) at https://signup.duo.com/- Follow the guided Duo setup to create an administrator account- Optionally add a separate user specifically for Nuki Hub.- On the user page add a Phone to the user and follow the instructions to setup and authorize the Duo app on an Android device or iPhone.- In the Duo Admin panel go to "Applications" and select "Protect an Application"- Search for "Partner Auth API" and click "Protect"- Optionally change the name to "Nuki Hub" under settings and click "Save"- Enter the Integration key, Secret key and API hostname on the "Credentials" page of Nuki Hub by using the buttons to copy the unredacted values.- Enter the username of your Duo user that you want to receive the push notification in the "Duo user" field in Nuki Hub- Check the box next to "Duo Push authentication enabled"- Optionally check the box next to "Require Duo Push authentication for all sensitive Nuki Hub operations" to require Duo Push approval on all sensitive Nuki Hub operations (changing/exporting settings)- Optionally (but very much preferred) set HTTP authentication type to "Form"- Click "Save"- Approve the Duo Push notification on your device. Note: If the first authentication after a change to these settings fails or is not approved (in time), MFA will be disabled to prevent a lockout.- Reboot the Nuki Hub device, logout and confirm that you are required to reauthenticate using Duo Push (and your Nuki Hub username and password)

HYBRID.md

@@ -2,6 +2,28 @@
 
 The purpose of this mode is to have Nuki Hub work in conjunction with the official MQTT implementation by Nuki.
 
+For Nuki Hub to work properly it is essential that Nuki Hub is notified by the lock of state changes (e.g. locking/unlocking) as soon as possible.
+Starting from the first versions of Nuki Hub this was achieved by registering Nuki Hub as a Nuki Bridge.
+
+When a Nuki Bridge is registered with a Nuki lock or opener the device will signal state changes using a Bluetooth Low Energy (BLE) iBeacon.
+If this state change is seen by Nuki Hub the Nuki Hub device will connect to the lock/opener over BLE and receive additional information about the state change.
+The beacon itself contains no information other than that a state change has occured.
+After the Nuki Bridge device (e.g. Nuki Hub in this case) has connected and requested the state change report the Nuki device will reset the iBeacon state to the "unchanged" state.
+
+With the introduction of WiFi/Thread and MQTT enabled locks there now was a second method of retrieving state changes, which we call "Hybrid mode".
+In Hybrid mode Nuki Hub subscribes to the MQTT topics that the Nuki lock writes to itself using the official Nuki MQTT implementation over WiFi/Thread.
+Nuki Hub will now pick up state changes from these official MQTT topics. 
+Part of these state changes is directly proxied to Nuki Hubs own MQTT topics (that your smart home system (e.g.) HomeAssistant is subscribed to) making this (in practise) just as fast as connecting your smart home application directly to the official MQTT implementation.
+Nuki Hub will however also request additional information from the lock using BLE that is not available using the official Nuki MQTT implementation and publish this to Nuki Hubs MQTT topics.
+If you have setup Hybrid mode consider taking a look at the information published on the official MQTT topics (base path "nuki/") and comparing this with the information Nuki Hub publishes (base topic "nukihub/" by default)
+
+All functionality of Nuki Hub is available in both regular and hybrid mode.
+In hybrid mode Nuki Hub will automatically choose the best way to communicate with the lock for retrieving information from the lock and pushing information (e.g. lock/unlock commands, change settings) to the lock based on the capabilities of the MQTT API and Bluetooth API.
+When compared to regular/bridge mode this leads to speed increases in getting state changes and pushing state changes (because we can send and receive usefull information directly over MQTT without having to connect over BLE)
+When compared to the official MQTT implementation this adds many many features that are not available in the official MQTT implementation and would normally require you to use the app or Web API (which has its own issues, downtime and cloud requirement).
+
+**As the Nuki Smartlock Ultra has no support for the Nuki Bridge it is mandatory to setup Hybrid mode to receive prompt state changes from the lock in Nuki Hub.**
+
 ### Requirements ###
 
 - ESP32 running Nuki Hub 9.08 or higher
@@ -40,11 +62,12 @@ The Hybrid Official MQTT over Thread + Nuki Hub solution allows for the best com
 
 - Install Nuki Hub 9.08 or higher on a supported ESP32 device
 - Make sure you are not paired as a bridge. Unpair your Nuki lock in Nuki Hub if Nuki Hub was paired as a bridge (this is mandatory even if you removed the bridge connection from the Nuki lock).
-- Enable `Enable hybrid official MQTT and Nuki Hub setup`. The `Lock: Nuki Bridge is running alongside Nuki Hub (needs re-pairing if changed)` setting will be automatically be enabled.
+- Enable `Enable hybrid official MQTT and Nuki Hub setup`. The `Lock: Nuki Bridge is running alongside Nuki Hub (needs re-pairing if changed)` setting will automatically be enabled.
 - Optionally enable `Enable sending actions through official MQTT`, if not enabled lock actions will be sent over BLE as usual (slower)
 - Set `Time between status updates when official MQTT is offline (seconds)` to a positive integer. If the Nuki lock MQTT connection goes offline for whatever reason Nuki Hub will update the lock state with the set interval in seconds.
-<!--- Optionally enable `Retry command sent using official MQTT over BLE if failed`. If sending a lock action over the official MQTT implementation fails the command will be resent over BLE if this is enabled. Requires `Enable sending actions through official MQTT` to be enabled.!-->
+- Optionally enable `Retry command sent using official MQTT over BLE if failed`. If sending a lock action over the official MQTT implementation fails the command will be resent over BLE if this is enabled. Requires `Enable sending actions through official MQTT` to be enabled.
+- Optionally enable `Reboot Nuki lock on official MQTT failure`. If Nuki Hub determains that the official MQTT implementation is offline (usually because of the Nuki lock losing Thread/WiFi connection and not properly reconnecting) for more than 3 minutes Nuki Hub will try to reboot the Nuki lock (equivalent to removing and reinstalling the batteries).
 - Save your configuration
 - Consider setting the `Query intervals` on the `Advanced Nuki configuration` to high numbers (e.g. 86400) to further reduce battery drain.
 - Pair your Nuki Lock with Nuki Hub
-- Test that state changes are recieved and processed by Nuki Hub by looking at the MQTT topics using an application like `MQTT Explorer`
+- Test that state changes are recieved and processed by Nuki Hub by looking at the MQTT topics using an application like `MQTT Explorer`