https://github.com/pascal-fb-martin/housemech
A home web service to automate actions on external events
https://github.com/pascal-fb-martin/housemech
home-automation http microservice smart-home triggers
Last synced: about 1 year ago
JSON representation
A home web service to automate actions on external events
- Host: GitHub
- URL: https://github.com/pascal-fb-martin/housemech
- Owner: pascal-fb-martin
- License: gpl-2.0
- Created: 2025-03-18T22:45:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-31T18:15:58.000Z (about 1 year ago)
- Last Synced: 2025-03-31T19:27:02.594Z (about 1 year ago)
- Topics: home-automation, http, microservice, smart-home, triggers
- Language: C
- Homepage:
- Size: 25.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HouseMech
A home web service to automate actions on external events.
## Overview
A micro service that executes user scripts as triggers on specific events or control point changes.
Any event initiated by any House service can be used as a trigger. This includes events initiated by a CCTV service (e.g. HouseMotion): lights, or other devices, may be turned on and off based on camera motion detection.
This project depends on [echttp](https://github.com/pascal-fb-martin/echttp) and [houseportal](https://github.com/pascal-fb-martin/houseportal). It accepts all standard options of echttp and the houseportal client runtime. See these two projects for more information.
## Command line options.
The HouseMech service is entirely configured from a "mechrules.tcl" script. That script must be uploaded to the "scripts" repository of the HouseDepot service. This can be done using the `housedepositor` command.
## Installation
To install, following the steps below:
* Install gcc, git, openssl (libssl-dev), tcl-dev.
* Install [echttp](https://github.com/pascal-fb-martin/echttp)
* Install [houseportal](https://github.com/pascal-fb-martin/houseportal)
* Clone this repository.
* make rebuild
* sudo make install
## Writing an automation script.
This service loads a Tcl automation script from HouseDepot, repository "scripts" and name "mechrules.tcl".
This script defines triggers that HouseMech will call when a matching event or control point change occurs. A trigger is a Tcl proc which name matches the source that caused the trigger. The match between the source and the Tcl proc is entirely based on the proc name.
This service uses 3 fields from an House event record: category, name and action.
The following types of trigger procs can be defined:
```
proc EVENT._category_._name_._action_ {} {
...
}
```
This trigger is called when an event occurs and its category, name and action fields all match the proc name.
```
proc EVENT._category_._name_ {action} {
...
}
```
This trigger is called when an event occurs, both its category and name fields match the proc name, and there was no more specific trigger defined.
```
proc EVENT._category_ {name action} {
...
}
```
This trigger is called when an event occurs and its category field matches the proc name, and there was no more specific trigger defined.
```
proc POINT._name_ {state} {
...
}
```
This trigger is called when a control point's state changes and the point name matches the proc name.
The same event detection will activate at most one trigger: HouseMech will choose the more specific trigger proc that matches, and ignore all other trigger procs.
Here is an example of two triggers; the first trigger is activated upon any service event and the second trigger is activated upon state change for the control point named "testpoint":
```
proc EVENT.SERVICE {name action} {
puts "================ Service $name $action detected"
}
proc POINT.testpoint {state} {
puts "================ Control point testpoint changed to $state"
}
```
An automation trigger script may access the following Tcl commands:
```
House::event {"state" category name}
```
This returns the last detected action for the specified event. This can be used to execute some logic only when multiple conditions are met, i.e. after detection of a sequence or combination of events.
```
House::event {"new" category name {action ""} {description ""}}
```
This generates a new event.
```
House::control {"start" name {pulse 0} {reason "HOUSEMECH TRIGGER"}}
```
This sets the specified control point to "on". If the pulse parameter is present, it represent for how long the control point must remain on. The reason parameter will be reflected in all subsequent event related to this command.
```
House::control {"cancel" name {reason "HOUSEMECH TRIGGER"}}
```
This sets the specified control point to "off". The reason parameter will be reflected in all subsequent events related to this command.
```
House::control {"state" name}
```
This returns the known state of the control point, or an empty string if the state is not known. There might be a delay between executin a control and the state changing: the state always represent the actual state of the control point as reported by the service handling the point.
## Note about Motion Detection
If a light is turned on or off based on camera motion detection, it is imperative to test for, and avoid, any unintended feedback loop, as the control of the light might trigger a new motion detection.
When using the Motion project coupled with the HouseMotion service, it is recommended to use the `lightswitch_percent` and `lightswitch_frames` options in file motion.conf to block the feedback. These two options are meant to prevent motion detection when a wide change of luminosity occurs, like at sunset or sunrise, or when a light turns on or off.
A similar feedback loop could occur when using other light-based motion detection devices, such as an infrared sensor.
## Interface
This service does not really have a web interface at this time, beside accessing its internal events.
## Test
The HouseDepot service must be running.
The HouseSaga service must be running (no special configuration is needed).
On a separate terminal, load the SimIO test configuration _from the housetest project_ in HouseDepot and then run the housesimio service:
```
housedepositor config simio.json simio.json
./housesimio
```
Load the HouseMech test rules in HouseDepot:
```
housedepositor scripts mechrules.tcl test/mechrules.tcl
```
Run HouseMech using the `test/runmech` script. The test will stop on its own when the success criteria defined in `test/mechrules.tcl` will be met.