{"id":27132228,"url":"https://github.com/pascal-fb-martin/housemech","last_synced_at":"2025-04-07T21:52:42.612Z","repository":{"id":283181113,"uuid":"950930650","full_name":"pascal-fb-martin/housemech","owner":"pascal-fb-martin","description":"A home web service to automate actions on external events","archived":false,"fork":false,"pushed_at":"2025-03-31T18:15:58.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T19:27:02.594Z","etag":null,"topics":["home-automation","http","microservice","smart-home","triggers"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pascal-fb-martin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-18T22:45:59.000Z","updated_at":"2025-03-31T18:16:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"c3fb98cb-7fd1-4906-b6c7-1f2b2c8bf12a","html_url":"https://github.com/pascal-fb-martin/housemech","commit_stats":null,"previous_names":["pascal-fb-martin/housemech"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousemech","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousemech/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousemech/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-fb-martin%2Fhousemech/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pascal-fb-martin","download_url":"https://codeload.github.com/pascal-fb-martin/housemech/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247737770,"owners_count":20987718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-automation","http","microservice","smart-home","triggers"],"created_at":"2025-04-07T21:52:42.110Z","updated_at":"2025-04-07T21:52:42.602Z","avatar_url":"https://github.com/pascal-fb-martin.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HouseMech\n\nA home web service to automate actions on external events.\n\n## Overview\n\nA micro service that executes user scripts as triggers on specific events or control point changes.\n\nAny 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.\n\nThis 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.\n\n## Command line options.\n\nThe 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.\n\n## Installation\n\nTo install, following the steps below:\n* Install gcc, git, openssl (libssl-dev), tcl-dev.\n* Install [echttp](https://github.com/pascal-fb-martin/echttp)\n* Install [houseportal](https://github.com/pascal-fb-martin/houseportal)\n* Clone this repository.\n* make rebuild\n* sudo make install\n\n## Writing an automation script.\n\nThis service loads a Tcl automation script from HouseDepot, repository \"scripts\" and name \"mechrules.tcl\".\n\nThis 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.\n\nThis service uses 3 fields from an House event record: category, name and action.\n\nThe following types of trigger procs can be defined:\n\n```\nproc EVENT._category_._name_._action_ {} {\n    ...\n}\n```\nThis trigger is called when an event occurs and its category, name and action fields all match the proc name.\n\n```\nproc EVENT._category_._name_ {action} {\n    ...\n}\n```\nThis 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.\n\n```\nproc EVENT._category_ {name action} {\n    ...\n}\n```\nThis trigger is called when an event occurs and its category field matches the proc name, and there was no more specific trigger defined.\n\n```\nproc POINT._name_ {state} {\n    ...\n}\n```\nThis trigger is called when a control point's state changes and the point name matches the proc name.\n\nThe 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.\n\nHere 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\":\n```\nproc EVENT.SERVICE {name action} {\n    puts \"================ Service $name $action detected\"\n}\n\nproc POINT.testpoint {state} {\n    puts \"================ Control point testpoint changed to $state\"\n}\n```\n\nAn automation trigger script may access the following Tcl commands:\n\n```\nHouse::event {\"state\" category name}\n```\nThis 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.\n\n```\nHouse::event {\"new\" category name {action \"\"} {description \"\"}}\n```\nThis generates a new event.\n\n```\nHouse::control {\"start\" name {pulse 0} {reason \"HOUSEMECH TRIGGER\"}}\n```\nThis 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.\n\n```\nHouse::control {\"cancel\" name {reason \"HOUSEMECH TRIGGER\"}}\n```\nThis sets the specified control point to \"off\". The reason parameter will be reflected in all subsequent events related to this command.\n\n```\nHouse::control {\"state\" name}\n```\nThis 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.\n\n## Note about Motion Detection\n\nIf 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.\n\nWhen 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.\n\nA similar feedback loop could occur when using other light-based motion detection devices, such as an infrared sensor.\n\n## Interface\n\nThis service does not really have a web interface at this time, beside accessing its internal events.\n\n## Test\n\nThe HouseDepot service must be running.\n\nThe HouseSaga service must be running (no special configuration is needed).\n\nOn a separate terminal, load the SimIO test configuration _from the housetest project_ in HouseDepot and then run the housesimio service:\n```\nhousedepositor config simio.json simio.json\n./housesimio\n```\n\nLoad the HouseMech test rules in HouseDepot:\n```\nhousedepositor scripts mechrules.tcl test/mechrules.tcl\n```\n\nRun 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.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpascal-fb-martin%2Fhousemech","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpascal-fb-martin%2Fhousemech","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpascal-fb-martin%2Fhousemech/lists"}