Amazon Alexa proxy documentation


#1

Hi, I’m looking for documentation to design a Device-Type that is compatible with the Artik Amazon Alexa proxy. I’m not finding any documentation on the “Work with…” page I’m particularly interested in supporting the Echo Smart-Home Skill API. Thank you.


#3

Hi Sylvain, We do not have an exposed api specifically for the smart home skill. However, following info may be what you are looking for: Once the user connects Alexa to our platform, a device is added to account and you can note the device’s Device Type: i.e., “Amazon Alexa” (Device Type ID: dt15a0925c492043dcabbc15f61d1d2249)

Then learn more about the the Device Type via the manifest using our API (ie: try our api console https://developer.artik.cloud/api-console/). For example, GET /devicetypes with name “Amazon Alexa” and you will get something like following from the manifestSource (ie: rawActionName)

  "id": "dt15a0925c492043dcabbc15f61d1d2249",
  "description": "Data coming from the SAMI Skill for Amazon Alexa Voice Service and Echo device :\n- Destination device\n- Target action name\n- Raw sentence heard\n- Raw device name heard\n- Raw action name heard",
  "manifestSourceType": "json",
  "manifestSource": "{\"fields\":[{\"name\":\"destinationDeviceName\",\"type\":\"CUSTOM\",\"valueClass\":\"String\",\"unit\":\"StandardUnits.NONE\",\"isCollection\":false,\"tags\":[]},{\"name\":\"targetActionName\",\"type\":\"CUSTOM\",\"valueClass\":\"String\",\"unit\":\"StandardUnits.NONE\",\"isCollection\":false,\"tags\":[]},{\"name\":\"ddid\",\"type\":\"CUSTOM\",\"valueClass\":\"String\",\"isCollection\":false,\"tags\":[]},{\"name\":\"rawDeviceName\",\"type\":\"CUSTOM\",\"valueClass\":\"String\",\"isCollection\":false,\"tags\":[]},{\"name\":\"rawActionName\",\"type\":\"CUSTOM\",\"valueClass\":\"String\",\"unit\":\"StandardUnits.NONE\",\"isCollection\":false,\"tags\":[]}],\"messageFormat\":\"json\",\"actions\":[]}"
}

DX-1524


#4

sorry but it’s not helping… this manifest only shows “raw” tts in/outputs… What I need is some info on what the Artik Alexa proxy is looking for in an Artik device’s actions/fields.

For example, I already have the “Artik Cloud Optimized for Smart Home” Alexa Skill installed on my Alexa account and I can see my custom Artik device, i.e. a thermostat, but it’s showing as a “Light” device with On/Off options. Fyi, my custom device-type already contains a SetTemperature action and temperature field.

I’m surprised that you don’t have any doc for Alexa support since the Alexa Artik skill is readily available through the Alexa app.


#5

Hi Sylvain,

Could you help clarify a little more so I can share with team? Are you looking for something more how the TTS is normalized into identifying intents such as nouns, adjectives, etc., along with the device name, action name, etc., given a range of different grammar spoken by user for the same thing.


DX-1524


#6

no I’d rather not mess with the TTS/parsing at all.

There are 2 Skills available on the Alexa app for the Artik Cloud service:

  • Samsung ARTIK Cloud
  • Samsung ARTIK Cloud Optimized for Smart Home

Ideally, I’d like to use the last one to be able to control my custom thermostat Artik device-type. To do so, I need to know what device fields/actions the Artik Alexa proxy is expecting from my Device-Type to interact with my devices.

So far, I got from the “Work with…” page that adding a state/status field and SetOn/SetOff actions will make my device look like a Light for Alexa (and Google Assistant.) So similarly, I’d like to know what fields/actions are required for a thermostat device-type.

I think it’d be helpful for all of us, developers, to publish some integration documentation on the various proxies available from Artik such as the Alexa, Google Assistant, IFTTT proxies (other than the very thin “Work with…” page.) There might be some doc somewhere around but I could not find any…


#7

Hi Sylvain,

Thanks for reply and clarification. I see better what you are trying. You are using the Alexa Skill: “Samsung ARTIK Cloud Optimized for Smart Home” and need to understand the device field/actions interact with your Thermostat Device Type.

