Skip to content

Commit

Permalink
fix/feat: Update Alexa integration and add Google Home support (night…
Browse files Browse the repository at this point in the history
…scout#4980)

* Copied work done by mdomox

* Updates and fixes to CONTRIBUTING.md

* Spacing unification

* One more fix for CONTRIBUTING.md

* Minor code formatting improvements

* One more time...

* Renamed Alexa stuff to virtAsst for generic-ness

* Corrected missed translate() text

* Updated googlehome plugin to mimic the alexa plugin

* Changed order of operations

* Fixed parameter referencing in googlehome

* Yet another CONTRIBUTING fix

* Removed extra google stuff

* Migrated standalone intents to MetricNow intent

* Simplified route handling

* Added logging

* Added forgotten path selector

* Separated instructions for adding virtual assistant support in a plugin

* A few typo fixes

* Improved logging

* Updated Google Home plugin instructions

* Attempt to trigger download of template file

* Small wording tweaks

* Updated Alexa plugin documentation

* Updated test files

* Re-added handler count tests so devs are prompted to write tests for new handlers

* Updated Alexa documentation

* Small typo fix

* Clarification

* Further clarifications and typos

* Added language info to Google Home plugin doc

* URL correction

* URL fix v2

* Wording clarification

* Ugh...

* Minor instruction fix

* Sub steps fix

* Fixed Alexa references in Google Home

* Added a couple steps for improved user experience

* One more forgotten step

* Updated pump reservoir handler to handle undefined values

* Updated titles and unknown-value responses

* Modified forecast responses to use translate()

* Updated tests

* Improved training phrases

* Wording improvements

* Google Home setup instruction corrections

* Corrected how metric selection is found
  • Loading branch information
inventor96 authored and PieterGit committed Oct 21, 2019
1 parent b8f28b0 commit 30b88f6
Show file tree
Hide file tree
Showing 33 changed files with 1,342 additions and 699 deletions.
12 changes: 6 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,13 +202,13 @@ Also if you can't code, it's possible to contribute by improving the documentati
| Release coordination 0.11.x: | [@PieterGit] |
| Issue/Pull request coordination: | Please volunteer |
| Cleaning up git fork spam: | Please volunteer |
| Documentation writers: | [@andrew-warrington][@unsoluble] [@tynbendad] [@danamlewis] [@rarneson] |
| Documentation writers: | [@andrew-warrington] [@unsoluble] [@tynbendad] [@danamlewis] [@rarneson] |
### Plugin contributors
| Contribution area | List of developers | List of testers
| ------------------------------------- | -------------------- | -------------------- |
| [`alexa` (Amazon Alexa)](README.md#alexa-amazon-alexa)| Please volunteer | Please volunteer |
| [`alexa` (Amazon Alexa)](README.md#alexa-amazon-alexa)| [@inventor96] | Please volunteer |
| [`ar2` (AR2 Forecasting)](README.md#ar2-ar2-forecasting)| Please volunteer | Please volunteer |
| [`basal` (Basal Profile)](README.md#basal-basal-profile)| Please volunteer | Please volunteer |
| [`boluscalc` (Bolus Wizard)](README.md#boluscalc-bolus-wizard)| Please volunteer | Please volunteer |
Expand All @@ -223,7 +223,7 @@ Also if you can't code, it's possible to contribute by improving the documentati
| [`direction` (BG Direction)](README.md#direction-bg-direction)| Please volunteer | Please volunteer |
| [`errorcodes` (CGM Error Codes)](README.md#errorcodes-cgm-error-codes)| Please volunteer | Please volunteer |
| [`food` (Custom Foods)](README.md#food-custom-foods)| Please volunteer | Please volunteer |
| [`googlehome` (Google Home)](README.md#google-home) |[@mdomox] [@rickfriele] | [@mcdafydd] [@oteroos] [@jamieowendexcom] |
| [`googlehome` (Google Home/DialogFlow)](README.md#googlehome-google-homedialogflow)| [@mdomox] [@rickfriele] [@inventor96] | [@mcdafydd] [@oteroos] [@jamieowendexcom] |
| [`iage` (Insulin Age)](README.md#iage-insulin-age)| Please volunteer | Please volunteer |
| [`iob` (Insulin-on-Board)](README.md#iob-insulin-on-board)| Please volunteer | Please volunteer |
| [`loop` (Loop)](README.md#loop-loop)| Please volunteer | Please volunteer |
Expand All @@ -232,9 +232,9 @@ Also if you can't code, it's possible to contribute by improving the documentati
| [`profile` (Treatment Profile)](README.md#profile-treatment-profile)| Please volunteer | Please volunteer |
| [`pump` (Pump Monitoring)](README.md#pump-pump-monitoring)| Please volunteer | Please volunteer |
| [`rawbg` (Raw BG)](README.md#rawbg-raw-bg)| [@jpcunningh] | Please volunteer |
| [`sage` (Sensor Age)](README.md#sage-sensor-age)| @jpcunningh | Please volunteer |
| [`sage` (Sensor Age)](README.md#sage-sensor-age)| [@jpcunningh] | Please volunteer |
| [`simplealarms` (Simple BG Alarms)](README.md#simplealarms-simple-bg-alarms)| Please volunteer | Please volunteer |
| [`speech` (Speech)](README.md#speech-speech) | [@sulkaharo] | Please volunteer |
| [`speech` (Speech)](README.md#speech-speech)| [@sulkaharo] | Please volunteer |
| [`timeago` (Time Ago)](README.md#timeago-time-ago)| Please volunteer | Please volunteer |
| [`treatmentnotify` (Treatment Notifications)](README.md#treatmentnotify-treatment-notifications)| Please volunteer | Please volunteer |
| [`upbat` (Uploader Battery)](README.md#upbat-uploader-battery)| [@jpcunningh] | Please volunteer |
Expand All @@ -251,7 +251,7 @@ Languages with less than 90% coverage will be removed in a future Nightscout ver
| Čeština (`cs`) |Please volunteer|OK |
| Deutsch (`de`) |[@viderehh] [@herzogmedia] |OK |
| Dansk (`dk`) | [@janrpn] |OK |
| Ελληνικά `(el`)|Please volunteer|Needs attention: 68.5%|
| Ελληνικά (`el`)|Please volunteer|Needs attention: 68.5%|
| English (`en`)|Please volunteer|OK|
| Español (`es`) |Please volunteer|OK|
| Suomi (`fi`)|[@sulkaharo] |OK|
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ Community maintained fork of the
- [`override` (Override Mode)](#override-override-mode)
- [`xdrip-js` (xDrip-js)](#xdrip-js-xdrip-js)
- [`alexa` (Amazon Alexa)](#alexa-amazon-alexa)
- [`googlehome` (Google Home/DialogFLow)](#googlehome-google-homedialogflow)
- [`speech` (Speech)](#speech-speech)
- [`cors` (CORS)](#cors-cors)
- [Extended Settings](#extended-settings)
Expand Down Expand Up @@ -518,6 +519,9 @@ For remote overrides, the following extended settings must be configured:
##### `alexa` (Amazon Alexa)
Integration with Amazon Alexa, [detailed setup instructions](docs/plugins/alexa-plugin.md)

##### `googlehome` (Google Home/DialogFLow)
Integration with Google Home (via DialogFlow), [detailed setup instructions](docs/plugins/googlehome-plugin.md)

##### `speech` (Speech)
Speech synthesis plugin. When enabled, speaks out the blood glucose values, IOB and alarms. Note you have to set the LANGUAGE setting on the server to get all translated alarms.

Expand Down
52 changes: 52 additions & 0 deletions docs/plugins/add-virtual-assistant-support-to-plugin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
Adding Virtual Assistant Support to a Plugin
=========================================

To add virtual assistant support to a plugin, the `init` method of the plugin should return an object that contains a `virtAsst` key. Here is an example:

```javascript
iob.virtAsst = {
intentHandlers: [{
intent: "MetricNow"
, metrics: ["iob"]
, intentHandler: virtAsstIOBIntentHandler
}]
, rollupHandlers: [{
rollupGroup: "Status"
, rollupName: "current iob"
, rollupHandler: virtAsstIOBRollupHandler
}]
};
```

There are 2 types of handlers that you will need to supply:
* Intent handler - Enables you to "teach" the virtual assistant how to respond to a user's question.
* A rollup handler - Enables you to create a command that aggregates information from multiple plugins. This would be akin to the a "flash briefing". An example would be a status report that contains your current bg, iob, and your current basal.

### Intent Handlers

A plugin can expose multiple intent handlers (e.g. useful when it can supply multiple kinds of metrics). Each intent handler should be structured as follows:
+ `intent` - This is the intent this handler is built for. Right now, the templates used by both Alexa and Google Home use only the `"MetricNow"` intent (used for getting the present value of the requested metric)
+ `metrics` - An array of metric name(s) the handler will supply. e.g. "What is my `metric`" - iob, bg, cob, etc. Make sure to add the metric name and its synonyms to the list of metrics used by the virtual assistant(s).
- **IMPORTANT NOTE:** There is no protection against overlapping metric names, so PLEASE make sure your metric name is unique!
- Note: Although this value *is* an array, you really should only supply one (unique) value, and then add aliases or synonyms to that value in the list of metrics for the virtual assistant. We keep this value as an array for backwards compatibility.
+ `intenthandler` - This is a callback function that receives 3 arguments:
- `callback` Call this at the end of your function. It requires 2 arguments:
- `title` - Title of the handler. This is the value that will be displayed on the Alexa card (for devices with a screen). The Google Home response doesn't currently display a card, so it doesn't use this value.
- `text` - This is text that the virtual assistant should speak (and show, for devices with a screen).
- `slots` - These are the slots (Alexa) or parameters (Google Home) that the virtual assistant detected (e.g. `pwd` as seen in the templates is a slot/parameter. `metric` is technically a slot, too).
- `sandbox` - This is the Nightscout sandbox that allows access to various functions.

### Rollup handlers

A plugin can also expose multiple rollup handlers
+ `rollupGroup` - This is the key that is used to aggregate the responses when the intent is invoked
+ `rollupName` - This is the name of the handler. Primarily used for debugging
+ `rollupHandler` - This is a callback function that receives 3 arguments
- `slots` - These are the values of the slots. Make sure to add these values to the appropriate custom slot
- `sandbox` - This is the nightscout sandbox that allows access to various functions.
- `callback` -
- `error` - This would be an error message
- `response` - A simple object that expects a `results` string and a `priority` integer. Results should be the text (speech) that is added to the rollup and priority affects where in the rollup the text should be added. The lowest priority is spoken first. An example callback:
```javascript
callback(null, {results: "Hello world", priority: 1});
```
Loading

0 comments on commit 30b88f6

Please sign in to comment.