Detection Alerts

Powered by Tuya (PBT) IP cameras (IPCs) support detection alerts in most cases. This feature can be enabled in the module of device features.

Functional description

Detection alarms are classified into: sound detection and motion detection. When sound or motion is detected, an IPC can trigger an alert. If your app supports push notifications, an alert will be sent to the app. For more information, see Integrate with Push Notifications.

• An alert includes a video screenshot in most cases.
• A doorbell connected to mains power supports video messages. For example, if the doorbell is pressed, the device uploads a video message. This message can be queried from alerts. Each video message includes a 6-second encrypted video clip.

Alert messages

Classes

Class name	Description
TuyaSmartCameraMessage	Manage detection alerts from IPCs

Initialize alert management class

Initializes the alert management class with the device ID and time zone before a list of alerts can be queried.

API description

- (instancetype)initWithDeviceId:(NSString *)devId timeZone:(NSTimeZone *)timeZone;

Parameters

Parameter	Description
devId	The device ID.
timeZone	The time zone. By default, it is the time zone of a mobile phone system, indicated by [NSTimeZone systemTimeZone].

Query alert calendar

Returns the date on which alerts are generated and displays the alert calendar.

API description

- (void)messageDaysForYear:(NSInteger)year
                     month:(NSInteger)month
                   success:(void (^)(NSArray<NSString *> *result))success
                   failure:(void (^)(NSError *error))failure;

Parameters

Parameter	Description
year	The year, such as 2020.
month	The month, such as 2.
success	The success callback. An array of dates on which alerts are generated is returned. result is an array of date strings, such as 01, 11, and 30.
failure	The failure callback. An error message is returned.

Query a list of alerts

Detection alerts are classified into multiple types based on trigger methods. Certain types belong to a specific category. The IPC SDK returns a list of alerts by default category to support queries of alerts based on categories.

API description

- (void)getMessageSchemes:(void (^)(NSArray<TuyaSmartCameraMessageSchemeModel *> *result))success
                  failure:(void (^)(NSError *error))failure;

Parameters

Parameter	Description
success	The success callback. An array of alert category models is returned.
failure	The failure callback. An error message is returned.

Fields of TuyaSmartCameraMessageSchemeModel

Field	Type	Description
describe	NSString	The description of an alert category.
msgCodes	NSArray	The array of alert types included in a category

Description of msgCodes

Type	Description
ipc_motion	Motion detection
ipc_doorbell	Doorbell call
ipc_dev_link	Device linkage
ipc_passby	Someone passes by
ipc_linger	Someone lingers
ipc_leave_msg	Leave messages on doorbell
ipc_connected	Doorbell answered
ipc_unconnected	Doorbell missed
ipc_refuse	Doorbell rejected
ipc_human	Human shape detection
ipc_cat	Pet detection
ipc_car	Vehicle detection
ipc_baby_cry	Baby cry
ipc_bang	Abnormal sound
ipc_antibreak	Tamper alarm
ipc_low_battery	Low battery alert

Query a list of detection alerts

Returns and deletes detection alerts based on the IPC SDK.

API description

- (void)messagesWithMessageCodes:(NSArray *)msgCodes
                          Offset:(NSInteger)offset
                           limit:(NSInteger)limit
                       startTime:(NSInteger)startTime
                         endTime:(NSInteger)endTime
                         success:(void (^)(NSArray<TuyaSmartCameraMessageModel *> *result))success
                         failure:(void (^)(NSError *error))failure;

Parameters

Parameter	Description
msgCodes	The type of message. Set the value to nil to return all types of alerts.
offset	The position starting from which alerts are returned. A value of 0 represents the first alert.
limit	The number of entries to be returned per page. Maximum value: 200.
startTime	The start Unix timestamp of the period in which target alerts were reported. Set the value to 0 to ignore the start time.
endTime	The end Unix timestamp of the period in which target alerts were reported.
success	The success callback. An array of alert models is returned.
failure	The failure callback. An error message is returned.

Delete alerts in bulk

Parameters

- (void)removeMessagesWithMessageIds:(NSArray *)msgIds
                             success:(void (^)(void))success
                             failure:(void (^)(NSError *))failure;

Parameters

Parameter	Description
msgIds	The list of IDs for the alerts to be deleted.
success	The success callback.
failure	The failure callback. An error message is returned.

Fields of TuyaSmartCameraMessageModel

Field	Type	Description
dateTime	NSString	The string date on which an alert was reported.
msgTypeContent	NSString	The description of an alert type.
attachPic	NSString	The URL of an attached image.
attachVideos	NSArray	The array of URLs for attached video footage.
msgSrcId	NSString	The ID of the device that triggers an alert.
msgContent	NSString	The content of an alert.
msgTitle	NSString	The title of the alert.
msgId	NSString	The alert ID.
msgCode	NSString	The type of alert.
time	NSInteger	The Unix timestamp when an alert was reported.

