{"id":23999086,"url":"https://github.com/bytekeeper/ham","last_synced_at":"2025-08-11T06:34:03.633Z","repository":{"id":31760269,"uuid":"35326461","full_name":"Bytekeeper/HAM","owner":"Bytekeeper","description":"Home automation solution, but with \"KISS\"","archived":false,"fork":false,"pushed_at":"2015-06-15T15:59:08.000Z","size":252,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-08T23:24:15.827Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bytekeeper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-09T11:41:56.000Z","updated_at":"2015-05-09T11:53:17.000Z","dependencies_parsed_at":"2022-09-18T19:00:49.287Z","dependency_job_id":null,"html_url":"https://github.com/Bytekeeper/HAM","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytekeeper%2FHAM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytekeeper%2FHAM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytekeeper%2FHAM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bytekeeper%2FHAM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bytekeeper","download_url":"https://codeload.github.com/Bytekeeper/HAM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240637120,"owners_count":19833006,"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":[],"created_at":"2025-01-07T23:45:36.904Z","updated_at":"2025-02-25T09:19:56.814Z","avatar_url":"https://github.com/Bytekeeper.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HAM\n\nMQTT based Home Automation. The focus of HAM is to provide an abstraction of sensors and actors, and yet remain close to the metal. To reach this goal devices are split into aspects with capabilities, without loosing the information that those aspects might work in tandem.\n\nA night light for example might have a LED and a motion sensor. Both have different capabilities. They also obviously operate together.\n\nHAM devices aren't meant to be necessarily stupid. It's quite sensible to have even small devices carry out some logic without querying some controller, to provide basic functionality even in case of a communication outage. The motion sensor from above performs its basic function without uplink. But it could also be triggered from a motion sensor in another room.\n\nShorthand for sensors/actors: entity\n\n## Messages\n\n### Message Format\nJSON:\n```json\n{ \"type\" : \u003ctype\u003e, \"aspect\" : \u003caspect name\u003e...}\n```\n### Message Types\n\n##### \"Transactions\"\nTBD!!\n\nMessage to driver: Activate pending config changes\n```json\n{ \"type\" : \"Activate\" }\n{ \"type\" : \"Start\" }\n```\n\n##### Color\nMessage to driver: Sets the color of a an aspect of an entity.\nMessage from driver: Color state of the aspect of an entity or sensed color from a sensor.\n```json\n{ \"type\" : \"Color\", \"aspect\" : \"\u003caspect name\u003e\", \"red\" : \"0-65535\", \"green\" : \"0-65535\", \"blue\" : \"0-65535\" }\n```\n\nFor example:\n```json\n{ \"type\" : \"Color\", \"aspect\" : \"light\", \"red\" : \"10000\", \"green\" : \"0\", blue : \"0\" }\n```\n\nThe driver is responsible for converting RGB back and forth between the actual hardware (if the acutal hardware uses a yellow LED, the driver performs the mixing of red + green)\n\n##### Trigger\nMessage to driver: Triggers an aspect on an entity\nMessage from driver: An aspect was triggered on the hardware (ie. motion sensor)\n```json\n{ \"type\" : \"Trigger\", \"aspect\" : \"\u003caspect name\u003e\" }\n```\n\n##### Switch\nMessage to driver: Switches an aspect of an entity on or off\nMessage from driver: An aspect was switched on or off (ie. a hardware switch, a light)\n```json\n{ \"type\" : \"Switch\", \"aspect\" : \"\u003caspect name\u003e\", \"state\": \"on/off\" }\n```\n\n##### Duration\nMessage to driver: Configures the duration of an aspect (ie. how long the floor light should stay on)\nMessage from driver: A duration measured by a sensor\n```json\n{ \"type\" : \"Duration\", \"aspect\" : \"\u003caspect name\u003e\", \"duration\" : \"\u003cn\u003e\" }\n```\nwhere \\\u003cn\\\u003e is given in seconds (ie. 0.5 for half a second).\n\n## Driver basics\nDrivers represent, possibly aggregated, devices like an Arduino with multiple sensors.\n\n### Driver registration\nDrivers should publish and subscribe to:\n\\\u003clocation\\\u003e/drivers/registry\n\n### Driver topics\nAll of the topics are with the following \"topic space\":\n\\\u003clocation\\\u003e/\\\u003cdriver_name\\\u003e\n\nOnly driver specific messages should be sent there (ie. \"activate\").\n\n#### In and Outgoing messages and Failures\nMessages to be processed by the driver should end in the topic \".../in\", while the driver will push its messages on \".../out\". If incoming messages couldn't be processed or something else went wrong, the driver should publish a message on \".../log\".\n\n#### Sensors and Actors\nThey should generally use the topic \"\\\u003clocation\\\u003e/\\\u003cdriver_name\\\u003e/\\\u003centity_name\\\u003e\". Some entities can have multiple aspects, for example a colored light with automatic dimmer (like bkbedlight) has a \"color\", a \"fade in duration\", a \"fade out duration\" and a \"light duration\". These are embedded in the messages themselves.\n\n# Advanced\n## Automatic discovery of drivers and MQTT brokers\n## Controllers\n## UI interfaces\nThey are basically just controllers, but might incorporate driver aspect (ie. for notifications).\n\n# Installation\nTo get started, you just need an MQTT broker and Java8. [Mosquitto](http://mosquitto.org/) for example works well as MQTT broker.\n\nHAM runs well on Raspberry Pi. To install, just execute the command:\n```\nsudo apt-get install mosquitto oracle-java8-jdk\n```\n\nNow clone this repository and build it\n```\ngit clone https://github.com/Bytekeeper/HAM.git\ncd HAM/Drivers\n./gradlew build\n```\nFind the compiled .jar in build/libs of the actual driver subdirectories\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytekeeper%2Fham","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytekeeper%2Fham","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytekeeper%2Fham/lists"}