接入必读

  • 本SDK只包含真机调试的功能,不支持任何模拟器的调试。
  • 适时查看萤石开放平台官网的内容更新,特别是FAQ栏目。尽量多使用FAQ,我们对开发过程中遇到的多次被提问的问题进行汇总,FAQ能解决您90%的问题,可以通过关键字进行搜索。
  • WiFi配置的流程请参考论坛说明 ,注意设备的状态。
  • iOS的demo已经移除了开放平台SDK的静态库和appKey,请将下载的SDK库文件和头文件拷贝到demo工程根目录下的EZOpenSDK文件夹中,并填写官网申请的appKey即可运行代码。

简介

本文档用于说明萤石开放平台SDK iOS版本接口之间的关系以及接口调用顺序,对开放平台SDK iOS版本主要流程都有详细说明和代码示例。主要有功能介绍、安装说明、权限配置和主要流程介绍。

名词解释

名词 注解
appKey AppKey的申请可以参阅: 官网
accessToken 访问令牌,由server返回给client用于认证
expire accessToken过期时间
DeviceSerial 设备序列号
CameraNo 设备通道号
DeviceSerial+CameraNo 摄像头唯一标志
OSD 视频视频当前时间
PTZ 云台控制,可以通过终端控制操作设备

功能介绍

功能 说明
账号对接(授权登录、sdk接口登录) 授权到萤石云平台,复用萤石云平台能力
摄像头列表 得到对应账号下设备
直播预览 直播预览,可设置直播分辨率
查看回放(SD卡、硬盘录像机、云存储) 回放
设备对讲 对讲(包含半双工对讲和全双工对讲)
设备的设置功能 设备设置接口api
设备控制接口(云台、镜头画面) 云台控制
WiFi配置 设备wifi配置
直播、回放边播边录 播放过程中录像
直播、回放边播边截屏 播放过程中截屏
告警消息 告警消息获取

安装SDK

SDK安装分为两种方式cocoapods安装和下载完整SDK包安装

cocoapods安装

cocoapods官网介绍

  1. 在Podfile文件中添加如下语句
    pod 'EZOpenSDK'
    
  2. 执行
    pod install
    
  3. 关闭目标target的bitcode功能 Build Settings->Enable Bitcode设置为NO
  4. 安装完成

下载安装

  1. 下载SDK并解压缩

  2. 创建一个新的XCode工程,然后导入SDK库libEZOpenSDK.a和头文件(如图所示);
    file tree

  3. 导入openssl依赖库libssl.a、libcrypto.a以及相关的头文件(如图所示);
    lib folder

  4. 导入系统依赖库libsqlite3.0、CoreMedia、AudioToolbox、VideoToolbox.framework、GLKit.framework、OpenAL.framework、MobileCoreServices、SystemConfiguration、CoreTelephony、AVFoundation.framework、libc++、libiconv.2.4.0、libbz2、libz(如图所示); list of frameworks

  5. 添加Other Linker Flags -ObjC
    注意区分大小写。
    Other Linker Flags

  6. 关闭目标target的bitcode功能 Build Settings->Enable Bitcode设置为NO
  7. 配置完成

权限配置

权限配置是在工程的info.plist文件中进行配置。在Xcode工程的文件导航栏中找到该文件,右键选择Open As -> Source Code,在合适位子添加对应权限代码。

  1. 相册权限: 如果需要使用开放平台播放器录像和截图并保存的功能,就需要配置相册权限。
    <key>NSPhotoLibraryUsageDescription</key>
    <string>需要使用手机相册</string>
    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>需要使用手机相册</string>
    
  2. 麦克风权限: 如果需要使用设备对讲功能,就需要配置麦克风权限。务必在发起对讲前向iOS系统申请麦克风权限,否则将导致第一次对讲异常。
    <key>NSMicrophoneUsageDescription</key>
    <string>需要使用手机麦克风</string>
    
  3. 摄像头权限: 如果需要仿照demo实现扫码添加设备功能,就需要配置摄像头权限。
    <key>NSCameraUsageDescription</key>
    <string>需要使用手机照相机</string>
    

主要流程

初始化流程

