IPC Control (iOS)

Last Updated on : 2023-06-05 02:50:02download

This topic describes a list of API methods that are used to control IP cameras (IPCs).

Functional description

  • For more information about control of common smart devices, see Device Control (iOS).

  • Data points (DPs) are configured to implement smart device control between the app and cloud. Standard DPs apply to interactions between devices and the app. For more information about DPs that are defined in the IPC SDK, see DP constants.

  • The following table describes the classes for IPC control:

    Class name (protocol name) Description
    ThingSmartCameraDPManager Enables communication with devices based on DPs.
    ThingSmartCameraDPObserver Provides the capability to listen for the changes of DP status.

Get an object

Initialize a device

API description

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

Parameters

Parameter Description
devId The device ID.

Add or remove a listener of device status

API description

/// Adds a listener of device status.
- (void)addObserver:(id<ThingSmartCameraDPObserver>)observer;

/// Removes a listener of device status.
- (void)removeObserver:(id<ThingSmartCameraDPObserver>)observer;

Parameters

Parameter Description
observer The listener. To call this API method, the protocol ThingSmartCameraDPObserver must be implemented.

Query DP status

Query DPs

API description

- (BOOL)isSupportDP:(ThingSmartCameraDPKey)dpName;

Parameters

Parameter Description
dpName The DP ID.

Return value

Type Description
BOOL Indicates whether the specified DP is supported.

Query a DP value

API description

Returns the cached value of a DP. If the specified DP is not supported, nil is returned.

- (id)valueForDP:(ThingSmartCameraDPKey)dpName;

Parameters

Parameter Description
dpName The DP ID.

Return value

Parameter Description
id The value is converted to support the specified type of DP. For more information, see DP constants.

Asynchronously query a DP value

API description

Asynchronously returns the value of a DP.

We recommend that you call this method only for SD card-related DPs.

- (void)valueForDP:(ThingSmartCameraDPKey)dpName success:(ThingSuccessID)success failure:(ThingFailureError)failure;

Parameters

Parameter Description
dpName The DP ID.
success The success callback. The current value of the specified DP is returned.
failure The failure callback. An error message is returned.

Send DPs

Set the value of a DP

API description

- (void)setValue:(id)value forDP:(ThingSmartCameraDPKey)dpName success:(ThingSuccessID)success failure:(ThingFailureError)failure;

Parameters

Parameter Description
value The value of a DP. The value or Boolean type is supported. The value must be encapsulated as NSNumber.
dpName The DP ID.
success The success callback. The current value of the specified DP is returned.
failure The failure callback. An error message is returned.
  • IPCs can initiate reporting of DP status changes, except for certain DPs of SD card status. The IPC SDK updates cached DP status in real time. Therefore, in most cases, valid DP values can be obtained from the cache.
  • To asynchronously query a DP value from a device, the cloud sends NULL to the device. The device initiates reporting the specified DP value for once after it receives NULL. This action is implemented by the IPC manufacturer. If the manufacturer does not implement this action, after NULL is sent, the IPC firmware program will crash. Therefore, before you call this method, make sure the IPC manufacturer has implemented the action to process NULL.

Trigger a data callback

Delegate callback of DP status changes

The protocol ThingSmartCameraDPObserver provides the capability to listen for DP status changes reported by a device. After a DP value is sent, the device also initiates reporting the DP value update for once.

API description

- (void)cameraDPDidUpdate:(ThingSmartCameraDPManager *)manager dps:(NSDictionary *)dpsData;

Parameters

Parameter Description
manager The ThingSmartCameraDPManager object that triggers the callback
dpsData The ID and current value of the updated DP. Format: {dpName: value}.

Example

Objective-C:

- (void)viewDidLoad {
    [super viewDidLoad];
    self.dpManager = [[ThingSmartCameraDPManager alloc] initWithDeviceId:self.devId];
        [self.dpManager addObserver:self];
        self.osdSwitch = [[self.dpManager valueForDP:ThingSmartCameraBasicOSDDPName] boolValue];
}

- (void)openOSD {
    if ([self.dpManager isSupportDP:ThingSmartCameraBasicOSDDPName]) {
        [self.dpManager setValue:@(YES) forDP:ThingSmartCameraBasicOSDDPName success:^(id result) {
              self.osdSwitch = [result boolValue];
        } failure:^(NSError *error) {
                        // A network error.
        }];
    }
}

#pragma mark - ThingSmartCameraDPObserver
- (void)cameraDPDidUpdate:(ThingSmartCameraDPManager *)manager dps:(NSDictionary *)dpsData {
    // The updated DPs contain the DP that enables or disables time watermarks.
    if ([dpsData objectForKey:ThingSmartCameraBasicOSDDPName]) {
        self.osdSwitch = [[dpsData objectForKey:ThingSmartCameraBasicOSDDPName] boolValue];
    }
}

Swift:

