/Viomi-S9-HA-Integration

Scripts and configurations for my Viomi S9 robot vacuum integration with Home Assistant. Check wiki for tips on how to fix / repair various issues with this vacuum.

MIT LicenseMIT

Overview

So I’ve got a Viomi S9 robot vacuum and while I’m happy with its own app interface and notifications, I figured I can get even more out of it via integration with HA. After a couple of months of playing around, here’s what I’ve managed to achieve.

Ditch the mihome app as I have (almost) complete control and visibility of the vacuum via HA mobile app

a) mobile vacuum dashboard

b) Changing clean type to rooms, zone or point

c) Changing clean mode to vacuum, vacuum & mop or just mop

d) Changing vacuum and mop options (relevant options are shown depending on clean mode)

Get useful mobile (and watch!) notifications

a) Summary of stats upon job completion including map screenshot (so I can see if the vac missed any areas)

b) Error notification including map screenshot (so I can see where it got stuck or encountered the issue)

c) Daily vacuum reminder - sent at 1pm only if I haven’t run the vacuum in the morning (bonus - I can start the cleaning right from the notification! Tapping the notification itself launches the Vacuum Dashboard in the HA app.)

Full control and visibility of the robot vacuum on my desktop (unlike the native Viomi interface which is mobile app only)

Since HA is accessible via the web, I now have full access to the controls and visibility of the cleaning progress while I'm on my desktop.

Monitor and control the robot vacuum from my Google Nest Hub

For the non-tech-savvy members of the household, they can access the same UI on the Google Nest Hub instead of the default basic vacuum UI. I have also created an automation helper that will show the vacuum dashboard on the Nest Hub (if its not playing other media) every time a cleaning job starts so we can monitor the cleaning process.

Switch between Vacuum and Mop modes automatically when mop pad is installed / removed

Speaking of automation, I also have an automation helper that will change the clean mode (i.e. vacuum or mop) automatically when the mop pad is physically installed/removed. IMHO, this is the most useful feature out of all the above as I can simply install/remove the pad and say “Hey Google, start the vacuum” knowing that the right job will run! (Before this, I almost always forget to change the mode in the app before hitting the start button)

How did I do it?

Dependencies

The following is the list of dependent components to get the above working. For details on how to set them up, please refer to the respective component documentation.

Backend

  • Xiaomi Miot Auto - This component is required for HA to communicate with the Viomi S9 Robot Vacuum.
  • Xiaomi Cloud Map Extractor - This component is required to extract the floor plan and retrieve the live view of the robot cleaning progress.

Frontend

  • Lovelace Vacuum Map card - This is the main UI component for the vacuum dashboard.
  • Card Mod 3 - This component is required to display the map and controls panels side-by-side in landscape view.

Configurations

Xiaomi Cloud Map Extractor

The following configuration goes into the main HA configuration.yaml file.

camera:
  - platform: xiaomi_cloud_map_extractor
    host: !secret xiaomi_vacuum_host
    token: !secret xiaomi_vacuum_token
    username: !secret xiaomi_cloud_username
    password: !secret xiaomi_cloud_password
    colors:
      color_path: [29, 47, 207] #dark blue
    room_colors:
      3: [57, 228, 237]
    draw:
      - charger
      - cleaned_area
      - goto_path
      - ignored_obstacles
      - ignored_obstacles_with_photo
      - no_go_zones
      - no_mopping_zones
      - obstacles
      - obstacles_with_photo
      - path
      - predicted_path
      - vacuum_position
      - virtual_walls
      - zones
    map_transformation:
      scale: 2
    attributes:
      - calibration_points
      - rooms

Lovelace Vacuum Map card

The configuration for the vacuum card is too long to list here so I've included it here

Text Input Helper - input_text.viomi_s9_script_helper

Create an invisible text input helper with entity id input_text.viomi_s9_script_helper. This field is used in a number of automations for

  1. Tracking the type of cleaning job (i.e. Vacuuming, Vacuum & Mop or Mopping)
  2. Holding the coordinates for Zone and Point cleaning (workaround as triggering the Zone and Point cleaning for the Viomi S9 vacuum requires multiple service calls and the Lovelace Vacuum Map card component is unable to handle that)

Automations

  • Viomi S9 - cleaning job started helper - This is a helper automation to
    1. track the cleaning job being performed (i.e. vacuuming, vacuum & mop or mopping). The info is stored in the helper variable input_text.viomi_s9_script_helper and is used by the Viomi S9 - job complete and device error notification automation.
    2. show the vacuum dashboard on kitchen display if its not playing any other media.
  • Viomi S9 - job complete and device error notifications - This is a helper automation that forward notifications from the Viomi S9 vacuum. Note the use of the helper variable input_text.viomi_s9_script_helper to store the type of the last job performed. V2 uses the MihomeMessageSensor entity for triggering notifications which appears to be quicker and more accurate. Also note that because this entity and the other S9 entities are updated at different times, do not reference any of the other S9 entities here as the state may not be correct. E.g. when this sensor triggers for error conditions, the entity sensor.viomi_v18_155a_device_fault may not be updated with the error details yet. As such we will need our own translation of the error codes (which may not be a bad thing since the original messages in the system is pretty basic and cryptic). Lastly it also stop displaying the vacuum dashboard on kitchen display when cleaning is complete.
  • Viomi S9 - zone & point cleanup helper - This is a helper automation script to start zone or point clean up. This script relies on the helper variable input_text.viomi_s9_script_helper to store the zone / point coordinates. Note that a scaling factor of 1/1000 needs to be applied to the coordinates in order to work with the Viomi S9 vacuum. Note also that for zone coordinates, the UI format is (x1,y1,x2,y2) whereas the vacuum expects (x1,y1,x1,y2,x2,y2,x2,y1). Note the use of raw JSON format for sending data with the xiaomi_miot.set_miot_property to avoid brackets being inserted in the value field (due to HA's auto type feature).
  • Viomi S9 - change clean mode based on presence of mop pad - This is a helper automation script to automatically change the vacuum clean mode between "vacuum" and "mop" depending on whether the mop pad is installed or not. (installed = mop). Note we should not change the clean mode if cleaning is in progress (by checking for paused and cleaning states). To handle the change of mop pad in those states, add a trigger for when the vacuum comes out of those states and perform the change then.
  • Viomi S9 - Daily vacuum reminder - Sends an actionable notification to parent's mobiles if the vacuum hasn't been run today.

Scripts