|
| 1 | +--- |
| 2 | +layout: docwithnav |
| 3 | +title: Custom Integration |
| 4 | +description: Custom integration guide |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +{% assign feature = "Platform Integrations" %}{% include templates/pe-feature-banner.md %} |
| 9 | + |
| 10 | +* TOC |
| 11 | +{:toc} |
| 12 | + |
| 13 | +### Introduction |
| 14 | + |
| 15 | +Custom integration is **only executed remotely** from the main ThingsBoard instance. It allows to create integration with custom configuration |
| 16 | +that will use any transport protocol for communication with your devices. |
| 17 | + |
| 18 | +This guide contains step-by-step instructions on how to create and launch ThingsBoard custom integration. |
| 19 | +For example, we will launch custom integration that uses TCP transport protocol to stream data from devices and pushes the converted data to |
| 20 | +[cloud.thingsboard.io](https://cloud.thingsboard.io/signup). |
| 21 | + |
| 22 | +Before we start, you can find the full code of custom integration example that we will use in this guide [here](https://github.com/thingsboard/remote-integration-example). |
| 23 | + |
| 24 | +### Prerequisites |
| 25 | + |
| 26 | +We assume you already have a tenant administrator account on your own ThingsBoard PE v2.4.1+ instance or cloud.thingsboard.io. |
| 27 | + |
| 28 | +Let’s assume that we have a sensor which is sending current temperature, humidity and battery level readings respectively in the following format: **“25,40,94”**. |
| 29 | + |
| 30 | +### Uplink and Downlink Converters |
| 31 | + |
| 32 | +Before setting up a custom integration, you need to create an Uplink and a Downlink converters. |
| 33 | + |
| 34 | +#### Uplink Converter |
| 35 | + |
| 36 | +Let's create uplink converter. |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +**NOTE**: Although the Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode may tremendously increase the disk space, used by the database, because all the debugging data is stored there. |
| 41 | +It is highly recommended to turn the Debug mode off when done debugging. |
| 42 | + |
| 43 | +See the following script that is pasted to the Decoder function section: |
| 44 | + |
| 45 | +```javascript |
| 46 | +/** Decoder **/ |
| 47 | + |
| 48 | +// decode payload to string |
| 49 | +var decodedString = decodeToString(payload); |
| 50 | +// remove unnecessary [\"] and split by [,] to get an array |
| 51 | +var payloadArray = decodedString.replace(/\"/g, "").split(','); |
| 52 | +var result = { |
| 53 | + deviceName: "Device A", |
| 54 | + deviceType: "type", |
| 55 | + telemetry: { |
| 56 | + // get each reading from the array and convert the string value to a number |
| 57 | + temperature: Number(payloadArray[0]), |
| 58 | + humidity: Number(payloadArray[1]), |
| 59 | + batteryLevel: Number(payloadArray[2]) |
| 60 | + }, |
| 61 | + attributes: {} |
| 62 | +}; |
| 63 | + |
| 64 | +/** Helper functions **/ |
| 65 | + |
| 66 | +function decodeToString(payload) { |
| 67 | + return String.fromCharCode.apply(String, payload); |
| 68 | +} |
| 69 | + |
| 70 | +function decodeToJson(payload) { |
| 71 | + // convert payload to string. |
| 72 | + var str = decodeToString(payload); |
| 73 | + |
| 74 | + // parse string to JSON |
| 75 | + var data = JSON.parse(str); |
| 76 | + return data; |
| 77 | +} |
| 78 | + |
| 79 | +return result; |
| 80 | +``` |
| 81 | + |
| 82 | +The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. |
| 83 | +**deviceName** and **deviceType** are required, while **attributes** and **telemetry** are optional. |
| 84 | +**Attributes** and **telemetry** are flat key-value objects. Nested objects are not supported. |
| 85 | + |
| 86 | +#### Downlink Converter |
| 87 | + |
| 88 | +We will not use the Downlink converter in this guide so there is no need to create one. |
| 89 | +In case you have another use case, please refer to the following [instructions](/docs/user-guide/integrations/#downlink-data-converter). |
| 90 | + |
| 91 | +### Custom Integration Setup |
| 92 | + |
| 93 | +Let's create custom integration. |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | +Notice that **Execute remotely** is enabled automatically when we choose **Custom** type and we enable **Debug mode**. |
| 98 | + |
| 99 | +**Integration class** is used to create an instance of the integration using the Java reflective method. |
| 100 | + |
| 101 | +The **Integration JSON configuration** is the custom configuration that has two fields in our case: |
| 102 | +- **port**, which will be used to bind the TCP server-client communication |
| 103 | +- **msgGenerationIntervalMs**, the interval between generating the messages |
| 104 | + |
| 105 | +We will get back to this later in this guide. |
| 106 | + |
| 107 | +### Custom Integration Application |
| 108 | + |
| 109 | +#### Download the sample application |
| 110 | + |
| 111 | +Feel free to grab the [code from the ThingsBoard repository](https://github.com/thingsboard/remote-integration-example) and build the project with maven: |
| 112 | + |
| 113 | +```bash |
| 114 | +mvn clean install |
| 115 | +``` |
| 116 | + |
| 117 | +Go ahead and add that maven project to your favorite IDE. |
| 118 | + |
| 119 | +#### Dependencies review |
| 120 | + |
| 121 | +Main dependencies that are used in the project: |
| 122 | + |
| 123 | +```xml |
| 124 | +<!-- Api ThingsBoard provides to create custom integration --> |
| 125 | +<dependency> |
| 126 | + <groupId>org.thingsboard.common.integration</groupId> |
| 127 | + <artifactId>remote-integration-api</artifactId> |
| 128 | + <version>${thingsboard.version}</version> |
| 129 | +</dependency> |
| 130 | +<!-- Netty for TCP client-server implementation --> |
| 131 | +<dependency> |
| 132 | + <groupId>io.netty</groupId> |
| 133 | + <artifactId>netty-all</artifactId> |
| 134 | + <version>${netty.version}</version> |
| 135 | +</dependency> |
| 136 | +<!-- Grpc transport between remote integration and ThingsBoard --> |
| 137 | +<dependency> |
| 138 | + <groupId>io.grpc</groupId> |
| 139 | + <artifactId>grpc-netty</artifactId> |
| 140 | + <version>${grpc.version}</version> |
| 141 | +</dependency> |
| 142 | +``` |
| 143 | + |
| 144 | +#### Source code review |
| 145 | + |
| 146 | +To be continued... |
| 147 | + |
| 148 | +## Next steps |
| 149 | + |
| 150 | +{% assign currentGuide = "ConnectYourDevice" %}{% include templates/guides-banner.md %} |
0 commit comments