override func viewDidLoad() {
    super.viewDidLoad()
    self.dpManager = ThingSmartCameraDPManager(deviceId: self.devId)
    self.dpManager.addObserver(self)
    if self.dpManager.isSupportDP(.basicOSDDPName) {
        self.osdSwitch = self.dpManager.value(forDP: .basicOSDDPName) as! Bool
    }
}

func openOSD() {
    // Checks whether the device supports the specified DP.
    guard self.dpManager.isSupportDP(.basicOSDDPName) else {
        return
    }
    self.dpManager.setValue(true, forDP: .basicOSDDPName, success: { result in
        self.osdSwitch = result as! Bool
    }) { _ in
        // The network error.
    }
}

func cameraDPDidUpdate(_ manager: ThingSmartCameraDPManager!, dps dpsData: [AnyHashable : Any]!) {
    // The updated DPs contain the DP that enables or disables time watermarks.
    if let osdValue = dpsData[ThingSmartCameraDPKey.basicOSDDPName] {
        self.osdSwitch = osdValue as! Bool
    }
}

DP constants

Existing standard DPs of IPCs are defined in ThingSmartCameraDPManager.h in the format of string constants. The type is redefined as ThingSmartCameraDPKey. Each constant name follows the format of ThingSmartCamera+Function+DPName. The following sections describe all DPs that are defined in the IPC SDK.

Basic functions

DP Data type Value range Description
BasicIndicator Boolean YES: on
NO: off
The indicator switch in normal state.
BasicFlip Boolean YES: on
NO: off
The switch of video flipping.
BasicOSD Boolean YES: on
NO: off
The switch of video time watermarks.
BasicPrivate Boolean YES: on
NO: off
The switch of the private mode. With the mode enabled, the specific IPC does not collect audio and video data.
BasicNightvision String 0: auto
1: off
2: on
The switch of the night vision function.

Motion detection alerts

DP Data type Value range Description
BasicPIR String 0: off
1: low sensitivity
2: medium sensitivity
3: high sensitivity
The settings of a passive infrared (PIR) sensor.
MotionDetect Boolean YES: on
NO: off
The switch of motion detection alerts.
MotionSensitivity String 0: low
1: medium
2: high
The sensitivity of motion detection.

Sound detection alerts

DP Data type Value range Description
DecibelDetect Boolean YES: on
NO: off
The switch of sound detection alerts.
DecibelSensitivity String 0: low
1: high
The sensitivity of sound detection.

SD card management

DP Data type Value range Description
SDCardStatus Enum 1: normal
2: error (SD card damage or incorrect format)
3: insufficient space
4: formatting
5: no SD card
The read-only status of an SD card.
SDCardStorage String - The read-only capacity of an SD card.
SDCardFormat Boolean YES: starts formatting. Formats an SD card. This DP can only be sent.
SDCardFormatState Integer -2000: formatting an SD card
-2001: error in formatting an SD card
1100: progress of formatting
The read-only status or progress of formatting an SD card.
SDCardRecord Boolean YES: on
NO: off
The switch of video recording. The video footage is stored on an SD card.
RecordMode String 1: triggered by an event
2: continuous recording
The recording mode of an SD card.

The value of SDCardStorage is a string in which vertical bars | are used to concatenate the total capacity, used capacity, and idle capacity. Unit: KB. For example, 16777216|1048576|15728640 means the total capacity of 16 GB, used capacity of 1 GB, and idle capacity of 15 GB.

PTZ control

DP Data type Value range Description
PTZControl String 0: upward
2: rightward
4: downward
6: leftward
Controls PTZ cameras to rotate in a specified direction. This DP can only be sent.
PTZStop Boolean YES: stops rotation. Stops a PTZ camera from rotation.

Low power

DP Data type Value range Description
WirelessAwake Boolean YES: wakes up.
NO: stays in sleep mode.
Specifies whether a device stays in sleep mode. Only the value YES can be sent to wake up the device.
WirelessPowerMode String 0: powered by a battery
1: connected to mains power
The power supply mode.
WirelessElectricity Integer 1100: the power capacity. The read-only current power capacity in percentage.
WirelessLowpower Integer 1100: the threshold of low power. When the device’s power capacity is lower than the threshold, an alert is triggered.
WirelessBatteryLock Boolean YES: on
NO: off
With this function enabled, a battery cannot be dismantled unless the battery is unlocked.

Enumeration DPs

String enumeration DPs are defined with enumeration string constants in the IPC SDK. The SD card status DP is defined with an enumeration of integers in ThingSmartCameraDPManager.h.

DP Constant type
BasicNightvision ThingSmartCameraNightvision
BasicPIR ThingSmartCameraPIR
MotionSensitivity ThingSmartCameraMotion
DecibelSensitivity ThingSmartCameraDecibel
RecordMode ThingSmartCameraRecordMode
PTZControl ThingSmartCameraPTZDirection
WirelessPowerMode ThingSmartCameraPowerMode
SDCardStatus ThingSmartCameraSDCardStatus