AND9264/D Video Development Kit Cloud Integration … · AND9264/D 3 The MatrixCam VDK supports Google Cloud Messaging. Cloud messages can follow any format as long as they are only

© Semiconductor Components Industries, LLC, 2015

September, 2015 − Rev. 11 Publication Order Number:

AND9264/D

AND9264/D

MatrixCam� Video Development Kit Cloud Integration Guide

IntroductionThis document covers the primary use cases of integrating the

MatrixCam� VDK within both Amazon® Web Service and GoogleCloud Platform�.

The intended audience of this document is someone with a technicalbackground in software, IT, or cloud infrastructure development.

The MatrixCam VDK will support three types of use cases of cloudintegration:• Push Notification

♦ From MatrixCam VDK to Mobile Device♦ Google® Cloud Messaging Push Notifications

• Live Streaming from the MatrixCam VDK to the Cloud♦ Hooks Inside the MatrixCam VDK♦ Demo Cloud Platform Documentation

• Video on Demand (Record Video on the Cloud for Playback ata Later Time)♦ Record Video on the Cloud for Playback at a Later Time

It also contains instructions on how to:1. Setup Push Servers to Send Out Push Notifications from the

Camera using Google Cloud Messaging2. Setup Cloud Servers for Live Streaming and Cloud Recording

Push NotificationsThe PIR (Passive Infrared) sensor on the MatrixCam VDK detects

motion and starts SD card recording of the video stream. Pushnotifications enable the user to receive a message on their mobiledevice each time there is movement detected. It does this with the helpof Google Cloud Messaging services. Instructions on how to set thisup are included in this documentation in Appendix A.

Currently, only Android� Devices are supported. Future supportwill be extended to web apps and iOS®

.

Live StreamingFor remote viewing of the MatrixCam VDK’s live stream, a media

server with Wowza Streaming Engine� will need to be setup on eitherAmazon EC2� or Google Compute Engine�. The media server willpull the RTSP video stream from the MatrixCam VDK via its public IPaddress. Additionally, since media servers have the ability to storevideo in the cloud, the camera hooks for sending could recordingtriggers once the PIR sensor notices movement. Wowza® comes witha 180 day trial license. Details on how to get this license is in the quickstart guide. Wowza runs on many different media servers as wellbesides just Amazon and Google.

Video on DemandUsing the same media server for live streaming, we can enable the

Wowza Streaming Engine to record videos to cloud storage, which canbe accessed at a later time.

www.onsemi.com

APPLICATION NOTE

Figure 1. MatrixCam VDK Camera

AND9264/D

www.onsemi.com2

PUSH NOTIFICATIONS

Figure 2. Push Notifications

PIRSensor

Push NotificationMatrixCam Video Development Kit

Ethernetor Wi-Fi®

GoogleCloud

Messaging

Coming Soon

1. When the MatrixCam VDK’s PIR sensor detectsmotion, a push notification is sent to your mobiledevice.

2. Push server credentials can be customized andentered via the web GUI.

3. Instructions on how to setup a sample push serveron Google cloud is included in Appendix A.

4. Open source code for the push server:https://github.com/ONSemiconductor/MatrixPush−AppEngine

5. Open source code for an Android app that receivespush notifications:https://github.com/ONSemiconductor/MatrixPush

Configure Push Server CredentialsOpen up the MatrixCam VDK web GUI in your web

browser and navigate to: Configuration −> Recording −>Push Notification.

Figure 3. Configuration of Push Server Credentials (1 of 2)

AND9264/D

www.onsemi.com3

The MatrixCam VDK supports Google Cloud Messaging.Cloud messages can follow any format as long as they areonly text. The push server URL follows this format:

https://matrix−cam−89717.appspot.com/_ah/api/messageEndpoint/v1/sendMessage

Figure 4. Configuration of Push Server Credentials (2 of 2)

Receive Push Notification on an Android DeviceDownload and install the OnSemiMatrixPush.apk from