图2

  1. 上图展示初始化SDK并进行授权登录的流程。

  2. 授权登录分为服务端获取accessToken和客户端获取accessToken两种方式。

    • 服务端模式:服务端获取accessToken后下发到客户端,客户端直接调用setAccessToken:接口即完成授权登录;
    • 客户端模式:客户端调用openLoginPage:接口,block中返回的accessToken不为空即完成授权登录。该模式下SDK内部会自动管理accessToken的有效性,会进行自动刷新等操作,可以用isLogin接口判断是否已登录。
  3. 完成授权登录后方可进行关于设备和用户的一系列操作。

    示例代码:

    初始化SDK

    [EZOpenSDK initLibWithAppKey:@"Your App Key"];
    

    授权登录流程 服务端模式:

    [EZOpenSDK setAccessToken:@"Your accessToken"];
    

    客户端模式:

    [EZOpenSDK openLoginPage:^(EZAccessToken * accessToken) {
    
    }];
    

直播流程

步骤

  1. 第一步创建播放器。可调用createPlayerWithDeviceSerial:cameraNo:方法创建播放器。

  2. 第二步配置播放器。播放器创建完成后需要进行设置代理,设置播放视图,验证码设置等配置。

  3. 第三步开始播放。调用startRealPlay开启直播。 示例代码:

    //创建播放器,也可以直接使用EZPlayer类中的方法创建
    EZPlayer *player = [EZOpenSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo];
    
    //可选,建议设置,设置后才可以处理代理方法
    player.delegate = self;
    
    //可选,设备开启了视频/图片加密功能后需设置,可根据EZDeviceInfo的isEncrypt属性判断
    [player setPlayVerifyCode:verifyCode];
    
    //设置用以展示直播画面的视图
    [player setPlayerView:playerView];
    
    //开始直播
    [player startRealPlay];
    

    说明

  4. 可调用setVideoLevel:cameraNo:videoLevel:completion:接口设置视频清晰度,此调节可以在视频播放前设置也可以在视频播放成功后设置。视频播放成功后设置了清晰度,需要先停止播放stopRealPlay,然后重新开启播放startRealPlay才能生效。
  5. 开始播放之后在didReceivedMessageCode:中会收到播放开始的消息;失败会在didPlayFailed:收到错误码,如果是错误码EZ_SDK_NEED_VALIDATECODE = 400035(需要设备验证码)或者EZ_SDK_VALIDATECODE_NOT_MATCH = 400036(设备验证码不匹配),需要开发者自己处理让用户输入验证密码,然后调用setPlayVerifyCode:设置密码,然后重新启动播放。
  6. 同一设备需要开启不同功能(直播/回放/对讲)的播放器时,需要分别对每个功能创建一个播放器。播放器的功能是单一的。

回放流程

步骤

  1. 第一步创建播放器。可调用createPlayerWithDeviceSerial:cameraNo:方法创建播放器。
  2. 第二步配置播放器。播放器创建完成后需要进行设置代理,设置播放视图,验证码设置等配置。
  3. 第三步开始回放。调用startPlaybackFromCloud:或startPlaybackFromDevice开始回放。 示例代码:

    //创建播放器,也可以直接使用EZPlayer类中的方法创建
    EZPlayer *player = [EZOpenSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo];
    
    //可选,建议设置,设置后才可以处理代理方法
    player.delegate = self;
    
    //可选,设备开启了视频/图片加密功能后需设置,可根据EZDeviceInfo的isEncrypt属性判断
    [player setPlayVerifyCode:verifyCode];
    
    //设置用以展示直播画面的视图
    [player setPlayerView:playerView];
    
    //回放云端存储的视频,cloudFile由searchRecordFileFromCloud:cameraNo:beginTime:endTime:completion:接口获取
    [player startPlaybackFromCloud:cloudFile];
    
    //或者
    //回放设备上存储的视频,deviceFile由searchRecordFileFromDevice:cameraNo:beginTime:endTime:completion:接口获取
    [player startPlaybackFromDevice:deviceFile];
    

    说明

  4. 回放需先获取到视频信息,searchRecordFileFromCloud:cameraNo:beginTime:endTime:completion:方法和searchRecordFileFromDevice:cameraNo:beginTime:endTime:completion:方法分别是获取云端视频列表和设备存储视频列表的两个方法。
  5. 开始播放之后在didReceivedMessageCode:中会收到播放开始的消息;失败会在didPlayFailed:收到错误码,如果是错误码EZ_SDK_NEED_VALIDATECODE = 400035(需要设备验证码)或者EZ_SDK_VALIDATECODE_NOT_MATCH = 400036(设备验证码不匹配),需要开发者自己处理让用户输入验证密码,然后调用setPlayVerifyCode:设置密码,重新启动播放。
  6. 同一设备需要开启不同功能(直播/回放/对讲)的播放器时,需要分别对每个功能创建一个播放器。播放器的功能是单一的。

