search

ioBroker / ioBroker.iot

Connection for Alexa, IFTTT, Google Home and co
MIT License
71 stars 25 forks source link
amazon-alexa google-home ifttt iobroker

readme

Logo

ioBroker IoT Adapter

Number of Installations Number of Installations NPM version

Test and Release Translation status Downloads

This adapter is ONLY for communication with Amazon Alexa, Google Home and Nightscout. It is not for remote access to your ioBroker instance. Use ioBroker.cloud adapter for that.

This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

Settings

To use the iot adapter, you should first register on the ioBroker cloud https://iobroker.pro.

Reference to google API type settings

Intro

Language

If you select "default" language, the smart names of devices and of enumerations will not be translated. If some language specified all known names will be translated into this language. It is done to switch fast between many languages for demonstration purposes.

Place function in names first

Change the order of function and roles in self-generated names:

Concatenate words with

You can define the word which will be placed between function and room. E.g. "in" and from "Dimmer living room" will be "Dimmer in living room".

But it is not suggested doing so, because recognition engine must analyze one more word, and it can lead to misunderstandings.

OFF level for switches

Some groups consist of mixed devices: dimmers and switches. It is allowed to control them with "ON" and "OFF" commands and with percents. If command is Set to 30% and the OFF level is 30% so the switches will be turned on. By command "Set to 25%" all switches will be turned OFF.

Additionally, if the command is "OFF", so the adapter will remember the current dimmer level if the actual value is over or equal to the "30%". Later when the new "ON" command will come, the adapter will switch the dimmer not to 100% but to the level in memory.

Example:

by ON

You can select the behavior of ON command will come for the number state. The specific value can be selected, or the last non-zero value will be used.

Write response to

For every command, the text response will be generated. You can define here the Object ID, where this text must be written to. E.g. sayit.0.tts.text.

Colors

The channel needs 3-5 states with the following roles:

Alexa, set the "device name" to "color"
Alexa, turn the light fuchsia
Alexa, set the bedroom light to red
Alexa, change the kitchen to the color chocolate

Lock

To have the possibility to lock the locks, the state must have the role "switch.lock" and have "native.LOCK_VALUE" to determine the lock state. If you need a separate Value to control the Lock, you can use "native.CONTROL VALUE".

Alexa, is "lock name" locked/unlocked
Alexa, lock the "lock name"

How names will be generated

The adapter tries to generate virtual devices for smart home control (e.g., Amazon Alexa or Google Home).

There are two important enumerations for that: rooms and functions.

Rooms are like: living room, bathroom, sleeping room. Functions are like: light, blind, heating.

The following conditions must be met to get the state in the automatically generated list:

If the state is only in "functions" and not in any "room", the name of state will be used.

The state names will be generated from function and room. E.g. all lights in the living room will be collected in the virtual device living room light. The user cannot change this name, because it is generated automatically. But if the enumeration name changes, this name will be changed too. (e.g., function "light" changed to "lights", so the living room light will be changed to living room lights)

All the rules will be ignored if the state has common.smartName. In this case, just the smart name will be used.

if common.smartName is false, the state or enumeration will not be included in the list generation.

The configuration dialog lets the comfortable remove and add the single states to virtual groups or as single device. Configuration

If the group has only one state, it can be renamed, as for this the state's smartName will be used. If the group has more than one state, the group must be renamed via the enumeration's names.

To create own groups, the user can install "scenes" adapter or create "script" in Javascript adapter.

Replaces

You can specify strings that could be automatically replaced in the device names. E.g., if you set replaces to: .STATE,.LEVEL, so all .STATE and .LEVEL will be deleted from names. Be careful with spaces. If you set .STATE, .LEVEL, so .STATE and .LEVEL will be replaced and not .LEVEL.

Helper states

Toggle mode

Alexa v3 supports toggle mode. It means that if you say "Alexa, turn on the light" and the light is already on, it will be turned off.

IFTTT

instructions

Google Home

If you see the following error message in the log: [GHOME] Invalid URL Pro key. Status auto-update is disabled you can set states but receive states only manually. So you must generate the URL-Key anew:

Url key

Services

There is a possibility to send messages to cloud adapter. If you call [POST]https://service.iobroker.in/v1/iotService?service=custom_<NAME>&key=<XXX>&user=<USER_EMAIL> und value as payload.

curl --data "myString" https://service.iobroker.in/v1/iotService?service=custom_<NAME>&key=<XXX>&user=<USER_EMAIL>

or

[GET]https://service.iobroker.in/v1/iotService?service=custom_<NAME>&key=<XXX>&user=<USER_EMAIL>&data=myString

