[miio] Add support for Xiaomi Vacuum Mop 2S

[Tiller]

Hello,
I needed support for the new Xiaomi Vacuum Mop 2S but it didn't exist yet. So I tried to add support by myself and ended-up with this result.
This is not a complete PR as it's missing at the very least an entry in the README, but I wanted your feedback before proceeding.

As I'm quite lazy, I did not write the JSON spec file myself. I extracted the JSON model from https://home.miot-spec.com/spec?type=urn:miot-spec-v2:device:vacuum:0000A006:ijai-v19:1 and wrote this little script to do the conversion for me:

var f = {
	"deviceMapping": {
		"id": [
			"ijai.vacuum.v19"
		],
		"propertyMethod": "get_properties",
		"maxProperties": 1,
		"channels": [
			{
				"property": "",
				"friendlyName": "Actions",
				"channel": "actions",
				"type": "String",
				"stateDescription": {
					"options": []
                },
                "actions": []
            }
        ]
    }
};


var allFormat = [];
var langs = [];

function mapType(property) {
    var format = property.format;

    if (! allFormat.includes(format)) {
        allFormat.push(format);
    }

    if (/^u?int/.test(format)) {
        if (/hour|minute|second/i.test(property.unit)) {
            return "Number:Time";
        } else if (/percent/i.test(property.unit)) {
            return "Number:Dimensionless";
        } else if (/square.?meter/i.test(property.unit)) {
            return "Number:Area";
        }

        return "Number";
    } else if (format == 'string') {
        return "String";
    } else if (format == 'bool') {
        return "Switch";
    }

    return "Number";
}

function mapPropertyType(property) {
    var format = property.format;

    if (/^u?int/.test(format)) {
        return "NUMBER";
    } else if (format == 'string') {
        return "STRING";
    } else if (format == 'bool') {
        return "ONOFFBOOL";
    }
    
    return "Number";
}

for (var siid in s) {
    var service = s[siid];

    for (var aiid in service.actions) {
        var action = service.actions[aiid];

        var res = {
            "command": "action",
            "parameterType": "EMPTY",
            "siid": service.iid,
            "aiid": action.iid,
            "condition": {
                "name": "matchValue",
                "parameters": [
                    {
                        "matchValue": service.name + "-" + action.name
                    }
                ]
            }
        };

        if (action.in.length > 0) {
            res.parameterType = 'NUMBER';
            res.parameters = action.in.map(d => d*1.0);
        }

        f.deviceMapping.channels[0].actions.push(res);
        f.deviceMapping.channels[0].stateDescription.options.push({
            "value": service.name + "-" + action.name,
            "label": action.description
        });
    }

    for (var piid in service.properties) {
        var property = service.properties[piid];

        var channelName = property.prop;
        if (f.deviceMapping.channels.filter(ch => ch.channel == channelName).length > 0) {
            channelName = service.name + '_' + property.prop;
        }

        var res = {
            "property": property.name,
            "siid": service.iid,
            "piid": property.iid,
            "friendlyName": service.description + " - " + property.description,
            "channel": channelName,
            "type": mapType(property),
            "unit": property.unit,
            "stateDescription": {},
            "refresh": true,
            "actions": []
        };

        if (! (property.access || []).includes('write')) {
            res.stateDescription.readOnly = true;
        } else {
            res.actions.push({
                "command": "set_properties",
                "parameterType": mapPropertyType(property)
            });
        }
        if (property['value-range']) {
            var r = property['value-range'];
            res.stateDescription.minimum = r[0];
            res.stateDescription.maximum = r[1];
            res.stateDescription.step = r[2];
        }
        if (property['value-list']) {
            res.stateDescription.options = property['value-list'].map(v => {
                return {
                    value: v.value + '',
                    label: v.description
                };
            });
        }

        f.deviceMapping.channels.push(res);
    }
}

for (var channel of f.deviceMapping.channels) {
    langs.push('ch.' + f.deviceMapping.id + '.' + channel.channel + ' = ' + channel.friendlyName);
}
for (var channel of f.deviceMapping.channels) {
    for (var o of (channel.stateDescription.options||[])) {
        langs.push('option.' + f.deviceMapping.id + '.' + channel.channel + '-' + o.value + ' = ' + o.label);
    }
}

console.log(JSON.stringify(f));
console.log(langs.join("\n"));

And it seems to work (I had time to only test some actions, but it did work).

But! I ended-up with a lot of actions and channels. A lot more than the others vacuums. So my main question is : how do I filter the actions / channels? Is there a criteria I could use? What's the rule on that usually? Can I keep them all?

Thanks

Note: the script could be used to import other devices from miot-spec.com :)

[marcelrv]

As I'm quite lazy, I did not write the JSON spec file myself. I extracted the JSON model from https://home.miot-spec.com/spec?type=urn:miot-spec-v2:device:vacuum:0000A006:ijai-v19:1 and wrote this little script to do the conversion for me:

I would not call that lazy at all ;-)

