IoT Hub
IoT Hub Documentation
Getting Started Documentation Guides API FAQ

On this page

Contribution Guide

We are constantly looking for a feedback from our community on how to improve IoT Hub. If you have an idea, or you have some new features in mind, please open an issue at IoT Hub GitHub issue page. Please make sure that the same ticket is not already opened in the issues list (or something very similar).

Before you start any implementation please wait from the IoT Hub team to comment on your ticket. We’ll try to get back to you ASAP.

Required tools

To build and run IoT Hub instance make sure that you have Java and Maven installed onto your system.

Please refer to Building from sources section where Java and Maven install processes are described.

Fork and build IoT Hub repository

Once you have completed installation of required tools please fork official IoT Hub repository.

Now you can clone source code of the forked project.

NOTE: We will refer later to the folder where you have cloned repository as ${TB_WORK_DIR}.

If are building on Windows for the first time, you may need to run these commands to ensure the required npm dependencies are available:

1
2

npm install -g cross-env 
npm install -g webpack

Before importing the project into the IDE please build it using Maven tool from the root folder:

1
2

cd ${TB_WORK_DIR}
mvn clean install -DskipTests

A build will generate all the protobuf files in the application module that are needed for the correct compilation in your IDE.

Next, import the project into your favorite IDE as Maven project. See separate instructions for IDEA and Eclipse.

NOTE: If you are using Eclipse, after the maven project is imported to the IDE, We recommend you to disable Maven Project builder on ui-ngx project. This will improve the Eclipse performance a lot, because it will avoid Eclipse Maven builder from digging in node_modules directory (which is unnecessary and only causes Eclipse to hang). To do this, right-click on ui-ngx project, go to Properties -> Builders, and then uncheck the Maven Project Builder checkbox and then click Ok.

Database

By default, IoT Hub uses embedded HSQLDB instance which is very convenient for evaluation or development purposes.

Alternatively, you can configure your platform to use either hybrid mode - PostgreSQL for entities data and scalable Cassandra DB cluster for timeseries data or PostgreSQL for both. If you prefer to use an SQL database, we recommend PostgreSQL.

[Optional] SQL Database: PostgreSQL

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

Please use this link for the PostgreSQL installation instructions.

Once PostgreSQL is installed you may want to create a new user or set the password for the main user.

Then, press “Ctrl+D” to return to main user console and connect to the database to create thingsboard DB:

1
2
3

psql -U postgres -d postgres -h 127.0.0.1 -W
CREATE DATABASE thingsboard;
\q
[Optional] NoSQL Database for timeseries data: Cassandra

Please refer to appropriate section where you find instructions on how to install cassandra:

[Optional] Configure IoT Hub to use external database

NOTE: This is an optional step. It is required only for production usage. You can use embedded HSQLDB for platform evaluation or development

Edit IoT Hub configuration file:

1

/application/src/main/resources/thingsboard.yml

Comment ‘# HSQLDB DAO Configuration’ block.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# HSQLDB DAO Configuration
#spring:
#  data:
#    jpa:
#      repositories:
#        enabled: "true"
#  jpa:
#    hibernate:
#      ddl-auto: "validate"
#    database-platform: "org.hibernate.dialect.HSQLDialect"
#  datasource:
#    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.hsqldb.jdbc.JDBCDriver}"
#    url: "${SPRING_DATASOURCE_URL:jdbc:hsqldb:file:${SQL_DATA_FOLDER:/tmp}/thingsboardDb;sql.enforce_size=false}"
#    username: "${SPRING_DATASOURCE_USERNAME:sa}"
#    password: "${SPRING_DATASOURCE_PASSWORD:}"

For PostgreSQL:

Uncomment ‘# PostgreSQL DAO Configuration’ block. Be sure to update the postgres databases username and password in the bottom two lines of the block (here, as shown, they are both “postgres”).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# PostgreSQL DAO Configuration
spring:
  data:
    jpa:
      repositories:
        enabled: "true"
  jpa:
    hibernate:
      ddl-auto: "validate"
    database-platform: "org.hibernate.dialect.PostgreSQLDialect"
  datasource:
    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.postgresql.Driver}"
    url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/thingsboard}"
    username: "${SPRING_DATASOURCE_USERNAME:postgres}"
    password: "${SPRING_DATASOURCE_PASSWORD:postgres}"

For Cassandra DB:

Locate and set database type configuration parameters to ‘cassandra’.

1
2
3

database:
  ts:
    type: "${DATABASE_TS_TYPE:cassandra}" # cassandra OR sql (for hybrid mode, only this value should be cassandra)

NOTE: If your Cassandra server is installed on the remote machine or it is bind to custom interface/port, you need to specify it in thingsboard.yml as well. Please, tefer to the configuration guide for the detailed description of thingsboard.yml file and what properties are used for cassandra connection configuration.

After the thingsboard.yml file was updated, please rebuild the application module so that the updated thingsboard.yml gets populated to the target directory:

1
2

cd ${TB_WORK_DIR}/application
mvn clean install -DskipTests
Create Database schema and populate demo data

In order to create the database tables, run the following:

On Linux:

1
2
3

cd ${TB_WORK_DIR}/application/target/bin/install
chmod +x install_dev_db.sh
./install_dev_db.sh

On Windows:

1
2

cd %TB_WORK_DIR%\application\target\windows
install_dev_db.bat

Running development environment

Running UI container in hot redeploy mode.

By default, IoT Hub UI is served at 8080 port. However, you may want to run UI in the hot redeploy mode.

NOTE: This step is optional. It is required only if you are going to do changes to UI.

1
2

cd ${TB_WORK_DIR}/ui-ngx
mvn clean install -P yarn-start

This will launch a special server that will listen on 4200 port. All REST API and websocket requests will be forwarded to 8080 port.

Running server-side container

To start server-side container you can use couple options.

As a first option, you can run the main method of org.thingsboard.server.IoT HubServerApplication class that is located in application module from your IDE.

As a second option, you can start the server from command line as a regular Spring boot application:

1
2

cd ${TB_WORK_DIR}
java -jar application/target/thingsboard-${VERSION}-boot.jar
Dry run

Navigate to http://localhost:4200/ or http://localhost:8080/ and login into IoT Hub using demo data credentials:

  • login tenant@thingsboard.org
  • password tenant

Make sure that you are able to login and everything has started correctly.

Code changes

Now you are ready to start to do some changes to the codebase. Update server-side or UI code. Verify that changes that you have done meet your requirements and expectations from the user perspective.

Verify build

Before you commit your changes to the remote repository build it locally with tests run using Maven:

1

mvn clean install

Make sure that build is fine and all the tests are successful.

Push changes to your fork

When you are done with code changes commit and push them to your forked repository with some meaningful comment:

1
2

git commit -m 'Some meaningful comment'
git push origin master
Create pull request

Please create pull request into the master branch by default (the additional branch name will be provided during the initial stage of github issue discussion if needed).

If there are some conflicts because new stuff has arrived into IoT Hub master branch before your commit, please resolve those conflicts to continue.

Sign up contribution license agreement (CLA) and verify that remote build has been successful. The CLA is signed automatically using the github CLA bot.

image

Be patient, pull request may take several days to review.

See also

Next steps

  • Getting started guides - These guides provide quick overview of main IoT Hub features. Designed to be completed in 15-30 minutes.