PTZ Control

Last Updated on : 2023-06-01 06:18:36download

Pan-tilt-zoom (PTZ) is one of the important data points (DPs) of IP cameras (IPCs) and is widely used in IPC scenarios. The integration of PTZ is lacking in the business encapsulation as vertical resources. To speed up the integration of PTZ, Tuya provides the encapsulation of PTZ features.

PTZ management class

The following PTZ features are supported:

  • PTZ control
  • Focal length adjustment
  • Site favorites
  • Auto-patrol mode
  • Motion tracking
  • Preset points

All these PTZ features are managed by the PTZ management class IThingIPCPTZ. To implement diverse PTZ DPs, required API methods are encapsulated in IThingIPCPTZ.

Get the PTZ management class

Example

IThingIPCPTZ thingIPCPTZ = ThingIPCSdk.getPTZInstance(mDevId)

Register a PTZ listener

API description

void addPTZListener(@NonNull IThingIPCPTZListener listener);

Request parameter

Parameter Description
listener The PTZ listener.

IThingIPCPTZListener

The PTZ listener is registered to listen for PTZ DP updates. The listener is described in the following table.

API name Parameter Return value Description
onPTZDeviceDpUpdate dpCode void The callback of PTZ DP updates. You call the API method getCurrentValue to query current DP data by dpCode.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.addPTZListener(new IThingIPCPTZListener() {
        @Override
        public void onPTZDeviceDpUpdate(String dpCode) {

        }
    });
}

Remove a PTZ listener

Removes a PTZ listener. We recommend that you remove the listener when the page is destroyed. Otherwise, a memory leak might occur.

API description

void removePTZListener(@NonNull IThingIPCPTZListener listener);

Request parameter

Parameter Description
listener The PTZ listener to be removed.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.removePTZListener(listener);
}

PTZ DP encapsulation

PTZ DPs are further encapsulated based on the API methods for device management and device control to implement different PTZ features. For more information about the concept of DPs, see Device Control (Android).

Query DP status

Checks whether a specific IPC DP is supported and whether the UI of the DP is displayed.

API description

boolean querySupportByDPCode(String dpCode);

Request parameter

Parameter Description
dpCode The identifier of the DP.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.querySupportByDPCode("motion_tracking");
}

Query DP data

Returns current DP data including the return value object. For example, to return a Boolean value, the tClass parameter is set to Boolean.class. The return value is of the Boolean object type. The same rules apply to other types of data. If the DP is not supported, a null value is returned.

API description

<T> T getCurrentValue(String dpCode, @NonNull Class<T> tClass);

Request parameter

Parameter Description
dpCode The identifier of the DP.
tClass The DP value object. Example: Boolean.class, Integer.class, String.class, and JSONBean.class.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.getCurrentValue("motion_tracking", Boolean.class);
}

Query data from an IPC

Returns current DP data that is not actively reported. The listener IThingIPCPTZListener returns the query result.

API description

void getCurrentValueFromDevice(String dpCode);

Request parameter

Parameter Description
dpCode The identifier of the DP.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.getCurrentValueFromDevice("cruise_status");
}

Query DP properties

Returns DP properties. For example, the API method can be used to return properties of Enum DPs. If the DP is not supported, a null value is returned.

API description

<T> T getSchemaProperty(String dpCode, @NonNull Class<T> tClass);

Request parameter

Parameter Description
dpCode The identifier of the DP.
tClass The DP property object. Example: com.tuya.smart.android.device.bean.EnumSchemaExBean.class, com.thingclips.smart.android.device.bean.ValueSchemaBean.class, and String.class.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.getSchemaProperty("ptz_control", EnumSchemaBean.class);
}

Send DPs

Sends DPs to an IPC to change the device status or features and control the device.

API description

void publishDps(@NonNull String dpCode, @NonNull Object value, IResultCallback callback);

Request parameter

Parameter Description
dpCode The identifier of the DP.
value The object of the new DP value.
callback The callback.

IResultCallback

