Build the Amazon Kinesis Video Streams Edge Agent

Build the Amazon Kinesis Video Streams Edge Agent

1. Download the tar file using the link that was provided to you.

   If you completed the Amazon Kinesis Video Streams Edge Agent interest form, check your email for the download link. If you haven't completed the form, complete it here.

2. Verify the checksum.

3. Extract the binaries and jar in your device.

   Type: tar -xvf kvs-edge-agent.tar.gz.

   After extraction, your folder structure will look like the following:

   kvs-edge-agent/LICENSE
   kvs-edge-agent/THIRD-PARTY-LICENSES
   kvs-edge-agent/pom.xml
   kvs-edge-agent/KvsEdgeComponent
   kvs-edge-agent/KvsEdgeComponent/recipes
   kvs-edge-agent/KvsEdgeComponent/recipes/recipe.yaml
   kvs-edge-agent/KvsEdgeComponent/artifacts
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/edge_log_config
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/kvs-edge-agent.jar
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/libgstkvssink.so
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/libIngestorPipelineJNI.so
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib/libcproducer.so
   kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib/libKinesisVideoProducer.so

   Note

   The release folder name should be set up in a way that reflects the latest binary release number. For example, a 1.0.0 release will have the folder name set as 1.0.0.

4. Build the dependencies jar.

   Note

   The jar included with the kvs-edge-agent.tar.gz does not have the dependencies. Use the following steps to build those libraries.

   Navigate to the kvs-edge-agent folder that contains pom.xml.

   Type mvn clean package.

   This generates a jar file containing the dependencies the Amazon Kinesis Video Streams Edge Agent requires at kvs-edge-agent/target/libs.jar.

5. Place the libs.jar into the folder that contains the component's artifacts.

   Type mv ./target/libs.jar ./KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/.

6. Set environment variables using the values from previous steps. The following table provides descriptions for the variables.

   Environment Variable Name	Required	Description
   AWS_REGION	Yes	The Region that is used. Example: us-west-2
   AWS_IOT_CA_CERT	Yes	File path to the CA certificate used to establish trust with the backend service through TLS. Example: /file/path/to/AmazonRootCA1.pem
   AWS_IOT_CORE_CERT	Yes	File path to the X.509 certificate. Example: /file/path/to/certificateID-certificate.pem.crt
   AWS_IOT_CORE_CREDENTIAL_ENDPOINT	Yes	The AWS IoT Core credential endpoint provider endpoint for your AWS account. Example: credential-account-specific-prefix.credentials.iot.aws-region.amazonaws.com
   AWS_IOT_CORE_DATA_ATS_ENDPOINT	Yes	The AWS IoT Core data plane endpoint for your AWS account. Example: data-account-specific-prefix.iot.aws-region.amazonaws.com
   AWS_IOT_CORE_PRIVATE_KEY	Yes	File path to the private key used in the public/private key pair. For more information, see Key management in AWS IoT. Example: /file/path/to/certificateID-private.pem.key
   AWS_IOT_CORE_ROLE_ALIAS	Yes	The name of the role alias pointing to the AWS IAM role to use when connecting to AWS IoT Core. Example: kvs-edge-role-alias
   AWS_IOT_CORE_THING_NAME	Yes	The name of the AWS IoT thing that the application is being run on. Example: my-edge-device-thing
   GST_PLUGIN_PATH	Yes	File path pointing to the folder that contains the gstkvssink and IngestorPipelineJNI platform-dependent libraries. Lets GStreamer load these plugins. For more information, see Download, build, and configure the GStreamer element. Example: /download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/
   LD_LIBRARY_PATH	Yes	File path pointing to the directory containing the cproducer and KinesisVideoProducer platform-dependent libraries. Example: /download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib/
   AWS_KVS_EDGE_CLOUDWATCH_ENABLED	No	Determines if the Amazon Kinesis Video Streams Edge Agent will post job health metrics onto Amazon CloudWatch. Accepted values: TRUE/FALSE (case insensitive). Defaults to FALSE if not provided. Example: FALSE
   AWS_KVS_EDGE_LOG_LEVEL	No	The level of logging the Amazon Kinesis Video Streams Edge Agent outputs. Accepted values: OFF ALL FATAL ERROR WARN INFO, default, if not provided DEBUG TRACE Example: INFO
   AWS_KVS_EDGE_LOG_MAX_FILE_SIZE	No	Once the log file reaches this size, a rollover will occur. Min: 0 Max: 10000 Default: 20, if not provided Units: Megabytes (MB) Example: 5
   AWS_KVS_EDGE_LOG_OUTPUT_DIRECTORY	No	The file path pointing to the directory where the Amazon Kinesis Video Streams Edge Agent logs are output. Defaults to ./log if not provided. Example: /file/path/
   AWS_KVS_EDGE_LOG_ROLLOVER_COUNT	No	The number of rolled-over logs to keep before deleting. Min: 1 Max: 100 Default: 10, if not provided Example: 20
   AWS_KVS_EDGE_RECORDING_DIRECTORY	No	File path pointing to the directory recorded media will be written to. Defaults to the current directory if not provided. Example: /file/path/
   GST_DEBUG	No	Specifies the level of GStreamer logs to output. For more information, see the GStreamer documentation. Example: 0
   GST_DEBUG_FILE	No	Specifies the output file of the GStreamer debug logs. If unset, debug logs get output to standard error. For more information, see the GStreamer documentation. Example: /tmp/gstreamer-logging.log

