ZCS Lawn Mower Robot

ZCS Lawn Mower Robots platform as a Custom Component for Home Assistant. All Ambrogio, Techline, Wiper and some Kubota, Stiga and Wolf robotic lawn mowers with Connect module are supported. This integration does not support Bluetooth connectivity with lawn mowers.

Examples of use

With configured map and activated vacuum entity, the lawn mower can be displayed on a Lovelace Vacuum Map card:

The spot cleaning points can be used to start the lawn mower in a specific area.

Installation

[!IMPORTANT]
Requires Home Assistant 2024.5.0 or newer.

Installation through HACS

Installation using Home Assistant Community Store (HACS) is recommended.

1. If HACS is not installed, follow HACS installation and configuration at https://hacs.xyz/.

2. Click the button below or visit the HACS Integrations pane and search for "ZCS Lawn Mower Robot".

   

3. Install the integration.

4. Restart Home Assistant!

5. Make sure that you refresh your browser window too.

Manual installation

1. Download the zcsmower.zip file from the repository release section.

   Do not download directly from the main branch.

2. Extract and copy the content into the path /config/custom_components/zcsmower of your HA installation.

3. Restart Home Assistant!

4. Make sure that you refresh your browser window too.

Setup integration

Start setup:

• Click this button:

  

• Or use the "Add Integration" in Home Assistant, Settings, Devices & Services and select "ZCS Lawn Mower Robot".

Configuration

Start

In this step, a new account is created at ZCS Cloud, to which your lawn mower(s) will later be linked.

1. Garage name: You can freely choose the name.

2. Position tracing: Activate this field if you want to use the periodical position tracing of your lawn mower(s). Your lawn mower(s) will report their position more often.

   :warning: Attention: Activating this function increases data usage significantly. For additional information go to General settings.

3. Map activation: Check this box if you want to set up your own map view. For additional information go to Map.

Map

The image entity will plot the current coordinates and location history of the lawn mower on a user provided image. To configure the entity you need to upload your desired map image and determine the coordinates of the top left corner and the bottom right corner of your selected image.

[!TIP]
If you don't like the map orientation, you can also rotate the section. First, adjust your image, note the degree of rotation and enter it in the map settings.

The image entity is configured via the setup and options flow on the integration.

You can then provide the path to the image you would like to use for the map and marker.

Best practice:

1. Create a new map on Google My Maps.

2. Take a snapshot of the desired area and save it. This has been tested with the PNG format, other formats may work.

3. Store the snapshot into your home assistant instance, e.g. /config/www/mower/.

   The folder /config/custom_components/zcsmower/resources/ is over written when the integration is updated, store the custom image in another location.

4. Type the full path to map into the config flow dialog.

5. Mark the corner points and export as CSV.

6. Type the coordinates into the config flow dialog. To enter the coordinates, ensure that they are in signed degree format and separated by a comma for example: 45.0135543,7.6181209

   :warning: Pay attention to the correct order of latitude and longitude.

7. (Optional) Enter the rotation of your map image in degrees.

8. (Optional) Get a image of your lawn mower with transparent background as a marker for the current position. Store the image into your home assistant instance, e.g. /config/www/mower/ and type the full path into the config flow dialog.

   The default marker /config/custom_components/zcsmower/resources/marker.png is over written when the integration is updated, store the custom image in another location.

Add lawn mower(s)

Get IMEI address from your lawn mower(s):

1. Open the app on your mobile device and select the lawn mower.

2. Click on the Info tab and scroll to the Connect section.

3. You need the Imei Address (starts with 35):

   

4. Type this address into the config flow dialog.

Remove client from lawn mower(s)

When adding a robot, you may receive a message that too many clients are linked to the lawn mower. Only five remote clients can be linked to the lawn mower.

You can fix this problem as follows:

1. Open the app on your mobile device.

2. Connect to the lawn mower via Bluetooth.

3. Click on the Setup tab and scroll to bottom.

4. Click on the General Settings section and open to the Client List:

   

5. Click on the "Delete" button of the client that you no longer need.

General settings

[!NOTE]
These settings have a major impact on data usage of the Connect module.

• In the best case, activate +Infinity for your lawn mower(s).
• If you have not activated +Infinity, you should only carefully select lower values than the default values. If you change these values, you should daily monitor your data usage in the mobile app and adjust the settings again if necessary.

The following settings are available:

• Re-generate client key: Regeneration is only recommended if authentication is no longer possible (see Debugging) and the state of the lawn mowers can no longer be retrieved.

  :information_source: Please note that regenerating will not bring any improvement if the monthly data volume has reached or the Connect expiration date has exceeded.

• Start and end of daily standby time: To save data volume at times when the lawn mowers are not working by default (e.g. at night), the start and end of the usual working hours can be specified. During this standby time, the status is updated more frequently than outside these times.