注意:回放结束时存在上报380101错误码的情况,并且播放器不会上报播放结束的消息。此时可调用EZPlayer中的getOSDTime方法获取当前播放时间,用该时间与录像的结束时间进行比较。如果时间点相近则认为播放结束,如果时间点相差较大则为播放错误。从4.8.2版本开始,已在SDK中对种情况进行了自动处理

录像下载流程

步骤

以云存储录像下载为例:
  1. 第一步创建下载任务。可调用EZCloudRecordDownloadTask的initTaskWithID:cloudRecordFile:verifyCode:savePath方法创建下载任务。
  2. 第二步设置回调函数。setDownloadCallBackWithFinshed:failed:方法设置回调。
  3. 第三步加入下载队列。加入下载队列后开始下载。 示例代码:
    //1.创建下载任务
    EZCloudRecordDownloadTask *task = [[EZCloudRecordDownloadTask alloc] initTaskWithID:@"2" cloudRecordFile:cloudFile verifyCode:self.verifyCode savePath:path];

    //2.设置回调函数
    __weak typeof(task) weakTask = task;
    [task setDownloadCallBackWithFinshed:^(EZRecordDownloaderStatus statusCode) {

        __strong typeof(weakTask) strongTask = weakTask;
        NSLog(@"statuCode:%ld", (long)statusCode);

        switch (statusCode) {
            case EZRecordDownloaderStatusFinish:
                //do something

                break;
            case EZRecordDownloaderStatusMoreToken:
                //do something

                break;
            default:

                break;
        }
        [[EZRecordDownloader shareInstane] stopDownloadTask:strongTask];

    } failed:^(NSError * _Nonnull error) {

        NSLog(@"EZDeviceRecordDownloader error:%@", error);
        __strong typeof(weakTask) strongTask = weakTask;

       //do something        
        [[EZRecordDownloader shareInstane] stopDownloadTask:strongTask];
    }];

        //3.加入下载队列下载
    [[EZRecordDownloader shareInstane] addDownloadTask:task];

说明

  1. 设备录像下载流程基本相同,但由于底层实现不同,创建任务方法为异步执行,其余操作需要在其回调中进行。
  2. 设备录像并发下载受设备路数限制,可通过错误码395416和380045判断。

对讲流程

步骤

  1. 第一步创建播放器。可调用createPlayerWithDeviceSerial:cameraNo:方法创建播放器。
  2. 第二步配置播放器。播放器创建完成后需要进行设置代理,验证码设置等配置。
  3. 第三步开始播放。调用startVoiceTalk开启对讲。 示例代码:

    //创建播放器,也可以直接使用EZPlayer类中的方法创建
    EZPlayer  *talkPlayer = [EZOpenSDK createPlayerWithDeviceSerial:deviceSerial cameraNo:cameraNo];
    
    //可选,建议设置,设置后才可以处理代理方法
    talkPlayer.delegate = self;
    
    //可选,设备开启了视频/图片加密功能后需设置,可根据EZDeviceInfo的isEncrypt属性判断
    [talkPlayer setPlayVerifyCode:verifyCode];
    
    //发起对讲
    [talkPlayer startVoiceTalk];
    
    //停止对讲
    [talkPlayer stopVoiceTalk];
    

半双工对讲在发起对讲成功后,默认模式为 手机端听-设备端说。可进行如下操作进行听说模式切换。

  //切换到 手机端说-设备端听 模式
  [talkPlayer audioTalkPressed:YES];

  //切换到 手机端听-设备端说 模式
  [talkPlayer audioTalkPressed:NO];

说明

  1. 对讲流程需要根据设备的对讲能力进行区分处理。EZDeviceInfo中的isSupportTalk可获取到设备的对讲能力,0-不支持对讲,1-支持全双工对讲,3-支持半双工对讲。
  2. 同一设备需要开启不同功能(直播/回放/对讲)的播放器时,需要分别对每个功能创建一个播放器。播放器的功能是单一的。