I think you essentially recreated another version of the miot file creator, right?

https://github.com/openhab/openhab-addons/blob/main/bundles/org.openhab.binding.miio/src/test/java/org/openhab/binding/miio/internal/MiotJsonFileCreator.java

which uses this to do most of the conversion:
https://github.com/openhab/openhab-addons/blob/main/bundles/org.openhab.binding.miio/src/main/java/org/openhab/binding/miio/internal/miot/MiotParser.java

The intention is that this can be even triggered by users if there is an unsupported device. triggering the 'create experimental support' channel aims do make a json file from the online spec.

[marcelrv]

Wrt to the contribution, looks good.

Suggest to try if your device accepts a "maxProperties":1, with a bit higher number as that may speed up the refresh.
If all channels give values you can keep them. the miot versions of the vacuums seem to have indeed many more channels, but some devices choke on having too many requests.

For the regular vacuums I marked several of the channels as 'advanced' but that is currently not possible with the json file created channels. Suggest to keep them unless they don't produce any data or they are really useless. (e.g. I can imagine the download progress channels are not really something that is usable for normal users)

Would be great if you can also run the readme maker, so that the miio readme is updated with the right channels/info

[Tiller]

Oh... I didn't know it already existed... Would you suggest that I regenerate the json file using the referenced generator instead?
I guess I'll give it a try and compare with mine.

I'll also have a look whether or not all channels returns something or not

[marcelrv]

Oh... I didn't know it already existed... Would you suggest that I regenerate the json file using the referenced generator instead?
I guess I'll give it a try and compare with mine.

Yes, That is always good to do. It will also help with creating the comments for the readme file.

What I normally do is to run the automatic thing and do a comparison with a similar device for validation.
Also the specs have many times missing values (though I did not directly see that in your file) or Chinese descriptions which than can be fixed. Likewise the tags/category can be re-used where applicable (so the users sees right icons etc).

The typical final result is 90% auto generated and 10% manual edits/fixes etc.

[Tiller]

FYI, the two output are quite similar, but you have some weird behavior on yours:

(right side is yours)

The parameterType of the action & the max in the stateDescription is broken (I might have a look into the generator and try to fix it, but I can't promise anything)
Edit: the max might be intentional and '-1' meaning unlimited

[Tiller]

@marcelrv do you know if there is a way I can convert properties like this in a boolean in openhab?

                        {
                                "property":"repeat-state",
                                "siid":7,
                                "piid":1,
                                "friendlyName":"Sweep - Repeat State",
                                "channel":"repeat_state",
                                "type":"Number",
                                "stateDescription":{
                                        "options":[
                                                {
                                                        "value":"0",
                                                        "label":"Close"
                                                },
                                                {
                                                        "value":"1",
                                                        "label":"Open"
                                                }
                                        ]
                                },
                                "refresh":true,
                                "actions":[
                                        {
                                                "command":"set_properties",
                                                "parameterType":"NUMBER"
                                        }
                                ],
                                "readmeComment":"Value mapping [\"0\"\u003d\"Close\",\"1\"\u003d\"Open\"]"
                        }

I guess if I just put "boolean" it won't work as it'll send a boolean to the vacuum
Also, how can I test the maxProperties? Will I get an error log if the value is too high for the device?

[marcelrv]

@marcelrv do you know if there is a way I can convert properties like this in a boolean in openhab?

I think you can just make it a switch as type.

in that case remove the statedescription section
In the action parameterType you need to use ONOFFNUMBER

[marcelrv]

Also, how can I test the maxProperties? Will I get an error log if the value is too high for the device?

Just set to something like 4 or 5, that is accepted by most devices. If it gives strange responses (e.g. leave out responses or timeouts )you known it is too high

[marcelrv]

The parameterType of the action & the max in the stateDescription is broken (I might have a look into the generator and try to fix it, but I can't promise anything)
Edit: the max might be intentional and '-1' meaning unlimited

Yes, looks like something is off. There are a few shortcuts in the conversion. I have seen the -1 before. I assumed it had something to do with unsigned vs signed number formats, but so far never really digged deep. I mostly remove max like that as it is not useful

[Tiller]

Ok, I've tried my best to provide the cleanest mapping possible. You can now review it to merge it

Thanks for the guidances

[marcelrv]

should this not be a switch? Is the contact working properly?

[Tiller]

From what I saw in openhab's documentation, a Contact is basically a read-only Switch. It seems to work properly, but it does not show a toggle switch, just a text with OPENED/CLOSED. But when I analyze the item, I see the on/off pattern fine.

[marcelrv]

few small comments. But looks good.

[marcelrv]

as I don't have commit rights, I added another reviewer.

[fwolter]

@Tiller You requested to merge your code into the 3.2.x branch in the repo. This branch is only for bug fixes. main would be correct.

[Tiller]

@Tiller You requested to merge your code into the 3.2.x branch in the repo. This branch is only for bug fixes. main would be correct.

No possible backport I guess? :(

[jlaur]

LGTM - thanks!