If you set in the settings the field teh "White list for services" the name custom_test, and call with "custom_test" as the service name, the state cloud.0.services.custom_test will be set to myString.

You may write "*" in the white list and all services will be allowed.

Here you can find instructions on how to use it with tasker.

IFTTT service is allowed only if an IFTTT key is set.

Reserved names are ifttt, text2command, simpleApi, swagger. These must be used without the custom_ prefix.

You can ask by message the valid URL for service too:

sendTo('iot.0', 'getServiceEndpoint', {serviceName: 'custom_myService'}, result => 
  console.log(JSON.stringify(result)));
  // Output: {"result":
  //  {"url": "https://service.iobroker.in/v1/iotService?key=xxx&user=uuu&service=custom_myService",
  //   "stateID":"iot.0.services.myService",
  //   "warning":"Service name is not in white list"
  //  }}

text2command

You may write text2command in white list, you can send POST request to https://service.iobroker.in/v1/iotService?service=text2command&key=<user-app-key>&user=<USER_EMAIL> to write data into text2command.X.text variable.

You can use GET method too https://service.iobroker.in/v1/iotService?service=text2command&key=<user-app-key>&user=<USER_EMAIL>&data=<MY COMMAND>

X can be defined in settings by the "Use text2command instance" option.

Custom skill

The answers for the custom skill can be processed in two ways:

text2command

if text2command instance is defined in the configuration dialog, so the question will be sent to the instance.

text2command must be configured that the expected phrase will be parsed and the answer will be given back.

Javascript

There is a possibility to process the question directly with the script. It is activated by default if no text2command instance is selected.

If text2command instance is defined, so this instance must provide the answer and the answer from script will be ignored.

The adapter will provide the details in two states with different detail level

Return result via smart.lastResponse state

The response needs to be sent within 200ms in the state smart.lastResponse, and can be a simple text string or a JSON object. If it is a text string, then this text will be sent as a response to the skill. If the text is a JSON object, then the following keys can be used:

Return result via the message to iot instance

The iot instance also accepts a message with the name "alexaCustomResponse" containing the key "response" with an object that can contain the keys responseText and shouldEndSession and sessionId as described above. There will be no response from the iot instance to the message!

Example of a script that uses texts

// important, that ack=true
on({id: 'iot.0.smart.lastCommand', ack: true, change: 'any'}, obj => {
    // you have 200ms to prepare the answer and to write it into iot.X.smart.lastResponse
    setState('iot.0.smart.lastResponse', 'Received phrase is: ' + obj.state.val); // important, that ack=false (default)
});

Example of a script that uses JSON objects

// important, that ack=true
on({id: 'iot.0.smart.lastCommandObj', ack: true, change: 'any'}, obj => {
    // you have 200ms to prepare the answer and to write it into iot.X.smart.lastResponse
    const request = JSON.parse(obj.state.val);
    const response = {
        'responseText': 'Received phrase is: ' + request.words.join(' ') + '. Bye',
        'shouldEndSession': true,
        'sessionId': request.sessionId
    };

    // Return response via state
    setState('iot.0.smart.lastResponse', JSON.stringify(response)); // important, that ack=false (default)

    // or alternatively return as message
    sendTo('iot.0', 'alexaCustomResponse', response);
});

Private cloud

If you use private skill/action/навык for communication with Alexa/Google Home/Алиса so you have the possibility to use IoT instance to process the requests from it.

E.g. for yandex alice:

const OBJECT_FROM_ALISA_SERVICE = {}; // object from alisa service or empty object
OBJECT_FROM_ALISA_SERVICE.alisa = '/path/v1.0/user/devices'; // called URL, 'path' could be any text, but it must be there
sendTo('iot.0', 'private', {type: 'alisa', request: OBJECT_FROM_ALISA_SERVICE}, response => {
    // Send this response back to alisa service
    console.log(JSON.stringify(response));
});

The following types are supported:

Yandex Алиса

instructions

Send messages to app

From version 1.15.x you can send messages to ioBroker.visu application (Android and iOS). For that, you need to write the following states:

setState('iot.0.app.expire', 60); // optional. Time in seconds
setState('iot.0.app.priority', 'normal'); // optional. Priority: 'high' or 'normal'
setState('iot.0.app.title', 'ioBroker'); // optional. Default "ioBroker"
setState('iot.0.app.message', 'Message text'); // important, that ack=false (default)

// or just one state
// only is message is mandatory. All other are optional
setState('iot.0.app.message', JSON.stringify({ 
  message: 'Message text',
  title: 'ioBroker',
  expire: 60,
  priority: 'normal'
})); // important, that ack=false (default)

