AWS Web Server Sample in PHP using AirVantage 4 APIs

This tutorial shows you how to create an Amazon Web Services Linux+Apache+PHP simple web server, running a PHP web application sample demoing the main features of AirVantage 4 APIs (authentication, data monitoring, command sending), within 15 minutes. It uses an AWS Cloud Formation stack template, already prepared for you and ready to be deployed.

PREREQUISITES

Before starting this tutorial, make sure you own:

• An activated AWS account (register one at: http://aws.amazon.com)
• An AirVantage 4 account (either regular or trial account). Register a trial account for free

INSTRUCTIONS

A- CREATE A CLIENT API ON AIRVANTAGE 4:

1. Login your account, go to "Develop" view.
2. Create a new API Client ("+" button"), with an unique name.
3. As a result, the page gives you an Client ID and Secret Key you'll need later below

B- CREATE YOUR AWS WEB SERVER STACK FROM OUR TEMPLATE

1. In AWS, select the AWS Zone where your server will reside.
2. As we'll create a new EC2 instance, we'll need a EC2 key pair in order to enable SSH on it
   1. Go to EC2 > Key Pairs > Create Key Pair
   2. Name your key pair (e.g. "LinuxApachePHPAV4SampleKeys")
   3. As a result, a .pem file has been downloaded onto your computer. It will have to be used to connect your EC2 instance once created, later below.
3. Open the CLoudFormation service > Create New Stack
4. Name your stack (e.g. "LinuxApachePHPAV4Sample"), provide the template URL (if providing the "Provide a Template URL" option doesn't work, download the file from the URL below on your computer, and upload it using the "Upload a template file" option instead):

   https://s3-eu-west-1.amazonaws.com/elasticbeanstalk-eu-west-1-281626357614/Linux_Apache_PHP_AV4_Sample.template

5. Enter your Client ID & Secret Key (cf. A-3)
6. Continue. Your stack is being created by Amazon. It will take about 4 minutes
7. Once the status is "CREATE_COMPLETE", select the instance, and select the "Outputs" tab. The template script gives you the URL of your newly created server. Open it in a web browser!

C- RUNNING THE WEB APP (HOW TO)

1. Open the webpage in your browser (cf. B-7 to get the URL). The web page is split into different paragraphs, each showing a common usage of AirVantage APIs: authentication, System information retrieval, Data monitoring, Commands sending:
2. AirVantage authentication and token retrieval
   • Your webapp knows how to retrieve AirVantage token (cf. E). If you've passed the right information to the template script in B5, "AirVantage authentication" section of the page should succeed.
3. System information retrieval
   • Enter the System UID and click "Change". Your System UID can be retrieve in the AV M2M Cloud UI > Monitor > System > select a particular system in the list > details (icon) --> the next page shows you the details of the system. The System UID is written on the URL:

     https://na.m2mop.net/monitor/systems/systemDetails?uid=System_UID

4. Data monitoring
   • Enter the System Data ID to monitor, and click "retrieve". The Data ID can be retrieve in AV M2M Cloud UI > Deploy > Applications > select your application > details icon. The application model displayed in XML will show you variables you can monitor. The Data ID to use is composed by "Asset_ID.Data_path", where Asset_ID and Data_path can be retrieved from:

     <asset default-label="…" id="Asset_ID">

     <variable default-label="…" path="Data_path">

   • Example for LCD Demo:
     Data ID = "Crystal.uplink.key"
5. Commands sending
   • In order to send commands, you need the Application Name, Application Revision, Command ID, and Command Key. They can be retrieved from the same AV M2M Cloud UI page as in C-4. The Command ID is a concatenation of Asset_ID and Command_path:

     <app:application xmlns:app="http://www.sierrawireless.com/airvantage/application/1.0" name="Application_Name" revision="Application_Revision" type="…">

     <asset default-label="…" id="Asset_ID">

     <command default-label="…" id="" path="Command_path">

     <parameter default-label="Text" default-value="..." id="Command_Key"/>

   • Example for LCD Demo:
     Application Name = "LCDDemo"
     Application Revision = "1"
     Command ID = "Crystal.Line1"
     Command Key = "Line1"
     Command Value = "Hello World!"

D- DEVELOPMENT: SSH/SCP ONTO YOUR INSTANCE

1. Locate the .pem key pair file on your local computer (cf. B-1.3)
2. If your local machine is running Linux/Unix, make sure your file is not read-able by anybody (otherwise, the ssh command will fail)

   • chmod 400 keysfile.pem

3. ssh -i yourfile.pem ec2-user@serverURL
   

   • the PHP web page is located at /var/www/html/index.php
   • the webserver error logs file is located at /var/log/httpd/error_log
4. Development: to copy your index.php file back and forth, just scp it using the .pem key pair:
   • Download it:

     scp -i keysfile.pem ec2-user@serverURL:/var/www/html/index.php .

   • Upload it back:

     scp -i keysfile.pem index.php ec2-user@serverURL:/var/www/html

5. Once the index.php file update, just reload the web page!