API name Parameter Return value Description
onSuccess void void The success callback.
onError String, String void The error code and error message.

The onSuccess() callback can be executed to process the logic of a successful call. For example, in the callback, the getCurrentValue API method can be used to get the latest DP data and update the UI.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.publishDps("ptz_stop", true, new IResultCallback() {
        @Override
        public void onError(String code, String error) {

        }

        @Override
        public void onSuccess() {

        }
    });
}

Report DP data

The listener IThingIPCPTZListener notifies DP changes when the DP that can be reported is changed. DP changes include but are not limited to:

  1. An IPC is controlled by a client other than the client that receives the DP changes.
  2. DPs are sent.
  3. Query data from an IPC

PTZ control

DP name Identifier Data transfer type Data type DP property Remarks
PTZ Direction ptz_control Send and report (rw) Enum Enum values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 direction: the direction. Valid values:
  • 0: up
  • 1: upper right
  • 2: right
  • 3: lower right
  • 4: down
  • 5: lower left
  • 6: left
  • 7: upper left
  • 8: rotate to the limit
  • 9: calibrating the PTZ, please wait.
PTZ Stop ptz_stop Send and report (rw) Bool -
  • true: stop
  • false: not stop

PTZ control is implemented with these DPs. For more information, see PTZ DP encapsulation.

Zoom control

DP name Identifier Data transfer type Data type DP property Remarks
Zoom Control zoom_control Send and report (rw) Enum Enum values: 0 and 1 Mechanical zoom. Valid values:
  • 0: zoom in
  • 1: zoom out
Stop Zoom zoom_stop Send and report (rw) Bool true: stop zoom

Zoom control is implemented with these DPs. For more information, see PTZ DP encapsulation.

Site favorites

DP name Identifier Data transfer type Data type
Site Favorites memory_point_set Send and report (rw) String

Site favorites are implemented with these DPs.

Get a list of site favorites

API description

void requestCollectionPointList(IThingResultCallback<List<CollectionPointBean>> callback);

Request parameter

Parameter Description
callback
  • The success callback
  • The failure callback. The error code and error message are returned.

CollectionPointBean

Parameter Description
id The ID of a site favorite.
devId The device ID.
pos The location information of a preset point.
name The name of a preset point.
pic The address of an image.
mpId The unique ID of a device. The device generates the value.
encryption The map that stores the image decryption key. The value is a JSON string.

For more information about displaying encrypted images of site favorites, see DecryptImageView.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.requestCollectionPointList(new IThingResultCallback<List<CollectionPointBean>>() {
        @Override
        public void onSuccess(List<CollectionPointBean> result) {

        }

        @Override
        public void onError(String errorCode, String errorMessage) {

        }
    });
}

Add a site favorite

Adds a site favorite. This API method is not recommended for panoramic auto-patrol and site favorite auto-patrol. Otherwise, the failure callback will be executed and the error code -2001 will be returned.

API description

void addCollectionPoint(@NonNull String name, IResultCallback callback);

Request parameter

Parameter Description
name The custom name of the site favorite.
callback The callback.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.addCollectionPoint("name", new IResultCallback() {
        @Override
        public void onError(String code, String error) {

        }

        @Override
        public void onSuccess() {

        }
    });
}

Modify a site favorite

API description

void modifyCollectionPoint(@NonNull CollectionPointBean pointBean, @NonNull String name, IResultCallback callback);

Request parameter

Parameter Description
pointBean The bean of the site favorite to be modified.
name The new name.
callback The callback.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.modifyCollectionPoint(collectionPointBean, "NewTitle", new IResultCallback() {
        @Override
        public void onError(String code, String error) {
        }

        @Override
        public void onSuccess() {
        }
    });
}

Delete site favorites

API description

void deleteCollectionPoints(@NonNull List<CollectionPointBean> points, IResultCallback callback);

Request parameter

Parameter Description
points The collection of site favorites to be deleted.
callback The callback.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.deleteCollectionPoints(points, new IResultCallback() {
        @Override
        public void onError(String code, String error) {

        }

        @Override
        public void onSuccess() {

        }
    });
}

