Quick Start with IPC SDK for iOS

Tuya IPC SDK for iOS is developed based on Tuya Cube App SDK. Mobile apps have gained popularity in smart device control. However, the increasing number of device categories has become a great challenge for application development. To simplify your development process, the Cube App SDK provides a bunch of extension SDKs. For example, the IPC SDK abstracts useful features from IP cameras (IPCs) and encapsulates APIs for communication with the devices. This SDK saves you a great deal of effort in application development.

This tutorial walks you through a few steps to get started with the IPC SDK and develop a preferred app within one hour. You will learn how to implement the following features:

• Pair an IPC with the app.
• Preview the live video images collected by the IPC.
• Play back video footage stored on an SD card.
• Record the live video images from the IPC by using the app.

You can go to GitHub and download the sample code for the different features mentioned in this tutorial. Then, you can integrate the required sample code into your SDK development on the Tuya Developer Platform.

App SDK Development GitHub Sample

Preview

This tutorial along with specific panel development helps you create the following sample app for iOS.

Preparation

Before you start, the following requirements must be met:

1. An account of the Tuya Developer Platform is registered, an app is built on the platform, and the values of AppKey and AppSecret of the SDK are obtained. For more information, see Preparation.
   The IPC SDK depends on the Cube App SDK. Therefore, you must implement certain features such as creating an app account and adding a home before you can turn IPC features into reality based on the SDK. For more information, see Quick Start with Cube App SDK for iOS.

2. A Tuya-enabled IPC product is created. To get the product, visit TuyaGo.
3. The Smart Home App SDK for iOS and the IPC SDK for iOS are integrated into your project with CocoaPods. For more information, see Fast Integration with IPC SDK for iOS.

Device pairing

Tuya-enabled IPCs support all pairing modes that are enabled by the Cube App SDK, for example, Wi-Fi access point (AP) or hotspot pairing and Bluetooth pairing. Especially, Tuya allows users to scan a QR code to pair an IPC.

Get the token

Similar to the Wi-Fi EZ and AP pairing modes, before the QR code pairing process, the SDK must get a pairing token from the cloud in the networked state.

The token is valid for 10 minutes and expires immediately after the device is paired. A new token must be generated if the device needs to be paired again. To get a token, the current value of homeId must be provided. Therefore, during this process, the account must be in the logged-in state and at least one home is created for the account.

[[ThingSmartActivator sharedInstance] getTokenWithHomeId:homeId
                                                success:^(NSString *token) {
                                            // NSLog(@"getToken success: %@", token);
                                        // you could start ConfigWi-Fi now
                                        } failure:^(NSError *error) {
                                        //NSLog(@"getToken failure: %@", error.localizedDescription);
                                        }
];

Provide compatibility with iOS

iOS 14

Starting from iOS 14, when users perform device pairing or control over a local area network (LAN), the local network privacy setting dialog box is triggered.

• The app can send data to the LAN only after users tap OK.
• Otherwise, if users tap Don’t Allow, the app cannot access the LAN.

Currently, Apple does not provide APIs to process this privacy setting. We recommend that you guide users to allow the app to access LAN data when features that require LAN connection cannot work. Specifically, go to Settings, choose Privacy > Local Network, and then allow the app to access the LAN.

iOS 13

Starting from iOS 13, if users do not allow the app to access location data, when the Wi-Fi feature is enabled, [[ThingSmartActivator sharedInstance] currentWifiSSID] cannot return a valid Wi-Fi service set identifier (SSID) or basic service set identifier (BSSID). In this case, iOS returns the following default values:

• SSID: WLAN or Wi-Fi. WLAN is returned for users in mainland China.
• BSSID: 00:00:00:00:00:00.

Generate a QR code

After you get the pairing token and the SSID and password of the current Wi-Fi network, concatenate them into a string based on the following code block. Then, you can use the string to generate a QR code.

NSDictionary *dictionary = @{
                            @"s": self.ssid,
                            @"p": self.pwd,
                            @"t": self.token
                            };
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:dictionary options:0 error:nil];
self.wifiJsonStr = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];

You must implement QR code generation with your own code or based on the GitHub Sample.

Start pairing

After a QR code is generated, guide users to point it to the IPC. Then, the device will get the QR code information and emit a prompt tone. After the pairing process is started, the SDK continuously broadcasts the pairing data until a device is paired or the process times out.

To call the API method startConfigWiFi, you must provide the SSID of the router, password, and the token obtained from the cloud.

[ThingSmartActivator sharedInstance].delegate = self;
[[ThingSmartActivator sharedInstance] startConfigWiFi:TYActivatorModeQRCode ssid:ssid password:password token:token timeout:100];

