AND9264/D
MatrixCamt
Video Development Kit
Cloud Integration Guide
Introduction
This document covers the primary use cases of integrating the
MatrixCamt VDK within both Amazon® Web Service and Google
Cloud Platformt.
The intended audience of this document is someone with a technical
background in software, IT, or cloud infrastructure development.
The MatrixCam VDK will support three types of use cases of cloud
integration:
• 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 at
a Later Time)
♦ Record Video on the Cloud for Playback at a Later Time
www.onsemi.com
APPLICATION NOTE
It also contains instructions on how to:
1. Setup Push Servers to Send Out Push Notifications from the
Camera using Google Cloud Messaging
2. Setup Cloud Servers for Live Streaming and Cloud Recording
Push Notifications
The PIR (Passive Infrared) sensor on the MatrixCam VDK detects
motion and starts SD card recording of the video stream. Push
notifications enable the user to receive a message on their mobile
device each time there is movement detected. It does this with the help
of Google Cloud Messaging services. Instructions on how to set this
up are included in this documentation in Appendix A.
Currently, only Androidt Devices are supported. Future support
will be extended to web apps and iOS®.
Figure 1. MatrixCam VDK Camera
Live Streaming
For remote viewing of the MatrixCam VDK’s live stream, a media
server with Wowza Streaming Enginet will need to be setup on either
Amazon EC2t or Google Compute Enginet. The media server will
pull the RTSP video stream from the MatrixCam VDK via its public IP
address. Additionally, since media servers have the ability to store
video in the cloud, the camera hooks for sending could recording
triggers once the PIR sensor notices movement. Wowza® comes with
a 180 day trial license. Details on how to get this license is in the quick
start guide. Wowza runs on many different media servers as well
besides just Amazon and Google.
Video on Demand
Using the same media server for live streaming, we can enable the
Wowza Streaming Engine to record videos to cloud storage, which can
be accessed at a later time.
© Semiconductor Components Industries, LLC, 2015
September, 2015 − Rev. 1
1
Publication Order Number:
AND9264/D
AND9264/D
PUSH NOTIFICATIONS
Google
Cloud
Messaging
PIR
Sensor
Ethernet
or Wi-Fi®
Coming Soon
Push Notification
MatrixCam Video Development Kit
Figure 2. Push Notifications
1. When the MatrixCam VDK’s PIR sensor detects
motion, a push notification is sent to your mobile
device.
2. Push server credentials can be customized and
entered via the web GUI.
3. Instructions on how to setup a sample push server
on 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 receives
push notifications:
https://github.com/ONSemiconductor/MatrixPush
Configure Push Server Credentials
Open 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)
www.onsemi.com
2
AND9264/D
The MatrixCam VDK supports Google Cloud Messaging.
Cloud messages can follow any format as long as they are
only text. The push server URL follows this format:
https://matrix−cam−89717.appspot.com/_ah/api/message
Endpoint/v1/sendMessage
Figure 4. Configuration of Push Server Credentials (2 of 2)
Receive Push Notification on an Android Device
Register the device with the push server by clicking the
register button. Successful registration will look like this:
Download and install the OnSemiMatrixPush.apk from
https://github.com/ONSemiconductor/MatrixPush.
Figure 5. Device Registration (1 of 4)
www.onsemi.com
3
AND9264/D
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)
www.onsemi.com
4
AND9264/D
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)
www.onsemi.com
5
AND9264/D
LIVE STREAMING
• This Section has instructions on how to set up Amazon
• If enabled by user, PIR motion will trigger cloud
EC2 or Google Compute Engine with Wowza
Streaming Media Engine in order to pull the RTSP
stream from the MatrixCam VDK.
NOTE:
recording for a short customizable time period
alongside the SD card.
MatrixCam VDK must have a publicly accessible IP
address. This can be done by using the uPnP feature of
your router, and the MatrixCam VDK.
Streaming
Server
Ethernet
or Wi-Fi
Pull rtsp
Media
Streaming
Server on
the Cloud
PIR
Sensor
http
http − Start Recording on Cloud
http − Stop Recording on Cloud
Video Streaming
MatrixCam Video Development Kit
Figure 9. Live Streaming
Configure Cloud Recording Credentials
Figure 10. Configuration of Cloud Recording Credentials (1 of 2)
www.onsemi.com
6
AND9264/D
Enable cloud recording through the MatrixCam VDK’s
web GUI so it can be set up as part of the PIR sequence. It
is assumed that the live stream has been previously set up for
the camera.
Figure 11. Configuration of Cloud Recording Credentials (2 of 2)
www.onsemi.com
7
AND9264/D
VIDEO ON DEMAND
Format for Video Playback
Video on demand is supported by using the cloud
recording feature on either Amazon EC2 or Google
Compute Engine.
Cloud Recording is started and stopped by initiating
simple HTTP commands with the following format*
http://<username>:<password>@<ipaddress>:<portnumb
er>/livestreamrecord?option=overwrite&app=<livestream
>&streamname=<streamname>&action=startRecording&
outputFile=<outputfile.mp4>
iOS: http://<ipaddress>:1935/vod/<outputfile.mp4>/playli
st.m3u8
Android: rtsp://<ipaddress>:1935/vod/<outputfile.mp4>
http://<username>:<password>@<ipaddress>:<portnumb
er>/livestreamrecord?app=<livestream>&streamname=<st
reamname>&action=stopRecording
*This format is based on how the Wowza Streaming Engine makes
API Calls. If this does not work for your streaming engine, please
send email to <TODO Support address>
www.onsemi.com
8
AND9264/D
APPENDIX A
GOOGLE CLOUD MESSAGING SERVER
(FOR PUSH NOTIFICATIONS)
Architecture and Technology
For the purpose of demonstration we use the following
architecture provided by Google − Google Cloud
Messaging.
Client App
3rd Party App
Server
GCM Connection Servers
Figure 12. Google Cloud Messaging
Reference Links:
The GCM is a 3-tiered architecture:
https://developers.google.com/cloud−messaging/gcm
3 rd Party App Server
This is a dedicated app server that users of the Matrix
Board set up to send messages from the camera via the GCM
Connection Servers to a dedicated application on mobile
devices. We will walk through the steps to set this up in
Section <TODO>.
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 to
Host the 3 rd 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.
GCM Connection Servers
Provided by Google. In this setup, we only http as the
communication protocol (not XMPP) and push notifications
are sent from camera to device. There is no communication
from device to the camera in the current version.
Client App
This is a GCM Enabled mobile app. This application
“registers” itself on the Matrix App Server. Sample code
provided in github.
Figure 13. Project Creation (1 of 2)
www.onsemi.com
9
AND9264/D
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−8989
Project Number: 35251955575
www.onsemi.com
10
AND9264/D
6. Click on “Permissions”, located in the left navigation panel. You can add other people with Google accounts to
manage 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
www.onsemi.com
11
AND9264/D
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 addresses
of devices from where you would receive requests. If successful, you will get something like the figure below. This API Key is secret
and will be used when you deploy code to the server.
www.onsemi.com
12
AND9264/D
Figure 20. Key for Server Applications
10. Create an Android Key.
Figure 21. Android Key Creation
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 −> App
Engine Connected Android Project
STEP 2: Configure the App Server and Android App to
Register Devices and Receive Push Notifications
NOTE:
This step needs software development experience and
familiarity with tools like Eclipse, Java, Android SDK etc.
Option 1:
Fork the Android Push App code from here and fork the
Android App Engine backend from here.
www.onsemi.com
13
AND9264/D
This API Key is the Android
Key that was generated in
STEP 1 above.
The Project Number is
found on the Dashboard at
console.developers.com
Figure 22. App Engine Connected Android Project
This generates 2 projects. An App Engine Project and an
Android Project.
Remove any compilation errors if any.
Select the <projectname>−AppEngine.
NOTE:
www.onsemi.com
14
Make sure that the app engine compiles using JDK 1.7
since app engine backend does not support JDK 1.8.
AND9264/D
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
www.onsemi.com
15
AND9264/D
The Google Plugin in Eclipse needs to be signed in to
before the deployment to the app engine server on Google
Cloud can happen. See right bottom and sign in with
a Google Account has permissions (owner/edit) for the App
Engine Server built in STEP 1.
Figure 25.
If the App Engine code gets deployed successfully, you
will set a page like this in the browser
http://my−iotcam−8989.appspot.com/.
Figure 26.
Right click the project and deploy the app to Android. For
instructions on building and running apps from Eclipse −
See this link.
Now, to get the GCM Client Android App on the phone,
go to the second project <projectname> that the Eclipse
Plugin Created.
Figure 27.
www.onsemi.com
16
AND9264/D
APPENDIX B
MEDIA STREAMING SERVER ON
GOOGLE COMPUTE ENGINE AND AMAZON EC2
Google Compute Engine Setup
1. 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 developers
console create a new project for your IoT
MatrixCam VDK.
Figure 28. New Project
so you know what package is installed. For the
source type select “Cloud Storage Object”. When
the “Cloud Storage Object Path” appears copy and
paste the line below after the gs://
3. Next you will be prompted to download and install
the 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”
wowzamediasystems/wse/WowzaStreaming
Engine−4.2.0.image.tar.gz
Figure 29. New Image
www.onsemi.com
17
AND9264/D
Figure 30. New Image Creation
5. Next, we will need to enable some extra firewall
settings for Wowza to function properly on its
required ports. Under the “Images” menu item
from earlier you will see “Networks”. Select this
and 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 and
ports” copy and paste the line below.
tcp:1935,8088
Figure 31. New Network (1 of 2)
www.onsemi.com
18
AND9264/D
Figure 32. New Network (2 of 2)
is largely up to you considering it will determine
the general speed and response time of the video
stream. For the “Boot disk” section change from
the default disk to your Wowza image that you
made earlier. Review your selections to make sure
everything is correct and select “Create”.
6. Towards the top of the same “Compute Engine”
sidebar click on “VM Instances”. Next, select
“New Instance” and name it something related to
the MatrixCam VDK or Wowza. Pick the
appropriate zone for where you are located and
allow HTTP and HTTPS traffic. The machine type
Figure 33. Boot Disk (1 of 2)
www.onsemi.com
19
AND9264/D
Figure 34. Boot Disk (2 of 2)
7. At this point you should see your instance in the
“VM Instances” section. The External IP listed
will be the public address in which you can access
your video stream through the Wowza Streaming
Engine Manager.
8. In your web browser, navigate to the public IP
address you found in the last step and append the
“:8088” port number to the end of it. This will
bring you to the Wowza Streaming Engine
Manager GUI landing page.
Figure 35.
9. Skip through the intro until you are prompted to
login with a username and password. Now go back
to your Google developer’s console. In the “VM
Instances” section click on the “SSH” button on
the right side of your public IP address in your
current instance.
Figure 36. VM Instances
www.onsemi.com
20
AND9264/D
10. When you are successfully logged in to the SSH
console paste this line into the window:
curl http://metadata/computeMetadata/v1/instance/
id −H “X−Google−Metadata−Request: True”
Figure 37. SSH Console
(You can change your password and add new users
later in the “Users” section within the “Server”
tab.)
11. You should get a string of numbers connected to
your user name and instance as shown below:
7444544590116263586<username>@<instance>
12. The string of numbers shown before your user
name will be your password for the Wowza
Streaming Engine Manager GUI. Your user name
will be “wowza”.
User Name: wowza
Password: 7444544590116263586
Figure 38. Sign In Window
www.onsemi.com
21
AND9264/D
13. After you are logged into the Wowza Streaming
Engine Manager, navigate to the “Server” tab on
the top of the page and select “Stream Files” in the
sidebar. Next click on “Add Stream File”. Here
you will name your stream and paste the rtsp
stream from your MatrixCam VDK that you have
verified works in VLC player.
Figure 39. Stream Files
www.onsemi.com
22
AND9264/D
14. Now click the connect button and select “live”.
Press ok and stream should be connected. Now
navigate to the “Applications” tab on the top of the
window and select “Incoming Streams” from the
sidebar.
Figure 40. Connection of Stream File
www.onsemi.com
23
AND9264/D
15. Next select the “Test Players” button in the top
right corner and make sure all of the fields are
accurate before pressing start. If all of the steps
have been performed correctly you should see
your MatrixCam VDK video stream.
Figure 41. Test Players
Wowza Streaming Engine for Google Compute Engine
http://www.wowza.com/forums/content.php?560
www.onsemi.com
24
AND9264/D
Amazon EC2 Setup
1. 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 left
corner, 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 left
and type “Wowza Streaming Engine” into the
search field. If you have already bought a license
or have just started a trial, choose the “Bring your
own license” option. If you have not bought
a license yet, then choose the “standard” option.
Figure 43. Choosing an Amazon Machine Image (AMI)
and storage space you chose before. If everything
here is correct, click the blue “Launch” button to
start your instance.
4. Next, follows the next few options and select the
proper usage tier and storage space that your
situation will require. On the review page it should
say “Wowza Streaming Engine” under AMI
Details and the instance type being the usage tier
www.onsemi.com
25
AND9264/D
5. When it asks you if you want a key pair, make sure
to select “Create new pair” so that it will have
a key pair assigned to this instance. This is
important for future steps to work properly.
Figure 44. Creating a New Key Pair
means that your Wowza Streaming Engine is set
up correctly.
8. Now append the “:8088” port number to the end of
your IP address and you will see the splash page
for the streaming engine with the words “Welcome
to the Wowza Streaming Engine!” in the middle of
the screen.
9. Skip to the next page and it will ask you to sign in.
The login info is listed below:
6. Next, navigate to the sidebar and click on “Elastic
IPs”. Create a new Elastic IP and assign it to your
new instance buy right clicking on the IP and
selecting “Associate Address”. This is an optional
step that is mainly due to convenience. However,
if you do not assign an elastic IP to your instance
and you end up stopping the instance, your IP
address will change upon starting the instance up
again.
7. Open a blank web page in your browser and
navigate to the new Elastic IP address. You should
see a blank white page that says “Wowza
Streaming Engine 4 for Amazon EC2…” This
User Name: wowza
Password: <Instance ID>
Figure 45. Instance ID
10. Follow steps 13 − 15 from Google Compute
Engine Setup.
Wowza Streaming Engine for Amazon EC2: Quick Start
Guide http://www.wowza.com/forums/content.php?191.
www.onsemi.com
26
AND9264/D
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 are
enabled in your Wowza Streaming Engine Manager.
Figure 46. Additional Ports
2. Patch the AMI
Wowza Streaming Engine Manager version 4.1.2.xx
sometimes experiences issues with video streaming on
Amazon Web Services. Because of this, you might need to
install an AMI patch (link here).
Wowza Streaming Engine 4 Monthly Edition 4.1.2.01
build14891.
To verify if the EC2 instance is on the same version/build
as the one that you have already tested, please launch the
following link for both servers:
http://<wowza−ip−address>:1935
Please compare the software version and build number for
both instances. If you find that the new EC2 instance has an
older version/build, please do apply the software patch
3. Other Wowza Settings
Set the RTSP KeepAlive GET_PARAMETER by
following the instructions here.
4. RTSP URL
The 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).
It should return text similar to the following:
Wowza Streaming Engine 4 Monthly Edition 4.1.2.01
build14891
Figure 47. RTSP URL
www.onsemi.com
27
AND9264/D
Additional Resources
Cloud Recording for Video on Demand
http://www.wowza.com/forums/content.php?123−How−to
−record−live−streams−%28HTTPLiveStreamRecord%29\
How to Set Up Video on Demand Streaming:
http://www.wowza.com/forums/content.php?35−How−to−
set−up−video−on−demand−streaming
The camera sends HTTP requests in the following format:
curl −L −−digest
“http://<username>:<password>@<ipaddress>:<portnum
ber>/livestreamrecord?option=overwrite&app=<livestrea
m>&streamname=<streamname>&action=startRecording
&outputFile=<outputfile.mp4>”
curl −L −−digest
“http://<username>:<password>@<ipaddress>:<portnum
ber>/livestreamrecord?app=<livestream>&streamname=<
streamname>&action=stopRecording”
How to Re-Stream Video from an IP Camera (RTSP/RTP
Re-Streaming):
http://www.wowza.com/forums/content.php?39
Wowza Media Server User Guide:
http://www.wowza.com/resources/WowzaMediaServer_
UsersGuide.pdf
Amazon is a registered trademark of Amazon.com, Inc. Google is a registered trademarks of Google Inc. iOS is a registered trademarks of
Apple Inc. Wi-Fi is a registered trademark of the Wi-Fi Alliance. Wowza is a registered trademark of Wowza Media Systems, LLC in the United
States and/or other countries. Android is a trademark of Google Inc. Amazon EC2 is a trademark of Amazon.com, Inc. Google Cloud Platform
and 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 the
United States and/or other countries. All other brand names and product names appearing in this document are registered trademarks or
trademarks of their respective holders.
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 accessed
at 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, representation
or 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, and
specifically disclaims any and all liability, including without limitation special, consequential or incidental damages. “Typical” parameters which may be provided in SCILLC data sheets
and/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 each
customer 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 which
the 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 or
unauthorized application, Buyer shall indemnify and hold SCILLC and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and
expenses, 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 claim
alleges 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 applicable
copyright laws and is not for resale in any manner.
PUBLICATION ORDERING INFORMATION
LITERATURE FULFILLMENT:
Literature Distribution Center for ON Semiconductor
19521 E. 32nd Pkwy, Aurora, Colorado 80011 USA
Phone: 303−675−2175 or 800−344−3860 Toll Free USA/Canada
Fax: 303−675−2176 or 800−344−3867 Toll Free USA/Canada
Email: orderlit@onsemi.com
N. American Technical Support: 800−282−9855 Toll Free
USA/Canada
Europe, Middle East and Africa Technical Support:
Phone: 421 33 790 2910
Japan Customer Focus Center
Phone: 81−3−5817−1050
www.onsemi.com
28
ON Semiconductor Website: www.onsemi.com
Order Literature: http://www.onsemi.com/orderlit
For additional information, please contact your local
Sales Representative
AND9264/D