Merge branch 'feature/persistent-rpc' of https://github.com/Dshcherbyna/thingsboard.github.io

Author: ashvayka

_includes/docs/user-guide/install/config.md

@@ -662,6 +662,18 @@ We will list only main configuration parameters below to avoid duplication of th
          <td>604800</td>
          <td>The parameter to specify TTL(Time To Live) value for Debug Events(DEBUG_CONVERTER, DEBUG_INTEGRATION, DEBUG_RULE_NODE, DEBUG_RULE_CHAIN) records. Value set in seconds. 0 - records are never expired. Default value corresponds to one week.</td>
       </tr>
+      <tr>
+         <td>sql.ttl.rpc.enabled</td>
+         <td>SQL_TTL_RPC_ENABLED</td>
+         <td>true</td>
+         <td>Parameter to enable or disable TTL(Time To Live) for Persistent RPC.</td>
+      </tr>
+      <tr>
+         <td>sql.ttl.rpc.checking_interval</td>
+         <td>SQL_RPC_TTL_CHECKING_INTERVAL</td>
+         <td>7200000</td>
+         <td>Parameter to specify how often TTL(Time To Live) will be checked.</td>
+      </tr>
       <tr>
            <td colspan="4"><span style="font-weight: bold; font-size: 24px;">PostgreSQL database parameters</span></td>
       </tr>  

_includes/docs/user-guide/rpc.md

