Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sigmdel/mochas

Domoticz Mochad bridge assistant for X10 dim/bright packets
https://github.com/sigmdel/mochas

cm1xa domoticz mochad x10

Last synced: 2 days ago
JSON representation

Domoticz Mochad bridge assistant for X10 dim/bright packets

Awesome Lists containing this project

README 

        
# mochas



Domoticz ***moch***ad bridge ***as***sistant 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](https://www.sigmdel.ca/michel/ha/rpi/boomerang_01_fr.html) 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](https://sourceforge.net/projects/mochad/files/). All X10 power line and wireless packets received by a controller are retransmitted through TCP socket connections by `mochad`. However, the [Domoticz](https://www.domoticz.com/) *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](https://www.domoticz.com/wiki/Domoticz_API/JSON_URL%27s) 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](https:////www.domoticz.com/wiki/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](https://www.domoticz.com/wiki/Security#Users). The credentials must be a "username:password" base64 encoded string specified as an option in the `mochas.json` configuration file.



```json

"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](https://www.base64decode.org/) 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  



```json

"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



```json

"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.



```json

{

    "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.