Presentation Documentation Todo-List / Changelog Dedicated Forum Beta-testing cat

Installing the Alexa-API Plugin

Install the Plugin from the Market

Note on the versions:

You have the choice between the version Stable or version beta. Many new features are always more present on the Beta than on the Stable but they are in test. If you are a gamer and curious, you can install the Beta version. Note: You do not need to install Jeedom in Beta (this is not recommended for that matter) to install the Beta plugin. You can switch from a Beta version to a Stable version quite easily and vice versa, just reinstall over the other version.

Activate Plugin

Reload dependencies

Manually generate the Amazon cookie

Log in to Amazon’s pop-up

Close the window as soon as the Amazon Cookie is created.

Launch the Daemon if it does not launch itself

Launching the SCAN

Devices appear, go into a device and in Orders launch a Speak to test. Alexa speaks in less than 5 minutes!!

Update or Change Version

What to do? Since the plugin and its API are alive (Amazon has not documented the API and allows it to change its protocols over time), updates make it possible to make corrections in the links between the plugin and the Amazon server.

Three solutions to have an operational installation:

• Remove all Amazon devices and their orders and recreate them
• Force update of all commands
• Launch a SCAN that detects new equipment or commands

The choice between these three solutions depends on the number of scenarios you have developed with the Alexa-API Plugin. Indeed, the first solution removes all devices and all commands, so it will remove them in your scenarios. The second solution is more respectful of your scenarios because it will update your orders without removing them and therefore your scenarios will be intact but if it does not work, you will have to use solution 1.

Solution 1: Remove all equipment and their controls and recreate them

This is the most important mode clean and the most optimised since you leave with an installation like new devices and their commands.

To do this, you have to use the button

Attention, this function removes all equipment and their commands, so you lose all links in your scenarios.

Solution 2: Force update of all commands

This is the most important mode simple and risk-free since your equipment and their orders are not deleted. This forcing therefore does not impact your scenarios.

To do this, you have to use the button

If you do not want to start the update forcing on all the Orders of all equipment, you can launch it on a single equipment (and therefore on all its orders). To do so, go to the equipment concerned and click on:

Solution 3: The SCAN

Finally, note that the scan can be launched at any time, it does not impact the equipment already detected or the existing commands, but it recreates all the new Devices or Devices removed. It also recreates all the news orders or orders deleted.

Management screens

Scan

Allows to automatically launch the detection of all your devices, you can launch it whenever you want, it never removes any device or command, no risk.

Configuration

This is the whole parameterisation engine. If something doesn't seem intuitive enough, please let us know, we'll document it or make it simpler.

Health

Gives indications on the health of your equipment

Routines

Lists the routines saved on your Amazon account and allows you to run them manually

Reminders/Alarms

Gives a list of your alarms or reminders, allows you to delete them. Manual deactivation is no longer working.

History

This is the entire history of the activity of your Amazon equipment, gives the indication of success if necessary.

Requester Info

Reserved for informed users, it allows to question the Amazon server

Requester Action

Reserved for highly savvy users, it allows you to launch raw requests to the Amazon server

The tiles

To date, each piece of equipment can generate 3 tiles.

• The main tile of the equipment with its interactions with you, your speaking orders, alarms/reminders, volume and the ability to launch routines
• Multimedia player tile
• The tile of the current playlist

The tile of the main equipment

A : This is the last interaction with you, note that you can retrieve this information and use it in a scenario.

B : You can start a routine by selecting it from the drop-down list

C : The volume, note that it updates if you change the volume on the device. (The volume of a group is imposed on all devices in the group)

D/E/F : This is the next alarm, music alarm or reminder.

G : It is a form that allows Alexa to speak.

Multimedia player tile

The tile of the current playlist

Simple orders

Principle

Simple commands are pre-installed to detect devices, so you have immediately usable commands. Pre-installed commands can be used as is in scenarios. Please note that all orders can be adapted individually, so that informed users will be able to create their orders and personalise them thanks to the possible parameters of each order. This documentation pays little attention to simple commands because their use is considered to be intuitive, but complex commands are detailed in the next chapter.

Next Alarm

Next Music Alarm

Next Timer

Next Reminder

These 4 INFO commands work the same way. They are updated automatically by the plugin (by MQTT and by CRON). The result is given in the following format: 2019-12-02 21:10:00. If you want it in another format 2110 e.g. A tutorial explains how to do it.

