angeloxx/landroid-bridge

Bridge for connecting the Worx Landroid S Lawn Mower to home automation systems like OpenHAB or FHEM.

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

• If you want to use MQTT instead of HTTP, you need to have an MQTT Broker like Eclipse Mosquitto installed.
• If you want to build from source, make sure you have Node.js installed.
• If you want to use the pre-built Docker image, you need to have Docker up and running.

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 \
       weweave/landroid-bridge
   

Building from source

1. Make sure you have Node.js installed (tested with Node.js v8).
2. Check out the source code and build it:

   git clone https://github.com/weweave/landroid-bridge.git
   cd landroid-bridge
   npm install
   npm run build-prod
   

3. Update config.json to match your environment.
4. Run the server:

   node dist/server.js
   

5. Optional: Set up an init.d script to start the bridge on system startup (Linux only, see example in initd-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

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:

• enable: true enables the integrated scheduler
• cron: true enables automatic cron-based scheduling (once per hour) - if false, scheduling must be triggered manually, see below
• weather.provider: Currently, only "wunderground" is supported weather.apiKey: Your Wunderground API key weather.latitude: Your location's latitude weather.longitude: Your location's longitude
• db: Location of the SQLite3 database file (created automatically)
• earliestStart: The earliest hour of the day the mower will start
• latestStop: The latest hour of the day the mower will stop
• startEarly: true schedules for the earliest start possible, whereas false schedules for the latest start possible
• offDays: Number of days per week your mower won't mow
• squareMeters: Square meters of lawn
• perHour: Square meters your mower will mow per hour
• mowTime: Minutes your mower will mow before returning to the basis for charging
• chargeTime: Minutes your mower needs to charge its batteries
• daysForTotalCut: Number of days you allow your mower for completely cutting your lawn
• rainDelay: Minutes of standby after a rain shower
• threshold: The minimum chance of rain (percentage) considered as "don't mow"

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

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

• Get status as JSON: GET /landroid-s/status
• Start mower: POST /landroid-s/start
• Stop mower: POST /landroid-s/stop
• Set rain delay: PUT /landroid-s/set/rainDelay/x (where 0 <= x <= 300)
• Set time extension: PUT /landroid-s/set/timeExtension/x (where -100 <= x <= 100)
• Set work time schedule: PUT /landroid-s/set/schedule/n (where 0 <= n <= 6, 0 is Sunday)

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)

• landroid/status/language
• landroid/status/dateTime
• landroid/status/macAddress
• landroid/status/firmware
• landroid/status/wifiQuality
• landroid/status/active
• landroid/status/rainDelay
• landroid/status/timeExtension
• landroid/status/serialNumber
• landroid/status/totalTime
• landroid/status/totalDistance
• landroid/status/totalBladeTime
• landroid/status/batteryChargeCycle
• landroid/status/batteryCharging
• landroid/status/batteryVoltage
• landroid/status/batteryTemperature
• landroid/status/batteryLevel
• landroid/status/errorCode
• landroid/status/errorDescription:
• landroid/status/statusCode
• landroid/status/statusDescription
• landroid/status/schedule/n (where n is the weekday, 0 is Sunday)

Published by your application (the bridge will perform updates)

• landroid/set/start (starts the mower)
• landroid/set/stop (stops the mower)
• landroid/set/rainDelay (sets rain delay in minutes, supply delay value as payload)
• landroid/set/timeExtension (sets time extension in percent, supply percentage value as payload)
• landroid/set/schedule/n (sets work time for weekday n, where 0 is Sunday – see examples below)

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}'