Preview a site favorite

API description

void viewCollectionPoint(@NonNull CollectionPointBean collectionPointBean, IResultCallback callback);

Request parameter

Parameter Description
collectionPointBean The site favorite to be previewed.
callback The callback.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.viewCollectionPoint(collectionPointBean, new IResultCallback() {
        @Override
        public void onError(String code, String error) {

        }

        @Override
        public void onSuccess() {

        }
    });
}

Auto-patrol mode

DP name Identifier Data transfer type Data type DP property The remarks.
Auto-patrol Switch cruise_switch Send and report (rw) Bool - -
Auto-patrol Mode cruise_mode Send and report (rw) Enum Enum values: 0 and 1 0: panoramic auto-patrol
1: site favorite auto-patrol
Auto-patrol Status cruise_status Send and report (rw) Enum Enum values: 0, 1, and 2 0: panoramic auto-patrol
1: site favorite auto-patrol
2: non-auto-patrol mode
Auto-patrol Schedule Setting cruise_time_mode Send and report (rw) Enum Enum values: 0 and 1 0: all-day auto-patrol
1: custom auto-patrol
Auto-patrol Schedule cruise_time Send and report (rw) String Data format:
t_start: start time
t_end: end time
Multiple time values are separated with semicolons (;).

Auto-patrol is implemented with these DPs. Individual API methods are available to implement the Auto-patrol Mode and Auto-patrol Schedule Setting DPs. For more information about other DPs, see PTZ DP encapsulation.

The Auto-patrol Status DP (cruise_status) is not actively reported. To get the DP data, call the API method getCurrentValueFromDevice. Other PTZ DPs are standard DPs. You can call the API method getCurrentValue to get the current values of these standard DPs.

Set the auto-patrol mode

Sets the auto-patrol mode. The DP identifier is cruise_mode. During the setting of site favorite auto-patrol, if the number of site favorites is less than2, the error code -2002 will be returned.

API description

void setCruiseMode(String mode, IResultCallback callback);

Request parameter

Parameter Description
mode The auto-patrol mode. Valid values:
0: panoramic auto-patrol
1: site favorite auto-patrol
callback The callback.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.setCruiseMode("0", new IResultCallback() {
        @Override
        public void onError(String code, String error) {
        }

        @Override
        public void onSuccess() {

        }
    });
}

Set the auto-patrol schedule

Sets the auto-patrol mode. The DPs cruise_time_mode and cruise_time are used. To set an auto-patrol schedule, use cruise_time_mode to enable the auto-patrol schedule and then use cruise_time to set the scheduled time.

API description

void setCruiseTiming(@NonNull String startTime, @NonNull String endTime, IResultCallback callback);

Request parameter

Parameter Description
startTime The start time. Format: 00:00.
endTime The end time. Format: 00:00.
callback The callback.

Example

if (thingIPCPTZ != null) {
    thingIPCPTZ.setCruiseTiming("08:00", "10:00", new IResultCallback() {
        @Override
        public void onError(String code, String error) {

        }

        @Override
        public void onSuccess() {

        }
    });
}

Motion tracking

DP name Identifier Data transfer type Data type
Motion Tracking Switch motion_tracking Send and report (rw) Boolean

Motion Tracking Switch is implemented with these DPs. For more information, see PTZ DP encapsulation.

Preset points

DP name Identifier Data transfer type Data type DP property The remarks.
Set Preset Point ipc_preset_set Send and report (rw) Enum Enum values: 1, 2, 3, and 4 Preset points 1, 2, 3, and 4

Preset points are implemented with these DPs. For more information, see PTZ DP encapsulation.

Error codes

The following table shows the error codes of PTZ features.

Error codes Description
-1431 Site favorites cannot be added during panoramic auto-patrol and site favorite auto-patrol.
-1432 The number of site favorites is less than 2 so that site favorite auto-patrol cannot be enabled.