search

jpgorganizer / ioBroker.smartgarden

GARDENA smart system adapter for ioBroker
Other
21 stars 8 forks source link
garden gardena gardena-api gardena-smart-system iobroker irrigation mower power-socket smart smart-irrigation-control water-control

readme

Logo

ioBroker.smartgarden

Installed NPM version Downloads Build Status Stable

NPM

ioBroker smartgarden adapter for GARDENA smart system

An adapter for GARDENA smart system using official GARDENA smart system API and service.

The adapter allows the development of an application (e.g. with VIS) that can be used in parallel with the official GARDENA app. The adapter and its additional features do not affect any of the basic functions of the GARDENA app and vice versa.

The adapter is not a complete replacement for the GARDENA app, but an addition to integrate the GARDENA devices into a smart home with ioBroker. The most important actions can be carried out with the adapter. It also offers the opportunity to implement your own ideas that are not possible with the GARDENA app.

Supported devices

Requirements

To use this adapter you need the following things:

  1. an GARDENA smart system account
  2. an GARDENA application key
  3. an GARDENA application secret

To get those things please go to Husqvarna Developer Portal at https://developer.husqvarnagroup.cloud/.

Please Sign up or Log in if you already have an account and create a new application to get your application key and application secret.

Currently the site looks like in the following screenshots.

myapplications

Press button NEW APPLICATION

createnewapplication

Edit form with your own data. Currently the field Redirect URLs is not used. That's why you can currently enter any value. Press button CREATE

mysmartgardenapplication

At the next page you get the application key and application secret. You will need those values for your adapter instance configuration. And you have to connect the APIs

For this press button CONNECT NEW API and select the first API. And repeat for the second API.

Note:

And of course you need a running ioBroker installation (at least using admin5 UI) and you should own at least one working GARDENA smart device.

Table of Contents

Installation

Adapter is available

Setup adapter

  1. Install the adapter
  2. Create an instance of the adapter

  3. Check and complete instance configuration

    If you change any value of those settings please restart your adapter.

    3.1 Edit application key and application secret and/or optional username, password in main instance configuration

    Parameter Description
    mandatory
    Application key Application key (API key), e.g. under Requirements
    either application secret
    or username and password *) **)
    recommended
    Application secret *) application secret, e.g. under Requirements - only if username and password are empty (new in v2.0.0)*
    not recommended
    username *) **) username for GARDENA smart system - only if application secret is empty
    password *) **) corresponding password - only if username is specified

    NOTES:
    *)

    • From release v2.0.0 the preferred login procedure is using application key and application secret as the former login procedure with username and password isn't supported by Gardena anymore, but nevertheless it's still working for many users. For this reason it is still available here, but in the event of an error, there is no longer any support for it. So it's recommended to use application key and applicaton secret!

    • Application key, application secret and password are encrypted and stored within the adapter and become just decrypted for authentication with the GARDENA application host.

    **)

    • parameter is discontinued and may no longer be available in a future version

    3.2 Verify default values of miscellaneous settings and switch on/off options in instance configuration. For most users the default values will be ok.

    Parameter Description
    forecast use forecast for charging time and mower remaining time; switch forecast charging and mowing time of mower on/off; default: off; (new in v0.5.0)
    cycles number of MOWER history cycles; you can use any number from 3 (minimum), but 10 (default) seems to be a good value; only relevant if the above 'forecast' is on; (new in v0.5.0)
    irrigation check use the check whether irrigation is allowed while mowing; switch on/off; default: off; (new in v0.6.0)
    monitor limit use monitoring for the rate limits of Gardena smart system API; switch on/off; default: off; (new in v1.0.2)

    3.3 Verify default values of systems settings and switch on/off options in instance configuration. Most users will not have to change anything on this tab.

    Parameter Description
    Loglevel Loglevel: 0 = no log entries, 1 = some log entries, 2 = some more log entries, 3 = all log entries; default: 0 - no log entries
    beautify log make state ids shorter in log; switch on/off; default: on; (new in v1.0.5)
    connection retry interval interval for retry to connect to Gardena Webservice in case of an error (in seconds); default: 300, minimum: 60; (new in v1.0.3)
    ping interval Interval for sending Ping's to Gardena Webservice (in seconds); default: 150, minimum: 1, maximum: 300
    auth factor Factor for validity of authentication token; default: 0.999
    Auth-URL Authentication host URL; default: https://api.authentication.husqvarnagroup.dev
    Base-URL Webservice Base-URL; default: https://api.smart.gardena.dev