设备添加流程

步骤

  1. 第一步查询设备信息。查询设备信息probeDeviceInfo:deviceType:completion:接口所获得对象是EZProbeDeviceInfo,正常查询到设备信息对象说明查询成功,可以直接进行设备添加操作。

  2. 第二步配置设备网络。调用startConfigWifi:password:deviceSerial:deviceStatus:进行网络配置。startConfigWifi:password:deviceSerial:deviceStatus:和stopConfigWifi需要成对调用,EZWifiConfigStatus的内容通过回调的block获取,详见demo。

    DEVICE_WIFI_CONNECTING = 1,   //设备正在连接WiFi
    DEVICE_WIFI_CONNECTED = 2,    //设备连接WiFi成功
    DEVICE_PLATFORM_REGISTED = 3, //设备注册平台成功
    DEVICE_ACCOUNT_BINDED = 4     //设备已经绑定帐户
    
  3. 第三步添加设备到当前帐号中。调用addDevice:deviceSerial:verifyCode:completion:接口进行设备添加。当状态为DEVICE_PLATFORM_REGISTED时方可添加成功。注意:DEVICE_WIFI_CONNECTED和DEVICE_PLATFORM_REGISTED状态上报可能会丢失,此时可在适当时机查询设备当前的状态,根据设备状态进行后续操作,详见demo中示例代码。重置设备再次添加时,某些设备DEVICE_ACCOUNT_BINDED状态返回出现异常,所以不建议根据DEVICE_ACCOUNT_BINDED判定设备是否已绑定。设备是否已绑定帐户以服务端查到的状态为准。

    说明

    4.8.3版本中新增配网接口:startConfigWifi:password:deviceSerial:mode:deviceStatus:。该接口通过设置mode参数可使用不同的配网方式,包括原有配网方式和新增的声波配网方式。如果使用声波配网方式,设备端也需支持声波配网功能。支持声波配网的设备见附录。同时该接口支持批量配网,deviceSerial设置为空即可实现批量配网。详见demo。

  4. 支持AP配网的设备可使用AP配网模式。根据EZProbeDeviceInfo信息可获知设备支持的配网方式,但由于旧设备在系统中可能查询不到,故也可以采用观察设备指示灯闪烁方式判断设备当前的配网模式。

  5. 红蓝闪烁为普通的配网方式,蓝灯闪烁为AP配网方式。
  6. AP配网需要将手机连接设备发出的Wi-Fi信号,然后调用EZWiFiConfigManager类中的startAPWifiConfigWithWifiName:wifiPwd:deviceSerial:verifyCode:reuslt:将可连接互联网的Wi-Fi信息发送给设备。设备在接收到Wi-Fi信息后,会关闭AP模式,尝试连接Wi-Fi。

    特别说明: 账户下删除设备重新进行wifi配置并且添加时,请在重置设备等待2分钟以后再调用wifi配置的相关接口可以提高wifi配置的成功率,否则会降低成功率,因为重置设备以后我们平台将在2分钟内得到设备下线的状态,只有平台认为下线了,wifi配置成功率才会高。

    示例代码:

  7. 查询设备状态

    [EZOpenSDK probeDeviceInfo:deviceSerial
                deviceType:deviceType
                completion:^(EZProbeDeviceInfo * deviceInfo, NSError * error) {
                    if (error)
                    {
                        if (error.code == EZ_HTTPS_DEVICE_ADDED_MYSELF)
                        {
                            //已添加过此设备
                        }
                        else if (error.code == EZ_HTTPS_DEVICE_ONLINE_IS_ADDED)
                        {
                            //此设备已被别人添加
                        }
                        else if (error.code == EZ_HTTPS_DEVICE_OFFLINE_NOT_ADDED ||
                                 error.code == EZ_HTTPS_DEVICE_NOT_EXISTS ||
                                 error.code == EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED ||
                                 error.code == EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED_MYSELF)
                        {
                            //设备不在线,需连接网络
                            if (deviceInfo)
                            {
                               //根据设备能力选择合适的配网方式
                               deviceInfo.supportWifi == 3;      //支持smartConfig配网
                               deviceInfo.supportSoundWave == 1; //支持声波配网
                               deviceInfo.supportAP == 2;        //支持AP配网
                            }
                            else
                            {
                               //根据设备闪灯情况选择合适的配网方式
                            }
                        }
                        else
                        {
                            //查询失败,网络不给力,可进行重试
                        }
                      }
                      else
                      {
                          //设备已在线,可进行添加
                      }
                }];
    
  8. 配置设备网络

    [EZOpenSDK startConfigWifi:WiFiSsid
                  password:WiFPassword
              deviceSerial:deviceSerial
                      mode:EZWiFiConfigSmart | EZWiFiConfigWave
              deviceStatus:^(EZWifiConfigStatus status, NSString * deviceSerial) {
                  if (status == DEVICE_WIFI_CONNECTING)
                  {
                      //设备正在连接WiFi
                  }
                  else if (status == DEVICE_WIFI_CONNECTED)
                  {
                      //设备连接WiFi成功
                  }
                  else if (status == DEVICE_PLATFORM_REGISTED)
                  {
                      //设备注册平台成功,可进行添加流程
                  }
              }];
    
  9. 配置设备网络过程中DEVICE_WIFI_CONNECTED和DEVICE_PLATFORM_REGISTED状态上报可能会丢失,此时可在适当时机调用步骤1中的接口,查询设备当前状态,根据设备状态进行后续操作。

  10. AP配网示例代码

    [EZOpenSDK startAPConfigWifiWithSsid:self.ssid
                            password:self.password
                        deviceSerial:[GlobalKit shareKit].deviceSerialNo
                          verifyCode:[GlobalKit shareKit].deviceVerifyCode
                              result:^(BOOL ret) {
                                    if (ret)
                                    {
                                        //配置成功
                                    }
                                    else
                                    {
                                        //配置失败
                                    }
                                    //停止AP配网
                                    [EZOpenSDK stopAPConfigWifi];
                                }];
    
  11. 全新或重置过的海康设备在添加之前需进行激活,萤石设备则不需激活。激活之前需将设备和手机连入同一个局域网,再使用对应接口进行激活,流程如下:

    //初始化模块
    [EZHCNetDeviceSDK initSDK];
    
    //局域网搜索设备
    [EZHCNetDeviceSDK startLocalSearch:^(EZSADPDeviceInfo * device, NSError * error) {
    
    }];
    
    //可根据EZSADPDeviceInfo对象中的actived属性判断设备是否已经激活
    //激活设备,此处device为EZSADPDeviceInfo对象,pwd为需设定的设备密码,密码为8-16位的字符
    [EZHCNetDeviceSDK activeDeviceWithSerial:device.deviceSerial pwd:pwd];
    
  12. 添加设备到当前帐号

    [EZOpenSDK addDevice:deviceSerial
          verifyCode:deviceVerifyCode
          completion:^(NSError * error) {
    
          }];
    

    详细使用方法见demo。