https://github.com/ONSemiconductor/MatrixPush.Register the device with the push server by clicking the

register button. Successful registration will look like this:

Figure 5. Device Registration (1 of 4)

AND9264/D

www.onsemi.com4

After pressing OK and dismissing the dialog box your screen should be identical to the picture below.

Figure 6. Device Registration (2 of 4)

When the MatrixCam VDK sends a notification, this app will receive it and display a dialog box like the one shown below.

Figure 7. Device Registration (3 of 4)

AND9264/D

www.onsemi.com5

To un-register from the Server, click the “Unregister Button”. If successful, a dialog box will be displayed like the one below.

Figure 8. Device Registration (4 of 4)

AND9264/D

www.onsemi.com6

LIVE STREAMING

• This Section has instructions on how to set up AmazonEC2 or Google Compute Engine with WowzaStreaming Media Engine in order to pull the RTSPstream from the MatrixCam VDK.

NOTE: MatrixCam VDK must have a publicly accessible IPaddress. This can be done by using the uPnP feature ofyour router, and the MatrixCam VDK.

• If enabled by user, PIR motion will trigger cloudrecording for a short customizable time periodalongside the SD card.

Figure 9. Live Streaming

StreamingServer

Video StreamingMatrixCam Video Development Kit

PIRSensor

Ethernetor Wi-Fi

MediaStreamingServer onthe Cloud

Pull rtsp

httphttp − Start Recording on Cloudhttp − Stop Recording on Cloud

Configure Cloud Recording Credentials

Figure 10. Configuration of Cloud Recording Credentials (1 of 2)

AND9264/D

www.onsemi.com7

Enable cloud recording through the MatrixCam VDK’sweb GUI so it can be set up as part of the PIR sequence. Itis assumed that the live stream has been previously set up forthe camera.

Figure 11. Configuration of Cloud Recording Credentials (2 of 2)

AND9264/D

www.onsemi.com8

VIDEO ON DEMAND

Video on demand is supported by using the cloudrecording feature on either Amazon EC2 or GoogleCompute Engine.

Cloud Recording is started and stopped by initiatingsimple HTTP commands with the following format*

http://<username>:<password>@<ipaddress>:<portnumber>/livestreamrecord?option=overwrite&app=<livestream>&streamname=<streamname>&action=startRecording&outputFile=<outputfile.mp4>

http://<username>:<password>@<ipaddress>:<portnumber>/livestreamrecord?app=<livestream>&streamname=<streamname>&action=stopRecording

*This format is based on how the Wowza Streaming Engine makesAPI Calls. If this does not work for your streaming engine, pleasesend email to <TODO Support address>

Format for Video Playback

iOS: http://<ipaddress>:1935/vod/<outputfile.mp4>/playlist.m3u8

Android: rtsp://<ipaddress>:1935/vod/<outputfile.mp4>

AND9264/D

www.onsemi.com9

APPENDIX A

GOOGLE CLOUD MESSAGING SERVER(FOR PUSH NOTIFICATIONS)

Architecture and TechnologyFor the purpose of demonstration we use the following

architecture provided by Google − Google CloudMessaging.

Figure 12. Google Cloud Messaging

GCM Connection Servers

Client App

3rd Party AppServer

The GCM is a 3-tiered architecture:

3rd Party App ServerThis is a dedicated app server that users of the Matrix

Board set up to send messages from the camera via the GCMConnection Servers to a dedicated application on mobiledevices. We will walk through the steps to set this up inSection <TODO>.

GCM Connection ServersProvided by Google. In this setup, we only http as the

communication protocol (not XMPP) and push notificationsare sent from camera to device. There is no communicationfrom device to the camera in the current version.

Client AppThis is a GCM Enabled mobile app. This application

“registers” itself on the Matrix App Server. Sample codeprovided in github.

Reference Links:

https://developers.google.com/cloud−messaging/gcm

