Generic implementation to enable Tinamous devices to interact with Amazon Alexa through the SmartHome skill.
- Create a Lambda function ** Note: This needs to be in an appropriate region for your skill language. i.e. English (UK) needs to be in EU-West (Ireland) region.
- Upload this assembly (Use AWS tools and right click on the project to upload).
- Entry point (Handler) should be ** Tinamous.SmartHome::Tinamous.SmartHome.SmartHomeSkill::FunctionHandler
- Runtime C# (.NET Core 2.0)
- Publish a new version ** Note the ARN (top right in AWS Lambda) - be sure to pick the versioned ARN.
- In the Skill developer portal (https://developer.amazon.com)
- Create a new skill, use the V3 Smart Home format
- Set the AWS Lamdba ARN to the lambda just created. ** Also set the appropriate geographical region (i.e. Europe/India).
- Configure Account Linking ** In Tinamous, add a "Alexa Bot", follow the instructions and endpoints on there for account linking.
- On the front (dashboard) page of skills, copy the Skill ID
- Back in Lambda... ** Add the Alexa Smart Home trigger ** Set the Application ID to the Skill ID from your skill. ** Click to the Monitoring tab, then Jump to Logs. *** If you get a "Log group not found" be sure you've given the execution role cloud watch permissions.
Head on over to Alexa.Amazon.co.uk (or .com I guess), add the skill:
- Skills
- My Skills
- Hopefully it shows up eventually in the dev section.
- Enable the skill and link to your tinamous account ** Enter the Tinamous account name, that's the .Tinamous.com bit you use when you navigate to Tinamous for your devices. ** Enter your username and password. Alexa will post messages as you so you may prefer to create a new member (called Alexa?) to do them instead.
When you use phrases such as, "Alexa, Turn on the kettle", the Tinamous SmartHome skill will post a status message "@Kettle turn on". Your device should use an MQTT connection to receive these status message and then process the "turn on" command.
Updates should be pushed back to Tinamous through MQTT in the form of field values, when the device is on, the appropriate field should be set to true.
- If you use different email / amazon accounts for day to day alexa, and development, then you can use "Alexa, switch profile" to switch between normal and dev.
- Tag the device with "Alexa.SmartDevice"
- Tag with the Alexa Interface the device supports (e.g. Alexa.PowerController)
- Implement the required status message (or in future named command) processing.
- Expose properties required by the Alexa Interface ** Use tags or named fields to match the required state property.
When Alexa runs device discover the interface will not add supported properties if the fields are not found.
For devices that have multple ports/outlets
- Tag with MultiPort
- Add the state variable (MetaTag) Name = 'PortCount' Value = the number of ports. (e.g. PortCount,4)
- For each port you wish to add to Alexa's devices add a Name = "Port-n", Value = Name of the device on the port. (e.g. Port-1,LED Lights )
- Ports without a name are ignored.
- Properties for the interfaces exposed by the device should be tagged with the suffix '-port-n' (e.g. powerState-port-1)
- When quering for properties if the port specific property is not found, the non-port field will be queries.
Run smart home discovery on Alexa. Your devices should be listed.
Directives: None Properties: temperature
Note: Currently only celcius is supported for temperature.
Directives: SetPercentage, AdjustPercentage Properties: percentage
Status Posts: "@Device Set percentage 90" Status Posts: "@Device Set percentage 90 port-1"
Status Posts: "@Device Adjust percentage 10" Status Posts: "@Device Adjust percentage 10 port-1"
Utterance: "Alexa, set <> to number percent"
Note: If you also support Alexa.Brightness percentage requests come in as brightness.
Directives: SetBrightness, AdjustBrightness Properties: brightness
Status Posts: "@Device Set brightness 90" Status Posts: "@Device Set brightness 90 port-1"
Status Posts: "@Device Adjust brightness 10" Status Posts: "@Device Adjust brightness 10 port-1"
Utterance: "Alexa, set the device to <>" Utterance: "Alexa, dim device <>"
Directives: SetColor Properties: color
Status Posts: "@Device Set color HSV 240,0.5,0.1 Status Posts: "@Device Set color HSV 240,0.5,0.1 port-1
Note: color property should be "h,s,v" string value (or h,s,b) - hue, saturation, brightness. (e.g. 200,0.1,0.9)
Note: Report the color property only when the bulb is set to an HSB color
Directives: TurnOn, TurnOff Properties: powerState (powerState-port-1)
Property can be boolean (on/off), or string "ON", "OFF" or numeric (>0 for on, 0 for off)
Status Posts: "@Device Turn On" Status Posts: "@Device Turn On port-1"
Status Posts: "@Device Turn Off" Status Posts: "@Device Turn Of port-1"
Directives: SetPowerLevel, AdjustPowerLevel Properties: powerLevel
Status Posts: "@Device Set powerlevel 20" Status Posts: "@Device Set powerlevel 20 port-1"
Status Posts: "@Device Adjust powerlevel 10" Status Posts: "@Device Adjust powerlevel 10 port-1"
Note: If you also support Alexa.Brightness power level requests come in as brightness.
Directives: Properties: lockState
Status Posts: "@Device
Directives: Properties: None
Status Posts: "@Device
Directives: Properties: lowerSetpoint,targetSetpoint,upperSetpoint,thermostatMode
Status Posts: "@Device
"Alexa, switch on [The Fans]" - Working
"Alexa, switch off [The Fans]" - Working
"Alexa, set [The Fans] to number percent""
"Alexa, set [The Fans] power to x" ??? (Power level)
"Alexa, dim [The Fans] 20%""
"Alexa, set the [The Fans] to 80%" -- this will clash with number percent fan control?
"Alexa, set the [The Fans] to [blue]"
-
Turn On
-
Turn Off
-
Fan Speed x (%)
-
Dim Leds by x
-
Set Leds to x
-
Set Color to ...,...,...,...
See StateReport and discovery capabilities.
- powerState (Power Controller) - fan only (leds done by brightness) (Field: masterPower 1 or 0.)
- powerLevel (Power Level Controller) (0..100) - fan (Field: speedPercentage)
- brightness (Brightness Controller) - leds only. (0..100) (Field: ledBrightness 0..100)
- percentage (Percentage controller - might clash with )
- color (not sure....)
- temperature (in °C)
Visual Studio Setup:
Install AWS Toolkit: https://aws.amazon.com/visualstudio/
Setup the AWS Explorer with IAM credentials.
// See: https://github.com/DamianMehers/AlexaSmartHomeDemo
// NB: To add Amazon.Lambda.Tools use... dotnet add package Amazon.Lambda.Tools (fails with NuGet)
To Update a new version
- Use the Publish To AWS Lambda (right click on project) to upload
- Create a new version of the Lambda, copy the arn.
- Paste arn into skill.
- Copy Skill Id
- Add Alexa Smart Home trigger to Lambda
- Paste skill it.
- Save!
Alexa Developer Console: https://developer.amazon.com/home.html
Alexa SmartHome Documentation:
This application is using Alexa V3 Smarthome API.
Alexa.TemperatureSensor https://developer.amazon.com/docs/device-apis/alexa-temperaturesensor.html
Alexa.PercentageController https://developer.amazon.com/docs/device-apis/alexa-percentagecontroller.html
Alexa.BrightnessController https://developer.amazon.com/docs/device-apis/alexa-brightnesscontroller.html
Alexa.ColorController https://developer.amazon.com/docs/device-apis/alexa-colorcontroller.html
Alexa.PowerController https://developer.amazon.com/docs/device-apis/alexa-powercontroller.html
Alexa.PowerLevelController https://developer.amazon.com/docs/device-apis/alexa-powerlevelcontroller.html
Sample Messages: https://github.com/alexa/alexa-smarthome/tree/master/sample_messages