search

virtualzone / landroid-bridge

Bridge for connecting the Worx Landroid S Lawn Mower to home automation systems like OpenHAB or FHEM.
GNU General Public License v3.0
65 stars 48 forks source link

readme

Warning

This repository is currently unmaintained. As I'm not using a Landroid mower anymore, it's impossible for me to update and test any changes. Sorry for that!

You can still try to use it at your own risk.

Please take a look at the issues. There are some great hints on how to get the bridge working with some workarounds. Thanks to all the dedicated people!

Landroid Bridge

Publishes readings from the Worx Landroid S Lawn Mower via HTTP (REST, JSON) and MQTT. Allows for modifying settings via HTTP and MQTT.

Provides an intelligent automatic scheduler, taking the hourly weather forecast and schedules your mower according to the weather forecast, history data and individual mower/garden profile.

You can see the current readings and scheduler results on an integrated web interface.

Setup

Prerequisites

Using Docker

  1. Create a config.json file (see template in source).
  2. Run the image like this (assuming you want to link it with your MQTT container, such as one based on the eclipse-mosquitto image): 
    docker run \
    -p 3000:3000 \
    --name landroid_bridge \
    --link mqtt:mqtt \
    -v /tmp/config.json:/usr/src/app/config.json \
    virtualzone/landroid-bridge

The pre-built Docker images are multi-arch images for amd64, arm32v6, arm32v7 and arm64v8. The correct image for your architecture will be used automatically.

Building from source

  1. Make sure you have Node.js installed (tested with Node.js v11).
  2. Check out the source code and build it: 
    git clone https://github.com/virtualzone/landroid-bridge.git
cd landroid-bridge
npm install
npm run grunt
  3. Update config.json to match your environment.
  4. Run the server: 
    node dist/server.js
  5. Optional (Linux only):
    1. Set up an init.d script to start the bridge on system startup (see example in initd-script folder).
    2. Set up a systemctl script to start the bridge on system startup (see example in systemctl-script folder).

Security

Landroid Bridge does not feature any authentication or authorization right now. If you're using MQTT to communicate with the bridge, make sure to use strong passwords to authenticate with your MQTT broker. If you're using HTTP/REST, use a proxy server like nginx or HAProxy that handles the authentication/authorization in front of the bridge.

Web interface

You can access the web interface at:

http://localhost:3000

Setting up MQTT

To connect to an MQTT broker without any authentication, please modify your config.json like this:

"mqtt": {
    "enable": true,
    "url": "mqtt://localhost",
    "topic": "landroid"
}

If your MQTT broker requires username/password authentication:

"mqtt": {
    "enable": true,
    "url": "mqtt://username:password@localhost",
    "topic": "landroid"
}

To use SSL/TLS, specify the paths to the CA, Key and Cert files (paths relative to the bridge's working directory). You can optionally allow self-signed certificates:

"mqtt": {
    "enable": true,
    "url": "mqtts://localhost",
    "topic": "landroid",
    "caFile": "./optional_path_to_ca_file.crt",
    "keyFile": "./optional_path_to_key_file.key",
    "certFile": "./optional_path_to_cert_file.crt",
    "allowSelfSigned": true
}

Configuring the scheduler

To enable and configure the scheduler modify your config.json:

"scheduler": {
    "enable": false,
    "cron": false,
    "weather": {
        "provider": "wunderground",
        "apiKey": "YOUR_API_KEY",
        "latitude": 50.0982164,
        "longitude": 8.221404
    },
    "db": "./scheduler.db",
    "earliestStart": 11,
    "latestStop": 21,
    "startEarly": false,
    "offDays": 2,
    "squareMeters": 300,
    "perHour": 50,
    "mowTime": 75,
    "chargeTime": 75,
    "daysForTotalCut": 2,
    "rainDelay": 120,
    "threshold": 30
}

The meaning of these settings:

Manually triggering the scheduler

If scheduler.cron is set to false in your config.json, no scheduling is performed automatically. You can trigger scheduling by firing an HTTP POST request to scheduler/apply (i.e. via your home automation system):

curl -X POST http://localhost:3000/scheduler/apply

Managing multiple mowers

If you have more than one mower connected to your Landroid Account, you can set the mower to be selected by changing the dev_sel value in the config.json file. The default value is 0 (zero-based for the first mower in your account).

If you want to manage more than one mower with this Landroid Bridge, please start multiple instances of the bridge, each with a differnt dev_sel value. You'll need to set a unique HTTP Port and MQTT Topic per instance then.

Connecting to OpenHAB

To connect this Landroid Bridge to OpenHAB, add the following configurations to your OpenHAB installation after Landroid Bridge is up and running successfully (see above):

  1. Install the MQTT Binding in OpenHAB (e.g. using the Paper UI).
  2. Add an MQTT configuration in services/mqtt.cfg: 
    mqtt.url=tcp://mqtt:1883
mqtt.user=MQTT_USERNAME
mqtt.pwd=MQTT_PASSWORD
  3. Add items (e.g. in items/mower.items): 
    Number Landroid_ErrorCode "Error Code [%d]" <lawnmower> {mqtt="<[mqtt:landroid/status/errorCode:state:default]"}
String Landroid_ErrorDescription "Error [%s]" <lawnmower> {mqtt="<[mqtt:landroid/status/errorDescription:state:default]"}
Number Landroid_StatusCode "Status Code [%d]" <lawnmower> {mqtt="<[mqtt:landroid/status/statusCode:state:default]"}
String Landroid_StatusDescription "Status [%s]" <lawnmower> {mqtt="<[mqtt:landroid/status/statusDescription:state:default]"}
String Landroid_DateTime "Last Update [%s]" <calendar> {mqtt="<[mqtt:landroid/status/dateTime:state:default]"}

HTTP REST URLs

Examples

The following examples use the cURL command line util.

Getting the status (current settings):

curl -X GET http://localhost:3000/landroid-s/status

Starting the mower:

curl -X POST http://localhost:3000/landroid-s/start

Setting rain delay to 120 minutes:

curl -X PUT http://localhost:3000/landroid-s/set/rainDelay/120

Setting Saturday's work time to start at 10:30 for 60 minutes with no edge cut:

curl -X PUT -H "Content-Type: application/json" -d '{"startHour":10,"startMinute":30,"durationMinutes":60,"cutEdge":false}' http://localhost:3000/landroid-s/set/schedule/6

MQTT Topics

Published by the bridge (you can listen on these topics with your application)

Published by your application (the bridge will perform updates)

Examples

The following examples use the mosquitto_pub command line util of the Mosquitto MQTT broker.

Starting the mower:

mosquitto_pub -t landroid/set/start

Setting rain delay to 120 minutes:

mosquitto_pub -t landroid/set/rainDelay -m 120

Setting Saturday's work time to start at 10:30 for 60 minutes with no edge cut:

mosquitto_pub -t landroid/set/schedule/6 -m '{"startHour":10,"startMinute":30,"durationMinutes":60,"cutEdge":false}'