Embedded SDK

This article describes how the VXG Cloud API relates to the built-in SDK functionality. You can use the VXG Cloud Agent documentation to build a simple application that contains callback function stubs. We recommend starting with a minimal app and check video streaming using the VXG Cloud. In the next step, you need to implement all the callback functions and adapt this source code for your awesome solution.

The integration process includes the following steps:

1. Build an application and check video streaming from a local IP camera to VXG Cloud

2. Camera capabilities

3. Video streaming

4. Integration with the settings API

5. Integrating PTZ commands

6. Integration of motion and sound events

7. Integration of the backward audio channel

Minimal requirements

Below are the minimal requirements for the camera to run the cloud agent based on Embedded SDK:

• gcc: >= 4.8.1

• RAM: 30 Mb per channel

• Flash memory: 12 Mb

1. Build an application and check video streaming from a local IP camera to VXG Cloud

VXG Cloud Agent documentation describes how to build samples. After successful building and installation, you can find the compiled application in the folder: install/bin. 

Before running the application you should go to the VXG dashboard and create a new camera and get a VXG access token:

1.1 Go to Video Management and click Add New Camera:

1.2 Select Cloud Camera and click Next:

1.3 Enter the camera name, set up recording and the timezone, and click Next:

1.4 Now the camera is created, please go to the Settings tab:

1.5 Scroll down to find the Streaming access token:

After obtaining the access token, you can run the following command and watch the video in the VXG dashboard:

./cloud-agent-minimal VXG_ACCESS_TOKEN RTSP_URL

for example:  

./cloud-agent-minimal eyJjYW1pZCI6IDIzNDQzMiwgImNtbmdyaWQiOiAyMzQ4NTcsICJhY2Nlc3MiOiAiYWxsIiwgInRva2VuIjogInNoYXJlLmV5SnphU0k2SURJd016YzJOSDAuNjA1YjA2MjJ0YmMxZmFiMDAuR0F5QmxaUDF4eXp5SXo4ZDdIOEtLOUxkLUNRIiwgImFwaSI6ICJ3ZWIuc2t5dnIudmlkZW9leHBlcnRzZ3JvdXAuY29tIiwgImNhbSI6ICJjYW0uc2t5dnIudmlkZW9leHBlcnRzZ3JvdXAuY29tIn0= "rtsp://192.168.0.1"

When you start it for the first time, you may see warnings and even errors in the logs. This is fine and means that some stubs are not properly implemented and you need to focus on implementing these callback's functions.

For example, you may see the following messages in the log:

error Cloud reported a problem: Cam 234432 '_update_video_stream_caps' exception IndexError: list index out of range at camera.py:1475
warning get_stream_config not implemented
warning set_steam_by_event not implemented
warning Failed to configure stream {} for pre/post recording.

2. Camera capabilities

The VXG Cloud requests all camera capabilities and current camera settings when the camera connects to the VXG Cloud for the first time or the app version is changed, so the camera app should provide camera capabilities to VXG Cloud. In order to do this, the following commands in your callbacks should be implemented.

Here is a list of callbacks classes and functions that must be implemented using your platform capabilities:   

3. Video streaming

The camera agent application broadcasts the video stream to VXG Cloud and uploads images and video files to the VXG storage directly. VXG Cloud sends "start" and "stop" commands to the camera, and the VXG agent starts or stops streaming.

The agent::media::stream class is an abstract class for media streams, the library provides basic media::rtsp_stream implementation which retransmits RTSP source stream to the endpoint of the VXG Cloud, all settings-related callbacks are stubbed. A developer should implement their own class derived from the media::stream with their own media::Streamer::ISource implementation, or implement their own class derived from the media::rtsp_stream but with callbacks implemented. 

4. Integration with the settings API

The list below shows the relationship between the VXG Cloud API and the callback functions in the VXG agent library that the application should handle: 

5. Integrating PTZ commands

The developer should implement the following callback functions if the camera supports PTZ controls:

vxg::cloud::agent::proto::ptz_command

vxg::cloud::agent::proto::ptz_config

vxg::cloud::agent::proto::ptz_preset

All supported PTZ actions are described in the enum ptz_action.

6. Integration of motion and sound events

The developer should implement their own class based on the event stream class and whether the camera supports any events. The number of supported events is specified in the vxg::cloud::agent::proto::event_type enumeration. It is recommended to prepare the event generating module in the vxg::cloud::agent::event_stream::start function and clean or stop this module in the vxg::cloud::agent::event_stream::stop function.

The camera application should call the function notify(event_object event) if the event occurs on the camera side. The developer can send the image in the parameters of the function notify.

The video downloading must be done in the callback function proto::video_clip_info record_export. The video is uploaded to the storage directly. It is best to upload videos a few seconds before the event and a few seconds after the event.

7. Integration of the backward audio channel

If any client initiates a backward audio session using the VXG Cloud, the VXG agent library calls the vxg::cloud::agent::callback::on_start_backward_audio callback function. The camera app gets the RTMP or RTMP URL in this callback.

The application must launch the RTMP client on its own. The RTMP stream contains only one audio track. Supported formats are G711 and AAC.

The final implementation is also responsible for demultiplexing, decoding, and rendering the audio stream.

The VXG agent invokes the following callback if the VXG client stops - vxg::cloud::agent::callback::on_stop_backward_audio.