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.
To use the iot adapter, you should first register on the ioBroker cloud https://iobroker.pro.
Reference to google API type settings
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.
Change the order of function and roles in self-generated names:
- if false: "Room function", e.g. "Living room dimmer"
- if true: "Function room", e.g. "Dimmer living room"
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.
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:
- Assume, that OFF level is 30%.
- Virtual device "Light" has two physical devices: switch and dimmer.
- Command: "set the light to 40%". The adapter will remember this value for dimmer, will set it for "dimmer" and will turn the switch ON.
- Command: "turn the light off". The adapter will set the dimmer to 0% and will turn off the switch.
- Command: "turn on the light". dimmer => 40%, switch => ON.
- Command: "set the light to 20%". dimmer => 20%, switch => OFF. The value for dimmer will not be remembered, because it is bellow OFF level.
- Command: "turn on the light". dimmer => 40%, switch => 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.
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.
The channel needs 3-5 states with the following roles:
level.color.saturation- required for detection of the channel,level.color.hue,level.dimmer,switch- optional,level.color.temperature(optional)
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
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"
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:
- the state must be in some "function" enumeration.
- the state must have role ("state", "switch" or "level.*", e.g. level.dimmer) if not directly included in "functions". It can be that the channel is in the "functions", but state itself not.
- the state must be writable:
common.write= true - the state dimmer must have
common.typeas 'number' - the state heating must have
common.unitas '°C', '°F' or '°K' andcommon.typeasnumber
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.
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.
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.
smart.lastObjectID: This state will be set if only one device was controlled by home skill (alexa, google home).smart.lastFunction: Function name (if exists) for which last command was executed.smart.lastRoom: Room name (if exists) for which last command was executed.smart.lastCommand: Last executed command. Command can be:true(ON),false(OFF),number(%),-X(decrease at x),+X(increase at X)smart.lastResponse: Textual response on command. It can be sent to sometext2speech(sayit) engine.
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.
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:
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"
// }}
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.
The answers for the custom skill can be processed in two ways:
text2commandjavascript
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.
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
smart.lastCommandcontains the received text including info about the type of query (intent). Example:askDevice Status Rasenmähersmart.lastCommandObjcontains an JSON string that can be parsed to an object containing the following informationwordscontain the received words in an arrayintentcontains the type of query. Possible values currently are:- v1 Skill:
askDevice,controlDevice,actionStart,actionEnd,askWhen,askWhere,askWho - v2 Skill:
queryIntentwhen the full said text was captured,controlDevicefor fallback with only partial text
- v1 Skill:
deviceIdcontains a deviceId identifying the device the request was sent to, delivered by Amazon, will be empty string if not provideddeviceRoomcontains a mapped room identifier you can configure in iot admin UI for collected deviceIdssessionIdcontains a sessionId of the Skill session, should be the same if multiple commands were spoken, delivered by Amazon, will be empty string if not provideduserIdcontains a userId from the device owner (or maybe later the user that was interacting with the skill), delivered by Amazon, will be empty string if not provideduserNamecontains a mapped username you can configure in iot admin UI for collected userIds
More details on how the words are detected and what type of queries the Alexa Custom Skill differentiates, please check https://forum.iobroker.net/viewtopic.php?f=37&t=17452 .
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:
responseTextneeds to contain the text to return to AmazonshouldEndSessionis a boolean and controls if the session is closed after the response was spoken or stays open to accept another voice input.sessionIdneeds to contain the sessionId the response is meant for. Ideally, provide it to allow concurrent sessions. If not provided, the first session that expects a response is assumed.
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);
});
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:
alexa- acting with Amazon Alexa or Amazon Custom Skillghome- acting with Google Actions via Google Homealisa- acting with Yandex Алисаifttt- acting like IFTTT (actually not required, but for tests purposes)
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)
- Smart names must have higher priority as groups
- Devices should be grouped by smart name
- (bluefox) updated packages
- (bluefox) Migrated GUI for admin v7
- (foxriver76) Fix error on reconnect
- (foxriver76) prepared adapter for new ioBroker Visu app states
- (bluefox) updated packages
- (foxriver76) remove some warnings that should only be debug log
- (foxriver76) fixed issue that only valid JSON could be sent to app via message state
- (foxriver76) implemented geofence with ioBroker Visu app
- (bluefox) Updated packages
- (bluefox) Disabled the state change report for alexa v3
- (bluefox) Updated packages
- (bluefox) The minimal supported node.js version is 16
- (bluefox) Added support for the state toggling (alexa 3)
- (bluefox) Done small improvements for alexa 3
- (bluefox) Working on support for amazon alexa v3
- (bluefox) Added support for amazon alexa v3
- (bluefox) Removed support for sugar blood indication
- (bluefox) Corrected translations
- (bluefox) Corrected names of enums in GUI
- (kirovilya) Fixed processing for lights with CT and RGB in Alisa
- (bluefox) Updated GUI packages
- (bluefox) Downgraded the axios version to 0.27.2
- (bluefox) Added netatmo support
- (Apollon77) Added support vor Custom Skill v2
- (bluefox) Small changes on configuration GUI
- (bluefox) Added ukrainian language
- (bluefox) Corrected blockly for unknown languages
- (Apollon77) Fixed crash case
- (bluefox) Corrected error in GUI with empty password
- (Apollon77) Do not control saturation with a percentage request via alexa
- (bluefox) Migrated GUI to v5
- (Apollon77) Fix temperature controlling for thermostats via alexa
- (Apollon77) Update dependencies to allow better automatic rebuild
- (bluefox) Tried to correct URL key creation for Google home
- (kirovilya) Alisa: update for binary-sensor "motion" and "contact"
- (Apollon77) Fix crash cases reported by Sentry
- (bluefox) Added the generation of URL key for services
- (Apollon77) Fix crash case reported by Sentry (IOBROKER-IOT-3P)
- (Apollon77) Optimize logging when many devices are used
- (Apollon77) Also support "stored" when a rgb state is turned on/off
- (Apollon77) Fixed control percent value to respect min/max correctly
- (bluefox) Support for response messages longer than 128k (zip)
- (Apollon77) Respect min/max when calculating the value for byOn with % values
- (Apollon77) Fix crash case reported by Sentry (IOBROKER-IOT-3C)
- (Apollon77) Make sure to not remember the off value when using stored values for on
- (Apollon77) Fix crash case reported by Sentry (IOBROKER-IOT-3A)
- (bluefox) Fixed Google home error with color control
- (bluefox) Fixed error with the certificates fetching
- (bluefox) Removed deprecated package
request - (bluefox) Refactoring and better error handling
- (bluefox) Added experimental support for remote access
- (bluefox) Corrected the enabling of the category
- (bluefox) Respect the min/max limits by controlling
- (bluefox) Fixed the response for the heating control
- (bluefox) Make it admin4 compatible
- (bluefox) Fixed the encryption of the password. Warning: if you see the message in the log, that password is invalid, please enter the password in configuration dialog one more time and save.
- (foxriver76) we now write data received from custom services with the acknowledge flag
- (bluefox) Only added one debug output
- (bluefox) fixed the blind functionality in alisa
- (bluefox) implemented the sensor functionality in alisa
- (bluefox) allowed the control of the blinds in alisa
- (Apollon77) add missing object smart.lastObjectID
- (bluefox) Fixed the dimmer issue with alisa.
- (Morluktom) Alexa - Corrected the request for percentage values
- (bluefox) Added the reconnection strategy if DNS address cannot be resolved
- (bluefox) Updated configuration GUI to the latest state
- (bluefox) Corrected the "Google home" error
- (bluefox) Try to fix google home error
- (bluefox) Corrected the configuration table for Google home
- (bluefox) Corrected the configuration table for Google home
- (bluefox) Trying to fix the set to false at start for Google home
- (bluefox) Added the debug outputs for Google home
- (bluefox) The deletion of google home devices was corrected
- (bluefox) The Google home table was rewritten
- (Morluktom) Corrected the request for temperature
- (bluefox) Updated the select ID dialog.
- (bluefox) Updated the select ID dialog.
- (bluefox) Updated GUI for config.
- (bluefox) Added information about changed linking process.
- (bluefox) Some colors were changed in the dark mode.
- (Apollon77) Crash prevented (Sentry IOBROKER-IOT-W)
- (bluefox) Values for modes will be converted to number in Alisa
- (bluefox) Added vacuum cleaner to Alisa
- (bluefox) Added blinds, lock and thermostat to Alisa
- (Apollon77) crash prevented (Sentry IOBROKER-IOT-V)
- (bluefox) Added french letters to allowed symbols
- (bluefox) Used new SelectID Dialog in GUI
- (bluefox) Small change for nightscout
- (bluefox) Changed requirements for password
- (bluefox) Do not try to load the "sharp" if the blood sugar not enabled
- (Apollon77) Make sure that invalid configured states or values without a timestamp do not crash adapter (Sentry IOBROKER-IOT-8)
- (Apollon77) Make sure publishes after the disconnect to not break adapter (Sentry IOBROKER-IOT-A)
- (bluefox) Better error output is implemented
- (bluefox) Fixed the problem if admin is not on 8081 port
- (Apollon77) error case handled where system.config objects does not exist (Sentry IOBROKER-IOT-5)
- (bluefox) fixed IOBROKER-IOT-REACT-F
- (bluefox) Fixed crashes reported by sentry
- fixed iot crash when timeouts in communications to Google happens (Sentry IOBROKER-IOT-2)
- fixed iot crash when google answers without customData (Sentry IOBROKER-IOT-1)
- (Apollon77) Add the Sentry error reporting to
React Frontend
- (Apollon77) remove js-controller 3.0 warnings and replace
adapter.objectsaccess - (Apollon77) add linux dependencies for canvas library
- (Apollon77) add sentry configuration
- (TA2k) Fix updateState for Google Home
- (bluefox) The blood glucose request supported now
- (TA2k) Fixed deconz issues in Google Home
- (Apollon77) fix alisa error with invalid smartName attributes
- (Apollon77) usage with all kinds of admin ports and reverse proxies optimized
- (Apollon77) Dependency updates
- (Apollon77) Make compatible with Admin > 4.0 because of updated socket.io
- (bluefox) Fixed problem if the port of admin is not 8081
- (TA2k) Google Home handling and visualization improved.
- (bluefox) Now is allowed to select the temperature values as alexa states
- (bluefox) Allowed the setting type immediately after insertion of new state
- (bluefox) Fixed: sometimes the configuration could not be loaded
- (bluefox) Optimization of google home communication was done
- (bluefox) The sending rate to google home is limited now
- (TA2k) Room fix for Google Home and LinkedDevices
- (bluefox) decreased keepalive value to fix issue with disconnect
- (TA2k) Google Home problem fixed with LinkedDevices
- (bluefox) Added support of aliases
- (TA2k) Improved support for Google Home
- (TA2k) Added auto detection for RGB, RGBSingle, Hue, CT, MediaDevice, Switch, Info, Socket, Light, Dimmer, Thermostat, WindowTilt, Blinds, Slider
- (TA2k) Added support for manually adding states as devices
- (TA2k) Fix update state after Sync
- (TA2k) Added typical Google Home devices and traits/actions
- (TA2k) Fix only process update message when Alexa is checked in the options
- (bluefox) Fixed password encoding. Please enter password anew!
- (bluefox) Fixed language issues for google home and yandex alice
- (bluefox) Support of private skills/actions was added.
- (TA2k) Google Home list was added
- (bluefox) tried to add yandex Alisa
- (Apollon77) Change enable/disable of Amazon Alexa and of Google Home from configuration to be really "active if selected".
- (bluefox) Allowed the enablement and disable of Amazon Alexa and of Google Home from configuration.
- (bluefox) Add version check to google home
- (bluefox) Blockly was fixed
- (bluefox) Detection of google devices was fixed
- (bluefox) Generation of new URL key was added
- (bluefox) Change the name of adapter
- (bluefox) Added extended diagnostics
- (bluefox) The configuration dialog was corrected
- (bluefox) The possibility to create the answer with script for the custom skill was implemented.
- (bluefox) Initial commit
The MIT License (MIT)
Copyright (c) 2018-2024 bluefox [email protected]
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.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent