Amazon Echo – DIY Project with PHPoC

[Khanh]

In this article, I am going to show how to use Amazon Echo to voice-control the DIY projects.
This project does the same work as the project https://www.hackster.io/44558/amazon...ia-http-154590 . But there is only one difference, the one project uses MQTT and the other uses HTTP.
It’s not difficult but quite long. I try describing clearly step by step.

Demonstration

Things Used In This Project

• 1 x Amazon Alexa Echo Dot
• 1 x PHPoC Blue
• 1 x PHPoC 4-Port Relay Expansion Board (T-type) http://www.phpoc.com/smart_expansion_board.php
• 1 x Light Bulb

The big picture of this article:

• I. System Architecture
  1. System diagram
  2. Functionalities of each part and interaction among the system parts.
  3. Which parts in system are changeable. If possible, which are the alternative
• II. Amazon Echo Dot – PHPoC
  • Step 1: Setting up an Amazon Echo or Echo Dot
  • Step 2: Creating and configuring Alexa Skill (on Alexa Service)
  • Step 3: Writing source code to handle requests Sent by Alexa (on AWS Lambda)
  • Step 4: Setting up MQTT cloud
  • Step 5: Writing source code on PHPoC to handle commands and control the devices

Now, let’s go into detail.



I. System Architecture

1. System diagram

The system architecture is depended on the type of your skill and your application. It can be customized by yourself. There are three different types of skills that Amazon offers. Refer https://developer.amazon.com/public/...ypes-of-skills for more detail. Each types of skill have its own the general architecture. You can refer to the system architecture of each skills as follows:

• Custom Skills: https://images-na.ssl-images-amazon....ture._TTH_.png
• Smart Home Skills: https://developer.amazon.com/public/..._ecosystem.png
• Flash Briefing Skills: https://developer.amazon.com/public/...0x420_asv2.png

In comparison with Custom Skills, Smart Home Skills is simpler to implement but less flexible. Therefore, in my design, I will build a “Custom Skill” based on system architecture of “Smart Home Skills”.




2. Functionalities of each part and interaction among the system parts

• Amazon echo:
  • (1) - getting your voice command, stream it to Alexa service.
  • (5a) - receiving response from Alexa Service.
• Alexa service: this is where you create the Alexa Skill.
  • (2) - It converts you voice to text, process it, create “intent” data and send it to your service. You need to provide the endpoint of your service (URL or Amazon Resource Names (ARNs)) when you create the skill.
  • (4a) - receiving response from your service and send it to Amazon echo
• Your service: (3) this is where you write your code to handle command from Alexa. Your code will perform two main tasks: send necessary data to Device Cloud and send the response to Alexa service. You need to know endpoint of Device cloud and put it in source code.
• Device cloud: (4b) forward command to IoT devices
• IoT device: get command and take action according to the command.

Discussion:
Someone may ask me “is it possible to remove Device Cloud?”. The answer is “yes”. Your service can send data directly to IoT device. By this way, the process is simpler. But it will be difficult to manage if we have many IoT devices. The following articles show how to send data directly to IoT device without Device Cloud:

• Control Light Bulb (HTTP) https://www.hackster.io/44558/amazon...ia-http-154590
• Read Temperature and Humidity: https://www.hackster.io/44560/amazon...-sensor-0d9b73

3. Which parts in system can be changed. If possible, which are the alternative

• Amazon Echo: you can use Amazon Echo, Amazon Tap, Echo Dot or Echo Look.
• Your service: Amazon provides two ways to build your custom skill:
  • You can build a web service for your skill and host it with any cloud provider. (This is a hard work)
  • You can host your service in AWS Lambda (This is a simpler work)
• Device cloud: you can use any kind of cloud such as:
  • AWS IoT
  • Cloud or PC with the installed MQTT broker
  • Etc.
• IoT device: Any kind of IoT hardware platform which can connect to internet such as PHPoC, Arduino + PHPoC shield, Raspberry

II. Amazon Echo Dot – PHPoC

I am going to show a very simple example of voice-controlling on/off a light bulb. Another example which is quite complicated will be present in the next article.

As mentioned, Amazon echo, the service, device cloud and IoT device are changeable parts. In this project, I use:

• Amazon Echo: Amazon Echo Dot.
• The service: AWS Lambda.
• Device Cloud: MQTT free cloud at iot.eclipse.org
• IoT device: PHPoC and a light bulb

As I described before, the system includes five parts. The following is five steps to do on five parts, respectively.


Pre-require

You need to register Amazon accounts:

• Amazon developer account at https://developer.amazon.com/
• AWS Account at https://aws.amazon.com/

Step 1: Setting up an Amazon Echo Dot

Refer to https://www.amazon.com/gp/help/custo...deId=201994280



Step 2: Creating and configuring Alexa Skill (on Alexa Service)