The following attached content might be returned depending on different message types:

• URL of attached images indicated by the attachPic property.
• URLs of attached video footage indicated by the attachVideos property. Typically, this property has only one element.

Get the latest motion detection images

API description

- (void)getLatestMessageImage:(NSString *)devIds
                      success:(void (^)(NSArray<NSDictionary *> *result))success
                      failure:(void (^)(NSError *error))failure;

Parameters

Parameter	Description
devIds	The list of device IDs in the JSON format.
success	The success callback.
failure	The failure callback. An error message is returned.

Description of return values

Parameter	Description
devId	The device ID.
picUrl	The URL of the image.
time	The time when the motion detection image was generated.
encryption	The key-value pair in the format of key:xxxxxx used for encryption. If key exists, the image is encrypted and must be decrypted with a decryption component before the image can be used.

Enable alert image encryption

To protect the data privacy of app users, users can encrypt images in alerts.

API description

This feature is disabled by default. After it is enabled, alert images will be encrypted. You must use the component TYEncryptImage to display the images. For more information, see Encrypted Image.

@property (nonatomic, assign) BOOL enableEncryptedImage;

Video messages

The video footage attached to video messages is encrypted. The API methods of TuyaSmartCameraKit and TuyaSmartCameraMessageMediaPlayer must be called to implement the video playback.

Query video frame rendering views

API description

- (UIView<TuyaSmartVideoViewType> *)videoView;

Play video messages

API description

- (void)playMessage:(TuyaSmartCameraMessageModel *)messageModel attachmentType:(TuyaCameraMessageAttachmentType)attachmentType success:(void(^)(void))success failure:(void(^)(int errCode))failure finished:(void(^)(int errCode))onFinish;

Parameters

Parameter	Description
messageModel	The alert data model.
attachmentType	The type of attached playback content. An alert might be a video message or audio message.
success	The success callback.
failure	The failure callback.
onFinish	The callback that is executed when video playback is finished. errCode indicates an error message and 0 indicates that playback is finished.

Play back attached messages

API description

- (void)playMessageAttachment:(NSString *)attachmentPath type:(TuyaCameraMessageAttachmentType)attachmentType success:(void(^)(void))success failure:(void(^)(int errCode))failure finished:(void(^)(int errCode))onFinish;

Parameters

Parameter	Description
attachmentPath	The URL of the attached content.
attachmentType	The type of attached audio or video content. The component TYEncryptImage must be used to display attached images.
success	The success callback.
failure	The failure callback.
onFinish	The callback that is executed when video playback is finished. errCode indicates an error message and 0 indicates that playback is finished.

Pause playback

API description

- (int)pausePlay:(TuyaCameraMessageAttachmentType)attachmentType;

Resume playback

API description

- (int)resumePlay:(TuyaCameraMessageAttachmentType)attachmentType;

Stop playback

API description

- (void)stopPlay:(TuyaCameraMessageAttachmentType)attachmentType;

Set mute status

API description

- (void)enableMute:(BOOL)mute success:(void(^)(void))success failure:(void (^)(NSError * error))failure;

Parameters

Parameter	Description
mute	Specifies whether to mute the video.
success	The success callback.
failure	The failure callback.

Return values

Type	Description
int	An error message is returned or a value of 0 indicates a successful request.

Callback for video frames

TuyaSmartCameraMessageMediaPlayerDelegate is the delegate protocol of the message player.

API description

- (void)mediaPlayer:(TuyaSmartCameraMessageMediaPlayer *)player didReceivedFrame:(CMSampleBufferRef)frameBuffer videoFrameInfo:(TuyaSmartVideoFrameInfo)frameInfo;

Parameters

Parameter	Description
player	The player object.
frameBuffer	The YUV data of video frames.
frameInfo	The information about video frame headers.
frameInfo.nDuration	The total duration of video footage.
frameInfo.nProgress	The progress of the current video frames.

Callback for audio frames

API description

- (void)mediaPlayer:(TuyaSmartCameraMessageMediaPlayer *)player  didReceivedAudioFrameInfo:(TuyaSmartAudioFrameInfo)frameInfo;

Parameters

Parameter	Description
player	The player.
frameInfo	The information about audio frame headers.
frameInfo.nDuration	The total duration of audio content.
frameInfo.nProgress	The progress of the current audio frames.

Navigate from alerts to playback of SD card-stored content

By default, alerts are generated independently from playback of SD card-stored content. During SD card-stored video recording, alerts and video footage can be simultaneously generated by the same triggers. Specifically, they have the following differences:

• Alerts are stored in the cloud.
• SD card-stored video footage is stored on an IPC. If the SD card capacity is insufficient, the earlier video footage might be overwritten by later footage.

The switch for SD card-stored video recording is set independently from the switch for detection alerts. Therefore, during SD card-stored video recording, alerts do not always trigger video recording.

In certain cases, alerts can be linked with video footage stored on the SD card. The IPC SDK does not provide a typical API method to query video footage based on this type of correlation. However, to find the video footage triggered by alerts, users can find the time and date when the alerts were generated. Then, check whether the target video footage was created on this date. You can implement navigation from alerts to playback of SD card-stored video footage in this way.

Example

- (void)enableDetect {
		if ([self.dpManager isSupportDP:TuyaSmartCameraMotionDetectDPName]) {
        bool motionDetectOn = [[self.dpManager valueForDP:TuyaSmartCameraMotionDetectDPName] tysdk_toBool];
        if (!motionDetectOn) {
            [self.dpManager setValue:@(YES)  forDP:TuyaSmartCameraMotionDetectDPName
            success:^(id result) {
                // Motion detection is enabled.
            } failure:^(NSError *error) {
             // A network error.
            }];
        }
      	[self.dpManager setValue:TuyaSmartCameraMotionHigh
                         	 forDP:TuyaSmartCameraMotionSensitivityDPName
                         success:^(id result) {
            // The sensitivity of motion detection is set to high sensitivity.
        } failure:^(NSError *error) {
            // A network error.
        }];
    }
}

- (void)viewDidLoad {
    [super viewDidLoad];
    self.cameraMessage = [[TuyaSmartCameraMessage alloc] initWithDeviceId:self.devId timeZone:[NSTimeZone defaultTimeZone]];
    [self.cameraMessage getMessageSchemes:^(NSArray<TuyaSmartCameraMessageSchemeModel *> *result) {
	      // The message category model.
        self.schemeModels = result;
				// The alerts of the first category are returned.
        [self reloadMessageListWithScheme:result.firstObject];
    } failure:^(NSError *error) {
        // A network error.
    }];
}

- (void)reloadMessageListWithScheme:(TuyaSmartCameraMessageSchemeModel *)schemeModel {
    NSDateFormatter *formatter = [NSDateFormatter new];
    formatter.dateFormat = @"yyyy-MM-dd";
    NSDate *date = [formatter dateFromString:@"2020-02-17"];
	  // The top 20 alerts generated in the period from 00:00:00 (UTC) on February 17, 2020 to the current time are returned.
    [self.cameraMessage messagesWithMessageCodes:schemeModel.msgCodes Offset:0 limit:20 startTime:[date timeIntervalSince1970] endTime:[[NSDate new] timeIntervalSince1970] success:^(NSArray<TuyaSmartCameraMessageModel *> *result) {
        self.messageModelList = result;
    } failure:^(NSError *error) {
        // A network error.
    }];
}

Swift:

func enableDectect() {
    guard self.dpManager.isSupportDP(.motionDetectDPName) else {
        return;
    }
    if let isMontionDetectOn = self.dpManager.value(forDP: .motionDetectDPName) as? Bool, !isMontionDetectOn {
        self.dpManager.setValue(true, forDP: .motionDetectDPName, success: { _ in
            // Motion detection is enabled.
        }) { _ in
            // A network error.
        }
    }
    self.dpManager.setValue(TuyaSmartCameraMotion.high, forDP: .motionSensitivityDPName, success: { _ in
        // The sensitivity of motion detection is set to high sensitivity.
    }) { _ in
        // A network error.
    }
}

override func viewDidLoad() {
    super.viewDidLoad()
    self.cameraMessage = TuyaSmartCameraMessage(deviceId: self.devId, timeZone: NSTimeZone.default)
    self.cameraMessage.getSchemes({ result in
        // The alerts of the first category are returned.
        self.schemeModels = result
        if let schemeModel = result?.first {
            reloadMessage(schemeModel: schemeModel)
        }
    }) { _ in
        // A network error.
    }
}

func reloadMessage(schemeModel: TuyaSmartCameraMessageSchemeModel) {
    let formatter = DateFormatter()
    formatter.dateFormat = "yyyy-MM-dd"
    let date = formatter.date(from: "2020-02-17")
    // The top 20 alerts generated in the period from 00:00:00 (UTC) on February 17, 2020 to the current time are returned.
    self.cameraMessage.messages(withMessageCodes: schemeModel.msgCodes, offset: 0, limit: 20, startTime: Int(date!.timeIntervalSince1970), endTime: Int(Date().timeIntervalSince1970), success: { result in
        self.messageModelList = result;
    }) { _ in
        // A network error.
    }
}