Listen for the pairing result

In QR code pairing mode, you must implement the protocol ThingSmartActivatorDelegate and listen for the callback of the pairing result.

@interface xxxViewController () <ThingSmartActivatorDelegate>

- (void)activator:(ThingSmartActivator *)activator didReceiveDevice:(ThingSmartDeviceModel *)deviceModel error:(NSError *)error {
    if (deviceModel && error == nil) {
            //success
            // NSLog(@"connected success: %@", deviceModel.name);
    }

    if (error) {
        //fail
    }

// stop config
}

Stop pairing

To allow users to cancel or complete pairing during the process, you must call the API method stopConfigWiFi.

[ThingSmartActivator sharedInstance].delegate = nil;
[[ThingSmartActivator sharedInstance] stopConfigWi-Fi];

Live video streaming

Tuya IPC SDK for iOS provides basic IPC capabilities, such as live video streaming, playing back footage on an SD card, video screenshot capturing, video recording, and live video talk with IPCs.

Step 1: Initialize an object

You must first initialize a ThingSmartCameraType object. This object is used to read properties and methods from IPCs.

Then, you can use the videoView property of the object to get the video rendered page.

// Initializes the device.
self.device = [ThingSmartDevice deviceWithDeviceId:devId];

// `delegate: ThingSmartCameraDelegate` is used to listen for the peer-to-peer (P2P) connection status.
self.cameraType = [ThingSmartCameraFactory cameraWithP2PType:@(self.device.deviceModel.p2pType) deviceId:self.device.deviceModel.devId delegate:self];

// Initializes the video previewing page.
self.videoView = self.cameraType.videoView;

Step 2: Create a P2P connection

After you initialize the ThingSmartCameraType object, create a P2P connection. The P2P connection status is subject to your maintenance.

To create a P2P connection, you can set the parameter ThingSmartCameraConnectMode to prioritize connections over a local area network (LAN) or the internet. When LAN connections are prioritized, if TCP connections are not created between the app and an IPC over the same LAN, or the IPC does not support prioritized LAN connections, the SDK automatically selects connections over the internet.

• Create a connection

  [self.cameraType connectWithMode:ThingSmartCameraConnectAuto];
  

• Close a connection

  You can call the following API method to close a P2P connection or leave the current page.

  [self.cameraType disConnect];
  

• Listen for the connection status

  To listen for the current connection status, implement the following events of the ThingSmartCameraDelegate delegate.

  - (void)cameraInitFailed:(ThingSmartCameraErrorCode)errorCode {
  // Failed to initialize camera. For more information, see the respective error code.
  }
  - (void)cameraDidConnected:(id<ThingSmartCameraType>)camera {
      //...
  }
  
  // Indicates that a P2P connection is closed. This method is called only in the case of a passive disconnection. For example, the connection is closed in poor network conditions or the IPC stops the connection.
  - (void)cameraDisconnected:(id<ThingSmartCameraType>)camera specificErrorCode:(NSInteger)errorCode {
      //...
  }
  

Step 3: Preview live videos

After you create a P2P connection, you can implement live video streaming.

• Start previewing.

  [self.cameraType startPreview];
  

• Stop previewing.

  [self.cameraType stopPreview];
  

• Listen for the connection status

  - (void)cameraDidBeginPreview:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidStopPreview:(id<ThingSmartCameraType>)camera {
  
  }
  

Video recording and live video talk

During live video streaming, video recording and live video talk are supported. For more information, see Audio and Video Features.

The recorded video footage will be automatically saved to the album of the mobile phone. Therefore, the app must be granted the following permissions:

<key>NSMicrophoneUsageDescription</key>
<string>Authorizes the app to access the microphone of the mobile phone and enables live video talk</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Authorizes the app to access the album of the mobile phone and enables video recording and storage</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Authorizes the app to access the album of the mobile phone and enables video recording and storage</string>

• Start recording or live video talk

  [self.cameraType startTalk];
  [self.cameraType startRecord];
  

• Stop recording or live video talk

  [self.cameraType stopTalk];
  [self.cameraType stopRecord];
  

• Listen for status

  Implement the delegate events to listen for the status of video recording and live video talk.

  - (void)cameraDidBeginTalk:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidStopTalk:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidStartRecord:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidStopRecord:(id<ThingSmartCameraType>)camera {
  
  }
  

Playback of video footage

After video footage is saved to an SD card, it can be played back on the app based on the IPC SDK.

Similar to live video streaming, a P2P connection must be created before video footage playback.

The IPC SDK supports query and playback of video footage by day. Users can also query the dates on which video footage is available in a certain month. The query result is returned by the delegate method of ThingSmartCameraDelegate.

