demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/openhab/openhab-addons.git synced 2025-01-10 07:02:02 +01:00
Code Issues Packages Projects Releases Wiki Activity

[amazonechocontrol] Improve documentation (#17525)

Browse Source 
* Adjust readme

Signed-off-by: Leo Siepel <leosiepel@gmail.com>
This commit is contained in:
lsiepel 2024-12-13 08:35:17 +01:00 committed by GitHub
parent 2a58b8ed9b
commit 334c909b90
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 149 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

428
bundles/org.openhab.binding.amazonechocontrol/README.md
View File

@ -69,13 +69,23 @@ With the possibility to control your lights you could do:
- automatically turn on your lights at the evening
- integrate your smart bulbs with rules
## Binding Configuration
## Supported Things
The binding does not have any configuration.
The configuration of your amazon account must be done in the 'Amazon Account' device.
| Thing Id | Thing Type | Description |
|----------------------|------------|---------------------------------------|
| account | Bridge | Amazon Account |
| echo | Thing | Amazon Echo Device |
| echospot | Thing | Amazon Echo Spot Device |
| echoshow | Thing | Amazon Echo Show Device |
| wha | Thing | Amazon Echo Whole House Audio Control |
| flashbriefingprofile | Thing | Amazon Echo Whole House Audio Control |
| smartHomeDevice | Thing | Smart Home Device |
| smartHomeDeviceGroup | Thing | Smart Home Device group |
## First Steps
You must define an `account` (Bridge) before defining any other Thing can be used.
1. Create an 'Amazon Account' thing
1. open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. `http://openhab:8080/amazonechocontrol/`), click the link for your account thing and login.
1. You should see now a message that the login was successful
@ -92,48 +102,21 @@ You will find the required serial number in settings of the device in the Alexa
If you want to discover your smart home devices you need to activate it in the 'Amazon Account' thing.
Devices from other skills can be discovered too.
See section _Smart Home Devices_ below for more information.
See section *Smart Home Devices* below for more information.
## Account
## Configuration
The configuration of your Amazon account must be done in the 'Amazon Account' device.
### `account` Bridge Configuration
### Account Thing
| Configuration name | Default | Description |
|-------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| discoverSmartHome | 0 | 0...No discover, 1...Discover direct connected, 2...Discover direct and Alexa skill devices, 3...Discover direct, Alexa and openHAB skill devices |
| pollingIntervalSmartHomeAlexa | 30 | Defines the time in seconds for openHAB to pull the state of the Alexa connected devices. The minimum is 10 seconds. |
| pollingIntervalSmartSkills | 120 | Defines the time in seconds for openHAB to pull the state of the over a skill connected devices. The minimum is 60 seconds. |
#### Supported Thing Type
### Thing Configuration
| Thing type id | Name |
|----------------------|---------------------------------------|
| account | Amazon Account |
#### Thing Configuration
| Configuration name | Default | Description |
|---------------------------------|---------|---------------------------------------------------------------------------------------|
| discoverSmartHome | 0 | 0...No discover, 1...Discover direct connected, 2...Discover direct and Alexa skill devices, 3...Discover direct, Alexa and openHAB skill devices |
| pollingIntervalSmartHomeAlexa | 30 | Defines the time in seconds for openHAB to pull the state of the Alexa connected devices. The minimum is 10 seconds. |
| pollingIntervalSmartSkills | 120 | Defines the time in seconds for openHAB to pull the state of the over a skill connected devices. The minimum is 60 seconds. |
#### Channels
| Channel Type ID | Item Type | Access Mode | Thing Type | Description
|-----------------------|-------------|-------------|-------------------------------|------------------------------------------------------------------------------------------
| sendMessage | String | W | account | Write Only! Sends a message to the Echo devices.
## Echo Control (Control Echo devices from openHAB)
### echo, echospot, echoshow, wha Things
#### Supported Thing Type
| Thing type id | Name |
|----------------------|---------------------------------------|
| echo | Amazon Echo Device |
| echospot | Amazon Echo Spot Device |
| echoshow | Amazon Echo Show Device |
| wha | Amazon Echo Whole House Audio Control |
#### Thing Configuration
The `echo`, `echospot`, `echoshow` and `wha` have the same configuration:
| Configuration name | Description |
|--------------------------|----------------------------------------------------|
@ -141,83 +124,116 @@ The configuration of your Amazon account must be done in the 'Amazon Account' de
You will find the serial number in the Alexa app or on the webpage YOUR_OPENHAB/amazonechocontrol/YOUR_ACCOUNT (e.g. `http://openhab:8080/amazonechocontrol/account1`).
### Flash Briefing Profile
#### `flashbriefingprofile` Thing Configuration
The flashbriefingprofile thing has no configuration parameters.
It will be configured at runtime by using the save channel to store the current flash briefing configuration in the thing.
The `flashbriefingprofile` has no configuration parameters.
It will be configured at runtime by using the save channel to store the current flash briefing configuration in the thing. Create a `flashbriefingprofile` Thing for each set you need.
E.g. One Flashbriefing profile with technical news and wheater, one for playing world news and one for sport news.
#### Channels
#### `smartHomeDevice` and `smartHomeDeviceGroup` Thing Configuration
| Channel Type ID | Item Type | Access Mode | Thing Type | Description
|-----------------------|-------------|-------------|-------------------------------|------------------------------------------------------------------------------------------
| player | Player | R/W | echo, echoshow, echospot, wha | Control the music player (Supported commands: PLAY or ON, PAUSE or OFF, NEXT, PREVIOUS, REWIND, FASTFORWARD)
| volume | Dimmer | R/W | echo, echoshow, echospot | Control the volume
| equalizerTreble | Number | R/W | echo, echoshow, echospot | Control the treble (value from -6 to 6)
| equalizerMidrange | Number | R/W | echo, echoshow, echospot | Control the midrange (value from -6 to 6)
| equalizerBass | Number | R/W | echo, echoshow, echospot | Control the bass (value from -6 to 6)
| shuffle | Switch | R/W | echo, echoshow, echospot, wha | Shuffle play if applicable, e.g. playing a playlist
| imageUrl | String | R | echo, echoshow, echospot, wha | Url of the album image or radio station logo
| title | String | R | echo, echoshow, echospot, wha | Title of the current media
| subtitle1 | String | R | echo, echoshow, echospot, wha | Subtitle of the current media
| subtitle2 | String | R | echo, echoshow, echospot, wha | Additional subtitle of the current media
| providerDisplayName | String | R | echo, echoshow, echospot, wha | Name of the music provider
| bluetoothMAC | String | R/W | echo, echoshow, echospot | Bluetooth device MAC. Used to connect to a specific device or disconnect if an empty string was provided
| bluetooth | Switch | R/W | echo, echoshow, echospot | Connect/Disconnect to the last used bluetooth device (works after a bluetooth connection was established after the openHAB start)
| bluetoothDeviceName | String | R | echo, echoshow, echospot | User friendly name of the connected bluetooth device
| radioStationId | String | R/W | echo, echoshow, echospot, wha | Start playing of a TuneIn radio station by specifying its id or stops playing if an empty string was provided
| radio | Switch | R/W | echo, echoshow, echospot, wha | Start playing of the last used TuneIn radio station (works after the radio station started after the openHAB start)
| amazonMusicTrackId | String | R/W | echo, echoshow, echospot, wha | Start playing of an Amazon Music track by its id or stops playing if an empty string was provided
| amazonMusicPlayListId | String | W | echo, echoshow, echospot, wha | Write Only! Start playing of an Amazon Music playlist by specifying its id or stops playing if an empty string was provided.
| amazonMusic | Switch | R/W | echo, echoshow, echospot, wha | Start playing of the last used Amazon Music song (works after at least one song was started after the openHAB start)
| remind | String | R/W | echo, echoshow, echospot | Write Only! Speak the reminder and sends a notification to the Alexa app
| nextReminder | DateTime | R | echo, echoshow, echospot | Next reminder on the device
| playAlarmSound | String | W | echo, echoshow, echospot | Write Only! Plays an Alarm sound
| nextAlarm | DateTime | R | echo, echoshow, echospot | Next alarm on the device
| nextMusicAlarm | DateTime | R | echo, echoshow, echospot | Next music alarm on the device
| nextTimer | DateTime | R | echo, echoshow, echospot | Next timer on the device
| startRoutine | String | W | echo, echoshow, echospot | Write Only! Type in what you normally say to Alexa without the preceding "Alexa,"
| musicProviderId | String | R/W | echo, echoshow, echospot | Current Music provider
| playMusicVoiceCommand | String | W | echo, echoshow, echospot | Write Only! Voice command as text. E.g. 'Yesterday from the Beatles'
| startCommand | String | W | echo, echoshow, echospot | Write Only! Used to start anything. Available options: Weather, Traffic, GoodMorning, SingASong, TellStory, FlashBriefing and FlashBriefing.<FlahshbriefingDeviceID> (Note: The options are case sensitive)
| announcement | String | W | echo, echoshow, echospot | Write Only! Display the announcement message on the display. See in the tutorial section to learn how it’s possible to set the title and turn off the sound.
| textToSpeech | String | W | echo, echoshow, echospot | Write Only! Write some text to this channel and Alexa will speak it. It is possible to use plain text or SSML: e.g. `<speak>I want to tell you a secret.<amazon:effect name="whispered">I am not a real human.</amazon:effect></speak>`
| textToSpeechVolume | Dimmer | R/W | echo, echoshow, echospot | Volume of the textToSpeech channel, if 0 the current volume will be used
| textCommand | String | W | echo, echoshow, echospot | Write Only! Execute a text command (like a spoken text)
| lastVoiceCommand | String | R/W | echo, echoshow, echospot | Last voice command spoken to the device. Writing to the channel starts voice output.
| mediaProgress | Dimmer | R/W | echo, echoshow, echospot | Media progress in percent
| mediaProgressTime | Number:Time | R/W | echo, echoshow, echospot | Media play time
| mediaLength | Number:Time | R | echo, echoshow, echospot | Media length
| notificationVolume | Dimmer | R | echo, echoshow, echospot | Notification volume
| ascendingAlarm | Switch | R/W | echo, echoshow, echospot | Ascending alarm up to the configured volume
| sendMessage | String | W | account | Write Only! Sends a message to the Echo devices.
| save | Switch | W | flashbriefingprofile | Write Only! Stores the current configuration of flash briefings within the thing
| active | Switch | R/W | flashbriefingprofile | Active the profile
| playOnDevice | String | W | flashbriefingprofile | Specify the echo serial number or name to start the flash briefing.
| Configuration name | Description |
|--------------------------|---------------------------------------------------------------------------|
| id | The id of the device or device group |
## Advanced Feature Technically Experienced Users
The only possibility to find out the id is by using the discover function in the UI. You can use then the id, if you want define the Thing in a file.
The url <YOUR_OPENHAB>/amazonechocontrol/<YOUR_ACCOUNT>/PROXY/<API_URL> provides a proxy server with an authenticated connection to the Amazon Alexa server.
This can be used to call Alexa API from rules.
1. Open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. `http://openhab:8080/amazonechocontrol/`)
1. Click on the name of the account thing
1. Click on the name of the echo thing
1. Scroll to the channel and copy the required ID
E.g. to read out the history call from an installation on openhab:8080 with an account named account1:
## Channels
`http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1`
| Channel Type ID | Item Type | Access Mode | Thing Type | Description |
|--------------------------|----------------------|-------------|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| player | Player | R/W | echo, echoshow, echospot, wha | Control the music player (Supported commands: PLAY or ON, PAUSE or OFF, NEXT, PREVIOUS, REWIND, FASTFORWARD) |
| volume | Dimmer | R/W | echo, echoshow, echospot | Control the volume |
| equalizerTreble | Number | R/W | echo, echoshow, echospot | Control the treble (value from -6 to 6) |
| equalizerMidrange | Number | R/W | echo, echoshow, echospot | Control the midrange (value from -6 to 6) |
| equalizerBass | Number | R/W | echo, echoshow, echospot | Control the bass (value from -6 to 6) |
| shuffle | Switch | R/W | echo, echoshow, echospot, wha | Shuffle play if applicable, e.g. playing a playlist |
| imageUrl | String | R | echo, echoshow, echospot, wha | Url of the album image or radio station logo |
| title | String | R | echo, echoshow, echospot, wha | Title of the current media |
| subtitle1 | String | R | echo, echoshow, echospot, wha | Subtitle of the current media |
| subtitle2 | String | R | echo, echoshow, echospot, wha | Additional subtitle of the current media |
| providerDisplayName | String | R | echo, echoshow, echospot, wha | Name of the music provider |
| bluetoothMAC | String | R/W | echo, echoshow, echospot | Bluetooth device MAC. Used to connect to a specific device or disconnect if an empty string was provided |
| bluetooth | Switch | R/W | echo, echoshow, echospot | Connect/Disconnect to the last used bluetooth device (works after a bluetooth connection was established after the openHAB start) |
| bluetoothDeviceName | String | R | echo, echoshow, echospot | User friendly name of the connected bluetooth device |
| radioStationId | String | R/W | echo, echoshow, echospot, wha | Start playing of a TuneIn radio station by specifying its id or stops playing if an empty string was provided |
| radio | Switch | R/W | echo, echoshow, echospot, wha | Start playing of the last used TuneIn radio station (works after the radio station started after the openHAB start) |
| amazonMusicTrackId | String | R/W | echo, echoshow, echospot, wha | Start playing of an Amazon Music track by its id or stops playing if an empty string was provided |
| amazonMusicPlayListId | String | W | echo, echoshow, echospot, wha | Start playing of an Amazon Music playlist by specifying its id or stops playing if an empty string was provided. |
| amazonMusic | Switch | R/W | echo, echoshow, echospot, wha | Start playing of the last used Amazon Music song (works after at least one song was started after the openHAB start) |
| remind | String | R/W | echo, echoshow, echospot | Speak the reminder and sends a notification to the Alexa app |
| nextReminder | DateTime | R | echo, echoshow, echospot | Next reminder on the device |
| playAlarmSound | String | W | echo, echoshow, echospot | Plays an Alarm sound |
| nextAlarm | DateTime | R | echo, echoshow, echospot | Next alarm on the device |
| nextMusicAlarm | DateTime | R | echo, echoshow, echospot | Next music alarm on the device |
| nextTimer | DateTime | R | echo, echoshow, echospot | Next timer on the device |
| startRoutine | String | W | echo, echoshow, echospot | Type in what you normally say to Alexa without the preceding "Alexa," |
| musicProviderId | String | R/W | echo, echoshow, echospot | Current Music provider |
| playMusicVoiceCommand | String | W | echo, echoshow, echospot | Voice command as text. E.g. 'Yesterday from the Beatles' |
| startCommand | String | W | echo, echoshow, echospot | Used to start anything. Available options: Weather, Traffic, GoodMorning, SingASong, TellStory, FlashBriefing and FlashBriefing.\<FlahshbriefingDeviceID> (Note: The options are case sensitive) |
| announcement | String | W | echo, echoshow, echospot | Display the announcement message on the display. See in the tutorial section to learn how it’s possible to set the title and turn off the sound. |
| textToSpeech | String | W | echo, echoshow, echospot | Write some plain text to this channel and Alexa will speak it. SSML is also possible: e.g. `<speak>I want to tell you a secret.<amazon:effect name="whispered">I am not a real human.</amazon:effect></speak>` |
| textToSpeechVolume | Dimmer | R/W | echo, echoshow, echospot | Volume of the textToSpeech channel, if 0 the current volume will be used |
| textCommand | String | W | echo, echoshow, echospot | Execute a text command (like a spoken text) |
| lastVoiceCommand | String | R/W | echo, echoshow, echospot | Last voice command spoken to the device. Writing to the channel starts voice output. |
| mediaProgress | Dimmer | R/W | echo, echoshow, echospot | Media progress in percent |
| mediaProgressTime | Number:Time | R/W | echo, echoshow, echospot | Media play time |
| mediaLength | Number:Time | R | echo, echoshow, echospot | Media length |
| notificationVolume | Dimmer | R | echo, echoshow, echospot | Notification volume |
| ascendingAlarm | Switch | R/W | echo, echoshow, echospot | Ascending alarm up to the configured volume |
| sendMessage | String | W | account | Sends a message to the Echo devices. |
| save | Switch | W | flashbriefingprofile | Stores the current configuration of flash briefings within the thing |
| active | Switch | R/W | flashbriefingprofile | Active the profile |
| playOnDevice | String | W | flashbriefingprofile | Specify the echo serial number or name to start the flash briefing. |
| powerState | Switch | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows and changes the state (ON/OFF) of your device |
| brightness | Dimmer | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows and changes the brightness of your lamp |
| color | Color | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows the color of your light |
| colorName | String | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows and changes the color name of your light (groups are not able to show their color) |
| colorTemperatureInKelvin | Number:Temperature | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows the color temperature of your light |
| colorTemperatureName | String | R/W | smartHomeDevice, smartHomeDeviceGroup | White temperatures name of your lights (groups are not able to show their color) |
| armState | String | R/W | smartHomeDevice, smartHomeDeviceGroup | State of your alarm guard. Options: ARMED_AWAY, ARMED_STAY, ARMED_NIGHT, DISARMED (groups are not able to show their state) |
| burglaryAlarm | Contact | R | smartHomeDevice | Burglary alarm |
| carbonMonoxideAlarm | Contact | R | smartHomeDevice | Carbon monoxide detection alarm |
| fireAlarm | Contact | R | smartHomeDevice | Fire alarm |
| waterAlarm | Contact | R | smartHomeDevice | Water alarm |
| glassBreakDetectionState | Contact | R | smartHomeDevice | Glass break detection alarm |
| smokeAlarmDetectionState | Contact | R | smartHomeDevice | Smoke detection alarm |
| temperature | Number:Temperature | R | smartHomeDevice | Temperature |
| targetSetpoint | Number:Temperature | R/W | smartHomeDevice | Thermostat target setpoint |
| upperSetpoint | Number:Temperature | R/W | smartHomeDevice | Thermostat upper setpoint (AUTO) |
| lowerSetpoint | Number:Temperature | R/W | smartHomeDevice | Thermostat lower setpoint (AUTO) |
| relativeHumidity | Number:Dimensionless | R | smartHomeDevice | Thermostat humidity |
| thermostatMode | String | R/W | smartHomeDevice | Thermostat operation mode |
### Example
*note* the channels of `smartHomeDevices` and `smartHomeDeviceGroup` will be created dynamically based on the capabilities reported by the amazon server. This can take a little bit of time.
The polling interval configured in the Account Thing to get the state is specified in minutes and has a minimum of 10. This means it takes up to 10 minutes to see the state of a channel. The reason for this low interval is, that the polling causes a big server load for the Smart Home Skills.
#### echo.things
## Full Example
### echo.things
```java
Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discoverSmartHome=2, pollingIntervalSmartHomeAlexa=30, pollingIntervalSmartSkills=120]
{
Thing echo echo1 "Alexa" @ "Living Room" [serialNumber="SERIAL_NUMBER"]
Thing echoshow echoshow1 "Alexa" @ "Kitchen" [serialNumber="SERIAL_NUMBER"]
Thing echospot echospot1 "Alexa" @ "Sleeping Room" [serialNumber="SERIAL_NUMBER"]
Thing wha wha1 "Ground Floor Music Group" @ "Music Groups" [serialNumber="SERIAL_NUMBER"]
Thing echo echo1 "Alexa" @ "Living Room" [serialNumber="SERIAL_NUMBER"]
Thing echoshow echoshow1 "Alexa" @ "Kitchen" [serialNumber="SERIAL_NUMBER"]
Thing echospot echospot1 "Alexa" @ "Sleeping Room" [serialNumber="SERIAL_NUMBER"]
Thing wha wha1 "Ground Floor Music Group" @ "Music Groups" [serialNumber="SERIAL_NUMBER"]
Thing flashbriefingprofile flashbriefing1 "Flash Briefing Technical" @ "Flash Briefings"
Thing flashbriefingprofile flashbriefing2 "Flash Briefing Life Style" @ "Flash Briefings"
Thing smartHomeDevice smartHomeDevice1 "Smart Home Device 1" @ "Living Room" [id="ID"]
Thing smartHomeDevice smartHomeDevice2 "Smart Home Device 2" @ "Living Room" [id="ID"]
Thing smartHomeDevice smartHomeDevice3 "Smart Home Device 3" @ "Living Room" [id="ID"]
Thing smartHomeDeviceGroup smartHomeDeviceGroup1 "Living Room Group" @ "Living Room" [id="ID"]
}
```
#### echo.items:
#### echo.items
Sample for the Thing echo1 only. But it will work in the same way for the other things, only replace the thing name in the channel link.
Take a look in the channel description above to know, which channels are supported by your thing type.
@ -292,12 +308,28 @@ String FlashBriefing_Technical_Play "Play (Write only)"
Switch FlashBriefing_LifeStyle_Save "Save (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing2:save"}
Switch FlashBriefing_LifeStyle_Active "Active" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing2:active"}
String FlashBriefing_LifeStyle_Play "Play (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing2:playOnDevice"}
// Lights and lightgroups
Switch Light_State "On/Off" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:powerState"}
Dimmer Light_Brightness "Brightness" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:brightness"}
Color Light_Color "Color" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:color"}
String Light_Color_Name "Color Name" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:colorName"}
String Light_White "White temperature" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:colorTemperatureName"}
// Smart plugs
Switch Plug_State "On/Off" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice2:powerState"}
// Alexa Guard
Switch Arm_State "State" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice3:armState"}
// Smart Home device group
Switch Group_State "On/Off" {channel="amazonechocontrol:smartHomeDeviceGroup:account1:smartHomeDeviceGroup1:powerState"}
```
#### echo.sitemap:
#### echo.sitemap
```perl
sitemap amazonechocontrol label="Echo Devices"
sitemap amazonechocontrol label="Amazone Devices"
{
Frame label="Alexa" {
Default item=Echo_Living_Room_Player
@ -344,62 +376,7 @@ sitemap amazonechocontrol label="Echo Devices"
Slider item=Echo_Living_Room_NotificationVolume
Switch item=Echo_Living_Room_AscendingAlarm
}
}
```
## Flash Briefing
### Supported Things
| Thing type id | Name |
|----------------------|---------------------------------------|
| flashbriefingprofile | Flash briefing profile |
### Channels
The flashbriefingprofile thing has no configuration parameters.
It will be configured at runtime by using the save channel to store the current flash briefing configuration which is set in the alexa app in the thing. Create a flashbriefingprofile Thing for each set you need.
E.g. One Flashbriefing profile with technical news and wheater, one for playing world news and one for sport news.
| Channel Type ID | Item Type | Access Mode | Thing Type | Description
|-----------------------|-------------|-------------|-------------------------------|------------------------------------------------------------------------------------------
| save | Switch | W | flashbriefingprofile | Write Only! Stores the current configuration of flash briefings within the thing
| active | Switch | R/W | flashbriefingprofile | Active the profile
| playOnDevice | String | W | flashbriefingprofile | Specify the echo serial number or name to start the flash briefing.
### Example
#### flashbriefings.things
```java
Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discoverSmartHome=2]
{
Thing flashbriefingprofile flashbriefing1 "Flash Briefing Technical" @ "Flash Briefings"
Thing flashbriefingprofile flashbriefing2 "Flash Briefing Life Style" @ "Flash Briefings"
}
```
#### flashbriefings.items:
Sample for the Thing echo1 only. But it will work in the same way for the other things, only replace the thing name in the channel link.
Take a look in the channel description above to know, which channels are supported by your thing type.
```java
// Flashbriefings
Switch FlashBriefing_Technical_Save "Save (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing1:save"}
Switch FlashBriefing_Technical_Active "Active" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing1:active"}
String FlashBriefing_Technical_Play "Play (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing1:playOnDevice"}
Switch FlashBriefing_LifeStyle_Save "Save (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing2:save"}
Switch FlashBriefing_LifeStyle_Active "Active" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing2:active"}
String FlashBriefing_LifeStyle_Play "Play (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing2:playOnDevice"}
```
#### flashbriefings.sitemap:
```perl
sitemap flashbriefings label="Flash Briefings"
{
Frame label="Flash Briefing Technical" {
Switch item=FlashBriefing_Technical_Save
Switch item=FlashBriefing_Technical_Active
@ -411,99 +388,7 @@ sitemap flashbriefings label="Flash Briefings"
Switch item=FlashBriefing_LifeStyle_Active
Text item=FlashBriefing_LifeStyle_Play
}
}
```
## Smart Home Devices
Note: the channels of smartHomeDevices and smartHomeDeviceGroup will be created dynamically based on the capabilities reported by the amazon server. This can take a little bit of time.
The polling interval configured in the Account Thing to get the state is specified in minutes and has a minimum of 10. This means it takes up to 10 minutes to see the state of a channel. The reason for this low interval is, that the polling causes a big server load for the Smart Home Skills.
### Supported Things
| Thing type id | Name |
|----------------------|---------------------------------------|
| smartHomeDevice | Smart Home Device |
| smartHomeDeviceGroup | Smart Home Device group |
### Thing configuration of smartHomeDevice, smartHomeDeviceGroup
| Configuration name | Description |
|--------------------------|---------------------------------------------------------------------------|
| id | The id of the device or device group |
The only possibility to find out the id is by using the discover function in the UI. You can use then the id, if you want define the Thing in a file.
### Channels
The channels of the smarthome devices will be generated at runtime. Check in the UI thing configurations, which channels are created.
| Channel Type ID | Item Type | Access Mode | Thing Type | Description
|--------------------------|----------------------|-------------|-------------------------------|------------------------------------------------------------------------------------------
| powerState | Switch | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows and changes the state (ON/OFF) of your device
| brightness | Dimmer | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows and changes the brightness of your lamp
| color | Color | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows the color of your light
| colorName | String | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows and changes the color name of your light (groups are not able to show their color)
| colorTemperatureInKelvin | Number:Temperature | R/W | smartHomeDevice, smartHomeDeviceGroup | Shows the color temperature of your light
| colorTemperatureName | String | R/W | smartHomeDevice, smartHomeDeviceGroup | White temperatures name of your lights (groups are not able to show their color)
| armState | String | R/W | smartHomeDevice, smartHomeDeviceGroup | State of your alarm guard. Options: ARMED_AWAY, ARMED_STAY, ARMED_NIGHT, DISARMED (groups are not able to show their state)
| burglaryAlarm | Contact | R | smartHomeDevice | Burglary alarm
| carbonMonoxideAlarm | Contact | R | smartHomeDevice | Carbon monoxide detection alarm
| fireAlarm | Contact | R | smartHomeDevice | Fire alarm
| waterAlarm | Contact | R | smartHomeDevice | Water alarm
| glassBreakDetectionState | Contact | R | smartHomeDevice | Glass break detection alarm
| smokeAlarmDetectionState | Contact | R | smartHomeDevice | Smoke detection alarm
| temperature | Number:Temperature | R | smartHomeDevice | Temperature
| targetSetpoint | Number:Temperature | R/W | smartHomeDevice | Thermostat target setpoint
| upperSetpoint | Number:Temperature | R/W | smartHomeDevice | Thermostat upper setpoint (AUTO)
| lowerSetpoint | Number:Temperature | R/W | smartHomeDevice | Thermostat lower setpoint (AUTO)
| relativeHumidity | Number:Dimensionless | R | smartHomeDevice | Thermostat humidity
| thermostatMode | String | R/W | smartHomeDevice | Thermostat operation mode
### Example
#### smarthome.things
```java
Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discoverSmartHome=2, pollingIntervalSmartHomeAlexa=30, pollingIntervalSmartSkills=120]
{
Thing smartHomeDevice smartHomeDevice1 "Smart Home Device 1" @ "Living Room" [id="ID"]
Thing smartHomeDevice smartHomeDevice2 "Smart Home Device 2" @ "Living Room" [id="ID"]
Thing smartHomeDevice smartHomeDevice3 "Smart Home Device 3" @ "Living Room" [id="ID"]
Thing smartHomeDeviceGroup smartHomeDeviceGroup1 "Living Room Group" @ "Living Room" [id="ID"]
}
```
#### smarthome.items:
Sample for the Thing echo1 only. But it will work in the same way for the other things, only replace the thing name in the channel link.
Take a look in the channel description above to know which channels are supported by your thing type.
```java
// Lights and lightgroups
Switch Light_State "On/Off" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:powerState"}
Dimmer Light_Brightness "Brightness" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:brightness"}
Color Light_Color "Color" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:color"}
String Light_Color_Name "Color Name" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:colorName"}
String Light_White "White temperature" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:colorTemperatureName"}
// Smart plugs
Switch Plug_State "On/Off" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice2:powerState"}
// Alexa Guard
Switch Arm_State "State" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice3:armState"}
// Smart Home device group
Switch Group_State "On/Off" {channel="amazonechocontrol:smartHomeDeviceGroup:account1:smartHomeDeviceGroup1:powerState"}
```
The only possibility to find out the id for the smartHomeDevice and smartHomeDeviceGroup Things is by using the discover function.
#### smarthome.sitemap:
```perl
sitemap smarthome label="Smart Home Devices"
{
Frame label="Lights and light groups" {
Switch item=Light_State
Slider item=Light_Brightness
@ -517,24 +402,23 @@ sitemap smarthome label="Smart Home Devices"
}
```
## How To Get IDs
## Advanced Feature Technically Experienced Users
1. Open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. `http://openhab:8080/amazonechocontrol/`)
1. Click on the name of the account thing
1. Click on the name of the echo thing
1. Scroll to the channel and copy the required ID
### Advanced Feature Technically Experienced Users
The url <YOUR_OPENHAB>/amazonechocontrol/<YOUR_ACCOUNT>/PROXY/<API_URL> provides a proxy server with an authenticated connection to the amazon alexa server. This can be used to call alexa api from rules.
The url <YOUR_OPENHAB>/amazonechocontrol/<YOUR_ACCOUNT>/PROXY/<API_URL> provides a proxy server with an authenticated connection to the Amazon Alexa server.
This can be used to call Alexa API from rules.
E.g. to read out the history call from an installation on openhab:8080 with an account named account1:
`http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1`
To resolve login problems the connection settings of an `account` thing can be reset via the karaf console.
The command `amazonechocontrol listAccounts` shows a list of all available `account` things.
The command `amazonechocontrol resetAccount <id>` resets the device id and all other connection settings.
After resetting a connection, a new login as described above is necessary.
## Tutorials
### Let Alexa speak a text from a rule:
### Let Alexa speak a text from a rule
1) Create a rule with a trigger of your choice
@ -558,7 +442,7 @@ then
end
```
### Show an announcement on the echo show or echo spot:
### Show an announcement on the echo show or echo spot
1) Create a rule with a trigger of your choice
@ -598,7 +482,7 @@ then
end
```
## Playing an alarm sound for 15 seconds with an openHAB rule if a door contact was opened:
## Playing an alarm sound for 15 seconds with an openHAB rule if a door contact was opened
1. Do get the ID of your sound, follow the steps in "How To Get IDs"
1. Write down the text in the square brackets. e.g. ECHO:system_alerts_repetitive01 for the nightstand sound
@ -628,7 +512,7 @@ It is not recommended to use a time below 10 seconds.
Note 2: The rule have no effect for your default alarm sound used in the Alexa app.
### Play a spotify playlist if a switch was changed to on:
### Play a spotify playlist if a switch was changed to on
1. Do get the ID of your sound, follow the steps in "How To Get IDs"
1. Write down the text in the square brackets. e.g. SPOTIFY for the spotify music provider
@ -646,7 +530,7 @@ end
Note: It is recommended to test the command send to play music command first with the voice and the real Alexa device. E.g. say 'Alexa, Playlist Party'
### Start playing weather/traffic/etc:
### Start playing weather/traffic/etc
1. Pick up one of the available commands: Weather, Traffic, GoodMorning, SingASong, TellStory, FlashBriefing
1. Create a rule for start playing the information where you provide the command as string:
@ -660,7 +544,7 @@ then
end
```
### Start playing a custom flashbriefing on a device:
### Start playing a custom flashbriefing on a device
1. Do get the ID of your sound, follow the steps in "How To Get IDs"
1. Write down the text in the square brackets. e.g. flashbriefing.flashbriefing1
@ -675,20 +559,6 @@ then
end
```
### Advanced Feature Technically Experienced Users
The url <YOUR_OPENHAB>/amazonechocontrol/<YOUR_ACCOUNT>/PROXY/<API_URL> provides a proxy server with an authenticated connection to the Amazon Alexa server.
This can be used to call Alexa API from rules.
E.g. to read out the history call from an installation on openhab:8080 with an account named account1:
`http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1`
To resolve login problems the connection settings of an `account` thing can be reset via the karaf console.
The command `amazonechocontrol listAccounts` shows a list of all available `account` things.
The command `amazonechocontrol resetAccount <id>` resets the device id and all other connection settings.
After resetting a connection, a new login as described above is necessary.
## Note
This binding uses the same API as the Web-Browser-Based Alexa site (alexa.amazon.de).