https://developers.google.com/cloud−messaging/

https://developers.google.com/console/help/new/

GCM Setup

STEP 1: Create a Bucket on the Google Cloud Platform toHost the 3rd Party App Server

1. Go to https://console.developers.google.com/.2. Sign in with a Google account. If you don’t have

one, create an account.3. Click on “create a project” and give it a relevant

name.

Figure 13. Project Creation (1 of 2)

AND9264/D

www.onsemi.com10

Figure 14. Project Creation (2 of 2)

4. Next you will be redirected to the project dashboard (shown below).

Figure 15. Project Dashboard

5. At the top of the dashboard you will see:Project ID: my−matrixcam−8989Project Number: 35251955575

AND9264/D

www.onsemi.com11

6. Click on “Permissions”, located in the left navigation panel. You can add other people with Google accounts tomanage your app server.

Figure 16. Permissions

7. Click on APIs & auth −> APIs −> Mobile APIs −> Google Messaging for Android. Click “Enable API”.

Figure 17. Enable API

AND9264/D

www.onsemi.com12

8. Click on APIs & auth −> Credentials −> Public API Access −> Create New Key.

Figure 18. New Key Creation

9. Create a Server Key.

Figure 19. Server Key Creation

NOTE: Leave the Accept requests from these Server IP Addresses blank in the demo. But in the production version, add the IP addressesof devices from where you would receive requests. If successful, you will get something like the figure below. This API Key is secretand will be used when you deploy code to the server.

AND9264/D

www.onsemi.com13

Figure 20. Key for Server Applications

10. Create an Android Key.

Figure 21. Android Key Creation

STEP 2: Configure the App Server and Android App toRegister Devices and Receive Push Notifications

NOTE: This step needs software development experience andfamiliarity with tools like Eclipse, Java, Android SDK etc.

Option 1:

Fork the Android Push App code from here and fork theAndroid App Engine backend from here.

Option 2:

Follow the tutorial at https://developers.google.com/eclipse/docs/endpoints−androidconnected−gae.

Download and install Google Plugin for Eclipse: https://developers.google.com/eclipse/docs/getting_started.

Open Eclipse: File −> New −> Project −> Google −> AppEngine Connected Android Project

AND9264/D

www.onsemi.com14

Figure 22. App Engine Connected Android Project

This API Key is the AndroidKey that was generated inSTEP 1 above.

The Project Number isfound on the Dashboard atconsole.developers.com

This generates 2 projects. An App Engine Project and anAndroid Project.

Remove any compilation errors if any.

Select the <projectname>−AppEngine.NOTE: Make sure that the app engine compiles using JDK 1.7

since app engine backend does not support JDK 1.8.

AND9264/D

www.onsemi.com15

Right Click on the Project in the Package Explorer, and go to the Google −> Deploy to App Engine.

Figure 23. Deploy to App Engine

If not added previously, add the Project ID: e.g. application ID my−iotcam−8989.

Figure 24. App Engine Properties

AND9264/D

www.onsemi.com16

The Google Plugin in Eclipse needs to be signed in tobefore the deployment to the app engine server on GoogleCloud can happen. See right bottom and sign in with

a Google Account has permissions (owner/edit) for the AppEngine Server built in STEP 1.

Figure 25.

If the App Engine code gets deployed successfully, youwill set a page like this in the browserhttp://my−iotcam−8989.appspot.com/.

Figure 26.

Now, to get the GCM Client Android App on the phone,go to the second project <projectname> that the EclipsePlugin Created.

Right click the project and deploy the app to Android. Forinstructions on building and running apps from Eclipse −See this link.

Figure 27.

AND9264/D

www.onsemi.com17

APPENDIX B

MEDIA STREAMING SERVER ON GOOGLE COMPUTE ENGINE AND AMAZON EC2

Google Compute Engine Setup1. Start by creating your Google Cloud account if

you don’t have one already.https://cloud.google.com/