• Update interval if at least one lawn mower is working:

  • Standard plan: A good value is 120 seconds.
  • +Infinity plan: A good value is 60 seconds.

• Update interval on standby time if no lawn mower is working:

  • Standard plan: A good value is 300 seconds.
  • +Infinity plan: A good value is 120 seconds.

• Update interval outside standby time (all lawn mowers are idle):

  • Standard plan: A good value is 3600 seconds.
  • +Infinity plan: A good value is 900 seconds.

• Position tracing: Activate this field if you want to use the periodical position tracing of your lawn mower(s). Your lawn mower(s) will report its position more often.

  :warning: Attention: Activating this function increases data usage significantly.

• Wake up command on lawn mower(s): While the lawn mower is working, the Connect Module must be woken up from time to time to send a current status. Waking up has a strong influence on data usage. For this reason, one value can be specified for lawn mower(s) with activated +Infinity and a value without.

  • Standard plan: A good value is 1800 seconds.
  • +Infinity plan: A good value is 300 seconds.

Available components

General

• All entities

  Attributes:

  imei, connected, last_communication, last_seen, last_poll, next_poll

Binary Sensor

• error

  Attributes:

  reason

Button

• update_now

• wake_up

• work_now

• charge_now

• border_cut

• trace_position

Device Tracker

• location

  Attributes:

  latitude, longitude, source_type (GPS), location_accuracy (10 meters)

Image

• map

  Attributes:

  calibration_points

Lawn Mower

• mower

  States:

  Values	Description	Lawn mower state(s)
  mowing	Mowing	Work, Go to area, Go to station, Border cut, Mapping started, Mapping ended
  docked	Docked	Charge
  paused	Paused	Pause, Work standby
  error	Error	Error, No signal, Expired, Renewed, Hot temperature

  Attributes:

  status

Number

These entities are disabled by default. You have to activate it if you want to use it.

• work_for

• charge_for

Sensor

• state

  States:

  Values	Description
  unknown	Unknown
  charge	Charge
  work	Work
  pause	Pause
  fail	Error
  nosignal	No signal
  gotostation	Go to station
  gotoarea	Go to area
  bordercut	Border cut
  expired	Expired
  renewed	Renewed
  work_standby	Work standby
  hot_temperature	Hot temperature
  mapping_started	Mapping started
  mapping_ended	Mapping ended

  Attributes:

  connect_expiration, infinity_state, infinity_expiration

Vacuum

This entity is disabled by default. You have to activate it if you want to use it.

• mower

  States:

  Values	Description	Lawn mower state(s)
  cleaning	Mowing	Work, Go to area, Border cut, Mapping started
  docked	Docked	Charge
  paused	Paused	Pause
  returning	Returning to dock	Go to station, Mapping ended
  idle	Idle	Work standby
  error	Error	Error, No signal, Expired, Renewed, Hot temperature

  Attributes:

  status

Services

• zcsmower.update_now:

  Fetch data for lawn mower immediately from API.

• zcsmower.wake_up:

  Command the lawn mower to wake up and connect to the cloud.

• zcsmower.set_profile:

  Configure the profile for auto-mode.

• zcsmower.work_now:

  Command the lawn mower to mow now.

• zcsmower.work_for:

  Command the lawn mower to mow for a certain duration.

• zcsmower.work_until:

  Command the lawn mower to mow until a certain time.

• zcsmower.border_cut:

  Command the lawn mower to cut the border.

• zcsmower.charge_now:

  Command the lawn mower to charge now.

• zcsmower.charge_for:

  Command the lawn mower to charge for a certain duration.

• zcsmower.charge_until:

  Command the lawn mower to charge until a certain time.

• zcsmower.trace_position:

  Command the lawn mower to report its current position.

• zcsmower.keep_out:

  Commands the lawn mower to keep out of a location (no-go area).

• zcsmower.custom_command:

  Send a custom command to the mower, like a command for a new feature, which is not implemented yet by this integration.

Usage

• lawn_mower.start_mowing, vacuum.start:

  The lawn mower starts to mow, within the specified schedule.

• lawn_mower.dock, vacuum.return_to_base:

  The lawn mower returns to the base and parks there until the next schedule start.

• vacuum.stop:

  Same as lawn_mower.dock and vacuum.return_to_base.

• button.charge_now:

  Override schedule to charge lawn mower now.

• button.work_now:

  Override schedule to mow now.

• button.border_cut:

  Override schedule to cut the border now.

• number.charge_for:

  Override schedule to charge lawn mower for specified number of minutes.

• number.work_for:

  Override schedule to mow for specified number of minutes.

Debugging

To enable debug logging for this integration you can control this in your Home Assistant configuration.yaml file.

Set the logging to debug with the following settings in case of problems:

logger:
  default: warn
  logs:
    custom_components.zcsmower: debug

After a restart detailed log entries will appear in /config/home-assistant.log.