Skip to content

MQTT integration

To make your robot talk to your MQTT broker and integrate with home automation software, such as but not limited to Home Assistant, openHAB and Node-RED, configure MQTT via Congatudo's web interface (Settings → MQTT).

Autodiscovery

See the specific integration pages for instructions on how to set up autodiscovery for your home automation software platform:

Other home automation software that follows the Homie convention should also be able to automatically discover your Congatudo instance.

Works with Homie

Map

Note that, in order to view the map provided over MQTT, you additionally need I Can't Believe It's Not Valetudo to generate PNG maps. You can then configure it to serve the PNG map over HTTP for openHAB and other software, or install the Lovelace Valetudo Card Map for Home Assistant.

Custom integrations

If you're planning to use one of the home automation platforms listed above, this is all you need to know to get started.

If you're instead planning to do something more custom, in this document you will find a reference to all MQTT topics provided by this software. Values such as <TOPIC PREFIX> and <IDENTIFIER> are those configured in the MQTT settings page.

{% include alert.html type="tip" content="It is recommended to leave Homie autodiscovery enabled, even if you're not planning to use it, if you want to develop custom integrations or access the MQTT topics directly: the Homie protocol is very readable and self-documenting. It will provide additional context and information on how to use specific APIs.

Homie autodiscovery info is best viewed with something like MQTT Explorer. " %}

Table of contents

State attributes index

Home Assistant components index

MQTT API reference

Robot

Device

Home Assistant components controlled by this device:

Capabilities

Basic control (BasicControlCapability)

Node, capability: BasicControlCapability

Operation (operation)

Property, command, not retained

Consumables monitoring (ConsumableMonitoringCapability)

Node, capability: ConsumableMonitoringCapability

{% include alert.html type="warning" content="Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.

|------+--------| | What | Reason | |------|--------| | Properties | Consumables depend on the robot model. | | Property datatype and units | Some robots send consumables as remaining time, others send them as endurance percent remaining. | |------+--------|

" %}

Status attributes managed by this node:

  • ConsumableStateAttribute
Consumable (minutes) (<CONSUMABLE-MINUTES>)

Property, readable, retained

This handle returns the consumable remaining endurance time as an int representing seconds remaining.

Sample value:

29520

Home Assistant components controlled by this property:

Consumable (percent) (<CONSUMABLE-PERCENT>)

Property, readable, retained

This handle returns the consumable remaining endurance percentage.

Sample value:

59

Home Assistant components controlled by this property:

Current Statistics (CurrentStatisticsCapability)

Node, capability: CurrentStatisticsCapability

Current Statistics Area (area)

Property, readable, retained

Sample value:

630000

Home Assistant components controlled by this property:

Refresh current statistics (refresh)

Property, command, not retained
Current Statistics Time (time)

Property, readable, retained

This handle returns the current statistics time in seconds

Sample value:

1440

Home Assistant components controlled by this property:

Fan control (FanSpeedControlCapability)

Node, capability: FanSpeedControlCapability

Status attributes managed by this node:

  • PresetSelectionStateAttribute
Fan (preset)

Property, readable, settable, retained

This handle allows setting the fan. It accepts the preset payloads specified in $format or in the HAss json attributes.

{% include alert.html type="warning" content="Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.

|------+--------| | What | Reason | |------|--------| | Enum payloads | Different robot models have different fan presets. Always check $format/json_attributes during startup. | |------+--------|

" %}

Sample value:

max

Go to location (GoToLocationCapability)

Node, capability: GoToLocationCapability

Go to location (go)

Property, command, not retained

This handle accepts a JSON object identical to the one used by the REST API.

Please refer to the "General Help" section in Valetudo for more information.

Sample payload:

{
  "coordinates": {
    "x": 50,
    "y": 50
  }
}

Locate (LocateCapability)

Node, capability: LocateCapability

Locate (locate)

Property, command, not retained

Segment cleaning (MapSegmentationCapability)

Node, capability: MapSegmentationCapability

Clean segments (clean)

Property, command, not retained

This handle accepts a JSON object identical to the one used by the REST API.

Please refer to the "General Help" section in Valetudo for more information.

Sample payload:

{
  "segment_ids": [
    "20",
    "18",
    "16"
  ],
  "iterations": 2,
  "customOrder": true
}

Speaker volume control (SpeakerVolumeControlCapability)

Node, capability: SpeakerVolumeControlCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Congatudo configuration.

Speaker volume (value)

Property, readable, settable, retained

This handle returns the current speaker volume

Sample value:

80

Home Assistant components controlled by this property:

Water control (WaterUsageControlCapability)

Node, capability: WaterUsageControlCapability

Status attributes managed by this node:

  • PresetSelectionStateAttribute
Water (preset)

Property, readable, settable, retained

This handle allows setting the water. It accepts the preset payloads specified in $format or in the HAss json attributes.

{% include alert.html type="warning" content="Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.

|------+--------| | What | Reason | |------|--------| | Enum payloads | Different robot models have different water presets. Always check $format/json_attributes during startup. | |------+--------|

" %}

Sample value:

min

Home Assistant components controlled by this property:

Wi-Fi configuration (WifiConfigurationCapability)

Node, capability: WifiConfigurationCapability

Home Assistant components controlled by this node:

Frequency (frequency)

Property, readable, retained

Sample value:

2.4ghz
IP addresses (ips)

Property, readable, retained

Sample value:

192.168.100.100,fe80::1ff:fe23:4567:890a,fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
Refresh configuration (refresh)

Property, command, not retained
Signal (signal)

Property, readable, retained

Sample value:

-26
Wireless network (ssid)

Property, readable, retained

Sample value:

Valetudo Wi-Fi

Zone cleaning (ZoneCleaningCapability)

Node, capability: ZoneCleaningCapability

Start zoned cleaning (start)

Property, command, not retained

This handle accepts a JSON object identical to the one used by the REST API.

Please refer to the "General Help" section in Valetudo for more information.

Sample payload:

{
  "zones": [
    {
      "points": {
        "pA": {
          "x": 50,
          "y": 50
        },
        "pB": {
          "x": 100,
          "y": 50
        },
        "pC": {
          "x": 100,
          "y": 100
        },
        "pD": {
          "x": 50,
          "y": 100
        }
      }
    }
  ],
  "iterations": 1
}

Map data

Node

This handle groups access to map data. It is only enabled if provideMapData is enabled in the MQTT config.

Map (map)

Property, readable, retained

This handle is only enabled if interfaces.homie.addICBINVMapProperty is enabled in the config. It does not actually provide map data, it only adds a Homie autodiscovery property so that 'I Can't Believe It's Not Valetudo' can publish its map within the robot's topics and be autodetected by clients.

ICBINV should be configured so that it publishes the map to this topic.

Raw map data (map-data)

Property, readable, retained

Raw map data for Home Assistant (map-data-hass)

Property, readable, retained

This handle is added automatically if Home Assistant autodiscovery is enabled. It provides a map embedded in a PNG image that recommends installing the Valetudo Lovelace card.

Home Assistant components controlled by this property:

Map segments (segments)

Property, readable, retained

This property contains a JSON mapping of segment IDs to segment names.

Sample value:

{
  "16": "Hallway",
  "18": "Bathroom",
  "20": "Kitchen"
}

Home Assistant components controlled by this property:

Status

Attachment state (AttachmentStateAttribute)

Node

Status attributes managed by this node:

  • AttachmentStateAttribute
Dust bin (dustbin)

Property, readable, retained

This handle reports whether the dust bin attachment is installed.

Sample value:

true

Home Assistant components controlled by this property:

Mop (mop)

Property, readable, retained

This handle reports whether the mop attachment is installed.

Sample value:

false

Home Assistant components controlled by this property:

Water tank (watertank)

Property, readable, retained

This handle reports whether the water tank attachment is installed.

Sample value:

true

Home Assistant components controlled by this property:

Battery state (BatteryStateAttribute)

Node

Status attributes managed by this node:

  • BatteryStateAttribute
Battery level (level)

Property, readable, retained

Sample value:

42

Home Assistant components controlled by this property:

Battery status (status)

Property, readable, retained

Sample value:

charging

Vacuum status (StatusStateAttribute)

Node

Status attributes managed by this node:

  • StatusStateAttribute

Home Assistant components controlled by this node:
Robot Error (error)

Property, readable, retained

This property contains the current ValetudoRobotError (if any)

Sample value:

{
  "severity": {
    "kind": "none",
    "level": "none"
  },
  "subsystem": "none",
  "message": ""
}
Error description (error_description)

Property, readable, retained

Sample value:

No error
Status flag (flag)

Property, readable, retained

Sample value:

segment

Home Assistant components controlled by this property:

Status (status)

Property, readable, retained

Sample value:

cleaning