Getting support

To get help read this README and the FAQ carefully. If you need further support please join the ioBroker forum thread.

Data points of the adapter

The adapter is designed to monitor and control GARDENA smart system devices. For this there will be one LOCATION and one or many DEVICE's. For each DEVICE there will be

Where <servicelink_type> is a type description for the device, for example MOWER or VALVE and <id> is a (encoded) GARDENA device id used by the API. See description for ServiceLink at https://developer.husqvarnagroup.cloud/apis/GARDENA+smart+system+API#/swagger.

Controlling/monitoring for each device is possible via the SERVICE_<servicelink_type> listed in the following table. The SERVICE_COMMON provides general information about the device.

device SERVICE_
smart SILENO robotic lawnmower SERVICE_MOWER and SERVICE_COMMON
smart Irrigation Control SERVICE_VALVE_SET, SERVICE_VALVE and SERVICE_COMMON
smart Pressure Pump SERVICE_VALVE and SERVICE_COMMON
smart Water Control SERVICE_VALVE and SERVICE_COMMON
smart Power Adapter SERVICE_POWER_SOCKET and SERVICE_COMMON
smart Sensor SERVICE_SENSOR and SERVICE_COMMON

If you need more information about the data points please have a look at https://developer.husqvarnagroup.cloud/apis/GARDENA+smart+system+API#/swagger. There you'll find a description for every data point; except for those which are marked as data points of the adapter and not of the GARDENA smart system API.

The adapter creates its own data points for various features / options when the feature is selected. These data points are not automatically deleted when the feature is deselected. If you no longer need these data points, they can be deleted manually.

General things to know about data points

The adapter doesn't change any values transmitted by the GARDENA smart system API. The only thing that is done (from version 1.0.0) is to check the type of timestamps and numbers.

check for description
timestamps all timestamps are given in UTC; if a received timestamp is not a valid timestamp, 01 Jan 1970 00:00:00Z (Unix time zero) is used instead. So if you see this date/time please report.
numbers if a number is not a valid number, -1 is used instead. So if you see this number please report.

Requests to control a device will succeed as soon as the command was accepted by the smart Gateway. A successful execution of the command on the device itself can be observed by a respective state change. Example: sending a command to start the VALVE service of a smart Water Control will result in the activity_value data point of the service to be changed after the device processed the command.

Notes:

For SERVICE_MOWER

Controlling

To control the device use data point

Monitoring

All other data points are just for monitoring and information.

Special data points:

For SERVICE_VALVE_SET

Controlling

To control the device use data point

Monitoring

All other data points are just for monitoring and information.

For SERVICE_VALVE

Controlling

To control the device use data point

Monitoring

All other data points are just for monitoring and information.

Special data point:

For SERVICE_POWER_SOCKET

Controlling

To control the device use data point

Monitoring

All other data points are just for monitoring and information.

Special data point:

For SERVICE_SENSOR

Controlling

No control functions available.

Monitoring

All data points are just for monitoring and information.

For SERVICE_COMMON

The SERVICE_COMMON provides general information about the device. Description is integrated into description of other SERVICE_... where necessary.

Rate Limits

There are some limits you shoud be aware of. Please see chapter Rate Limits in README of GARDENA smart system API description.

To help you to see if you hit those rate limits you can switch on monitoring in instance configuration with parameter monitoring Rate Limits.

If you've enabled monitoring state info.RateLimitCounter gets actualized with every request. This state saves a data structure with the number of requests per month, day, hour and for the last 30 and 31 days.

The structure is in JSON and looks like