Todo

Changelog

WORK IN PROGRESS

3.3.0 (2024-05-09)

3.2.2 (2024-04-11)

3.2.1 (2024-04-11)

3.2.0 (2024-04-10)

3.1.0 (2024-02-05)

3.0.0 (2023-10-24)

2.0.11 (2023-06-20)

2.0.9 (2023-06-15)

2.0.2 (2023-06-05)

1.14.6 (2023-05-12)

1.14.5 (2023-03-01)

1.14.3 (2023-01-10)

1.14.2 (2022-12-23)

1.14.1 (2022-12-22)

1.14.0 (2022-12-13)

1.13.0 (2022-12-08)

1.12.5 (2022-11-09)

1.12.4 (2022-11-03)

1.12.2 (2022-10-01)

1.12.1 (2022-09-27)

1.12.0 (2022-09-27)

1.11.9 (2022-07-22)

1.11.8 (2022-06-24)

1.11.7 (2022-06-13)

1.11.5 (2022-06-03)

1.11.4 (2022-03-29)

1.11.3 (2022-03-23)

1.11.2 (2022-03-20)

1.11.1 (2022-03-18)

1.11.0 (2022-03-17)

1.10.0 (2022-03-09)

1.9.7 (2022-02-20)

1.9.6 (2022-02-19)

1.9.5 (2022-02-08)

1.9.4 (2022-02-08)

1.9.3 (2022-02-03)

1.9.2 (2022-01-26)

1.8.25 (2021-11-18)

1.8.24 (2021-09-19)

1.8.23 (2021-09-18)

1.8.22 (2021-05-16)

1.8.21 (2021-05-16)

1.8.20 (2021-05-16)

1.8.19 (2021-05-14)

1.8.16 (2021-03-13)

1.8.15 (2021-03-12)

1.8.14 (2021-03-12)

1.8.13 (2021-02-04)

1.8.12 (2021-02-02)

1.8.11 (2021-01-20)

1.8.10 (2021-01-20)

1.8.9 (2020-12-27)

1.8.8 (2020-12-14)

1.8.6 (2020-12-13)

1.8.5 (2020-11-23)

1.8.4 (2020-11-18)

1.8.3 (2020-11-16)

1.8.2 (2020-11-15)

1.8.1 (2020-11-13)

1.8.0 (2020-11-12)

1.7.15 (2020-11-05)

1.7.14 (2020-11-05)

1.7.12 (2020-09-25)

1.7.9 (2020-09-17)

1.7.7 (2020-09-02)

1.7.6 (2020-08-25)

1.7.5 (2020-08-21)

1.7.3 (2020-08-16)

1.7.1 (2020-08-16)

1.6.4 (2020-08-06)

1.6.3 (2020-08-04)

1.6.1 (2020-07-10)

1.5.3 (2020-05-28)

1.5.2 (2020-05-21)

1.4.18 (2020-05-11)

1.4.17 (2020-05-11)

1.4.14 (2020-05-01)

1.4.12 (2020-04-30)

1.4.11 (2020-04-26)

1.4.10 (2020-04-24)

1.4.7 (2020-04-23)

1.4.6 (2020-04-18)

1.4.4 (2020-04-14)

1.4.2 (2020-04-08)

1.4.1 (2020-04-04)

1.3.4 (2020-02-26)

1.3.3 (2020-02-12)

1.3.2 (2020-02-10)

1.3.1 (2020-02-09)

1.2.1 (2020-01-18)

1.2.0 (2020-01-04)

1.1.10 (2020-01-03)

1.1.9 (2019-11-27)

1.1.8 (2019-09-12)

1.1.7 (2019-09-11)

1.1.6 (2019-09-11)

1.1.4 (2019-09-10)

1.1.3 (2019-09-09)

1.1.0 (2019-09-06)

1.0.8 (2019-09-03)

1.0.4 (2019-08-01)

1.0.3 (2019-07-30)

1.0.1 (2019-07-26)

1.0.0 (2019-07-14)

0.5.0 (2019-06-29)

0.4.3 (2019-04-14)

0.4.2 (2019-03-10)

0.4.1 (2019-02-19)

0.3.1 (2019-01-13)

0.3.0 (2018-12-30)

0.2.2 (2018-12-21)

0.2.0 (2018-12-18)

0.1.8 (2018-10-21)

0.1.7 (2018-10-14)

0.1.4 (2018-09-26)

License

The MIT License (MIT)

Copyright (c) 2018-2024 bluefox dogafox@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.