Cloud Storage

Cloud storage stores the recording data on object storage servers provided by third-party cloud vendors. The ring buffer combined with the cloud object storage service enables you to back up recording data to the cloud instantly.

Features

Cloud storage reads audio and video data from the ring buffer and then uploads it to the cloud object storage server after encryption. Cloud storage features:

• Cloud storage comes in two flavors:
  • Event-based cloud storage: Record and upload videos to the cloud when an event is detected.
  • Continuous cloud storage: Record and upload videos to the cloud 24/7 automatically.
• Pre-record: Record a video for a few seconds before the occurrence of an event.
• Turn on/off audio, and enable/disable audio upload.
• In privacy mode, recording cloud storage will be temporarily disabled.

Security

Both the channel and data are encrypted to secure transmission.

Channel encryption

HTTPS protocol secures transferring the data between a device and a cloud object storage server. The device uploads the recording data only after the certificate authority (CA) certificate of the object storage server is verified successfully.

Data encryption

Before the recording data is uploaded, the video I-frames and audio frames will be encrypted with AES algorithms.

Components

svc_cloud_storage

Data structure

Order type

typedef enum
{
    CLOUD_STORAGE_TYPE_CONTINUE,        // Continuous cloud storage.
    CLOUD_STORAGE_TYPE_EVENT,           // Event-based cloud storage.
    CLOUD_STORAGE_TYPE_INVALID          // No subscription.
} CLOUD_STORAGE_TYPE_E;

APIs

Initialization

Initialize the cloud storage service. This allocates the internal buffer memory and creates recording threads.

/**
 * @brief    initialize cloud storage, which will malloc all needed memory after this
 * @return   error code
 * - OPRT_OK init success
 * - Others  init failed
 */
OPERATE_RET tuya_ipc_cloud_storage_init(VOID);

Deinitialization

Deinitialize the cloud storage service. This deallocates the buffer memory and destroys the recording threads.

/**
 * @brief    uninit cloud storage, free used memory
 * @return   VOID
 */
VOID tuya_ipc_cloud_storage_uninit(VOID);

Get the order type

Get the order type to determine if the device has subscribed to the cloud storage service. The order type can be continuous cloud storage, event-based cloud storage, and no subscription.

/**
 * @brief    get current storage type, based on purchase order
 * @return   CLOUD_STORAGE_TYPE_E
 * - CLOUD_STORAGE_TYPE_CONTINUE  continuous record type
 * - CLOUD_STORAGE_TYPE_EVENT     event-based type, only record and store audio/video when there is event happening
 * - CLOUD_STORAGE_TYPE_INVALID   no cloud storage order exist
 */
CLOUD_STORAGE_TYPE_E tuya_ipc_cloud_storage_get_store_mode(VOID);

Start event recording

The device records a video clip when an event occurs.

/**
 * @brief    start event cloud storage
 * @return   error code
 * - OPRT_OK cloud storage start success
 * - Others cloud storage start failed
 */
OPERATE_RET tuya_ipc_cloud_storage_event_start(VOID);

Stop event recording (synchronous)

The device stops recording when an event ends. This is a synchronous API, with a maximum blocking time of 30 seconds.

/**
 * @brief    stop event cloud storage, synchronous api
 * @return   error code
 * - OPRT_OK cloud storage stop success
 * - Others  cloud storage stop failed
 */
OPERATE_RET tuya_ipc_cloud_storage_event_stop(VOID);

Stop event recording (asynchronous)

The device stops recording when an event ends. This is a non-blocking asynchronous API.

/**
 * @brief    stop event cloud storage, asynchronous api
 * @return   error code
 * - OPRT_OK cloud storage stop success
 * - Others  cloud storage stop failed
 */
OPERATE_RET tuya_ipc_cloud_storage_event_stop_async(VOID);

Get recording status

Get the current recording status to determine if the device is recording a video.

/**
 * @brief    get cloud storage status
 * @return   BOOL_T
 * - TRUE    cloud storage is uploading
 * - FALSE   cloud storage is not uploading
 */
BOOL_T tuya_ipc_cloud_storage_get_status(VOID);

Turn on/off audio

When audio is turned off, only video data is read from the ring buffer for cloud storage.

/**
 * @brief    set audio open/close
 * @param[in] is_audio_open
 * @ref       TRUE open audio for cloud storage
 * @ref       FALSE close audio for cloud storage
 * @return    VOID
 */
VOID tuya_ipc_cloud_storage_set_audio_stat(BOOL_T is_audio_open);

Set pre-record duration

The maximum pre-record duration cannot exceed the maximum ring buffer duration. If you do not specify a value, the default duration is two seconds.

/**
 * @brief    set cloud storage pre record time duration
 * @param[in] pre_recode_time  pre record time duration for cloud storage
 * - OPRT_OK set pre record time success
 * - Others  set pre record time failed
 */
OPERATE_RET tuya_ipc_cloud_storage_set_pre_record_time(INT_T pre_record_time);

Pause recording

Temporarily disable recording cloud storage. The recording thread stops reading data from the ring buffer and uploading data to the server. This feature is typically triggered when the user turns on privacy mode.

/**
 * @brief    pause cloud storage, used in privacy mode e.g.
 * @return   VOID
 */
VOID tuya_ipc_cloud_storage_pause(VOID);

Resume recording

Resume recording cloud storage and the recording thread. Used with tuya_ipc_cloud_storage_pause, this feature is triggered when the user turns off privacy mode.

/**
 * @brief    resume cloud storage which is paused by pause API
 * @return   VOID
 */
VOID tuya_ipc_cloud_storage_resume(VOID);

FAQs

When should I allocate and deallocate memory? How much memory is required?

Contiguous memory is allocated when the cloud storage service is initialized. This can avoid the out of memory (OOM) error caused by changes in memory usage when the program is run. The footprint is: 11 × bit rate

The allocated memory is used to buffer the encrypted audio and video data to be uploaded to the cloud object storage server.

The allocated memory is freed when the cloud storage is deinitialized.

Why is the recording of an event interrupted?

• The actual bitrate exceeds the set maximum bitrate.
• Recording data fails to be uploaded due to poor network conditions.
• Recording data upload is slow due to poor network conditions.
  The device reads and uploads recording data in the recording thread serially. If the recording upload time exceeds the maximum ring buffer duration due to poor network conditions, data loss might occur.

Why doesn’t the actual pre-record duration match the set value?

To locate the pre-frame in the ring buffer, starting from the latest frame, search backward for frame_num frame and then continue the search until the I-frame is reached. frame_num is calculated by the formula: pre-record duration × frame rate in fps

Therefore, the pre-frame is not at a fixed position, so the actual pre-record duration might deviate from the set value.

Is the mainstream or substream used for cloud storage?

The mainstream is used by default. Substream recording is not supported currently.