Query a list of video footage

The query result is returned by the delegate method of ThingSmartCameraDelegate.

Step 1: Query the dates on which video footage is available in a certain month

• Make an API request

  [self.cameraType queryRecordDaysWithYear:2021 month:8];
  

• Listen for the callback

  - (void)camera:(id<ThingSmartCameraType>)camera didReceiveRecordDayQueryData:(NSArray<NSNumber *> *)days {
  //   days    The array of dates on which video footage is available. For example, `@[@(1), @(2)]` indicates that video footage is available on the first and second days of the month. An empty array is returned if the request failed.
  }
  

Step 2: Query the video footage stored on a certain date

Users can query the list of video footage on the dates returned in the previous step.

• Make an API request

  [self.cameraType queryRecordTimeSliceWithYear:2021 month:8 day:30];
  

• Listen for the callback

  - (void)camera:(id<ThingSmartCameraType>)camera didReceiveTimeSliceQueryData:(NSArray<NSDictionary *> *)timeSlices {
  //...
  }
  

  The timeSlices field does not return video data. The dictionary stores the start and end time of video footage. The following code block shows the structure of the dictionary:

  @{
      @"kThingSmartPlaybackPeriodStartDate" : NSDate   The start time of video footage.
      @"kThingSmartPlaybackPeriodStopDate" :  NSDate   The end time of video footage.
      @"kThingSmartPlaybackPeriodStartTime" : NSNumber The start Unix timestamp of video footage.
      @"kThingSmartPlaybackPeriodStopTime" :  NSNumber The end Unix timestamp of video footage.
  }
  

Play back video footage

After the target video footage is found, it can be played back.

• Initialize the playback page

  // Initializes the device.
  self.device = [ThingSmartDevice deviceWithDeviceId:devId];
  
  // `delegate: ThingSmartCameraDelegate` is used to listen for the peer-to-peer (P2P) connection status.
  self.cameraType = [ThingSmartCameraFactory cameraWithP2PType:@(self.device.deviceModel.p2pType) deviceId:self.device.deviceModel.devId delegate:self];
  
  // Initializes the video previewing page.
  self.videoView = self.cameraType.videoView;
  

• Starts playback.

  [self.cameraType startPlayback:playTime startTime:startTime stopTime:stopTime];
  

  This method includes the following three timestamp parameters:

  • playTime: the time of the initial frame to be played back. It can be set to the same value as startTime.
  • startTime: the start time of playback. It is the value of kThingSmartPlaybackPeriodStartTime in the returned timeSlices.
  • stopTime: the end time of playback. It is the value of kThingSmartPlaybackPeriodStopTime in the returned timeSlices.

• Pause playback

  [self.cameraType pausePlayback];
  

• Resume playback

  [self.cameraType resumePlayback];
  

• Stop playback

  [self.cameraType stopRecord];
  

• Listen for the callback of ThingSmartCameraDelegate

  - (void)cameraDidBeginPlayback:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidPausePlayback:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidResumePlayback:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraDidStopPlayback:(id<ThingSmartCameraType>)camera {
  
  }
  
  - (void)cameraPlaybackDidFinished:(id<ThingSmartCameraType>)camera {
  
  }
  

  Both pausePlayback and stopPlayback can be used to stop playback. When they are called, these rules must be followed:

  • After stopPlayback is called, resumePlayback cannot be called to resume playback. To resume playback from the time when the playback is last stopped, the timestamp of the last stopped video frame and the duration of the video footage must be saved. This way, the startPlayback method can be called to resume playback.
  • After the dates on which video footage is available are queried, startPlayback can be called to resume playback of a video clip when another video clip is being played back or paused. In this case, you do not need to call stopPlayback to stop the ongoing playback.

Logout

To implement logout, you must make the following request:

[ThingSmartCameraFactory userDidLogOut];

Concepts

The video recording types supported by Tuya-enabled IPCs are classified into continuous recording and event recording.

Continuous recording

The duration of each video clip is 10 minutes and all video clips proceed continuously. If video recording is paused in the middle of the process, a time interval might exist between video clips in continuous recording mode.

If all video clips on a certain date proceed continuously, a video clip is automatically followed by the next video clip during the playback. Therefore, after the playback start method is called with the first time point of the first video clip on that date, the playback will continue until the last video frame on that date. Then, the delegate callback of video playback is executed.

Event recording

The duration of each video clip can be different and the interval between video clips can vary.

The video clips on a certain date can also be interrupted. For example, an interval exists between Clips A and B. In this case, playback is automatically stopped at the last video frame of Clip A.

Next Step

More features are available with the IPC SDK. You can build an app based on the sample project and instructions in the IPC SDK documents.