IPC Control (iOS)

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.

- (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.

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 1–100: 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	1–100: the power capacity.	The read-only current power capacity in percentage.
WirelessLowpower	Integer	1–100: 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