mochas

Domoticz mochad bridge assistant for dim/bright packets

A Python3 script to handle X10 bright/dim packets for dimmable devices in Domoticz

Version 0.5 (2024-03-10)

---

FR : Le billet intitulé Des appareils sans fil X10 refusent de mourir contient plus d'information sur ce sujet.

---

Raison d'être

mochad is "a Linux TCP gateway daemon for the X10 CM15A RF (radio frequency) and PL (power line) controller and the CM19A RF controller" source. All X10 power line and wireless packets received by a controller are retransmitted through TCP socket connections by mochad. However, the Domoticz Mochad CM15Pro/CM19A bridge with LAN interface decodes only the On and Off packets received from mochad. Dim and Bright packets result in a decode error:

Error: Mochad: Cannot decode 'Rx RF House: J Func: Bright' 

This script contains a user-defined dictionary of X10 units numbers and corresponding Domoticiz idx numbers for dimmable devices. It also keeps track of the last used X10 unit number. When a Dim/Bright packet is received, it attempts to decrease/increase the level of the last used X10 unit. It does this by obtaining the current light level of the corresponding device using the Domoticz HTTP/JSON API and then sets the new modified light level using the same API.

Status

The mochas add-on service has been used with a CM15A controller which handles RF packets only. Consequently, RF packets from the CM19A should work, but no test has been done with PL packets that could be sent by mochad if that controller is used. Assuming that the only difference between RF and PL packets generated by mochad is the two-letter source label,

02/01 18:57:11 Rx RF HouseUnit: J1 Func: On
02/01 18:57:15 Rx PL HouseUnit: J3 Func: On

then, starting with version 0.4, mochas should also work with power line X10 packets sent by mochad if connected to a CM15A. Again, this has not been tested.

Starting with version 0.5 mochas offers support for the security provisions introduced in Domoticz 2023.1.

It remains the case that only IPv4 host addresses are used.

Testing was done on a first generation Raspberry Pi B circa 2011 running both mochas and mochad. The operation system was Raspberry Pi OS Lite (32-bit) (2024-01-25) for armhf with a 6.1.0 Linux kernel.

Security

By default, mochas assumes Domoticz security settings are set at the lowest possible level. No user name and password are provided when using the Domoticz API with plain text HTTP requests. For this to work Domoticz and mochas must be on the same subnet which, in turn, must be included in the Trusted Networks (no username/password) in the Domoticz Security settings.

With version 0.5, mochas no longer needs to be on a trusted network. In that case, HTTP or HTTPS requests sent to Domoticz must contain the name and password of a Domoticz user with admin rights. The credentials must be a "username:password" base64 encoded string specified as an option in the mochas.json configuration file.

"CREDS64": "cG9uZG1pc3Q6c2VhYnJlYXpl"

Insecure HTTP requests (the default in mochas) with credentials will be ignored by Domoticz unless
  [] Allow Basic-Auth authentication over plain HTTP (API only)
is checked in API Protection of the Domoticz Security settings.

In no way should base64 encoding be viewed as secure. It is easily verified that the above example corresponds to the string "pondmist:seabreaze". Consequently if that option is used with HTTP requests, it amounts to sending the credentials as plain text in an HTTP header.

Starting with version 0.5, secure HTTP requests are enabled with

"TLS": true

in the mochas.json configuration file. Because the digital certificate supplied with Domoticz is self-signed, verification will fail unless the self-signed certificate is replaced with a certificate from a recognized authority or if CA verification is disabled in mochas with the

"VERIFY": false

option in the mochas.json configuration file.

Source

• mochas - the executable Python3 script that should be installed in /usr/local/bin/.
• mochas.json.template - a model JSON configuration file that should be modified and installed in /etc/mochas/ as mochas.json.
• mochad.service - the systemd service file that could be installed in /etc/systemd/system/.

If mochas is installed in a directory other than the one suggested, ExecStart in mochad.service must be modified accordingly.

Only root, the owner of mochas in /usr/local/bin, should have read, write, and execute permissions over the script:
# sudo chmod 700 mochas

Configuration

The configuration file is JSON formatted. Here is the template which will have to be edited.

{
    "LOGLEVEL": "error",
    "HOST": "192.168.168.168",
    "PORT": 1099,
    "HOUSE": "J",
    "DELTA": 15,
    "CREDS64": "",
    "TLS": false,
    "VERIFY": true,
    "DOMOTICZ": "192.168.168.168:8080",
    "DEVICES": {
        "6": 66,
        "7": 177,
        "8": 288
    }
}

Type	Key	Value
m/s	LOGLEVEL	system log level, one of : "error", "info" or "debug".
m/s	HOST	mochad IP address.
m/i	PORT	mochad TCP port. It is hard-coded in the mochad source so unlikely to change.
m/s	HOUSE	Monitored X10 house code, a letter from "A" to "P".
m/i	DELTA	Absolute value of the change in the light level to be applied when a Dim or Bright packet is received. The light level is an integer from 0 to 100, so the delta value should be considerably less than 50 and greater than 0 of course.
o/s	CREDS64	base64 encoded "user:password" credentials of a Domoticz user with admin rights. Default: "" (none).
o/b	TLS	When true encrypted HTTPS requests are forwarded to Domoticz, otherwise plain text HTTP requests are used. The TCP port specified in the DOMOTICZ value must be correct. Default: false.
o/b	VERIFY	When true, the digital certificate returned by Domoticz will be verified. This value will have to be explicitely set to false if the self-signed certificate provided with Domoticz has not been replaced by a certificate from a recognized certificate authority. This value is ignored if TLS is false. Default: true
m/s	DOMOTICZ	Domoticz IP address and TCP port. There is no default value for the port and it must correspond with the insecure or secure HTTP protocol specified with the TLS setting.
m/s	DEVICES	Map of key:value pairs where the key is a X10 unit number (from "1" to "16") and its value is the Domoticz light sensor idx number of the corresponding dimmable light.

Note

Type: an entry can be mandatory (m) or optional (o). The value can be a string (s), an integer (i), or a boolean (b). The default value will be used if the optional value is not present.

The presence of the mandatory keys is verified when the configuration file is loaded. There is no validity check of the values performed at that time.

Shameless Self Promotion

If installing mochad on a recent Linux distribution with systemd, such as Raspberry Pi OS, then https://github.com/sigmdel/mochad might be a good fork to try.