#Docking Guide
<p>[TOC]</p>
<p>> If you need to apply for Kalay APP docking, please contact the business negotiation:</p>
<p>> WeChat public account: ThroughTek
Enterprise website：<a href="https://www.throughtek.cn/">https://www.throughtek.cn/</a>
Feedback email：kalaysz_support@tutk.com</p>
<hr />
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=9e9936e425e4c963f6c03d6a82883b17&amp;file=file.jpg" alt="Kalay2.0 Basic Docking Process" /></p>
<p><strong>Before starting, please make sure the following information be ready:</strong></p>
<ul>
<li>Test UID & certKey</li>
<li>SDK LicenseKey</li>
<li>Standard SDK and Documentation</li>
<li>[IO Command Document](<a href="https://www.showdoc.com.cn/tutkiocmd/8933939875585050">https://www.showdoc.com.cn/tutkiocmd/8933939875585050</a> "IO Command Document")</li>
<li>Device Profile</li>
<li>Kalay2.0_Function Check List</li>
<li>Cloud Recording Coupon Code（if you need to activate the cloud recording function)</li>
<li>KOTA US Test Account（if you need to activare the OTA upgrade function,specify the non-Mainland China area） </li>
<li>KOTA CN Test Account（if you need to activare the OTA upgrade function,specify the Mainland China area ）</li>
<li>KOTA User Manual（if you need to activate the OTA upgrade function)</li>
</ul>
<h1>Important</h1>
<h2>One. About Device Verification</h2>
<h3>1.1 Why do you need to perform device verification？</h3>
<ul>
<li>Device verification refers to a mechanism for presenting device-related functions by generating a corresponding configuration file for a single model of device.</li>
<li>Verified devices indicate that TUTK officially authorizes such devices to use Kalay App; such devices have passed the internal verification test of TUTK, and all functions are activated normally.</li>
</ul>
<p>> Note: It is recommended to add a verification mechanism when the device is connected. Because after the verification mechanism, a device sample image will be presented when adding a device, which simplifies the process of adding a device and presents the corresponding function items, so as to have a better experience.</p>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=30884c5c763cf516e667cfe613f67058" alt="" /></p>
<h3>1.2 Prerequisites for function availability</h3>
<p>> The device Profile is uploaded to the verification server and verified by the TUTK test.</p>
<p><strong>The device needs to be connected to the IO Command Inform the device of CertKey and ProfileVer information.</strong>
IOTYPE_USER_IPCAM_GET_PROFILE_REQ = 0x9014；
IOTYPE_USER_IPCAM_GET_PROFILE_RESP = 0x9015；</p>
<h3>1.3 Design Logic</h3>
<ul>
<li>Customers need to fill in and provide the relevant information of "Kalay2.0_Function Spec Fill In xxx" to confirm the basic information such as device model/related functions.</li>
<li>TUTK generates Device Profile and provides files for local debugging.</li>
<li>The customer completes the docking of the following relevant protocols and provides a test device.</li>
<li>After the TUTK verification function is passed, help upload it to the verification server for official shipment.</li>
</ul>
<h3>1.4 Related IO Command</h3>
<p><strong>IOTYPE_USER_IPCAM_GET_PROFILE_REQ = 0x9014；</strong></p>
<ul>
<li>Send from App to Device</li>
<li>App tells Device to obtain device's certKey and profileVer.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char reserved[8];
}SMsgAVIoctrlGetProfileReq;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_GET_PROFILE_RESP = 0x9015；</strong></p>
<ul>
<li>Send Device to App</li>
<li>Device tells the App the device's certKey and profileVer.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char certKey[40];
unsigned char profileVer[20]; //profile version
unsigned char reserved[8];
} SMsgAVIoctrlGetProfileResp;</code></pre>
<p>> Note: The device can still be added through "Skip Login" or "Other ways to add" without the verification mechanism, but the user will need to manually select which method to use to add the device.</p>
<h2>Two. About the Developer Mode</h2>
<h3>2.1 Open/Exit</h3>
<ul>
<li>Open Developer Mode：Go to the "My" - "About" page, and quickly click the Kalay icon 4 times.</li>
<li>Exit Developer Mode：Based on the enabled state, enter the "My"-"About" page again, and quickly click the Kalay icon 4 times.</li>
</ul>
<h3>2.2 Import Device Profile</h3>
<p>> Prerequisite: Confirm that the App has opened developer mode.</p>
<ul>
<li>
<p>Android Mobile Phone：Enter "File Management"-"Android" folder-"data" folder-"com.tutk.kalay" folder-"files" folder, and then put the Device Profile file;
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=08b4465d9a0e859da6f4c5129cd741a2&amp;file=file.jpg" alt="" /></p>
</li>
<li>
<p>iOS Mobile Phone：Install the "iTools" tool on the PC-Connect to the PC via the data cable-Click "Apps"-Find the folder of the "Kalay" application-Enter the "Documents" folder - "Files" folder, and then put the Device Profile file;
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=b2e59358e3c65a2d0c83932914cbd0f6&amp;file=file.png" alt="" /></p>
</li>
<li>After successfully placing the Device Profile file, restart the APP and add the device for debugging.</li>
</ul>
<h3>2.3 Log Acquisition</h3>
<ul>
<li>
<p>Android Mobile Phone：Enter "File Management"-"Android" folder-"data" folder-"com.tutk.kalay" folder-"files" folder-"Log" folder-find the log corresponding to the time .txt export
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/8be4b3bc88824ea6e9876728bc632c1f" alt="" />
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/ce0c6a6d8ed693609e9cbd6c28674c47" alt="" /></p>
</li>
<li>iOS Mobile Phone：Install the "iTools" tool on the PC-Connect to the PC via the data cable-Click "Apps"-Find the folder of the "Kalay" application-Enter the "Log" folder-Find the log.txt export corresponding to the time
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/64832a454184689b4e6df2f21fd4912c" alt="" /></li>
</ul>
<h3>2.4 Coupon Code Redeem</h3>
<p>> Prerequisite: Confirm that the App has opened developer mode.</p>
<ul>
<li>Enter the Cloud Service Page from the purchase portal — click "I have coupon code" — enter the correct coupon code — click the "Redeem" button — Redeem successful</li>
</ul>
<p>![Coupon Code](<a href="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=9436a790011c08e7e3a37c17afa46476&file=file.png">https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=9436a790011c08e7e3a37c17afa46476&file=file.png</a> "Coupon Code")</p>
<h2>Three. About the Device Scan QRCode adding method</h2>
<h3>3.1 Prerequisites for function availability</h3>
<p>On Kalay2.0, the user needs to log in to the account before using the Device Scan QRCode to add; if the user selects "skip login" to use, this function cannot be enabled.
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/0d3b12c8d9dd694a13cf79daabbeabad" alt="" /></p>
<h3>3.2 Design Logic</h3>
<ul>
<li>The App will establish a connection with the IRIS server and wait for IRIS to send back device information.</li>
<li>The App will generate a QR code for the connection and network distribution information and send it to the device.</li>
<li>After the device is successfully connected to the Internet, upload the relevant information of the device to the IRIS server.</li>
<li>The IRIS server sends the device information back to the App.</li>
<li>The App connects to the device successfully and completes the adding process.
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/f7ce18c6a134a02f838893d0ced6176a" alt="" /></li>
</ul>
<h3>3.3 Sample</h3>
<h4>1）App Side</h4>
<p>QRCode generated by App in the following format:</p>
<p><code>{&quot;r&quot;:&quot;kalayapp-cn&quot;,&quot;s&quot;:&quot;579vca7h8wcj3g2wg1a9&quot;,&quot;ss&quot;:&quot;TUTK-GUEST&quot;,&quot;p&quot;:&quot;hshhs&quot;,&quot;re&quot;:&quot;cn&quot;}</code></p>
<table>
<thead>
<tr>
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Definition</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">r</td>
<td style="text-align: left;">realm</td>
<td style="text-align: left;">This parameter needs to be filled when the device uploads information</td>
</tr>
<tr>
<td style="text-align: left;">s</td>
<td style="text-align: left;">session_id</td>
<td style="text-align: left;">This parameter needs to be filled when the device uploads information</td>
</tr>
<tr>
<td style="text-align: left;">ss</td>
<td style="text-align: left;">wifi ssid</td>
<td style="text-align: left;">Wifi network configured by the device</td>
</tr>
<tr>
<td style="text-align: left;">p</td>
<td style="text-align: left;">wifi password</td>
<td style="text-align: left;">The password for configuring the wifi network of the device</td>
</tr>
<tr>
<td style="text-align: left;">re</td>
<td style="text-align: left;">region</td>
<td style="text-align: left;">Region area, the device should upload device information to the IRIS server in the region. The server addresses in different regions are as follows：<strong>CN-iris domain</strong>：cn-iris-tutk.kalay.net.cn; <strong>US-iris domain</strong>：us-iris-tutk.kalayservice.com</td>
</tr>
</tbody>
</table>
<h4> 2）Device Side</h4>
<p>After the device has decoded the QRCode content, refer to the following steps to complete the adding process:</p>
<ul>
<li>Connect the device to the corresponding wifi.</li>
<li>Upload the device information to the IRIS server.</li>
<li>Start the P2P module.</li>
</ul>
<p>The information uploaded by the device is as follows:</p>
<ul>
<li>url: <a href="https://{iris_server_domainname}/iris/api/v1/prevali/session/{session_id}?realm={realm">https://{iris_server_domainname}/iris/api/v1/prevali/session/{session_id}?realm={realm</a>}</li>
<li>command：post</li>
<li>Parameters carried by application/json:</li>
</ul>
<pre><code class="language-c">{
&quot;state&quot;:{uid}，
&quot;secretData&quot;:{
&quot;udid&quot;:{uid}，
&quot;credential&quot;:{credential}
}
}</code></pre>
<h4>3）For example:</h4>
<ul>
<li>The information issued by the App is as follows:</li>
</ul>
<p><code>{&quot;r&quot;:&quot;kalayapp-cn&quot;,&quot;s&quot;:&quot;579vca7h8wcj3g2wg1a9&quot;,&quot;ss&quot;:&quot;TUTK-GUEST&quot;,&quot;p&quot;:&quot;hshhs&quot;,&quot;re&quot;:&quot;cn&quot;}</code>
</p>
<ul>
<li>The device information is as follows:</li>
</ul>
<pre><code class="language-c">UID：UUUUUUUUUUUUUUUUUUUU,
Authkey：00000000
Av account: admin
Av passwd: 88888888</code></pre>
<ul>
<li>Then the credential after assembly is:</li>
</ul>
<pre><code class="language-c">{
&quot;av&quot;: &quot;88888888&quot;,
&quot;ak&quot;: &quot;00000000&quot;, //If authkey is not used, this field is not required
&quot;identity&quot;: &quot;admin&quot;
}</code></pre>
<ul>
<li>After base64 encoding is：</li>
</ul>
<p><code>ewoJ4oCcYXbigJ06IOKAnDg4ODg4ODg44oCdLAoJ4oCcYWvigJ06IOKAnDAwMDAwMDAw4oCdLAoJ4oCcaWRlbnRpdHnigJ06IOKAnGFkbWlu4oCdCn0=</code>
</p>
<ul>
<li>The final request is:
Post: <a href="https://cn-iris-tutk.kalay.net.cn/iris/api/v1/prevali/session/579vca7h8wcj3g2wg1a9?realm=kalayapp-cn">https://cn-iris-tutk.kalay.net.cn/iris/api/v1/prevali/session/579vca7h8wcj3g2wg1a9?realm=kalayapp-cn</a>
</li>
<li>Parameters carried by application/json:</li>
</ul>
<pre><code class="language-c">{
&quot;state&quot;:&quot;UUUUUUUUUUUUUUUUUUUU&quot;，
&quot;secretData&quot;:{
&quot;udid&quot;:&quot;UUUUUUUUUUUUUUUUUUUU&quot;，
&quot;credential&quot;:&quot;ewoJ4oCcYXbigJ06IOKAnDg4ODg4ODg44oCdLAoJ4oCcYWvigJ06IOKAnDAwMDAwMDAw4oCdLAoJ4oCcaWRlbnRpdHnigJ06IOKAnGFkbWlu4oCdCn0=&quot;
}
}</code></pre>
<p>> Note: Currently IRIS Server is divided into CN and US areas. The device side needs to report device information according to the area specified by the App, otherwise it cannot be added successfully.</p>
<h2>Four. About Cloud Recording Function</h2>
<h3>4.1 Prerequisites for function availability</h3>
<p>> The device needs to use SDK 3.4 or above.</p>
<p><strong>The device needs to be connected to the IO Command to inform whether it supports cloud storage.</strong>
IOTYPE_USER_IPCAM _DEVICE_SUPPORT_CLOUD_REQ = 0x800C；
IOTYPE_USER_IPCAM _DEVICE_SUPPORT_CLOUD _RESP = 0x800D；</p>
<p><strong>The device needs to be connected to the IO Command to obtain and set the device to turn on/off the cloud storage push function.</strong>
IOTYPE_USER_IPCAM_DEVICE_SET_CLOUD_REQ = 0x8010;
IOTYPE_USER_IPCAM_DEVICE_SET_CLOUD_RESP = 0x8011;
IOTYPE_USER_IPCAM_DEVICE_GET_CLOUD_REQ = 0x8012；
IOTYPE_USER_IPCAM_DEVICE_GET_CLOUD_RESP = 0x8013;</p>
<h3>4.2 Design Logic</h3>
<p>APP sends 0x800C to inquire whether the device supports cloud storage function.</p>
<ul>
<li>If the device replies with 0x800D support, the user can purchase cloud services for this device.</li>
<li>If the device responds with 0x800D not supported, the user cannot perform the operation of purchasing cloud services for this device.</li>
</ul>
<p>The APP sends 0x8012 to inquire about the startup status of the cloud storage push function of the device.</p>
<ul>
<li>If the device replies 0x8013 to enable, the device will enable the streaming function to the server.</li>
<li>If the device replies 0x8013 to turn off, the device will turn off the server push function.</li>
</ul>
<p>The APP sends 0x8010, which is used to set the device's cloud storage push function on/off.</p>
<ul>
<li>The device responds with 0x8011, which is used to inform the APP of the setting result.</li>
</ul>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/aad966a768e504191caa19f4145040de" alt="" /></p>
<h3>4.3 Related IO Command</h3>
<p><strong>IOTYPE_USER_IPCAM _DEVICE_SUPPORT_CLOUD_REQ = 0x800C；</strong></p>
<ul>
<li>Send from App to Device</li>
<li>App tells Device to check whether cloud recording is supported</li>
<li>IOCtrl Data:</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char reserved[8];
}SMsgAVIoctrlDeviceSupportCloudReq;</code></pre>
<p><strong>IOTYPE_USER_IPCAM _DEVICE_SUPPORT_CLOUD _RESP = 0x800D；</strong></p>
<ul>
<li>Send Device to App</li>
<li>Device tells the App whether the device supports cloud recording results</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned int result; //0 Not support；1 Support
unsigned char reserved[4];
} SMsgAVIoctrlDeviceSupportCloudResp;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_DEVICE_GET_CLOUD_REQ = 0x8012；</strong></p>
<ul>
<li>Send from App to Device</li>
<li>App gets Device cloud storage recording status.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned int channel; // camera index
unsigned char reserved[4];
}SMsgAVIoctrlGetCloudReq;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_DEVICE_GET_CLOUD_RESP = 0x8013;</strong></p>
<ul>
<li>Send Device to App</li>
<li>Device informs App cloud storage recording status.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned int channel; // camera index
unsigned int isOn; // 1 on, 0 off
}SMsgAVIoctrlGetCloudResp;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_DEVICE_SET_CLOUD_REQ = 0x8010;</strong></p>
<ul>
<li>Send from App to Device</li>
<li>The App tells the Device to turn on or off the cloud storage video recording function.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c"> typedef struct
{
unsigned int channel; // camera index
unsigned int isOn; // 1 on, 0 off
}SMsgAVIoctrlSetCloudReq;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_DEVICE_SET_CLOUD_RESP = 0x8011;</strong></p>
<ul>
<li>Send Device to App</li>
<li>Device tells the App to turn on or off the cloud storage recording results.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned int channel; // camera index
unsigned int result; // 0 successful, 1 fail
}SMsgAVIoctrlSetCloudResp;</code></pre>
<h3>4.4 Sample Code</h3>
<p>> SDK_3.4.0 started：Notify the server to pull the steaming</p>
<pre><code class="language-c">void FakeEventForVsaas(unsigned long timestamp_sec)
{
char att_json_str[2048] = {0};
unsigned long interval_ms = timestamp_sec - gLastVsaasEventTimestamp_sec;
int ret = 0;
NebulaJsonObject *attr_obj = NULL;
if (gIOTCLoginSuccess == -1) {
return;
}
if (gLastVsaasEventTimestamp_sec == 0 || interval_ms &gt; 60) // trigger fake event every 60sec
{
printf(&quot;\t%s() at %lu\n&quot;, __FUNCTION__, timestamp_sec);
if (VSAAS_EVENT_TYPE) {
// meaning the video is playback
sprintf(att_json_str, &quot;{\&quot;starttime\&quot;:\&quot;%lu\&quot;,\&quot;protocol\&quot;:\&quot;tutk\&quot;,\&quot;event_id\&quot;:\&quot;%d\&quot;,\&quot;event_file\&quot;:\&quot;%s\&quot;,\&quot;media_type\&quot;:\&quot;0\&quot;}&quot;, timestamp_sec, VSAAS_EVENT_GENERAL, gRecordFileName);
} else {
// meaning the video is live stream.
sprintf(att_json_str, &quot;{\&quot;starttime\&quot;:\&quot;live\&quot;,\&quot;protocol\&quot;:\&quot;tutk\&quot;,\&quot;event_id\&quot;:\&quot;%d\&quot;,\&quot;media_type\&quot;:\&quot;0\&quot;}&quot;, VSAAS_EVENT_GENERAL);
}
printf(&quot;send avServNotifyCloudRecordStream\n&quot;);
Nebula_Json_Obj_Create_From_String(att_json_str, &amp;attr_obj);
ret = avServNotifyCloudRecordStream(attr_obj, 3000, NULL);
printf(&quot;avServNotifyCloudRecordStream() =%d\n&quot;, ret);
gLastVsaasEventTimestamp_sec = timestamp_sec;
if (ret != AV_ER_NoERROR) {
PrintErrHandling(ret);
return;
}
}
}void FakeEventForVsaas(unsigned long timestamp_sec)
{
char att_json_str[2048] = {0};
unsigned long interval_ms = timestamp_sec - gLastVsaasEventTimestamp_sec;
int ret = 0;
NebulaJsonObject *attr_obj = NULL;
if (gIOTCLoginSuccess == -1) {
return;
}
if (gLastVsaasEventTimestamp_sec == 0 || interval_ms &gt; 60) // trigger fake event every 60sec
{
printf(&quot;\t%s() at %lu\n&quot;, __FUNCTION__, timestamp_sec);
if (VSAAS_EVENT_TYPE) {
// meaning the video is playback
sprintf(att_json_str, &quot;{\&quot;starttime\&quot;:\&quot;%lu\&quot;,\&quot;protocol\&quot;:\&quot;tutk\&quot;,\&quot;event_id\&quot;:\&quot;%d\&quot;,\&quot;event_file\&quot;:\&quot;%s\&quot;,\&quot;media_type\&quot;:\&quot;0\&quot;}&quot;, timestamp_sec, VSAAS_EVENT_GENERAL, gRecordFileName);
} else {
// meaning the video is live stream.
sprintf(att_json_str, &quot;{\&quot;starttime\&quot;:\&quot;live\&quot;,\&quot;protocol\&quot;:\&quot;tutk\&quot;,\&quot;event_id\&quot;:\&quot;%d\&quot;,\&quot;media_type\&quot;:\&quot;0\&quot;}&quot;, VSAAS_EVENT_GENERAL);
}
printf(&quot;send avServNotifyCloudRecordStream\n&quot;);
Nebula_Json_Obj_Create_From_String(att_json_str, &amp;attr_obj);
ret = avServNotifyCloudRecordStream(attr_obj, 3000, NULL);
printf(&quot;avServNotifyCloudRecordStream() =%d\n&quot;, ret);
gLastVsaasEventTimestamp_sec = timestamp_sec;
if (ret != AV_ER_NoERROR) {
PrintErrHandling(ret);
return;
}
}
}</code></pre>
<h2>Five. About KOTA Upgrade</h2>
<h3>5.1 Prerequisites for function availability</h3>
<p><strong>The device needs to be connected to the IO Command to inform whether it supports OTA upgrade.</strong>
IOTYPE_USER_IPCAM _DEVICE_SUPPORT_OTA_REQ = 0x800A；
IOTYPE_USER_IPCAM _DEVICE_SUPPORT_OTA _RESP = 0x800B；</p>
<p><strong>The device needs to be connected to the IO Command to inform the device information.</strong>
IOTYPE_USER_IPCAM_DEVICE_INFO_REQ = 0x8015；
IOTYPE_USER_IPCAM_DEVICE_INFO_RESP = 0x8016；</p>
<p><strong>The device needs to be connected to the IO Command to inform the device of the progress of the OTA upgrade.</strong>
IOTYPE_USER_IPCAM_OTA_REQ = 0x8001；
IOTYPE_USER_IPCAM_OTA_RESP = 0x8002；</p>
<h3>5.2 Design Logic</h3>
<p>APP sends 0x800A to inquire whether the device can support OTA upgrade function.</p>
<ul>
<li>If the device replies with 0x800B support, the APP sends 0x8015 to obtain device information, and according to the 0x8016 reply result, stitches the API request, obtains the download url of the OTA upgrade file from the server and sends it back to the device.</li>
<li>If the device replies with 0x800B not supported, the device cannot perform the OTA upgrade function.</li>
</ul>
<p>The APP sends 0x8001 to transfer the download url of the OTA upgrade file to the device, requesting the device to start the OTA upgrade.</p>
<ul>
<li>The device responds with 0x8002 (per second/time), which is used to inform the APP of the current progress of downloading the upgrade file.</li>
</ul>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/6b4ec535382f8f80ce3f77944887ef93" alt="" /></p>
<h3>5.3 Related IO Command</h3>
<p><strong>IOTYPE_USER_IPCAM _DEVICE_SUPPORT_OTA_REQ = 0x800A；</strong></p>
<ul>
<li>Send from App to Device</li>
<li>App tells Device to obtain whether the device supports OTA.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char reserved[8];
}SMsgAVIoctrlDeviceSupportOTAReq; </code></pre>
<p><strong>IOTYPE_USER_IPCAM _DEVICE_SUPPORT_OTA _RESP = 0x800B；</strong></p>
<ul>
<li>Send Device to App</li>
<li>Device tells the App whether the device supports OTA.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char isSupport; //0 Not support；1 Support
unsigned char reserved[4];
} SMsgAVIoctrlDeviceSupportOTAResp;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_DEVICE_INFO_REQ = 0x8015；</strong></p>
<ul>
<li>Send from App to Device</li>
<li>App tells Device to get device information</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char reserved[8];
} SMsgAVIoctrlDeviceInfoReq; </code></pre>
<p>> Note: It is recommended to use when the new device needs to be connected to the OTA function. It has the same effect as the old cmd IOTYPE_USER_IPCAM_DEVINFO_REQ = 0x0330.</p>
<p><strong>IOTYPE_USER_IPCAM_DEVICE_INFO_RESP = 0x8016；</strong></p>
<ul>
<li>Send Device to App</li>
<li>Device informs App device information.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c"> typedef struct
{
unsigned char model[32]; //Product model
unsigned char product[32]; //Product name
unsigned char vender[32]; //Manufacturer(must be consistent with the vendor on the KOTA server)
unsigned int version; //Current version number
unsigned int free; //SD card remaining space
unsigned int total; //Total space of SD card
unsigned char region; //Get the location of the device,0：Mainland China；1：Non-Mainland China
unsigned char reserved[3];
} SMsgAVIoctrlDeviceInfoResp; </code></pre>
<p>> Note: The above parameters are used to splice the download url request for obtaining the upgrade file from the KOTA server,so they need to be consistent with the information such as vender,product, and mode created on the KOTA server,and pay attention to distinguishing the device area.</p>
<p><strong>IOTYPE_USER_IPCAM_OTA_REQ = 0x8001；</strong></p>
<ul>
<li>Send from App to Device</li>
<li>APP informs Device to start OTA upgrade.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned char file_checksum[32]; //MD5 checksum
unsigned char url[256]; //Download firmware url link
unsigned int file_size; //Firmware package size
unsigned char reserved[4];
}SMsgAVIoctrlOTAReq;</code></pre>
<p><strong>IOTYPE_USER_IPCAM_OTA_RESP = 0x8002；</strong></p>
<ul>
<li>Send Device to App</li>
<li>The Device informs the App of the result of the OTA upgrade.</li>
<li>IOCtrl Data：</li>
</ul>
<pre><code class="language-c">typedef struct
{
unsigned int progress; //Download firmware progress
unsigned int endflag； //1：download completed；0：downloading
unsigned char reserved[8];
}SMsgAVIoctrlOTAResp;</code></pre>
<h2>Six. About Enabling DTLS/Authkey</h2>
<h3>6.1 Why upgrade Authkey and DTLS?</h3>
<ul>
<li>Based on the UID, the device and the APP establish an IOTC connection through the TUTK cloud service.</li>
<li>The normal usage scenarios of IOTC connection are as follows:</li>
</ul>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/d46aa11f0e706bcc988e933694cbab15" alt="" /></p>
<ul>
<li>Malicious users (counterfeit devices) intercept/hijack the APP connection by using the victim's UID.</li>
<li>The concept of vulnerabilities is as follows:</li>
</ul>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/78ca751bb0b453793aee8692d16cc218" alt="" /></p>
<p>> <strong>Authkey: The password for the IOTC connection, which can solve the problem of device fraud when DTLS is not enabled.</strong></p>
<ul>
<li>Establishing an IOTC connection will refer to authkey in addition to UID, and APP will only connect to devices with the correct UID and authkey combination.</li>
<li>The establishment of the connection enables authkey:</li>
</ul>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/69455a13ce4bf09cd47019b1c0340910" alt="" /></p>
<p>> <strong>DTLS: A more secure encryption method, after opening, data transmission is more secure, and can solve the problem of fraudulent use of equipment.</strong>。</p>
<ul>
<li>Enabling DTLS can ensure the security of data packet transmission.</li>
<li>Enable DTLS:</li>
</ul>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/ae03687b6ee310629b365bab45443574" alt="" /></p>
<h3>6.2 How to judge whether the device supports AuthKey / DTLS?</h3>
<ul>
<li>If the device uses the SDK version 3.1.10 or later, which already supports AuthKey / DTLS, it is recommended to immediately enable the implementation of AuthKey / DTLS.</li>
<li>If the SDK version used on the device is lower than 3.1.10 and does not support AuthKey / DTLS, it is recommended to upgrade the SDK version to 3.3.1.0 or 3.4.2.0 and above and enable AuthKey / DTLS.</li>
</ul>
<p>> Note: For security considerations, it is recommended to enable AuthKey / DTLS on the device side.</p>
<h3>6.3 How to enable AuthKey on the device side?</h3>
<ul>
<li>Enable authkey on the device side: use IOTC_Device_LoginEx to log in to the server.</li>
</ul>
<p>> Note: authkey is an 8-bit ascii character and cannot have the '\0' terminator. Therefore, you need to pay attention when copying authkey data (such as strcpy) in certain scenarios.</p>
<h3>6.4 How to enable DTLS on the device side?</h3>
<ul>
<li>Device side: use avServStartEx to establish AV channel, parameter security_mode = AV_SECURITY_DTLS.</li>
<li>If the parameter security_mode = AV_SECURITY_SIMPLE, the SDK uses TUTK private encryption method to encrypt the data. It should be noted that both ends must use the same encryption method to ensure normal data transmission.</li>
</ul>
<h3>6.5 How is Kalay APP compatible with non-AuthKey and AuthKey devices?</h3>
<p><strong>First time connection:</strong>
a. APP use IOTC_Connect_ByUIDEx and bring in the default authkey "00000000"；</p>
<p>b. After the connection is successful, call IOTC_Session_Check_Ex to obtain the value of isUseAuthKey to confirm whether the device supports authkey;</p>
<pre><code> i. If the device does not use authkey (isUseAuthKey=0)：
1. Write down the device authkey related information;
2. Use IOTC_Connect_ByUID_Parallel to connect later.
ii. If the device uses authkey (isUseAuthKey=1)：
1. Write down the device authkey related information;
2. APP use IOTC_Connect_ByUIDEx and bring in the default authkey &quot;00000000&quot;</code></pre>
<p>c. If the connection fails (error code may be -19, -23, -13, -69), the APP switches to use IOTC_Connect_ByUID_Parallel to connect;</p>
<pre><code> i. If the connection fails after switching:
1. Prompt connection failure/device addition failure;
2. Change to &quot;First time connection&quot; to reconnect.
ii. If the connection is successful after switching:
1. Write down the result that the device does not support authkey;
2. Use IOTC_Connect_ByUID_Parallel for subsequent connections;
3. Keep monitoring the result of IOTYPE_USER_IPCAM_OTA_RESP = 0x8002. If the APP detects that the device is undergoing a firmware upgrade, it will change to the &quot;First time connection&quot; method to connect.</code></pre>
<p><strong>Kalay APP and device interaction logic:</strong>
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/fc25eb6e06b4b5be70dcc9b258f0138f" alt="" /></p>
<p><strong>Kalay APP processing logic:</strong>
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/059421d537dcc1283a236c464755e8e9" alt="" /></p>
<h3>6.6 How is Kalay APP compatible with non-DTLS and DTLS devices?</h3>
<p><strong>Connecting device:</strong>
a. The default setting is security_mode = AV_SECURITY_AUTO(2);</p>
<p>b. Check the security_mode recorded locally in the APP;</p>
<pre><code> i. If security_mode = AV_SECURITY_AUTO(2)，it means that it is unknown whether the device supports DTLS:
1. Use the avClientStartEx Input parameter security_mode to set to AV_SECURITY_AUTO (2) to connect;
2. If the connection is successful, judge whether the current connection supports DTLS and record it according to the Output parameter security_mode;
3. If the connection fails (may be caused by the network), it will prompt &quot;connection failed&quot;/&quot;device addition failed&quot;, change security_mode = AV_SECURITY_AUTO (2), and return to step b for the next connection.
ii. If security_mode = AV_SECURITY_SIMPLE (0), it means that DTLS is not supported:
1. Use avClientStartEx Input parameter security_mode to set AV_SECURITY_SIMPLE (0) to connect;
2. If the connection is successful, when the APP receives the device to reply IOTYPE_USER_IPCAM_OTA_RESP = 0x8002 to confirm the result of the upgrade, change security_mode = AV_SECURITY_AUTO (2), and return to step b for the next connection.
3. If the connection fails (may be caused by network reasons, or it may be an unknown upgrade behavior that supports DTLS), change security_mode = AV_SECURITY_AUTO (2), and return to step b for the next connection.
iii. If security_mode = AV_SECURITY_DTLS(1), it means that DTLS is supported:
1. Use the avClientStartEx Input parameter security_mode to be set to AV_SECURITY_DTLS (1) to connect;
2. If the connection is successful, when the APP receives the device to reply IOTYPE_USER_IPCAM_OTA_RESP = 0x8002 to confirm the result of the upgrade, change security_mode = AV_SECURITY_AUTO (2), and return to step b for the next connection.
3. If the connection fails (may be caused by network reasons, or it may be due to unknown degradation behavior that does not support DTLS), change security_mode = AV_SECURITY_AUTO (2), and return to step b for the next connection.</code></pre>
<p>c. Keep the listening device replying IOTYPE_USER_IPCAM_OTA_RESP = 0x8002 to confirm the result of the upgrade. If the APP detects that the device is undergoing a firmware upgrade, change security_mode = AV_SECURITY_AUTO (2), and return to step b.</p>
<p><strong>Remove device:</strong>
a. When the APP removes the device, clear the record.</p>
<p>> Note: In the following two cases, the IOTC_Connect_ByUID_Parallel or IOTC_Connect_ByUIDEx connection will time out and you will not get a special error code:</p>
<ul>
<li>One end uses authkey and one end does not use authkey.</li>
<li>The APP uses the wrong authkey.</li>
</ul>
<p><strong>Kalay APP processing flow:</strong>
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/0b6ae9c6388add2c20bd2bedf22f4e34" alt="" /></p>