Amazon Kinesis Video Streams
Developer Guide

Using the C++ Producer SDK on Raspberry Pi

The Raspberry Pi is a small, inexpensive computer that can be used to teach and learn basic computer programming skills. This tutorial describes how you can set up and use the Amazon Kinesis Video Streams C++ Producer SDK on a Raspberry Pi device. The steps also include how to verify the installation using the GStreamer demo application.

Prerequisites

Before you set up the C++ Producer SDK on your Raspberry Pi, ensure that you have the following prerequisites:

Create an IAM User with Permission to Write to Kinesis Video Streams

If you haven't already done so, set up an AWS Identity and Access Management (IAM) user with permissions to write to a Kinesis video stream.

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation menu on the left, choose Users.

  3. To create a new user, choose Add user.

  4. Provide a descriptive User name for the user, such as kinesis-video-raspberry-pi-producer.

  5. Under Access type, choose Programmatic access.

  6. Choose Next: Permissions.

  7. Under Set permissions for kinesis-video-raspberry-pi-producer, choose Attach existing policies directly.

  8. Choose Create policy. The Create policy page opens in a new web browser tab.

  9. Choose the JSON tab.

  10. Copy the following JSON policy and paste it into the text area. This policy gives your user permission to create and write data to Kinesis video streams.

    { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "kinesisvideo:DescribeStream", "kinesisvideo:CreateStream", "kinesisvideo:GetDataEndpoint", "kinesisvideo:PutMedia" ], "Resource": [ "*" ] }] }
  11. Choose Review policy.

  12. Provide a Name for your policy, such as kinesis-video-stream-write-policy.

  13. Choose Create policy.

  14. Return to the Add user tab in your browser, and choose Refresh.

  15. In the search box, type the name of the policy you created.

  16. Select the check box next to your new policy in the list.

  17. Choose Next: Review.

  18. Choose Create user.

  19. The console displays the Access key ID for your new user. Choose Show to display the Secret access key. Record these values; they are required when you configure the application.

Join Your Raspberry Pi to Your Wi-Fi Network

You can use the Raspberry Pi in headless mode, that is, without an attached keyboard, monitor, or network cable. If you are using an attached monitor and keyboard, proceed to Configure the Raspberry Pi Camera.

  1. On your computer, create a file named wpa_supplicant.conf.

  2. Copy the following text and paste it into the wpa_supplicant.conf file:

    country=US ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 network={ ssid="<YOUR_WIFI_SSID>" scan_ssid=1 key_mgmt=WPA-PSK psk="<YOUR_WIFI_PASSWORD>" }

    Replace the ssid and psk values with the information for your Wi-Fi network.

  3. Copy the wpa_supplicant.conf file to the SD card. It must be copied to the root of the boot volume.

  4. Insert the SD card into the Raspberry Pi, and power the device. It joins your Wi-Fi network, and SSH is enabled.

Connect Remotely to Your Raspberry Pi

You can connect remotely to your Raspberry Pi in headless mode. If you are using your Raspberry Pi with a connected monitor and keyboard, proceed to Configure the Raspberry Pi Camera.

  1. Before connecting to your Raspberry Pi device remotely, do one of the following to determine its IP address:

    • If you have access to your network's Wi-Fi router, look at the connected Wi-Fi devices. Find the device named Raspberry Pi to find your device's IP address.

    • If you don't have access to your network's Wi-Fi router, you can use other software to find devices on your network. Fing is a popular application that is available for both Android and iOS devices. You can use the free version of this application to find the IP addresses of devices on your network.

  2. When you know the IP address of the Raspberry Pi device, you can use any terminal application to connect.

    • On macOS or Linux, use ssh:

      $ ssh pi@<IP address>
    • On Windows, use PuTTY, a free SSH client for Windows.

    For a new installation of Raspbian, the user name is pi, and the password is raspberry. We recommend that you change the default password.

Configure the Raspberry Pi Camera

