Skip to main content

This library aims to provide python way to communicate with gardena smart gateway and all smart gardena systems.

Project description

py-smart-gardena

License: MIT PyPI version Build Status Updates

Feel free to join the discord server : Support Server

Description

The py-smart-gardena library aims to provide python way to communicate with gardena smart systems and all gardena smart equipment. Configuration of the equipement and inclusion has still to be done using the Gardena application or website.

Support

This project needs your support.
Gardena equipments are expensive, and I need to buy them in order to add support. If you find this library useful and want to help me support more devices (or if you just want to reward me for my spent time), you are very welcome !
Your help is very much appreciated.

Here are the links if you want to show your support :
PayPal donate button

Thx for your support !

Requirements

  • Python 3.8+

Supported devices

For now, only few devices are supported. I may add new ones in the future :

  • Gateway
  • Smart Mower
  • Smart water control
  • Smart sensor
  • Power plugs
  • Smart Irrigation control

Account creation in order to have access to Gardena API

Gardena requires the creation of an account and an application in order to use their API. You can find how to create such an account and application here : Account and application creation

Installation

$ pip install py-smart-gardena

Usage

Data model

The entrypoint of the library is the the SmartSytem class (in gardena.smart_system package). From there, you can get all locations from your account, and for each of these locations, get the declared devices.

All communications are not done directly with the gateway. This library uses a websocket in order to communicate with gardena systems in order to avoid throttling. There is only one connection to authenticate, and two connections to revoke tokens, everything else is done through websockets.

Authentication

You first need to get a client id (also called application key in the API documentation) for your personal installation of gardena. To do so, create an account here : https://developer.husqvarnagroup.cloud/

Then you need to create an application, add APIs (Authentication API and GARDENA smart system API), and copy the application key as explained here: https://developer.husqvarnagroup.cloud/docs/getting-started

The library manages the token for you then. An exception is raised if authentication fails.

from gardena.smart_system import SmartSystem
import pprint

smart_system = SmartSystem(client_id="client_id", client_secret="client_secret")
await smart_system.authenticate()
await smart_system.update_locations()
for location in smart_system.locations.values():
    await smart_system.update_devices(location)
    pprint.pprint(location)
    for device in location.devices.values():
        pprint.pprint(device)

await smart_system.start_ws(smart_system.locations['LOCATION_ID'])

Once authentication is successful, you need to gather locations and devices for the first time and then, you can create start the websocket in order to get updates automatically.

Locations

Locations are automatically retrieved the first time from the API, and then the websocket is used to get updates.

Here is the list of the current available fields and methods :

for location in smart_system.locations.values():
    print("location : " + location.name + "(" + location.id + ")")

Devices

Devices are automatically retrieved the first time from the API, and then the websocket is used to get updates. They are stored in each locations. Depending on the function type, you can have diffrents fields.

Mowers

    for device in smart_system.locations["LOCATION_ID"].find_device_by_type("MOWER"):
          print(f"name : {device.name}")
          print(f"id : {device.id}")
          print(f"type : {device.type}")
          print(f"model_type : {device.model_type}")
          print(f"battery_level : {device.battery_level}")
          print(f"battery_state : {device.battery_state}")
          print(f"rf_link_level : {device.rf_link_level}")
          print(f"rf_link_state : {device.rf_link_state}")
          print(f"serial : {device.serial}")
          print(f"activity : {device.activity}")
          print(f"operating_hours : {device.operating_hours}")
          print(f"state : {device.state}")
          print(f"last_error_code : {device.last_error_code}")

Power Socket

    for device in smart_system.locations["LOCATION_ID"].find_device_by_type("POWER_SOCKET"):
          print(f"name : {device.name}")
          print(f"id : {device.id}")
          print(f"type : {device.type}")
          print(f"model_type : {device.model_type}")
          print(f"battery_level : {device.battery_level}")
          print(f"battery_state : {device.battery_state}")
          print(f"rf_link_level : {device.rf_link_level}")
          print(f"rf_link_state : {device.rf_link_state}")
          print(f"serial : {device.serial}")
          print(f"activity : {device.activity}")
          print(f"state : {device.state}")