Make Alexa speak in SSML

Amazon has integrated SSML into its equipment and this makes the way of speaking extremely natural. You can further personalise sentences by providing details on breaks, as well as audio formatting of acronyms, dates, times, … abbreviations, you can also choose the language of reading, a quote or a foreign language expression so that it can be read with the foreign accent in a text in your original language. Unlike the other commands to make Alexa speak, on this command, the choice was made to scrupulously respect the syntax of the SSML protocol, tags included. It will therefore be necessary to use the opening and closing tags and be rigorous in the way these sentences are coded.

Examples include:

<speak> <voice name="Conchita"> <prosody rate="medium" pitch="high"> Yé calls me Conchita. yé fair lé menache partou dans la maichon.</prosody></voice> </speak>

or

<speak> Hello I can read <say-as interpret-as="characters">SSML</say-as>. I can pause <break time="3s"/>. A cardinal <say-as interpret-as="cardinal">10</say-as>. in ordinal <say-as interpret-as="ordinal">10</say-as>. or digit <say-as interpret-as="characters">10</say-as>. </speak>

or

<speak><amazon:effect name="whispered">Hello, I'm a ghost</amazon:effect></speak>

Some interesting links:

• The W3C reference on the SSML
• Amazon’s documentation on SSML
• Google documentation on SSML (in English)
• The interjections French programmed on Amazon devices (interesting!!!)

Launch an ad (so on all devices)

To date, we do not yet know how to use the ‘Advertisement’ command in the Alexa smartphone app, but we can do the same with the ‘Speak to Alexa’ command. Thus, to make an announcement "The factor has passed, it is necessary to make (in a scenario):

• Order Talk to Alexa
• Put the message in Message Alexa announces the postman has passed

Complex orders

Principle

Simple commands (previous paragraph) are pre-installed to detect devices, so you have immediately usable commands. Complex commands are accessible to experienced users and their use is much more difficult but they are much more powerful. Note that simple commands can be customized. They will become complex orders. To do so, use the button (below the control panel):

You can use pre-installed commands to copy the syntax and use the documentation below to find out all the possible options. If you want another function, another format or do not find your happiness, contact the plugin creation team, there will always be a solution for you.

Note: : So that the command " Add an action command either active, check this box in the configuration of the plugin:

alarm?when=#when#&recurring=#recurring#&sound=#sound#

This command allows you to add an alarm to the device in which the command is created.

Here are the options:

• when=YYYY-MM-DD HH24:MI:SS

Example: 2019-12-31 21:36:00

Note that alarms are different from reminders and must be in a 24-hour slot (an alarm for 31/12 in April is not possible, unlike reminders). Thus, if no recurrence is programmed (by the recurring parameter), only the time is taken into account, the day is ignored by Amazon.

• recurring=#recurring#

The programming of this parameter is much easier by a scenario since a drop-down list allows you to easily choose the recurrence. But this can be done manually in an action command with the following encoding:

P1D=Every day
XXXX-WD=weekdays
XXXX-WE=Weekends
XXXX-WXX-1=Every Monday
XXXX-WXX-2=Every Tuesday
XXXX-WXX-3=Every Wednesday
XXXX-WXX-4=Every Thursday
XXXX-WXX-5=Every Friday
XXXX-WXX-6=Every Saturday
XXXX-WXX-7=Every Sunday

• sound=#sound#

This is the sound of the alarm. #sound# may be replaced by:

_alerts _melodic _01 for Simple Alarm
_alerts _melodic _01 for Simple Timer
_alerts _melodic _02 for A la Drift
_alerts _atonal _02 for Metallic
_alerts _melodic _05 for Clarity
_alerts _repetitive _04 for Comptoir
_alerts _melodic _03 for Focus
_alerts _melodic _06 for Glow
_alerts _repetitive _01 for Bedside table
_alerts _melodic _07 for Vif
_alerts _soothing _05 for Orca
_alerts _atonal _03 for Light of the porch
_alerts _rhythmic _02 for Pulsar
_alerts _musical _02 for Pluvieux
_alerts _alarming _03 for Square Waves

reminder?text=#message#&when=#when

This command allows you to add a reminder to the device in which the command is created.

Here are the options:

• when=YYYY-MM-DD HH24:MI:SS

Example: 2019-12-31 21:36:00

• text=#message#

You have the possibility to give a title to your recall.

whennextalarm?position=1&status=ON&format=hour