• Visit https://developer.amazon.com/home.html and sign in
• Navigate to “Alexa” tab, Click “Alexa Skills Kit”
  
  
• Click “Add a New Skill” button, fill some information as below, click “save” and then “next” button.
• In “Skill Information”:
  
  
  
  Note that: invocation name should be written with space “P H P o C” for correct the recognition. And you will interact with Amazon Echo Dot with structure:
  • Alexa, tell P H P o C turn on/off the light
  • Alexa, tell P H P o C turn the light on/off
  
  You can change vocation name to “robot” and can say: Alexa, tell robot turn on/off the light.
• In “Interaction Model”:
  • Intent Schema
    

    		{
    		 "intents": [
    		   {
    		     "slots": [
    		       {
    		         "name": "LightState",
    		         "type": "LIGHT_STATE"
    		       }
    		     ],
    		     "intent": "ControlLightBulb"
    		   }
    		 ]
    		}

  • Custom Slot Types
    • Enter Type: LIGHT_STATE
    • Enter Value: on and off
    • => Click “Add Slot Type” button
    
    For "LightState" and "ControlLightBulb", you can search them on index.js to see their meaning.
  • Sample Utterances
    

    		ControlLightBulb Turn {LightState} the light
    		ControlLightBulb Turn the light {LightState}
    		ControlLightBulb {LightState} the light
    		ControlLightBulb the light {LightState}

• Click “Next”
• Do step 3 to get AWS Lambda ARN and then come back here, put ARN as below image
  
  
• Click “Next” button.
  
  If you finished step 3, you can test this skill by using service simulator
  
  

Step 3: Writing source code to handle data from Alexa Skill (on AWS Lambda)

We need to create a lambda function and write source code for it. This function is fired when there is an incoming request from Alexa. The function will:

• Process the request
• Send the response back to Alexa
• Publish a message to MQTT cloud.

Create a Lambda function:

• Go to https://aws.amazon.com/ , Click “Sign in to The Console” button at the top-left.
• Search “Lambda” on the search bar and click on “Lambda” result
• Click “Create a Lambda function” button
  
  
• Select runtime Node.js 6.10
  
  
• You will see a template function “alexa-skills-kit-color-expert”, click download icon to get the sample code. We will modify and compare this code later. Then, close download window and click “Blank Function”. (Amazon may change the template code overtime).
  
  
• Choose “Alexa Skill Kit” and click “next”
  
  
• Configure function:
  • Name: any name, for example: myLightBulb
  • Runtime: Node.js 6.10
  • Handler: index.handler (by default)
  • Role: Firstly, select “Create a custom role”, it will redirect to create a custom role. (refer to Appendix 1 to create a role). Secondly select “choose an existing role”.
  • Existing role: choose the custom role you have just created.
  • Click “next” button
• Click “Create Function” it will redirect to function management page. You will upload code at this page. Please pay attention to the upper right corner of the ARN string, this is the endpoint of this Lambda function which we will put it in Alexa Skill configuration in step 2.
  
  You can code in Node.js (JavaScript), Java, Python, or C#. In this project, I code in Node.js.
