[RELEASE] Linktap Driver for Hubitat – Local Integration through MQTT

Introduction

This driver is for smart watering devices from Linktap (https://www.link-tap.com) with local network integration through the use of a MQTT broker. Linktap is currently working on a version of the firmware which allows local network integration using MQTT protocol. With this approach, Hubitat can issue commands and receive updates from Linktap devices without communicating outside the local network.

** UPDATES **
18 Jan 2022: The drivers are now available through Hubitat Package Manager as well.
18 Jan 2022: v1.1 released, which adds MQTT broker reconnection capability, as well as attributes that accumulate total water volumes on daily, weekly, monthly and yearly basis
23 Jan 2022: v1.2 released, Fixed issue with water volumes, added command for submission of rain data to gateway, changed child device logging

The default integration option officially supported by Linktap is through API exposed by their cloud server. This option though limits the possibility to integrate with Hubitat as it requires to open a local network port to listen to status updates from Linktap’s cloud server. On the other hand, it does not require an MQTT broker. I have also developer a driver for this integration option which you can find in a different post.

Pre-Requisites

  • One or more Linktap gateways setup in the local network. Gateways need to be setup using the Linktap App
  • A running MQTT broker in the local network. The drivers were tested using Mosquitto MQTT broker (https://mosquitto.org)
  • The beta version of the Linktap firmware with MQTT support installed on your gateway(s). You can contact Linktap for this, they were very helpful and supportive, and you should not have an issue to get them to push this firmware to your device

Supported Features

The initial version of the Hubitat drivers support the following capabilities:

  1. Recognize and create automatically in Hubitat all watering devices already setup and connected to a gateway
  2. Register a new watering device to an existing gateway
  3. Delete a watering device from one of the gateways
  4. Receive and store watering device status:
    4.1 Connection status
    4.2 Connection signal strength
    4.3 Battery status
    4.4 Flow meter connection status (for G2s)
    4.5 Valve status: open/closed
    4.6 Currently setup type of watering plan (e.g. instant)
    4.7 Current watering session details (duration, remaining, flow rate, water volume)
    4.8 Physical button lock (child lock)
    4.9 Alerts
  5. Start watering
  6. Start watering with parametric duration (in seconds)
  7. Stop watering
  8. Setup a scheduled watering (for a specific start date/time and duration)
  9. Delete a scheduled watering plan
  10. Enable/disable alerts from the device
  11. Clear/dismiss previously issued alerts from the device
  12. Retrieve current gateway date/time
  13. Device wireless test
  14. Send local rain data to gateway for rain skipping functionality

MQTT Connection Management

  • Allows scheduling a connectivity test every x seconds
  • If connectivity has been lost, the driver will automatically try to reconnect
  • You can specify the number of reconnection attempts. When this is reached, the driver will give up and reconnection should be performed manually

Watering volumes calculation

  • 4 new attributes to display daily, weekly monthly and yearly water volumes
  • Attributes are reset (respectively) at midnight (daily), sunday (weekly), 1st of the month (monthly) and 1st january (yearly) through a scheduled execution of a handler method

Not supported features

Linktap provides the option to have both cloud (App) and local (MQTT) integrations active. While several features work, especially related to device status and watering start/stop, simultaneous control through the two methods can create behavior inconsistencies, especially in what refers to registration/deletion of end devices. If you intend to keep the cloud integration active when setting up local integration, I strongly recommend that you setup all devices through the app only, and not through Hubitat.

The following features are supported by the Linktap gateway firmware, but not implemented in the Hubitat driver:

  • Other types of watering plans (e.g. Calendar, 7-day, Odd-even, Interval, Month). The input parameters for setting up these types of plans are complex and not suited to Hubitat UI, Rule Machine, etc.. If someone has a specific need, happy to evaluate the possibility of implementing some of these in the future.

The following features are not currently supported by the Linktap gateway firmware through MQTT integration:

  • Eco mode
  • Rain control
  • High flow alert
  • Low flow alert
  • Device model cannot be determined

The following features while supported have not been thoroughly tested (I only own one gateway and device):

  • Multiple gateways
  • Multiple devices per gateway
  • Alerts besides the water cut-off
  • Sync gateway time request

Installation

You can use Hubitat Package Manager (HPM) or manually as described below:

  1. Copy the code for the two drivers into Hubitat:
    1.1 Linktap MQTT Controller
    1.2 Linktap MQTT Taplinker
  2. Create a new Virtual Device of type Linktap MQTT Controller
  3. Enter the correct parameters for the configuration of the controller
    3.1 Broker IP: IP of the MQTT Broker
    3.2 Broker Port: Port of the MQTT Broker
    3.3 Username: Username for the client to connect to the MQTT Broker
    3.4 Password: Password for the client to connect to the MQTT Broker (note: I have not tested anonymous connection to MQTT broker, if required let me know to try to support it)
    3.5 Log Level:
    • 0: Error only
    • 1: Also Warnings
    • 2: Also Information (recommended)
    • 3: Also Debug
    • 4: Also Trace
  4. Press Save Preferences
  5. Connect to MQTT Broker by pressing the MQTTConnect button. Status and errors (if any) will be printed to log
  6. Configure each Linktap gateway (very important):
    6.1 Open the gateway configuration page, by entering the IP of the gateway in your local network in a browser
    6.2 Update the options as below, pressing Submit after filling in each table

    6.3 Reboot the gateway (button at the bottom of page)
  7. After rebooting each gateway, it should send a handshake message to the broker, which Hubitat will use to create all devices managed. These will appear as child devices of the Controller device
  8. You can change the name of the device if needed, it is not used for identification purpose (e.g. you can use Backyard, Patio, etc.)
  9. If you add later new devices through the App, you should also reboot the gateway to ensure the devices will be created in Hubitat also

Usage

In each child device, the supported commands and associated input parameters are available for execution. These should be self-explanatory, but if not feel free to drop a message below for any questions.

Notes:

  • Gateway ID always shows the first 16 digits without dashes
  • Device ID means the first 16 digits, without dahses, except when registering a new device, where the full 20 digits should be used (without dashes)
  • The driver implements a state variable to register or delete new child devices, to ensure actions are only applied in Hubitat after confirmation by the gateway. It prevents issuing a new registration or deletion command until the previous has either confirmed or failed. In case something goes wrong, there is a command in the Controller to erase the state variables and allow a new command to be sent.
  • You can also set/reset manually the water volume attributes through the driver
  • You can also post to the gateway rain volumes (past and forecast). This will then be used by the gateway to skip scheduled waterings according to the rules you set in the app. This will only work for watering plans set in the app, not scheduled instant watering created through the driver. This is useful in case you have access to local observation (e.g. a personal weather station) and forecast data and want to use it instead of the weather service used by Linktap.
5 Likes

I've been looking for an automated watering solution for a while, so this looks like a fun project - thanks!. I'll have to set up an MQTT broker, but a RPi Zero seems like it would work OK.

Which LinkTap device did you use? I'm looking at the G2S + Gateway

Also, is the driver available via HPM?

Hi, I developed and tested using the G2s. But the integration is not model dependent, so if you use another end device, most likely you just won't the info which is not supported by the device (like flow metering).

I will have to look into HPM, give me some days to see what I can do.

For MQTT broker, yes you can use a Rasperry Pi. Not sure about the zero, i am planning to setup a RPi 4 to also run other projects. All tests were done with Mosquitto running on a PC, but this should be irrelevant.

Cheers
Pedro

1 Like

Thanks Pedro! I have a Pi Zero already spare, so I'll try that first. If I can get MQTT working OK on that, I'll order a G2S :+1:

Ok let me know how you get on with the zero, so I know if it can be an option. Setting up Mosquitto in a PC is straightforward, what took me some time was to setup the authentication (Linktap gateway cannot connect to broker anonymously), but it is just a matter of reading the manual carefully :slight_smile:

So, i got impatient and got myself a Raspberry Pi Zero 2 W, setup mosquitto on it, using it for linktap integration. Much easier than I expected! So now I have local control of Linktap with hubitat, using a PWS, some soil humidity sensors, and Hubitat's Rule Machine.

Ah that's cool :+1:

I'm busy with life for the next couple of weeks so mine's going to have to wait a bit. Great to know it works though!

What soil sensors did you use?

I use Ecowitt WH51 (actually an european version called froggit dp100). I also have a personal weather station, and these sensors connect through the same gateway which provides local integration.

1 Like

Do you still use the Gateway?

Very curious about this, as my current remote water timer (Rainpoint) does not appear to be Hubitat controlled (without proxy through Alexa). The cost of this one is a little hard to chew.

Hi yes, you still need the gateway. You need only one gateway for multiple devices. The gateway connects to the MQTT broker providing control of all connected devices, and in its turn connects through radio to each device.

Device (Timer) <-radio-> Gateway <-MQTT-> MQTT Broker <-MQTT-> Hubitat

The gateway sends periodic status updates by publishing to the broker, or immediately when certain events occur. It also subscribes to the broker to receive commands from Hubitat, connecting to the end devices through radio to execute.

Using Rule Machine you can for example trigger watering based on a schedule or external events (such as readings from moisture sensors, rainfall data from a PWS or weather service, forecasted rain from a weather service, etc.). The driver also provides other functionalities such as alerts (e.g. if no water is running after opening the valve), wireless testing, water volume measurement, etc.

It is not cheap, but it is quite complete and has good support. Allowing local-only integration is a great feature that I am not aware of similar products offering. Of course, you also pay for the app and cloud integration, which with local integration you will not need, but I still think it is a good product.

Hey, I have setup the drivers to be available and updateable through HPM.
Cheers
Pedro

1 Like

A new version has been released to github, which includes:

MQTT Connection Management

  • Allows scheduling a connectivity test every x seconds
  • If connectivity has been lost, the driver will automatically try to reconnect
  • You can specify the number of reconnection attempts. When this is reached, the driver will give up and reconnection should be performed manually

Watering volumes calculation

  • 4 new attributes to display daily, weekly monthly and yearly water volumes
  • Attributes are reset (respectively) at midnight (daily), sunday (weekly), 1st of the month (monthly) and 1st january (yearly) through a scheduled execution of a handler method

You can also update with HPM if you have already installed

Cheers

I've just installed and tested Mosquitto MQTT broker/client on the Pi Zero - seems to be working fine. My Linktap G2S and Gateway should arrive tomorrow :+1:

@pedro.f.andrade I seem to recall reading in your earlier post that it required a beta version of the Gateway software, available from Linktap, but I can't find that reference now. Is it still required?

Ah, I just found it under Pre-Reqs! Do you have a contact for Linktap, so I can go directly to someone who knows what they are talking about? :joy:

I chat with them through Facebook (facebook.com/LinkTapWaterTimer/), but I suppose you can ask them through the email contact in their website (Wireless Watering System - LinkTap).

1 Like

While you wait, you can install the hubitat driver already and setup mqtt connection to check the hub can connect to the broker. You should create one user for the hub and one for linktap gateway in the broker (or use the same user for both).

I'm busy this evening but I'll give that a go tomorrow!

Thanks for your help so far, @pedro.f.andrade I'm really looking forward to getting this set up

Hi @pedro.f.andrade , I now have my Gateway and G2-S. The Gateway is connected to my network, the G2-S is connected to my Gateway (I did this via the Linktap App as I want to be able to control via the cloud as well as via Hubitat). All looks good on the Linktap side.

The Hubitat is connected successfully to my MQTT Broker on the Pi Zero (via the virtual device I created using your driver) so all seems good there.

However when I try to connect to the Gateway via a browser, I get connection refused. The IP address is correct (as confirmed with both my router and the Linktap App) but I can't get in to configure the Gateway.

I've reached out to Linktap support, but in the meantime, do you have any ideas? Did you experience this issue? Everything seems correct as far as I can tell, but I'm stuck at this step

Ah, I've just had a thought...do I need to get the beta firmware installed on the Gateway before I try to connect and configure? Perhaps the stock firmware only allows connection via the App?

Yes this is exactly the reason. You need the new fw before doing this.

1 Like

Download the Hubitat app