Note: This command is hidden, it gives the result in the info command: Next Alarm Hour

This command returns the next alarm of the device in which the command is created. Attention, this command is a command ACTION, it must be connected to an order INFO which will show the result, look at the explanation below the description of the options.

Here are the options:

position=x

• Putting 1 for the next alarm
• 2 for the next
• and so on

Default, position=1 if not specified

status=x

• Putting ON to take into account only active alarms
• Putting OFF to take into account only inactive alarms
• Putting ALL to take into account all alarms

By default, status=ON if not specified

format=x

• Putting hour to have a result in format HH:MM (Warning, this display is dangerous in case you program alarms beyond 24h, this is possible with repetitions)
• Putting hhmm to have a result in format HHMM
• Putting full to have a detailed display yyyy-MM-dd’T’HH:mm:ss.SSS

By default, format=hhmm if not specified

Note: : If you need another format, do not hesitate to ask me, I will add it in the next version.

Creation of the order INFO which will display the result of the command whenNextAlarm

The INFO command that will give you the result of the WhenNextAlarm command will be created automatically as soon as the field Order Name Info in the column Result in will be filled.

Explanation of the interaction between the ACTION command and the INFO command

• When you run the ACTION command, the Amazon server is queried and the result is assigned to the INFO command
• When you launch the INFO command, Jeedom will give you the result of the corresponding ACTION command.

(All this is designed in the same logic as the Virtual plugin)

Note: : If there will be no alarm in the near future, the server will reply ‘none’.

whennextmusicalalarm?position=1&status=ON&format=hour

Works as whennextalarm but for music alarms.

musicalalarmmusicentity?position=1&status=ON

Works as whennextmusicalalarm but provides information MusicEntity This corresponds to what will be played at the time of the alarm.

whennextreminder?position=1&status=ON

Note: This command is hidden, it gives the result in the info command: Next Reminder Hour

This command gives the next reminder, it works exactly like WhenNextAlarm.

deleteallalarms?type=alarm&status=all

This command removes all reminders and/or alarms from the device in which the command is created.

Here are the options:

type=x

• Putting alarm to remove only alarms
• Putting reminder to delete only reminders
• Putting all to remove alarms and reminders

By default, type=alarm if not specified

status=x

• Putting ON to remove only active alarms and/or reminders
• Putting OFF to remove only inactive alarms and/or reminders
• Putting ALL to remove all alarms and/or reminders

By default, status=ON if not specified

Note: : For the deletion to work, the Alexa must be connected!!

history?maxRecordSize=50&recordType=’VOICE_HISTORY’

Any new order in test that will look for the history.

• maxRecordSize indicates the record nb to be uploaded (50 on the plugin)
• recordType is probably the record type, VOICE _HISTORY is the default, no other possible values are known.

command?command=#command#

This command sends a command to the device in which the command is created.

Two ways to use this command:

• With a scenario

By going through a scenario, you leave command?command=#command# as an action command and you will have a drop-down list in the scenario, the drop-down list offers you all possible commands.

• With direct order

In this case, it is at the level of the device commands that you will create an action-by-command command to send to Alexa. You will use the following syntax: command?command=play to launch a play and command?command=pause to make a break and so on with orders: pause play next prev fwd rwd shuffle repeat

Note: : STOP does not exist at Amazon, PAUSE should be used

radio station=#select#

This command launches a radio station on the device in which the command is created. For better use in Dashboard, this command has been simplified. We can now select the desired radio rather than knowing by heart the code (s0000) of the radio. Thus, you must first "configure" your radio stations in the commands part of the player who will read it.

By default, the following are configured: s2960|Nostalgia;s6617|RTL;s6566|Europe1

Just follow the format idStation1|Name1;idStation2|Name2

Once you have set up your stations, you can choose them on the radio widget:

Stations:

To find the id of the stations, go to the site https://tunein.com/radio/home/. You choose your radio, and to have the id, click on share, you will see in the link something that starts with a s followed by numbers, it is the id.

Note that the plugin is able to give you the id of the station being played, the procedure is identical to TrackID, look here

Use of a radio control in a scenario

To use a radio command in a scenario, you must be an experienced user (in the config) and know how to create a new command (in the device player):

On this new command, we configure in a very simple way by freezing the station id (or using a variable), for example:

routine?routine=#select#

This command initiates the specified routine.

Two ways to use this command:

• With a scenario