I am aware our team is currently working on an updated, more robust version, however, right now it would be similar to only on/off capabilities similar to our Google Home works-with doc (https://artik.cloud/works-with/google-home.html).

If you share the field / actions you would like to define for your Thermostat, I can initially share this with the team so they can have this considered for a future update and they may be able to provide any renaming until such update is available. My understanding this moment is you can have “setOn, setOff, setTemperature”, so what you can start with time being until such update is available.


#8

If above summary is correct, I have requested from team to provide following:
Requirement for Alexa to be able to interact with a Device Type (ie: Thermostat Device Type). As initial suggestion, provided the following actions as a starting point which our team team can clarify.

getTemperature, setTemperature, on, off, setOn, setOff, setMode, etc., … (=> requested a more comprehensive list).


#9

ok, yes, initially I had used this Google Home page as reference. In my case, my device has both the SetOn/Off actions AND the SetTemperature but the temperature doesn’t seem to work for me…

Anyway, to be of any use with a thermostat, a Smart-Home API should at least match the Alexa Smart-Home API for the Thermostat.Controller and Temperature.Sensor.

Do you have any ETA for the Alexa/Smart-Home upcoming release? my main appeal for using Artik for my current application was the advertised cloud integration with third-party services… but it currently looks pretty limited out of the box.

Thank you


#10

At this time I do not have an ETA to share regarding release. However, I do have more information which may help regarding the thermostat which team has provided. This is in regards to not being able to set the temperature (could verify with trying #1 #2 below)?

  1. DT should provide an action setTargetTemperature (or setTemperature) with unit in C°
  2. alexa should be configured to use C° for temperature
  3. increase/decrease commands are not implemented
  4. Kelvin degree are not implemented

#11

Thank you, I’ll give it a try.

But, without Fahrenheit, it’s pretty much useless for US market :slight_smile:


#12

Jonathan, could you, please, confirm whether a DT that has both SetOn/Off AND setTemperature will be recognized as a thermostat by Alexa?

Right now, it’s being recognized as a Light. So I’m guessing, the Alexa proxy “sees” the SetOn/Off first and ignores the setTemperature, right?


#13

Thanks for reporting this … let me check with our team responsible for this and get back to you soon.


#14

@Sylvain_Bernard

For your issue “Device Type with setOn, setOff, and setTemperature, is recognized as a light, rather than a thermostat.”, please provide the corresponding ARTIK cloud device type / manifest. We want to take a close look at the device type.


#15

Here is the device manifest:

{
“fields”: [
{
“name”: “temperature”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“isCollection”: false,
“description”: “Current temperature in Fahrenheit”,
“tags”: [],
“unitSymbol”: “°F”
},
{
“name”: “coolSetpoint”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“isCollection”: false,
“description”: “Cool setpoint”,
“tags”: [],
“unitSymbol”: “°F”
},
{
“name”: “heatSetpoint”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“isCollection”: false,
“description”: “Heat setpoint”,
“tags”: [],
“unitSymbol”: “°F”
},
{
“name”: “setpoint”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“isCollection”: false,
“description”: “Currently active setpoint”,
“tags”: [],
“unitSymbol”: “°F”
},
{
“name”: “hvacMode”,
“type”: “CUSTOM”,
“valueClass”: “String”,
“isCollection”: false,
“description”: “Currently active HVAC mode”,
“tags”: [],
“metaData”: [
{
“type”: “VALUES_STRING”,
“value”: [
“cool”,
“heat”,
“auto”,
“off”
]
}
]
},
{
“name”: “operatingMode”,
“type”: “CUSTOM”,
“valueClass”: “String”,
“isCollection”: false,
“description”: “Currently active HVAC operating mode”,
“tags”: [],
“metaData”: [
{
“type”: “VALUES_STRING”,
“value”: [
“off”,
“idle”,
“heating”,
“cooling”
]
}
]
},
{
“name”: “fanMode”,
“type”: “CUSTOM”,
“valueClass”: “String”,
“isCollection”: false,
“description”: “Currently active Fan mode”,
“tags”: [],
“metaData”: [
{
“type”: “VALUES_STRING”,
“value”: [
“off”,
“on”,
“auto”
]
}
]
},
{
“name”: “state”,
“type”: “CUSTOM”,
“valueClass”: “String”,
“isCollection”: false,
“description”: “HVAC operating state”,
“tags”: []
},
{
“name”: “bootCount”,
“type”: “CUSTOM”,
“valueClass”: “Integer”,
“isCollection”: false,
“description”: “Counter used to track the number of reboots”,
“tags”: []
},
{
“name”: “currentTemp”,
“type”: “CURRENT_TEMPERATURE”,
“valueClass”: “Double”,
“isCollection”: false,
“description”: “Current temperature in Celsius”,
“tags”: [],
“unit”: “SI.CELSIUS”
},
{
“name”: “targetTemp”,
“type”: “TARGET_TEMPERATURE”,
“valueClass”: “Double”,
“isCollection”: false,
“description”: “Target current-setpoint temperature in Celsius”,
“tags”: [],
“unit”: “SI.CELSIUS”
}
],
“messageFormat”: “json”,
“actions”: [
{
“name”: “setHeatSetpoint”,
“description”: “Sets the Heat setpoint in Fahrenheit”,
“parameters”: [
{
“name”: “hsp”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“unitSymbol”: “°F”
}
],
“isStandard”: false,
“type”: “CUSTOM”
},
{
“name”: “setTempF”,
“description”: “Set current-setpoint in Fahrenheit”,
“parameters”: [
{
“name”: “temp”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“unitSymbol”: “°F”
}
],
“isStandard”: false,
“type”: “CUSTOM”
},
{
“name”: “setCoolSetpoint”,
“description”: “Sets the Cool setpoint in Fahrenheit”,
“parameters”: [
{
“name”: “csp”,
“type”: “CUSTOM”,
“valueClass”: “Double”,
“unitSymbol”: “°F”
}
],
“isStandard”: false,
“type”: “CUSTOM”
},
{
“name”: “setHvacMode”,
“description”: “Sets the HVAC mode”,
“parameters”: [
{
“name”: “mode”,
“type”: “CUSTOM”,
“valueClass”: “String”,
“metaData”: [
{
“type”: “VALUES_STRING”,
“value”: [
“cool”,
“heat”,
“auto”,
“off”
]
}
]
}
],
“isStandard”: false,
“type”: “CUSTOM”
},
{
“name”: “setFanMode”,
“description”: “Sets the Fan mode”,
“parameters”: [
{
“name”: “mode”,
“type”: “CUSTOM”,
“valueClass”: “String”,
“metaData”: [
{
“type”: “VALUES_STRING”,
“value”: [
“off”,
“on”,
“auto”
]
}
]
}
],
“isStandard”: false,
“type”: “CUSTOM”
},
{
“name”: “setOff”,
“description”: “Turns Off the HVAC”,
“parameters”: [],
“isStandard”: true,
“type”: “CUSTOM”
},
{
“name”: “setOn”,
“description”: “Turns On the HVAC”,
“parameters”: [],
“isStandard”: true,
“type”: “CUSTOM”
},
{
“name”: “setTemperature”,
“description”: “Set current setpoint in Celsius”,
“parameters”: [
{
“name”: “temp”,
“valueClass”: “Double”,
“children”: null,
“unit”: “SI.CELSIUS”,
“isCollection”: false,
“type”: “CUSTOM”
}
],
“isStandard”: true,
“type”: “CUSTOM”
}
]
}


#16

Can you provide the device type(device type unique name) as well?
You can send it via support@artik.cloud if not posting here.


#17

@Sylvain_Bernard could you please address my question above if you still need our assistance?


#18

For the manifest copied into the forum, please change setTemperature to setTargetTemperature. Then alexa should support “set … to … degree”.

Remember temperature is NOT SUPPORTED officially.


#19

Starting your comment, we could think that the Smart Home Skill use the first Alexa Smart Home Skill API and not v2 or v3.
There are a list of avaiable devices in Artik Smart Home Skill?

Alexa Smart Home Skill has these devices:
https://developer.amazon.com/docs/smarthome/understand-the-smart-home-skill-api.html

Lights, switches and bulbs ( I think yes)
Door locks ??
Entertainment devices like smart TVs ??
Smart home cameras ??
Thermostats and fans ??
Microwave ovens  ??

Bye
Sandro


#20

@Sandro_Di_Maco

Happy to answer here. This is what I’ve compiled from our team to assist with your development:

  1. Please be sure you are using the proper Alexa Skill, with the “Optimized” name.

"Samsung ARTIK Cloud Optimized for Smart Home"

  1. At the time of this writing, this uses the Alexa v3 API.

  2. To develop a compatible Device Type which works with our Skill (1) above, this very moment we only officially support “Switch” and “Dimmers”. We will provide a list of compatble devices here in the future:

https://artik.cloud/works-with/amazon-echo.html

Here are details you need to develop a compatible Device Type:


Switch
=====
Device Type's Manifest should include the following:

Fields

A field for the state
(requires) tag "switch" or "state"
(requires) type "Boolean"

Actions

(requires) action to turn on
(requires) with name in: "setOn", "on", "turnOn" (case insensitive)
(requires) with no parameters

(requires) action to turn off
(requires) with name in: "setOff", "off", "turnOff" (case insensitive)
(requires) with no parameters

Dimmer
=====
Device Type's Manifest should include the following:

Fields:

a field for the level
with the tag "level" or "percentage" or "brightness"
with type "Double" or "Integer" or "Long"
Actions:

action to set the level
with name in: "setLevel", "setPercentage", "setBrightness" (case insensitive)
with parameters:
one parameter
with type "Double" or "Integer" or "Long"
with unit "%"


#21

Any update on enabled devices? Lock, temperature etc?
Thks
Sandro