2. When logged into the Google compute developersconsole create a new project for your IoTMatrixCam VDK.

Figure 28. New Project

3. Next you will be prompted to download and installthe Google Cloud SDK.https://cloud.google.com/sdk/

4. After the Google Cloud SDK install is finalized,navigate to Compute −> Compute Engine −>Images. From here select the blue “New Image”button. Name the image something like “wowza”

so you know what package is installed. For thesource type select “Cloud Storage Object”. Whenthe “Cloud Storage Object Path” appears copy andpaste the line below after the gs://

wowzamediasystems/wse/WowzaStreamingEngine−4.2.0.image.tar.gz

Figure 29. New Image

AND9264/D

www.onsemi.com18

Figure 30. New Image Creation

5. Next, we will need to enable some extra firewallsettings for Wowza to function properly on itsrequired ports. Under the “Images” menu itemfrom earlier you will see “Networks”. Select thisand click on “default” to set a new firewall rule.Click “Add Firewall Rule” and name it something

similar to what you named your image earlier. For “Source Filter” select “Allow from any source(0.0.0.0/0)”. Lastly, in “Allowed protocols andports” copy and paste the line below.

tcp:1935,8088

Figure 31. New Network (1 of 2)

AND9264/D

www.onsemi.com19

Figure 32. New Network (2 of 2)

6. Towards the top of the same “Compute Engine”sidebar click on “VM Instances”. Next, select“New Instance” and name it something related tothe MatrixCam VDK or Wowza. Pick theappropriate zone for where you are located andallow HTTP and HTTPS traffic. The machine type

is largely up to you considering it will determinethe general speed and response time of the videostream. For the “Boot disk” section change fromthe default disk to your Wowza image that youmade earlier. Review your selections to make sureeverything is correct and select “Create”.

Figure 33. Boot Disk (1 of 2)

AND9264/D

www.onsemi.com20

Figure 34. Boot Disk (2 of 2)

7. At this point you should see your instance in the“VM Instances” section. The External IP listedwill be the public address in which you can accessyour video stream through the Wowza StreamingEngine Manager.

8. In your web browser, navigate to the public IPaddress you found in the last step and append the“:8088” port number to the end of it. This willbring you to the Wowza Streaming EngineManager GUI landing page.

Figure 35.

9. Skip through the intro until you are prompted tologin with a username and password. Now go backto your Google developer’s console. In the “VM

Instances” section click on the “SSH” button onthe right side of your public IP address in yourcurrent instance.

Figure 36. VM Instances

AND9264/D

www.onsemi.com21

10. When you are successfully logged in to the SSHconsole paste this line into the window:

curl http://metadata/computeMetadata/v1/instance/id −H “X−Google−Metadata−Request: True”

Figure 37. SSH Console

11. You should get a string of numbers connected toyour user name and instance as shown below:7444544590116263586<username>@<instance>

12. The string of numbers shown before your username will be your password for the WowzaStreaming Engine Manager GUI. Your user namewill be “wowza”.

(You can change your password and add new userslater in the “Users” section within the “Server”tab.)

User Name: wowzaPassword: 7444544590116263586

Figure 38. Sign In Window

AND9264/D

www.onsemi.com22

13. After you are logged into the Wowza StreamingEngine Manager, navigate to the “Server” tab onthe top of the page and select “Stream Files” in thesidebar. Next click on “Add Stream File”. Here

you will name your stream and paste the rtspstream from your MatrixCam VDK that you haveverified works in VLC player.

Figure 39. Stream Files

AND9264/D

www.onsemi.com23

14. Now click the connect button and select “live”.Press ok and stream should be connected. Nownavigate to the “Applications” tab on the top of the

window and select “Incoming Streams” from thesidebar.

Figure 40. Connection of Stream File

AND9264/D

www.onsemi.com24

15. Next select the “Test Players” button in the topright corner and make sure all of the fields areaccurate before pressing start. If all of the steps