By going through a scenario, you leave routine?routine=#select# as an action command and in the scenario, in the ‘routine ID’ field, specify the routine identifier, see paragraph below to find that identifier.

• With direct order

In this case, you will create an action command at the level of the device’s commands. You will use the following syntax: routine?routine=xxxxx to launch the routine whose ID is xxxx

To find the Routine ID:

You can easily find the Routines ID by consulting the plugin’s Routines screen, last column on the right.

playmusictrack?trackId=#select#

This command initiates playback of the Amazon music playback track by its trackID number. TrackIDs are configured in the action command Listening to a musical track in your device equipment, this is a drop-down list, with the following syntax:

53bfa26d-f24c-4b13-97a8-8c3debdf06f0|Piste1;7b12ee4f-5a69-4390-ad07-00618f32f110|Piste2

So you can change your tracks and their names.

Once the command has been configured, all you have to do is use the drop-down list that will be proposed, both on the Dashboard and in the scenarios.

How to find the trackID of an Amazon-Music track?

The Alexa-API plugin is able to give you the trackID of the track that is being played. To do so, follow these steps:

• Go to the controls of the equipment you are using and check the box Show of the order Amazon Music Id

• A music note will appear on the Dashboard, on the tile of your equipment, this is where the ID will appear
• Launch the music and record the information displayed

• You keep or not the information on your dashboard, to delete it, uncheck Show of the order Amazon Music ID

Note that it also works to find the ID of a music station that can be launched with radio station=#select#

However, it was found that for some playlists, the ID did not go up. To make sure you have it, launch only the track you want (not a playlist).

Other features

Edit player icon

Player tile images are images sent by music providers' servers. These images are links temporary and so you can end up with empty images. This results in:

To avoid this, the players have been modified and if there is no image, the thumbnail of the player is displayed, which gives:

If you want to change the image, simply replace the file logourl.png which can be found in:

plugins/alexaamazonmusic/core/config (e.g. change amazonmusic for other players)

Using tags for interjections and sounds

For the feature "Make Alexa speak" but it also works for the other methods to make Alexa speak, it is set up two novelties. Interjections and sounds from the library.

• FR interjections are described here, the other countries also have their page.
• The sounds of the library are described here

To make it easier to send commands, Alexa-API has designed a tag system.

The sounds of the Amazon library

For example, instead of sending

<audio src= »soundbank://soundlibrary/animals/amzn_sfx_lion_roar_01″/>

we can simply add

#animals/amzn_sfx_lion_roar_01#

Throw the roar of a lion. Many other sounds are in Amazon Sound Library.

Interjections

On a principle similar to the sounds of the library, the interjections are to be put between tag #

Example:

Text and interjection sequence

Be careful, unlike sounds that can be drowned in sentences, interjections must be in separate sentences, so this example will not work:

For the interjection to be taken into account, it must be put in a separate sentence, so add a point:

Volume Slider

In the April 2021 version, the volume slider has been completely revised. The Widget of Noodom (a very big thank you to him) has been recast and integrated into the widgets. The widget looked like:

(Use Alexaapi/Volume_legacy now to have this widget) and it becomes:

(Corresponds now to Alexaapi/Volume)

The footprint is the same to be compatible with each individual’s personalised designs.

Customize the widget

The widget is fully customizable, just use the widget variables NooSlider, a doc is available with all optional parameters.

By default, the parameters sent are:

• displayedValues = "0.20,40,60,80,100"
• step = 10
• width = 200
• height = 50
• handleSize =15
• cursorLeftPos =50
• cursorTopPos = 88
• top parameter not set by default, cf a little lower.

To customize your widget, you can add the parameter as Optional Widget Settings the ‘Volume’ action command, for example:

Back to previous Widget

If you want to keep the old widget, don’t panic, it is still in the plugin. Select Volume_legacy 😉

Improved widget layout

A top parameter is available to set theTop spacing of the widget, it is sufficient to specify it as follows:

Remove loudspeaker logo

If the small loudspeaker logo that indicates the sound, inherited from the previous version of the plugin, bothers you:

Do not panic, it is simple to delete it, go to your equipment, then in commands, click on this little logo in question to the left, it will disappear and save. He is no longer here. (If "Volume" appears, uncheck "Show Name" in the Widget options)

Information Mute

New information arrives on the Alexa equipment widget. This is the information Mute which appears when Alexa is told: Alexa cuts the sound.