附录:

声波配网仅支持以下设备类型及对应最低版本,仅供参考

设备型号 设备具体 版本号 声波配置
C2C CS-C2C-1B2WFR V5.1.2 build 180313 支持
C6P CS-C6P-7A3WFR V5.3.2 build 180117 支持
C2HC CS-C2HC-3B2WFR V5.2.4 build 180125 支持
C3W CS-C3W-3B1WFR V5.2.4 build 180131 支持
C5S CS-C5S-1B2WFR V5.2.4 build 180129 支持
C5Si CS-C5Si-3C2WFR V5.2.4 build 180307 支持
C6H CS-C6H-3B1WFR V5.2.4 build 180129 支持
C6C CS-C6C-3B2WFR V5.2.4 build 180129 支持
C6HC CS-C6HC-3B2WFR V5.2.4 build 180129 支持

目前支持AP配网的设备型号如下:

国内型号 海外型号
CS-C4Wi-3C2WFR HSFLC1(VOXX定制型号)
CS-C4Wi-3C2EFR HSDB2(VOXX定制型号)
CS-C4W-3C2WFR CS-CV206-C0-3B2WFR-KJDS)
CS-C3A-1C2WPMFBR CS-CV206-C0-1A1WFR-KJDS
CS-CV310-A0-3B1WFR-KJDS
CS-CV310-A0-1B2WFR-KJDS
CS-CV246-B0-3B2WFR-KJDS

results matching ""

    No results matching ""