Settings and Credentials

Settings and Credentials

These two files (Settings.h and Credentials.h) must be updated to match your environment prior to uploading the sketch to your ESP8266 board. These are provided as separate files so that future updates to the primary .ino file do not overwrite these options and require re-entry on each new version. Note however that while still in alpha/beta state, it is likely that updated settings and credential files may be released, forcing you to overwrite your current files. For this reason, it is recommended that you make backup copies of these two files outside of your sketch folder once you have updated them. You will then have a record of the settings should they need to be reapplied on a future update.

Credentials.h

This file holds your login information and other settings that are unique to your environment and that you will want to keep private. They are generally self-explanatory, but are describe here anyway:

DEFINE VALUE	DESCRIPTION
SID "your_SSID"	The SSID of your Wifi (must be same SSID as Tailwind
PW "your_password"	Your WiFi password
MQTTUSERNAME "your_mqtt_user"	User name for MQTT broker
MQTTPWD "your_mqtt_password"	Password for MQTT broker
MQTTPORT 1883	Port of MQTT broker
AP_SSID "tailwind_ap"	Optional hotspot to broadcast (see Settings)
AP_PWD "12345678"	Password for optional hotspot (see Settings)
TAILWIND_IP "192.168.1.45"	IP address of your Tailwind. This should be a static or DHCP reserved address.

Settings.h

These are settings and options you may wish to update for your install. They are listed in a summary table here, but described in more detail below.

SETTING/Example	Valid Values and Notes
WIFIMODE 2	0=AP mode only, 1=Wifi only, 2=both
MQTTMODE 1	0 or 1 - enable/disable MQTT
MQTTCLIENT "TailwindClient"	MQTT Client name - must be unique on your network
MQTT_TOPIC_SUB "cmnd/tailwind"	Default topic bridge listens on
MQTT_TOPIC_PUB "stat/tailwind"	Default topic bridge publishes to
OTA_HOSTNAME "tailwindOTA"	Hostname broadcast for OTA updates
ota_flag = true;	Enable or disable over-the-air updates
ota_boot_time_window = 2500;	Time (ms) to initialize OTA on boot
ota_time_window = 20000;	Window (ms) to start an OTA update
tailwind_poll = 10000;	How often (ms) to poll Tailwind
ha_discovery = true;	Enable/disable Home Assistant MQTT Discovery (v0.43 and later)
switch_delay_open = 5000;	Delayswitch state update until door open state change reported (ms) (v0.45 and later)
switch_delay_close = 20000;	Delay switch state update until door close state change reported (ms) (v0.45 and later)

Detailed settings descriptions

WIFI MODE The bridge can broadcast a local hotspot in addition to, or instead of, connecting to your WiFi Network. The hotspot broadcast will be the AP_SSID you defined in the Credentials.h file. Currently, this option must be set to either 1 or 2 to communicate with your MQTT broker and Tailwind. Option 0 is reserved for future use and potential uploading of BIN files where credentials and settings may be stored in flash memory.

MQTTMODE This enables or disables MQTT functionality. Obviously, it needs to be set to 1 for the bridge to function. Option 0 is reserved for future use.

MQTTCLIENT Each MQTT client on your network must have a unique name. This can be any string value you wish, as long as no other MQTT clients use that name.

MQTT_TOPIC_SUB This is the topic that the bridge will subscribe to (/#) and generally the topic you will use when issuing commands to Tailwind (e.g. open door, close door). It can be any valid MQTT topic and can be a simple or compound topic. For example, you could use a simple topic such as "tailwind" or compound such as "cmnd/tailwind" depending on how you wish to use or group your MQTT topics. Do not include a leading or trailing slash (/) in the topic. Commands issued to this topic should not have the retained flag set (retain=false), or ghost commands may occur upon reboot of the broker or bridge.

MQTT_TOPIC_PUB This is the topic that the bridge will report states and statuses (e.g. door status, command results, etc.). The topic follows the same naming rules as the MQTT_TOPIC_SUB. However, these topics will be sent with the retained flag set to true (retain=true), as the states need to be maintained between restarts and not expire, resulting in an unkown state.

ota_flag This enables or disables the ability to upload new code via over-the-air updates. If set to false updates must be performed via USB.

ota_boot_time_window (milliseconds) For the board to begin broadcasting via mDNS for OTA updates, the OTA process much be initialized for a short time on boot up. If too short, the board may not show up as a port in the IDE. Too long and it just delays the boot time. I've found about 2.5 seconds (2500 ms) is the sweet spot. If your board does not show up as a port in the IDE, you may need to tweak this time.

ota_time_window (milliseconds) When the board is placed into OTA mode for uploading (see OTA updating for how to do this), it enters a blocking mode. If an upload does not begin in this window, the OTA process is exited and the bridge returns to normal operation. However, since it is a blocking process, allowing too long of a window may result in the ESP8266 watchdog times causing a reboot of the board. I've found that 20 seconds (20000 ms) is a safe window to avoid reboots. But this does mean that you must have the code verified and ready to go as soon as the board is put into OTA update mode. You can experiment with this value, but if you notice the board rebooting before an OTA starts, trying shortening this window.

tailwind_poll (milliseconds) This is how often the bridge will poll the Tailwind device for any state changes. This value should not be set to less than 1 second (1000 ms), or it will be ignored and 1000 ms will be used. Setting this value to 5-10 seconds is probably acceptable for most cases. It can be set to longer times, but this will result in a delay between the time that the state of the door changes and the time it is reported via MQTT.

ha_discovery This enables or disables Home Assistant MQTT Discovery. If enabled, all available sensors are automatically created in Home Assistant and they do not need to be defined manually via YAML. See the Wiki topic MQTT \ Home Assistant for more details on the sensors that are created if this option is enabled. Only available in releases v0.43 and later.

switch_delay_open Because a Home Assistant switch both issues commands and shows the current state, a delay is necessary on updating the switch state when the switch is changed and the command to open the door is issued. This is because there is a slight delay (for me about 4-5 seconds) between issuing the command and when Tailwind actually opens the door and reports the state change. Without this delay, when toggling the switch to 'on' to open the door, the switch will also update status. Since the door status still is not technically open, the switch will bounce back to an off state temporarily until the door reports open and then the switch will bounce back to the 'on' state. This delay prevents this 'bouncing'. To determine the proper delay value for your install, measure the time it takes from when you issue the open command (either from the Tailwind app, by issuing an MQTT command, or just pushing the manual open button on your wall) and when Tailwind actually shows the door is open - or the app notifies you that 'Your Garage Door just opened'. Take this time round up, or maybe add a second. Enter this as the delay in milliseconds. For example, if you measure the time and find it is about 4 seconds on average, enter a delay value of 5000 (5 seconds). If you still experience switch bouncing when opening the door, add 1000 (1 sec) to this delay.

switch_delay_close This is very similar to the open delay above, but the delay will be significantly longer for the close operation. This is due to the fact that once the close command is received by Tailwind (other than from the original opener), it beeps for approximately 5 seconds as a safety warning before starting to close the door. Then there is the time it takes the door to physically close and the door sensor to register it is completely closed and the status is updated. So, once again, issue the closed door command (either via the Tailwind app or via MQTT - you cannot use the wall or original remote buttons in this case because those bypass the safety delay) and measure the time until the door shows a closed status (or Tailwind notifies you the door is closed). Again, add maybe 1 second to this value and enter the delay value in milliseconds (e.g. 20 seconds = 20000). If you still experience occasional switch bouncing in Home Assistant, increase this value by 1000 (1 second) until the bouncing ceases.