7. Clear the GStreamer cache. Type:

   rm ~/.cache/gstreamer-1.0/registry.your-os-architecture.bin

   For more information, see the GStreamer registry documentation.

8. Prepare and run the java command. The Amazon Kinesis Video Streams Edge Agent accepts the following arguments:

   Java Property Name	Required	Description
   java.library.path	No	File path pointing to the folder containing the gstkvssink and IngestorPipelineJNI dependent libraries. If not provided, the Amazon Kinesis Video Streams Edge Agent will search for them in the current directory. Important The Amazon Kinesis Video Streams Edge Agent won't function correctly if it can't locate these files. Example: /file/path/

   To set these, add -Djava-property-name=value to the java command used to run the jar.

   For example:

   java -Djava.library.path=/download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion \
     --add-opens java.base/jdk.internal.misc=ALL-UNNAMED \
     -Dio.netty.tryReflectionSetAccessible=true \
     -cp kvs-edge-agent.jar:libs.jar \
     com.amazonaws.kinesisvideo.edge.controller.ControllerApp

   Important

   Run the java command above from the same directory as /download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion.

9. Send configurations to the application using the AWS CLI.

   1. Create a new file, example-edge-configuration.json.

      Paste the following code into the file. This is a sample configuration that records daily from 9:00:00 AM to 4:59:59 PM (according to the system time on your AWS IoT device). It also uploads the recorded media daily from 7:00:00 PM to 9:59:59 PM.

      For more information, see StartEdgeConfigurationUpdate.

      {
          "StreamARN": "arn:aws:kinesisvideo:your-region:your-account-id:stream/your-stream/0123456789012",
          "EdgeConfig": {
              "HubDeviceArn": "arn:aws:iot:your-region:your-account-id:thing/kvs-edge-agent-demo",
              "RecorderConfig": {
                  "MediaSourceConfig": {
                      "MediaUriSecretArn": "arn:aws:secretsmanager:your-region:your-account-id:secret:your-secret-dRbHJQ",
                      "MediaUriType": "RTSP_URI"
                  },
                  "ScheduleConfig": {
                      "ScheduleExpression": "0 0 9,10,11,12,13,14,15,16 ? * * *",
                      "DurationInSeconds": 3599
                  }
              },
              "UploaderConfig": {
                  "ScheduleConfig": {
                      "ScheduleExpression": "0 0 19,20,21 ? * * *",
                      "DurationInSeconds": 3599
                  }
              },
              "DeletionConfig": {
                  "EdgeRetentionInHours": 15,
                  "LocalSizeConfig": {
                    "MaxLocalMediaSizeInMB": 2800,
                    "StrategyOnFullSize": "DELETE_OLDEST_MEDIA"
                  },
                  "DeleteAfterUpload": true
              }
          }
      }

   2. To send the file to the Amazon Kinesis Video Streams Edge Agent, type the following in the AWS CLI:

      aws kinesisvideo start-edge-configuration-update --cli-input-json "file://example-edge-configuration.json"

10. Repeat the previous step for each stream for the Amazon Kinesis Video Streams Edge Agent.