# ThingsBoard Extensions

[toc]

## BE

:::info
使用 Maven 編譯後端原始碼，並經由 Spring Data JPA (Java Persistence API) 進行數據處理與擴展的技術指引。
:::

1. 建立 Spring Boot Project ( https://start.spring.io/ || 透過 IDE )
2. 建立功能所需 MVC 並執行確認功能是否正常使用
3. 在 org.thingsboard.server.config package 底下建立 IoC 管理檔案路徑設定(com.fgiotlead.signage)

package org.thingsboard.server.config;

import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

@Configuration
@ComponentScan({"com.fgiotlead.signage"})
@EnableJpaRepositories("com.fgiotlead.signage")
@EntityScan({"com.fgiotlead.signage"})
public class SignageConfig {
}

<!--
4. 修改 pom.xml

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
+       <skip>true</skip>
    </configuration>
</plugin>

-->
4. build ``mvn clean install -DskipTests``
將 jar 作為 tb-extensions 複製到 [/usr/share/thingsboard/extensions](https://github.com/thingsboard/thingsboard/blob/master/msa/tb/docker/thingsboard.conf#L24) 引入。
(預設是沒有extension folder的)

docker exec -it mytb sh -c "mkdir -p /usr/share/thingsboard/extensions"
docker cp <your-backend-extension>.jar mytb:/usr/share/thingsboard/extensions

5. 執行 tb 並測試功能是否正常 ( custom API etc... )
Eclipse 沒有內建 Protobuf，TB 有些 package ( 如 org.thingsboard.server.gen )，是透過 proto 自動建立，但目前補上插件依然有誤，待解決。

<!--
### 取得JWT

curl -X POST http://tb.example.com:8080/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username": "username", "password": "password"}'

### 使用JWT驗證

curl -X GET http://192.168.1.232:8080/api/admin/systemInfo \
    -H "Authorization: Bearer <jwt>"

-->
### 參考使用repo
https://github.com/5giotlead/tb-api-extensions

## FE

* Create your own angular components and use them in your widgets and actions.
* This feature for any complex logic in your solutions
* Reuse the code
* All functionality of TypeScript, RXJS, Angular, etc.
* In the ThingsBoard v3.6 and higher (support CE &amp; PE)
* It can adopt with UI

Information before the TB v3.6, the extension file has to load manually to your server and restart it. ( Detail info is in github of thingsboard-extensions ReadMe ) 

* **The following steps are for the ThingsBoard equal or above the version 3.6**
* **Before env setup, node version suggest equal or above v16.17.0 and Angular CLI above v15**
* Setup node firstly and then use **the node** to install the Angular CLI

### Step 1 - Prepare compiled components

You need a file with your compiled components. By default, it is called thingsboard-extension-widgets.js. All instructions on how to create it can be found inside the README file to [ThingsBoard extensions](https://github.com/thingsboard/thingsboard-extensions/tree/master).

### Step 2 - Add into the Resouces library

Add the JS module into the Resouces library


### Step 3 - Use it in a custom widget

Use in a custom widget


### Issues

透過 yarn start 執行的 web server 沒有對外開放 Port，嘗試在 thingsboard-extensions/widgets/package.json 的 start 指令新增 --host 0.0.0.0 錯誤

修改內容:

...
  "scripts": {
    ...
    "start": "node --max_old_space_size=8048 ./node_modules/@angular/cli/bin/ng serve --host 0.0.0.0",
    ...
  }

Error:

yarn start
yarn run v1.22.17
$ node --max_old_space_size=8048 ./node_modules/@angular/cli/bin/ng serve --host 0.0.0.0
Error: Unknown argument: host
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

**Root cause:**
- angular.json (custom-builder:static-serve, 非官方 ng serve, 不支援 host 參數。)

        "serve": {
          "builder": "@tb/custom-builder:static-serve",
          "options": {
            "host": "0.0.0.0",
            "port": 5000,
            "tsConfig": "src/tsconfig.lib.json",
            "project": "src/ng-package.json",
            "staticServeConfig": "static.serve.conf.js"
          }
        }

- index.js (**localhost hardcoded**)

star@delta:~/workspace/thingsboard-extensions$ grep -ir localhost ./node_modules/@tb/custom-builder/static-serve/*

./node_modules/@tb/custom-builder/static-serve/index.js:    const host = 'localhost';
./node_modules/@tb/custom-builder/static-serve/index.js:        context.logger.info(`==> 🌎  Listening on port ${options.port}. Open up http://localhost:${options.port}/ in your browser.`);
./node_modules/@tb/custom-builder/static-serve/index.ts:  const host = 'localhost';
./node_modules/@tb/custom-builder/static-serve/index.ts:    context.logger.info(`==> 🌎  Listening on port ${options.port}. Open up http://localhost:${options.port}/ in your browser.`);

- Modify index.js line 97 (**localhost to 0.0.0.0**)

    server = http.createServer(app);
    const host = 'localhost';
    server.on('error', (error) => {
        context.logger.error(error.message);
    });

- ``yarn start``
- Listening port validation

$ ss -tupln | grep 5000
tcp   LISTEN 0      511           0.0.0.0:5000       0.0.0.0:*    users:(("ng serve",pid=1925247,fd=24))

- Browser HTTP URL Test

### Run the project in development mode

* Setup Env
* Thingsboard CE build in local
* Thingsboard-extensions package in local
* Yarn Start (run the develop mode)

cd ${TB_EXTENSION_WORK_DIR}
yarn install
yarn start

* In widgets library create a new widget and in the resources tab of the widget editor add this file path: `http://localhost:5000/static/widgets/thingsboard-extension-widgets.js`
* Component `<tb-example></tb-example>`

#### Create a component to be used in TB

* File `public-api.ts` must exist
* Used to export module
* To add some of ThingsBoard dependencies imports to your &quot;extension&quot; Angular component, please use this import structure:
* `import { <dependency> } from '<TB-module>/public-api';`
* example: `import { WidgetConfig } from '@shared/public-api';`

## References

* BE
* [亿琪软件官方博客](https://www.yiqisoft.cn/blogs/)
* [如何无缝扩展 ThingsBoard 功能？原来二次开发如此简单！](https://www.yiqisoft.cn/blogs/category/thingsboard/15/)
* FE
* [ThingsBoard Extensions Doc](https://thingsboard.io/docs/user-guide/contribution/widgets-development/#thingsboard-extensions)
* [Github thingsboard-extension](https://github.com/thingsboard/thingsboard-extensions/tree/release-3.6.2)