Follow these steps to configure the Raspberry Pi camera to send video from the device to a Kinesis video stream.

  1. Open an editor to update the modules file with the following command:

    $ sudo nano /etc/modules
  2. Add the following line to the end of the file, if it's not already there:

    bcm2835-v4l2
  3. Save the file and exit the editor (Ctrl-X).

  4. Reboot the Raspberry Pi:

    $ sudo reboot
  5. When the device reboots, connect to it again through your terminal application if you are connecting remotely.

  6. Open raspi-config:

    $ sudo raspi-config
  7. Choose Interfacing Options, Camera. Enable the camera if it's not already enabled, and reboot if prompted.

  8. Verify that the camera is working by typing the following command:

    $ raspistill -v -o test.jpg

    The display shows a five-second preview from the camera, takes a picture (saved to test.jpg), and displays informational messages.

Install Software Prerequisites

The C++ Producer SDK requires that you install the following software prerequisites on Raspberry Pi.

  1. Install Git:

    $ sudo apt-get update $ sudo apt-get install git
  2. Install Yacc, Lex, and OpenJDK (Open Java Development Kit):

    $ sudo apt-get install byacc flex $ sudo apt-get install openjdk-8-jdk
  3. Set the JAVA_HOME environment variable:

    $ export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-armhf/

    Note

    If you reboot the device before building the SDK, you must repeat this step. You can also set this environment variable in your ~/.profile file.

  4. CMake is used to build the SDK. Install CMake with the following command:

    $ sudo apt-get install cmake
  5. Copy the following PEM file to /etc/ssl/cert.pem:

    https://www.amazontrust.com/repository/SFSRootCAG2.pem

Download and Build the Kinesis Video Streams C++ Producer SDK

  1. Install the C++ Producer SDK:

    $ git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp
  2. Change your current working directory to the install directory:

    $ cd amazon-kinesis-video-stream-producer-sdk-cpp/kinesis-video-native-build
  3. Make the install script executable:

    $ chmod +x install-script
  4. Run the install script. The script downloads the source and builds several open-source projects. It might take several hours to run the first time it is executed:

    $ ./install-script
  5. Type Y to verify. Then the build script runs.

Stream Video to Your Kinesis Video Stream and View the Live Stream

  1. To run the sample application, you need the following information:

  2. Run the sample application using the following command:

    $ export AWS_ACCESS_KEY_ID=<Access Key ID> export AWS_SECRET_ACCESS_KEY=<Secret Access Key> ./kinesis_video_gstreamer_sample_app Stream Name
  3. You can specify the image size, framerate, and bitrate as follows:

    $ export AWS_ACCESS_KEY_ID=<Access Key ID> export AWS_SECRET_ACCESS_KEY=<Secret Access Key> ./kinesis_video_gstreamer_sample_app -w <width> -h <height> -f <framerate> -b <bitrateInKBPS> Stream Name
  4. If the sample application exits with a library not found error, type the following commands to verify that the project is correctly linked to its open-source dependencies:

    $ rm -rf ./kinesis-video-native-build/CMakeCache.txt ./kinesis-video-native-build/CMakeFiles $ ./kinesis-video-native-build/install-script
  5. Open the Kinesis Video Streams console at https://console.aws.amazon.com/kinesisvideo/.

  6. Choose the Stream name of the stream you created.

The video stream that is sent from the Raspberry Pi appears in the console.

When the stream is playing, you can experiment with the following features of the Kinesis Video Streams console:

  • In the Video preview section, use the navigation controls to rewind or fast-forward the stream.

  • In the Stream info section, notice the codec, resolution, and bit rate of the stream. The resolution and bitrate values are set purposefully low on the Raspberry Pi to minimize bandwidth usage for this tutorial. To view the Amazon CloudWatch metrics that are being created for your stream, choose View stream metrics in CloudWatch.

  • Under Data retention period, notice that the video stream is retained for one day. You can edit this value and set it to No data retention, or set a value from one day to several years.

    Under server-side encryption, notice that your data is being encrypted at rest using a key maintained by the AWS Key Management Service (AWS KMS).