have been performed correctly you should seeyour MatrixCam VDK video stream.

Figure 41. Test Players

Wowza Streaming Engine for Google Compute Enginehttp://www.wowza.com/forums/content.php?560

AND9264/D

www.onsemi.com25

Amazon EC2 Setup1. Start by creating your Amazon AWS account if

you don’t have one already.http://aws.amazon.com/account/

2. When logged in, click on “EC2” in the upper leftcorner, then click the blue “Launch Instance”button to choose your Amazon Machine Image(AMI).

Figure 42. Amazon EC2 Setup

3. Navigate to the “AWS Marketplace” bar on the leftand type “Wowza Streaming Engine” into thesearch field. If you have already bought a license

or have just started a trial, choose the “Bring yourown license” option. If you have not boughta license yet, then choose the “standard” option.

Figure 43. Choosing an Amazon Machine Image (AMI)

4. Next, follows the next few options and select theproper usage tier and storage space that yoursituation will require. On the review page it shouldsay “Wowza Streaming Engine” under AMIDetails and the instance type being the usage tier

and storage space you chose before. If everythinghere is correct, click the blue “Launch” button tostart your instance.

AND9264/D

www.onsemi.com26

5. When it asks you if you want a key pair, make sureto select “Create new pair” so that it will have

a key pair assigned to this instance. This isimportant for future steps to work properly.

Figure 44. Creating a New Key Pair

6. Next, navigate to the sidebar and click on “ElasticIPs”. Create a new Elastic IP and assign it to yournew instance buy right clicking on the IP andselecting “Associate Address”. This is an optionalstep that is mainly due to convenience. However,if you do not assign an elastic IP to your instanceand you end up stopping the instance, your IPaddress will change upon starting the instance upagain.

7. Open a blank web page in your browser andnavigate to the new Elastic IP address. You shouldsee a blank white page that says “WowzaStreaming Engine 4 for Amazon EC2…” This

means that your Wowza Streaming Engine is setup correctly.

8. Now append the “:8088” port number to the end ofyour IP address and you will see the splash pagefor the streaming engine with the words “Welcometo the Wowza Streaming Engine!” in the middle ofthe screen.

9. Skip to the next page and it will ask you to sign in.The login info is listed below:

User Name: wowzaPassword: <Instance ID>

Figure 45. Instance ID

10. Follow steps 13 − 15 from Google ComputeEngine Setup.

Wowza Streaming Engine for Amazon EC2: Quick StartGuide http://www.wowza.com/forums/content.php?191.

AND9264/D

www.onsemi.com27

Additional Information for Wowza Streaming Engine GUI

1. Additional Ports:If you are experiencing difficulty getting your video to

stream, make sure that all of the ports shown below areenabled in your Wowza Streaming Engine Manager.

Figure 46. Additional Ports

2. Patch the AMIWowza Streaming Engine Manager version 4.1.2.xx

sometimes experiences issues with video streaming onAmazon Web Services. Because of this, you might need toinstall an AMI patch (link here).

Wowza Streaming Engine 4 Monthly Edition 4.1.2.01build14891.

To verify if the EC2 instance is on the same version/buildas the one that you have already tested, please launch thefollowing link for both servers:

http://<wowza−ip−address>:1935

It should return text similar to the following:

Wowza Streaming Engine 4 Monthly Edition 4.1.2.01build14891

Please compare the software version and build number forboth instances. If you find that the new EC2 instance has anolder version/build, please do apply the software patch

3. Other Wowza SettingsSet the RTSP KeepAlive GET_PARAMETER by

following the instructions here.

4. RTSP URLThe RTSP URL of the camera can be found in the user’s

guide, as well as through the MatrixCam VDK’s web GUI(shown below).

Figure 47. RTSP URL

AND9264/D

www.onsemi.com28

Additional Resources

How to Set Up Video on Demand Streaming:http://www.wowza.com/forums/content.php?35−How−to−set−up−video−on−demand−streaming