@@ -82,6 +82,70 @@ This token should belong to either
 
 You can use the following [guide](/docs/{{docsPrefix}}reference/rest-api/#rest-api-auth) to get the token.
 
+## Persistent RPC
+
+Since version 3.3, ThingsBoard provides the new feature: **Persistent RPC**.
+Unlike basic RPC, Persistent RPC has an increased timeout and the command is stored in the database for configurable amount of time.
+Persistent RPC is extremely useful when your device is in power-saving mode. 
+Power-saving mode (or PSM) is when the device temporary is turning off to save the battery energy.
+You can set the PSM in the device profile or device configuration. This feature is available for [CoAP](/docs/{{docsPrefix}}reference/coap-api/) and [LWM2M](/docs/{{docsPrefix}}reference/lwm2m-api/) only.
+After you send an RPC request to this device, the request will be saved in the database for the time you configured and the device will receive the request and send the response when it is turned on again.  
+In addition, every time you send the Persistent RPC, the response will contain RPC ID. Whenever you need to find a specific RPC and view its states and responses, you can do it with that ID through the database.
+
+#### Persistent RPC Configuration
+
+To configure parameters for sending a Persistent RPC request, first, you need to edit the ThingsBoard configuration file:
+
+```
+sudo nano /etc/thingsboard/conf/thingsboard.conf
+```
+{: .copy-code}
+
+Then, add the following lines to the configuration file to add these parameters:
+
+```
+export SQL_TTL_RPC_ENABLED=true
+export SQL_RPC_TTL_CHECKING_INTERVAL=7200000
+```
+{: .copy-code}
+
+Where:
+
+1. **SQL_TTL_RPC_ENABLED** <br>parameter is for configuring whether Persistent RPC data will be removed from the database in case it's outdated.
+
+2. **SQL_RPC_TTL_CHECKING_INTERVAL** <br>parameter is for configuring how often Persistent RPC will be checked whether it's outdated. By default, this parameter is set to two hours (in milliseconds).
+
+The system administrator can configure the default parameter for the tenants through the Tenant Profile. This is **RPC TTL days configuration** parameter.
+Configuring this parameter will change the number of days when RPC will be deleted from the database. See the screenshot below: 
+
+{% include images-gallery.html imageCollection="tenant-profile-rpc" %}
+
+#### RPC Rule chain events 
+
+In the Rule chain, you are able to configure events that will be dispatched every time you send an RPC request: RPC queued, RPC delivered, RPC successful, RPC timeout, RPC failed.
+Configured RPC events reflect [RPC states](/docs/{{docsPrefix}}user-guide/rpc/#rpc-states).
+
+{% include images-gallery.html imageCollection="rule-chain" %}
+
+#### Persistent RPC States
+
+Once you send an RPC, you can observe what exactly happened with the request that you sent in the Rule node events tab. 
+RPC states determine steps that happen when you send RPC request. There are five possible states that can occur when the request is sent:
+
+**QUEUED** - RPC was saved to the database;  
+**DELIVERED** - RPC was delivered to the device (for two-way RPC);  
+**SUCCESSFUL** - if RPC is one-way, SUCCESSFUL means that RPC was delivered to the device. If RPC is two-way, SUCCESSFUL means that we've already received response from the device;  
+**TIMEOUT** - RPC was not delivered to the device;  
+**FAILED** - an error occurred either while sending RPC, or during one of the steps.
+
+#### Usage of Persistent RPC
+
+To send the Persistent RPC through ThingsBoard, you need to add RPC Debug Terminal widget to your dashboard. 
+How to add RPC Debug Terminal and use this widget, you can read [here](/docs/{{docsPrefix}}reference/lwm2m-api/#rpc-commands).
+Then, follow these steps to test the Persistent RPC:
+
+{% include images-gallery.html imageCollection="rpc-test" showListImageTitles="true" %}
+
 ## RPC Rule Nodes
 It is possible to integrate RPC actions into processing workflow. There are 2 Rule Nodes for working with RPC requests. 
 

docs/pe/user-guide/rpc.md

@@ -5,6 +5,35 @@ assignees:
 title: Using RPC capabilities
 description: Remote control of IoT devices from the ThingsBoard IoT cloud using RPC feature
 
+tenant-profile-rpc:
+    0:
+        image: /images/user-guide/persistent-rpc/tenant-rpc-pe.png
+        title: 'Click the orange pencil icon in the upper corner of the screen to enter dashboard edit mode.'
+    1:
+        image: /images/user-guide/persistent-rpc/tenant-rpc-1-pe.png
+        title: 'Set the number of days in the RPC TTL days line. Apply changes by clicking the orange checkmark icon in the upper right corner of the page.'
+
+rule-chain:
+    0:
+        image: /images/user-guide/persistent-rpc/rule-chain-pe.png
+
+rpc-test:
+    0:
+        image: /images/user-guide/persistent-rpc/rpc-test-pe.png
+        title: 'Click the orange pencil icon in the lower corner of the screen to enter dashboard edit mode.'
+    1:
+        image: /images/user-guide/persistent-rpc/rpc-test-1-pe.png
+        title: 'Click the pencil icon in the upper right corner of the RPC debug terminal to enter widget edit mode.'
+    3:
+        image: /images/user-guide/persistent-rpc/rpc-test-2-pe.png
+        title: 'Move to the Advanced tab, increase request timeout of RPC and check the box "RPC request persistent" to enable it. Click the orange checkmark icon in the upper corner of the window to apply the changes.'
+    4:
+        image: /images/user-guide/persistent-rpc/rpc-test-3-pe.png
+        title: 'Click the orange checkmark icon in the lower corner of the screen to save all applied changes.'
+    5:
+        image: /images/user-guide/persistent-rpc/rpc-test-4-pe.png
+        title: 'In the tutorial, we will use the command "test". As you can see, the response contains RPC ID.'
+
 ---
 
 {% assign docsPrefix = "pe/" %}

docs/user-guide/rpc.md

@@ -5,6 +5,35 @@ assignees:
 title: Using RPC capabilities
 description: Remote control of IoT devices from the ThingsBoard IoT cloud using RPC feature
 
+rule-chain:
+    0:
+        image: /images/user-guide/persistent-rpc/rule-chain-ce.png
+
+rpc-test:
+    0:
+        image: /images/user-guide/persistent-rpc/rpc-test-ce.png
+        title: 'Click the orange pencil icon in the lower corner of the screen to enter dashboard edit mode.'
+    1:
+        image: /images/user-guide/persistent-rpc/rpc-test-1-ce.png
+        title: 'Click the pencil icon in the upper right corner of the RPC debug terminal to enter widget edit mode.'
+    3:
+        image: /images/user-guide/persistent-rpc/rpc-test-2-ce.png
+        title: 'Move to the Advanced tab, increase request timeout of RPC and check the box "RPC request persistent" to enable it. Click the orange checkmark icon in the upper corner of the window to apply the changes.'
+    4:
+        image: /images/user-guide/persistent-rpc/rpc-test-3-ce.png
+        title: 'Click the orange checkmark icon in the lower corner of the screen to save all applied changes.'
+    5:
+        image: /images/user-guide/persistent-rpc/rpc-test-4-ce.png
+        title: 'In the tutorial, we will use the command "test". As you can see, the response contains RPC ID.'
+
+tenant-profile-rpc:
+    0:
+        image: /images/user-guide/persistent-rpc/tenant-rpc-ce.png
+        title: 'Click the orange pencil icon in the upper corner of the screen to enter dashboard edit mode.'
+    1:
+        image: /images/user-guide/persistent-rpc/tenant-rpc-1-ce.png
+        title: 'Set the number of days in the RPC TTL days line. Apply changes by clicking the orange checkmark icon in the upper right corner of the page.'
+
 ---
 
 {% include docs/user-guide/rpc.md %}