SpinalHub

SpinalHub, usually just called “hub”, is at the core of the IoT systems using SpinalCom technologies. All the data collected and processed by the organs is synchronized between them through the SpinalHub. Its main goal is that all the organs work on the same data, even if they are distributed.

For development, you could run the organs and the hub on the same machine. In a production environment, however, the hub should run in a separate node of the network, generally in a gateway. The gateway will be in charge of the communication between your local network and the internet, and will therefore, thanks to SpinalHub, be able to exchange data locally without relying on the cloud.

The organs can connect to the hub thanks to the connectors (SpinalCoreJS and SpinalCoreQt), and provide a transparent layer for the developers that will be in charge of loading, storing and synchronizing the data.

SpinalHub run natively on Linux platforms (since it is meant to run mainly in gateways and servers), you can use your favourite OS for development stages and you can deploy the hub on virtual machine, in Docker container or use it on ubuntu for windows... 

To run natively on Linux, you can download the free version from the the npm package (see getting started pages). You first need to add execute permission to the binaries. From a terminal, run:

To start the hub, run from a terminal:

$ ./spinalhub

If you wish to have global access to it, you can copy it to a directory included in the global path environment variable (make sure you have permissions). In Ubuntu you can do like this:

$ sudo cp /path/to/spinalhub /usr/bin/

The hub can be divided in 4 parts:

• Authentication: defines the rights of the user to manage data
• The data storage: where the data persists
• The exchange of data: in charge of synchronizing the current data with the incoming one
• The web server: appart of managing data, the hub contains a web server, useful for providing a web graphical interface of the system

Authentication

By default, there are two types of user in SpinalHub, and one user of each type. The type 0 has rights to read and write any data in the hub, while the type 1 can only read data. You can change the passwords of these users by passing them as arguments when executing the hub (see more in the following section).

Once the hub is launched, it prints all the information about the users. You can also see this information by accessing the following URL, as long as the hub is running: http://localhost:8889. In the organs of your system, you should connect to the hub using the login credentials according to the type of operations you need to perform on the data.

Data storage

When launching SpinalHub, a new folder named memory is created in the same directory from where it is launched. Inside it, there is a file called dump.db, which will contain all the structured data of the system, and a folder data.db, for the external uploaded files (images, pdf, etc). As long as the folder memory exists, and it’s on the same path of the hub, the data will persist across the different running instances of SpinalHub.

Data exchange

SpinalHub listens on different ports, mainly with the purpose of synchronizing the stored data with incoming data from the organs. These are:

• Http (by default 8888): Listens for requests made from the organs using SpinalCoreJS connectors. Also used by the web server.
• Binary stream (over TCP/IP) (by default 8890): Listens for requests made from the organs using SpinalCoreQt connectors.
• Monitoring (by default 8889): HTTP port used by an administration panel, still in development.

For information about changing the default ports, check the command line documentation about arguments.

Web server

SpinalHub will look by default for a folder named html relative to its execution path, and use it as a web root directory, in the HTTP port configured (by default 8888). This can be used for creating a graphical web interface for the users to interact with the system from a computer or mobile phone.

For information about changing the name of the folder, check the command line documentation about arguments.

There is no necessary extra configuration to be made for running SpinalHub. However, if you would like to customize it, there are a few parameters you can pass when executing it. The usage is:

$ ./spinalhub [options]

Where the options are:

• -b : base directory of files to be served (/ in http requests); by default html
• -p : http port for public pages; by default 8888
• -P : http port for supervision; by default 8889
• -q : port for binary public communication; by default 8890
• -r : password for user with read permissions
• -w : password for root user with write/read permissions
• -x : password for admin user with admin permissions
• -m : by default, the passwords will only be saved in the first execution; when passing this argument, the system will update the passwords even after the first execution