How to Re-Stream Video from an IP Camera (RTSP/RTPRe-Streaming):http://www.wowza.com/forums/content.php?39

Wowza Media Server User Guide:http://www.wowza.com/resources/WowzaMediaServer_UsersGuide.pdf

Cloud Recording for Video on Demandhttp://www.wowza.com/forums/content.php?123−How−to−record−live−streams−%28HTTPLiveStreamRecord%29\

The camera sends HTTP requests in the following format:

curl −L −−digest“http://<username>:<password>@<ipaddress>:<portnumber>/livestreamrecord?option=overwrite&app=<livestream>&streamname=<streamname>&action=startRecording&outputFile=<outputfile.mp4>”

curl −L −−digest“http://<username>:<password>@<ipaddress>:<portnumber>/livestreamrecord?app=<livestream>&streamname=<streamname>&action=stopRecording”

ON Semiconductor and the are registered trademarks of Semiconductor Components Industries, LLC (SCILLC) or its subsidiaries in the United States and/or other countries.SCILLC owns the rights to a number of patents, trademarks, copyrights, trade secrets, and other intellectual property. A listing of SCILLC’s product/patent coverage may be accessedat www.onsemi.com/site/pdf/Patent−Marking.pdf. SCILLC reserves the right to make changes without further notice to any products herein. SCILLC makes no warranty, representationor guarantee regarding the suitability of its products for any particular purpose, nor does SCILLC assume any liability arising out of the application or use of any product or circuit, andspecifically disclaims any and all liability, including without limitation special, consequential or incidental damages. “Typical” parameters which may be provided in SCILLC data sheetsand/or specifications can and do vary in different applications and actual performance may vary over time. All operating parameters, including “Typicals” must be validated for eachcustomer application by customer’s technical experts. SCILLC does not convey any license under its patent rights nor the rights of others. SCILLC products are not designed, intended,or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in whichthe failure of the SCILLC product could create a situation where personal injury or death may occur. Should Buyer purchase or use SCILLC products for any such unintended orunauthorized application, Buyer shall indemnify and hold SCILLC and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, andexpenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claimalleges that SCILLC was negligent regarding the design or manufacture of the part. SCILLC is an Equal Opportunity/Affirmative Action Employer. This literature is subject to all applicablecopyright laws and is not for resale in any manner.

PUBLICATION ORDERING INFORMATIONN. American Technical Support: 800−282−9855 Toll FreeUSA/Canada

Europe, Middle East and Africa Technical Support:Phone: 421 33 790 2910

Japan Customer Focus CenterPhone: 81−3−5817−1050

AND9264/D

Amazon is a registered trademark of Amazon.com, Inc. Google is a registered trademarks of Google Inc. iOS is a registered trademarks ofApple Inc. Wi-Fi is a registered trademark of the Wi-Fi Alliance. Wowza is a registered trademark of Wowza Media Systems, LLC in the UnitedStates and/or other countries. Android is a trademark of Google Inc. Amazon EC2 is a trademark of Amazon.com, Inc. Google Cloud Platformand Google Compute Engine are trademarks of Google Inc. MatrixCam is a trademark of Semiconductor Components Industries, LLC (SCILLC)or its subsidiaries in the United States and/or other countries. Wowza Streaming Engine is a trademark of Wowza Media Systems, LLC in theUnited States and/or other countries. All other brand names and product names appearing in this document are registered trademarks ortrademarks of their respective holders.

LITERATURE FULFILLMENT:Literature Distribution Center for ON Semiconductor19521 E. 32nd Pkwy, Aurora, Colorado 80011 USAPhone: 303−675−2175 or 800−344−3860 Toll Free USA/CanadaFax: 303−675−2176 or 800−344−3867 Toll Free USA/CanadaEmail: [email protected]

ON Semiconductor Website: www.onsemi.com

Order Literature: http://www.onsemi.com/orderlit

For additional information, please contact your localSales Representative