diff --git a/README.md b/README.md index a2d1018..51d0b3c 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,14 @@ [![Build Status](https://travis-ci.org/ghys/habot.svg?branch=master)](https://travis-ci.org/ghys/habot) -HABot is a chatbot for [openHAB](https://openhab.org), running inside the [Eclipse SmartHome](https://eclipse.org/smarthome/) runtime with no dependency; it is offline and private by design, but can be added to the Android homescreen as a [Progressive Web App](https://developers.google.com/web/progressive-web-apps/) with resource caching (so it's very fast!) if served over HTTPS from an openHAB Cloud instance (like [myopenhab.org](https://www.myopenhab.org)) and used on the go. - -__If you have feature requests or issues, please have a look at the (already quite full) [roadmap](https://github.com/ghys/habot/projects) first! Thanks :)__ +HABot is a chatbot for [openHAB](https://openhab.org), running inside the [Eclipse SmartHome](https://eclipse.org/smarthome/) runtime with no dependency; it can run offline and keep your data out of third-party clouds, but works very well remotely if served from an openHAB Cloud instance (like [myopenhab.org](https://www.myopenhab.org)). In that scenario it can even be added to the Android homescreen as a [Progressive Web App](https://developers.google.com/web/progressive-web-apps/), and adds features working only on "secure origins" like push notifications, speech recognition and resource caching. It consists in: - a machine-learning natural language processor based on [Apache OpenNLP](https://opennlp.apache.org) for intent classification and entity extraction (thanks to [nlp-intent-toolkit](https://github.com/mlehman/nlp-intent-toolkit)); -- a modular skill system with intent interpreters and learning data provision (can be injected as OSGi components); -- a mobile-first (but usable on a desktop too) web UI built with the [Quasar Framework](http://quasar-framework.org) and related REST API, to interact with the bot with messages and a full card designer -- the interpreter is also an Eclipse SmartHome [Human Language Interpreter](http://docs.openhab.org/configuration/multimedia.html#human-language-interpreter) - this means the natural language answers will eventually expand to more than "here's what I found" and "there you go", athen it will eventually be able to answer questions and execute orders without a visual UI, when coupled with speech-to-text and text-to-speech engines in ESH. It is another step to have a full, open source, privacy-focused, integrated natural language processing toolchain for your openHAB smart home. +- a modular intent-based skill system with learning data provisioning (basic skills to retrieve item statuses, historical data and send basic commands are built-in, but more can be injected by other OSGi dependency injection); +- a fully-featured responsive card-based user interface built with the [Quasar Framework](http://quasar-framework.org) and its companion REST API to interact with the bot; +- an Eclipse SmartHome [Human Language Interpreter](http://docs.openhab.org/configuration/multimedia.html#human-language-interpreter) - this means once the natural language answers expand to more than "here's what I found" and "there you go", you will eventually be able to ask HABot questions and give it orders without a visual UI when coupled with speech-to-text and text-to-speech engines in ESH, for instance to build privacy-focused specialized voice assistant. It is another step to have a full, open source, privacy-focused, integrated natural language processing toolchain for your openHAB smart home. ## Screenshots @@ -25,56 +23,68 @@ Grab the latest release from https://github.com/ghys/habot/releases and drop the To upgrade, just replace the .jar by the new version. Also go the web app's settings and hit _"Refresh the application"_ to make sure the old version doesn't remain cached. Verify the version by checking the build date under _About HABot_. You might encounter exceptions after upgrading (see https://github.com/ghys/habot/projects/5#card-8141287), this is known and will be fixed. Restarting openHAB should fix the problem. -### Tag your items +### Configure named attributes on your items + +#### What are named attributes? + +When chatting with HABot you'll likely mention some _object_ (the "what", which can be a physical thing, or a property or purpose like "temperature" or "smoke alarm") and/or a _location_ (the "where", for instance "kitchen" or "first floor"). -When chatting with HABot you'll likely mention some _object_ and a _location_. +It will try to extract those concepts from your query and then match items to display or act upon, by looking into "named attributes" it knows about them. -HABot is only able to determine which items correspond to those entities recognized in the query by looking at certain tags applied to your items. +A table of named attributes for each item can be displayed by selecting the "View item attributes" option in HABot webapp's Settings page. -You can either apply these tags in your .items files, or with an (upcoming) screen inside the web app for things added from the inbox in Paper UI. +#### How to add named attributes -Tags recognized by HABot have this syntax (**use only lowercase**): +Named attributes can be added to items in several ways: + +1. Using tags from the Eclipse SmartHome [semantic tag library](https://github.com/eclipse/smarthome/wiki/Semantic-Tag-Library). Example of those tags include `object:Camera`, `property:Temperature`, `purpose:Heating` or `location:FirstFloor`. If a semantic tag is applied on an item, will translate it into one of several named attributes (including synonyms and plurals) for you using an internal dictionary, available in 3 languages. Semantic tags can be added on items through .items files, or they may be set automatically by bindings or other means in the future. Multiple tags, even of the same type (for instance both `location:GroundFloor` and `location:Kitchen`), are allowed on a item. + +2. Using a comma-separated list of monikers in the item's `habot` [metadata namespace](http://www.eclipse.org/smarthome/documentation/concepts/items.html#item-metadata) - this is especially useful for very specific names or items not corresponding to any known concept in the semantic tag library. Monikers added though metadata in this way are supposed to be of the "object" ("what") type unless you specify `type="location"` in the additional metadata configuration: ``` -entity_type:value +Switch Bedside_Lamp ["purpose:Lighting"] { habot="Bedside Lamp" } +Group FF_Child_Bedroom ["location:Bedroom"] { habot="Amelia's Room,Amy's Room" [ type="location" ] } ``` -For example: +In the "View item attributes" setting dialog, named attributes added through semantic tags appear as blue chips, while attributes added through the "habot" metadata namespace appear as dark gray chips. Both methods may be used on a single item. -- `object:temperature` -- `object:water consumption` -- `location:kitchen` -- `location:first floor` +#### Group inheritance principle -If openHAB is set to another language supported by HABot, leave the `object:` and `location:` prefixes untranslated; examples: `object:beleuchtung` or `location:salle à manger`. +To avoid adding the same attributes individually to similar items one by one, either via tags or metadata, HABot will by default consider that a semantic tag or metadata specified on a Group item applies implicitely to all direct or indirect members of the group too. This is shown on the "View item attributes" setting dialog: attributes inherited from a parent group are shown in a faded color. -It is possible to have multiple tags of the same type for an item: for instance, lights can also be called "hue" or "lighting", and they can be both in the location "kitchen" and the location "ground floor". +You can however prevent this behavior for a specific group, and for tags only, with a special property in the item's "habot" metadata namespace configuration: -To avoid tagging items one by one, tags can also be used on groups, this is useful because all members of the group will then inherit the tag, saving you from applying it individually. In the HABot web app settings, you will find an option to display all your items, their groups, tags directly applied to them, and tags inherited because they're members of a tagged group. You'll also be able (soon) to apply tags to items mapped to things in Paper UI from there. +``` +Group GF_Kitchen "Kitchen Beacon" ["object:room"] { habot="" [ inheritTags=false ] } +``` + +Attributes added though metadata are always inherited to group members. -Complete example below: +#### Complete example ``` -Group gFF "First Floor" ["location:first floor"] -Group gGF "Ground Floor" ["location:ground floor"] -Group gC "Cellar" ["location:cellar"] -Group Garden "Garden" ["location:garden"] - -Group GF_Living "Living Room"