{
  "2020": {                          <<< year
    "2020-08": {                     <<< month
      "count": 21,                   <<< number of requests for month
      "2020-08-27": {                <<< day
        "11": {                      <<< hour
          "count": 3                 <<< number of requests for hour
        },
        "12": {                      <<< hour   
          "count": 13                <<< number of requests for hour
        },
        "count": 16                  <<< number of requests for day
      },
      "2020-08-28": {                <<< day
        "14": {                      <<< hour
          "count": 5                 <<< number of requests for hour 
        },
        "count": 5                   <<< number of requests for day
      }
    }
  },
     ...
  "last30days": {                     
    "count": 2021                    <<< number of requests in last 30 days
  },
  "last31days": {
    "count": 2098                    <<< number of requests in last 31 days
  }
}

Note:

Irrigation not allowed while mowing

What's the problem?

If you have both a mower and an irrigation system with pop-up sprinklers, there is a risk that your mower will run into a pop-up sprinkler while the irrigation is running and damage it or cause damage itself.

To prevent this, the irrigation system or better individual valves should be switched off when the mower is mowing.

What is being done?

With this function it is possible to stop irrigation when the mower is on the lawn. This can be defined separately for each valve.

One or more mowers can be defined for each valve, for which the valve is not allowed to be open while the mower is mowing. Basically, the mower has priority over irrigation, i.e. if the conflict arises that the mower is mowing and a valve is open, the valve is closed and a corresponding warning is set.

Additionally it is possible to define that a valve should never open regardless of a mower. E.g. can be used if a valve or the pipe behind it is damaged.

The whole check can be switched on or off in instance configuration with parameter irrigation check.

There are three data points available for each SERVICE_VALVE. They are used for configuration and for reporting warnings.

data point writeable Description of data points
irrigationWhileMowing_allowed_i yes set to false if it should be checked if irrigation is allowed while the mower is mowing on the lawn, true otherwise
irrigationWhileMowing_mowerDefinition_i yes one or more id's of SERVICE_MOWER which get checked. Format of mower id see below. There is a special code IRRIGATION_FORBIDDEN meaning that the valve is always closed regardless of a mower. If more than one id should be set then separate them by semicolon (;).
irrigationWhileMowing_warningCode_i no warning code is set if valve opens. Possible warning codes see next table. If more than one warning is set, codes are concatenated with + (e.g. STOPPED+UNKNOWN_MOWER).

This function is runnig every time when

It doesn't run when you change the values in the data points listed above. That means: if there is a conflict situation and you change irrigationWhileMowing_allowed_i from true to false, the conflict is not recognized and the conflict will continue. The same behaviour applies to a change of irrigationWhileMowing_mowerDefinition_i.

Basic behaviour -- WARNING

This feature cannot prevent a valve from opening while the mower is mowing. E.g. this can be done manually through the GARDENA app or automatically through a schedule.

This function can only close the valve as quickly as possible in the event of a conflict. And a conflict may not be recognized either. So it can happen that water is let through. E.g. it cannot be prevented that the pop-up sprinklers extend and that the mower hits the pop-up sprinklers, but the likelihood that this will happen has been minimized. So it is up to your application to make sure that this conflict will never happen.

Wishes for data points

This adapter reports every value as a data point that is supplied via the GARDENA smart system API. If someone wants more values, please contact GARDENA and inform them that this value will also be included in the API. To do this, please go to Contact us & Leave feedback in the footer on the GARDENA Developer Portal.

Note

This is a private project. I am not in any association with GARDENA or Husqvarna.

Changelog

2.0.1

2.0.0

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.6.0

0.5.1

0.5.0

0.4.2

0.4.1

0.4.0

0.3.0

0.2.0

0.0.1

Credits

Many thanks to GARDENA/Husqvarna for providing this public API and special thanks to your support team for providing very good and very fast support.

smartgarden logo: http://www.freepik.com Designed by Freepik

License

Copyright (c) 2020 - 2024 jpgorganizer, https://github.com/jpgorganizer

smartgarden by jpgorganizer is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC-BY-NC-SA-4.0) Based on a work at https://github.com/jpgorganizer/ioBroker.smartgarden.