Sensor

    for device in smart_system.locations["LOCATION_ID"].find_device_by_type("SENSOR"):
          print(f"name : {device.name}")
          print(f"id : {device.id}")
          print(f"type : {device.type}")
          print(f"model_type : {device.model_type}")
          print(f"battery_level : {device.battery_level}")
          print(f"battery_state : {device.battery_state}")
          print(f"rf_link_level : {device.rf_link_level}")
          print(f"rf_link_state : {device.rf_link_state}")
          print(f"serial : {device.serial}")
          print(f"ambient_temperature : {device.ambient_temperature}")
          print(f"light_intensity : {device.light_intensity}")
          print(f"soil_humidity : {device.soil_humidity}")
          print(f"soil_temperature : {device.soil_temperature}")

Smart irrigation control

    for device in smart_system.locations["LOCATION_ID"].find_device_by_type("SMART_IRRIGATION_CONTROL"):
          print(f"name : {device.name}")
          print(f"id : {device.id}")
          print(f"type : {device.type}")
          print(f"model_type : {device.model_type}")
          print(f"battery_level : {device.battery_level}")
          print(f"battery_state : {device.battery_state}")
          print(f"rf_link_level : {device.rf_link_level}")
          print(f"rf_link_state : {device.rf_link_state}")
          print(f"serial : {device.serial}")
          print(f"valve_set_id : {device.valve_set_id}")
          print(f"valve_set_state : {device.valve_set_state}")
          print(f"valve_set_last_error_code : {device.valve_set_last_error_code}")
          for valve in device.valves.values():
            print(f"name : {valve['name']}")
            print(f"{valve['name']} - id : {valve['id']}")
            print(f"{valve['name']} - activity : {valve['activity']}")
            print(f"{valve['name']} - state : {valve['state']}")
            print(f"{valve['name']} - last_error_code : {valve['last_error_code']}")

Smart water control

    for device in smart_system.locations["LOCATION_ID"].find_device_by_type("WATER_CONTROL"):
          print(f"name : {device.name}")
          print(f"id : {device.id}")
          print(f"type : {device.type}")
          print(f"model_type : {device.model_type}")
          print(f"battery_level : {device.battery_level}")
          print(f"battery_state : {device.battery_state}")
          print(f"rf_link_level : {device.rf_link_level}")
          print(f"rf_link_state : {device.rf_link_state}")
          print(f"serial : {device.serial}")
          print(f"valve_set_id : {device.valve_set_id}")
          print(f"valve_name : {device.valve_name}")
          print(f"valve_id : {device.valve_id}")
          print(f"valve_activity : {device.valve_activity}")
          print(f"valve_state : {device.valve_state}")

Using websocket

Once the websocket has been started, everything is managed and the devices are automatically updated once their state change. In order for your to be alerted of such a change, you need to add a callback to the device. This callback will be called each time the device state changed :

def my_callback(device):
    print(f"The device {device.name} has been updated !")

device.add_callback(my_callback)

Development environment

To install the dev environment, you just have to do, in the source code directory :

$ pip install -e .[dev]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_smart_gardena-1.3.17.tar.gz (34.4 kB view details)

Uploaded Source

Built Distribution

py_smart_gardena-1.3.17-py3-none-any.whl (17.7 kB view details)

Uploaded Python 3

File details

Details for the file py_smart_gardena-1.3.17.tar.gz.

File metadata

  • Download URL: py_smart_gardena-1.3.17.tar.gz
  • Upload date:
  • Size: 34.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for py_smart_gardena-1.3.17.tar.gz
Algorithm Hash digest
SHA256 b93f00d89a06f6c01d56e7d80c3f278b359518f5701a723f2041d8710992916e
MD5 6ce317da22b67e088b71efce7758584a
BLAKE2b-256 182bcd1d618c8592cb0f3f45056bb1af02c95d18d2a9b2c4219af0480fff5fd2

See more details on using hashes here.

File details

Details for the file py_smart_gardena-1.3.17-py3-none-any.whl.

File metadata

File hashes

Hashes for py_smart_gardena-1.3.17-py3-none-any.whl
Algorithm Hash digest
SHA256 8f3fc157a802161fb11120a1688ac27f0f22b0966139b44e6bbe0f95ca67ac2e
MD5 3680686bd1a30ec72b584a33303342de
BLAKE2b-256 9cdba59cd5c724d78a78e337ae041f592b8b04eb6a65f46870a76cc8f1d72cad

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page