• Write main code (index.js)
  
  we downloaded ““alexa-skills-kit-color-expert”” sample code. Unzip this code and see the index.js file. I modified it to control the light bulb (see index.js in source code section). You can compare my index.js code and index.js code from template to see the difference (I recommend to use the WinMerge tool for compare two files. http://winmerge.org/ ). When you compare two file, it’s easier to understand the source code and how it works.
  
  <index.js>
  
  

  	'use strict';
  
  	/**
  	* This sample demonstrates a simple skill built with the Amazon Alexa Skills Kit.
  	* The Intent Schema, Custom Slots, and Sample Utterances for this skill, as well as
  	* testing instructions are located at http://amzn.to/1LzFrj6
  	*
  	* For additional samples, visit the Alexa Skills Kit Getting Started guide at
  	* http://amzn.to/1LGWsLG
  	*/
  
  	var mqtt = require('mqtt');
  
  	// --------------- Helpers that build all of the responses -----------------------
  
  	function buildSpeechletResponse(title, output, repromptText, shouldEndSession) {
  	   return {
  	       outputSpeech: {
  	           type: 'PlainText',
  	           text: output,
  	       },
  	       card: {
  	           type: 'Simple',
  	           title: "SessionSpeechlet - " + title,
  	           content: "SessionSpeechlet - " + output,
  	       },
  	       reprompt: {
  	           outputSpeech: {
  	               type: 'PlainText',
  	               text: repromptText,
  	           },
  	       },
  	       shouldEndSession: shouldEndSession
  	   };
  	}
  
  	function buildResponse(sessionAttributes, speechletResponse) {
  	   return {
  	       version: '1.0',
  	       sessionAttributes,
  	       response: speechletResponse,
  	   };
  	}
  
  
  	// --------------- Functions that control the skill's behavior -----------------------
  
  	function getWelcomeResponse(callback) {
  	   // If we wanted to initialize the session to have some attributes we could add those here.
  	   const sessionAttributes = {};
  	   const cardTitle = 'Welcome';
  	   const speechOutput = "Welcome to P H P o C. How can I help you?"
  	   // If the user either does not reply to the welcome message or says something that is not
  	   // understood, they will be prompted again with this text.
  	   const repromptText = "How can I help you?";
  	   const shouldEndSession = false;
  
  	   callback(sessionAttributes,
  	       buildSpeechletResponse(cardTitle, speechOutput, repromptText, shouldEndSession));
  	}
  
  	function handleSessionEndRequest(callback) {
  	   const cardTitle = 'Session Ended';
  	   const speechOutput = 'Thank you for trying the Alexa Skills Kit sample. Have a nice day!';
  	   // Setting this to true ends the session and exits the skill.
  	   const shouldEndSession = true;
  
  	   callback({}, buildSpeechletResponse(cardTitle, speechOutput, null, shouldEndSession));
  	}
  
  	function createLightBulbAttributes(lightBulb) {
  	   return {
  	       lightBulb: lightBulb
  	   };
  	}
  
  	/**
  	* Control Light Bulb in the session and prepares the speech to reply to the user.
  	*/
  	function controlLightBulbInSession(intent, session, callback) {
  	   const cardTitle = intent.name;
  	   const lightStateRequest = intent.slots.LightState;
  	   let repromptText = '';
  	   let sessionAttributes = {};
  	   const shouldEndSession = true;
  	   let speechOutput = '';
  
  	   if (lightStateRequest) {
  	var lightState = lightStateRequest.value;
  	//Update
  	var mqttpromise = new Promise( function(resolve,reject){
  	var client = mqtt.connect({port:1883,host:'iot.eclipse.org'})
  
  	client.on('connect', function() { // When connected
  	// publish a message to any mqtt topic
  	client.publish('alexa/phpoc/lightbulb', lightState)
  	client.end()
  	resolve('Done Sending');
  	});
  
  	});
  	mqttpromise.then(
  	function(data) {
  	console.log('Function called succesfully:', data);
  	sessionAttributes = createLightBulbAttributes(lightState);
  	speechOutput = "Ok, turning the light " + lightState;
  	repromptText = "Ok, turning the light " + lightState;
  	callback(sessionAttributes,buildSpeechletResponse(cardTitle, speechOutput, repromptText, shouldEndSession));
  	},
  	function(err) {
  	console.log('An error occurred:', err);
  	}
  	);
  
  	} else {
  	speechOutput = "Please try again";
  	repromptText = "Please try again";
  	callback(sessionAttributes,buildSpeechletResponse(cardTitle, speechOutput, repromptText, shouldEndSession));
  	}
  	}
  
  	// --------------- Events -----------------------
  
  	/**
  	* Called when the session starts.
  	*/
  	function onSessionStarted(sessionStartedRequest, session) {
  	   console.log("onSessionStarted requestId=${sessionStartedRequest.requestId}, sessionId=${session.sessionId}");
  	}
  
  	/**
  	* Called when the user launches the skill without specifying what they want.
  	*/
  	function onLaunch(launchRequest, session, callback) {
  	   console.log("onLaunch requestId=${launchRequest.requestId}, sessionId=${session.sessionId}");
  
  	   // Dispatch to your skill's launch.
  	   getWelcomeResponse(callback);
  	}
  
  	/**
  	* Called when the user specifies an intent for this skill.
  	*/
  	function onIntent(intentRequest, session, callback) {
  	   console.log("onIntent requestId=${intentRequest.requestId}, sessionId=${session.sessionId}");
  
  	   const intent = intentRequest.intent;
  	   const intentName = intentRequest.intent.name;
  
  	   // Dispatch to your skill's intent handlers
  	   if (intentName === 'ControlLightBulb') {
  	       controlLightBulbInSession(intent, session, callback);
  	   } else if (intentName === 'AMAZON.HelpIntent') {
  	       getWelcomeResponse(callback);
  	   } else if (intentName === 'AMAZON.StopIntent' || intentName === 'AMAZON.CancelIntent') {
  	       handleSessionEndRequest(callback);
  	   } else {
  	       throw new Error('Invalid intent');
  	   }
  	}
  
  	/**
  	* Called when the user ends the session.
  	* Is not called when the skill returns shouldEndSession=true.
  	*/
  	function onSessionEnded(sessionEndedRequest, session) {
  	   console.log("onSessionEnded requestId=${sessionEndedRequest.requestId}, sessionId=${session.sessionId}");
  	   // Add cleanup logic here
  	}
  
  
  	// --------------- Main handler -----------------------
  
  	// Route the incoming request based on type (LaunchRequest, IntentRequest,
  	// etc.) The JSON body of the request is provided in the event parameter.
  	exports.handler = (event, context) => {
  	   try {
  	       console.log("event.session.application.applicationId=${event.session.application.applicationId}");
  
  	       /**
  	        * Uncomment this if statement and populate with your skill's application ID to
  	        * prevent someone else from configuring a skill that sends requests to this function.
  	        */
  	       /*
  	       if (event.session.application.applicationId !== 'amzn1.echo-sdk-ams.app.[unique-value-here]') {
  	            context.fail("Invalid Application ID");
  	       }
  	       */
  
  	       if (event.session.new) {
  	           onSessionStarted({ requestId: event.request.requestId }, event.session);
  	       }
  
  	       if (event.request.type === 'LaunchRequest') {
  	           onLaunch(event.request,
  	               event.session,
  	               function callback(sessionAttributes, speechletResponse) {
  	context.succeed(buildResponse(sessionAttributes, speechletResponse));
  	});
  	       } else if (event.request.type === 'IntentRequest') {
  	           onIntent(event.request,
  	               event.session,
  	               function callback(sessionAttributes, speechletResponse) {
  	context.succeed(buildResponse(sessionAttributes, speechletResponse));
  	});
  	       } else if (event.request.type === 'SessionEndedRequest') {
  	           onSessionEnded(event.request, event.session);
  	           context.succeed();
  	       }
  	   } catch (e) {
  	       context.fail("Exception: " + e);
  	   }
  	};

• Since this function publish message on MQTT cloud, we need to install mqtt library for Node.js. Refer to Appendix 2. Suppose that mqtt library is installed in “D:\lambda_function” directory.
• Copy the index.js file to “D:\lambda_function”. Zip it to anyname.zip (do not zip the folder, just zip all inside “D:\lambda_function”). My zip file is here.
• Upload anyname.zip file to AWS lambda function and click “save”
  
  

Step 4: Setting up MQTT cloud

In some MQTT cloud, we may need to register an account or do some the setting. However, in iot.eclipse.org, we don’t need to do anything, just publish/subscribe any topics on it.


Step 5: Writing source code on PHPoC to handle commands and control the devices.

In this code, we just need to subscribe the topic on MQTT broker to receive message from Lambda function. When receiving the message (json format), this code turn on or off the light bulb according to value in MQTT message.

<task0.php>

<?php

if(_SERVER("REQUEST_METHOD"))
    exit; // avoid php execution via http request

include_once "/lib/sd_spc.php";
include_once "/lib/sn_dns.php";
include_once "/lib/vn_mqtt.php";

spc_reset();
spc_sync_baud(115200);

//$host_name = "test.mosquitto.org";
$host_name = "iot.eclipse.org";
//$host_name = "broker.hivemq.com";
//$host_name = "broker.mqttdashboard.com";
//$host_name = "[192.168.0.3]";
$port = 1883;

mqtt_setup(0, "Alexa PHPoC 1",  $host_name, $port);

$will = "";
$username = "";
$password = "";

mqtt_connect(true, $will, $username, $password);

$out_topics = array(array("alexa/phpoc/lightbulb", 1));

if(mqtt_state() == MQTT_CONNECTED)
    mqtt_subscribe($out_topics);

$in_topic = "";
$in_content = "";
$is_retain = 0;

while(1)
{    
    if(mqtt_state() == MQTT_DISCONNECTED)
        while(mqtt_reconnect() == false);

    if(mqtt_loop($in_topic, $in_content, $is_retain))
    {
        if($in_content === "on")
        {
            //turn on the light bulb
            echo "turn on the light bulb\r\n";
            spc_request(14, 4, "set 0 output high");
        }
        else if($in_content === "off")
        {
            //turn off the light bulb
            echo "turn off the light bulb\r\n";
            spc_request(14, 4, "set 0 output low");
        }
        else
        {
            echo "unknown command\r\n";
        }
    }
}

mqtt_disconnect();

?>

For MQTT library, you can get it here:

• https://forum.phpoc.com/blogs/khanh-...40-support-ssl
• Or https://www.hackster.io/phpoc_man/mq...l-0-1-2-a210d2

Appendix 1: creating a role





Appendix 2: installing mqtt library

• Download and install Node.js and npm on your PC https://www.npmjs.com/get-npm
• Download MQTT library for node.js https://github.com/mqttjs/MQTT.js
• Unzip it at the nodejs directory that Node.js was installed. (In window 10 x64, nodejs directory is C:\Program Files\nodejs)
• Create a folder to store the mqtt installed file. for example, “D:\lambda_function”
• Run “command prompt” program as administrator, change directory to nodejs directory
• Install mqtt library to “D:\lambda_function”.
  

  C:\Program Files\nodejs>npm install --prefix "D:\lambda_function” mqtt