Detection Alerts

Last Updated on : 2024-06-17 08:40:57download

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
ThingSmartCameraMessage 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<ThingSmartCameraMessageSchemeModel *> *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 ThingSmartCameraMessageSchemeModel

Field Type Description
describe NSString The description of an alert category.
msgCodes NSArray The array of alert types included in a category
  • You can set the alert category property msgCodes to query all types of alerts that belong to a specified category.
  • A message type represents a trigger method of alerts. It is indicated by the msgCode property of the alert data model.

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

The types of alerts that can be triggered vary depending on device capabilities. Alert categories and alert types are distinguished in the following ways:

  • An alert type represents a trigger method of an alert.
  • An alert category is a collection of one or more message types. For example, ipc_passby, ipc_linger, and ipc_motion can belong to the alert category of motion detection.

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<ThingSmartCameraMessageModel *> *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 ThingSmartCameraMessageModel

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.

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 ThingSmartCameraKit and ThingSmartCameraMessageMediaPlayer must be called to implement the video playback.

Query video frame rendering views

API description

- (UIView<ThingSmartVideoViewType> *)videoView;

Play video messages

API description

- (void)playMessage:(ThingSmartCameraMessageModel *)messageModel attachmentType:(ThingCameraMessageAttachmentType)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:(ThingCameraMessageAttachmentType)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 ThingEncryptImage 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:(ThingCameraMessageAttachmentType)attachmentType;

Resume playback

API description

- (int)resumePlay:(ThingCameraMessageAttachmentType)attachmentType;

Stop playback

API description

- (void)stopPlay:(ThingCameraMessageAttachmentType)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

ThingSmartCameraMessageMediaPlayerDelegate is the delegate protocol of the message player.

API description

- (void)mediaPlayer:(ThingSmartCameraMessageMediaPlayer *)player didReceivedFrame:(CMSampleBufferRef)frameBuffer videoFrameInfo:(ThingSmartVideoFrameInfo)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:(ThingSmartCameraMessageMediaPlayer *)player  didReceivedAudioFrameInfo:(ThingSmartAudioFrameInfo)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.

For SDK versions earlier than v3.20.0, an API method of ThingSmartCloudManager is called to implement playback of attached content. This API method is deprecated in v3.20.0. We recommend that you update to the latest SDK version at the earliest opportunity.

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:ThingSmartCameraMotionDetectDPName]) {
        bool motionDetectOn = [[self.dpManager valueForDP:ThingSmartCameraMotionDetectDPName] tysdk_toBool];
        if (!motionDetectOn) {
            [self.dpManager setValue:@(YES)  forDP:ThingSmartCameraMotionDetectDPName
            success:^(id result) {
                // Motion detection is enabled.
            } failure:^(NSError *error) {
             // A network error.
            }];
        }
          [self.dpManager setValue:ThingSmartCameraMotionHigh
                              forDP:ThingSmartCameraMotionSensitivityDPName
                         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 = [[ThingSmartCameraMessage alloc] initWithDeviceId:self.devId timeZone:[NSTimeZone defaultTimeZone]];
    [self.cameraMessage getMessageSchemes:^(NSArray<ThingSmartCameraMessageSchemeModel *> *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:(ThingSmartCameraMessageSchemeModel *)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<ThingSmartCameraMessageModel *> *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(ThingSmartCameraMotion.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 = ThingSmartCameraMessage(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: ThingSmartCameraMessageSchemeModel) {
    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.
    }
}