UpBlue Collector

What is the Collector?

The UpBlue Collector is a stand alone tool that is configured in the UpBlue Management Environment. It cannot be configured in the collector itself. The Collector is needed because UpBlue cannot and should not directly be connected to end devices. The Collector is a secure way to connect end devices to the cloud. The Collector is designed with the following design philosophy: install and forget. Everything is management remote in the UpBlue Management Environment.

How does it work?

After installation and authorization, the Collector sets up a connection with UpBlue. By this connection the Collector receives commands. When in the UpBlue Management Environment a new connection is send to the Collector, the connection is run locally. Connection tests,Rule tests and the OPC UA browser are also run locally.

The collector running the connections receives values from the end devices. Each value received is stored in a memory cache. Each 10 sec this cache is send to UpBlue for storage.

If UpBlue is unreachable, because for example the local network is down, the memory cache is written to disk. Each new datapoint is written to disk each 10 sec. The Collector will keep retrying. If the internet is back online, priority is given to new datapoints. These will be send to UpBlue first. The cache written to disk is sent to UpBlue 100 datapoints each 10 sec.

⚠️

If you reset the Collector, the pressing this button: the disk cache is cleared.

The following external domains are used by the Collector;

https://auth.upblue.io - For authorization to UpBlue
https://stream.upblue.io - Data stream to UpBlue
https://upblue.io - Ping to get local IP address of the machine running the Collector
https://github.com - For updating the Collector

Install Collector

Windows

The collector can be downloaded from the collector page within an organisation. Go to the UpBLue Management Environment to open an organisation..

Click on this button in the UpBLue Management Environment: to download the collector.

To find all releases, go to UpBlue Collector release page

The Collector can be installed as a service. Only install as a service if you have good reason to. A non service installation runs als local user and has no elevated rights in Windows. If you want to change the installation from service to non service or visa versa, uninstall the collector and run the installer again.

After installation of the Collector, navigate to; http://localhost:61879/. In a non service installation, a UpBlue icon will appear in the system tray (next to the time and date). Right click to open UpBlue.

Docker

Docker is a virtualization platform that can run software in so called containers. Each containers contain one program. In our case the UpBlue Collector. For Linux, using Docker is the only option to run the UpBlue Collector

Find how to install docker here

Docker compose

After installation of docker. Create a docker-compose.yaml some where on your pc

version: '3'
services:
  upblue-collector:
    image: 'upblueio/upblue-collector:latest'
    container_name: UpBlue-Collector
    restart: unless-stopped
    volumes:
      - upblue_data:/etc/xdg/UpBlue
    ports:
      - 8181:61879
volumes:
  upblue_data:

Open terminal.

CD to the folder.

docker compose up -d --remove-orphans

Authorization

The Collector needs authorization to connect to UpBlue. This is done by supplying a token. To generate a token, a few steps needs to be taken;

Create a service user
Add the service user to a organisation
Give the service user the Insert role
Generate a token
Use token in the collector

Create service user

Go to the user page.

Click on: Give the user a email address. This can be a fake email address. The address is not validated.

A service user has no password and cannot be used for logging in. A service user is only used for the Collector or direct API use.

Add the service user to a organisation

Open the organisation to add the service user to the organisation. Go to the UpBLue Management Environment to open an organisation..

Go to “Organisation User” page. Add the user.

Give the service user the Insert role

On the same page (Organisation User), click on the user.

Click on:

Add the “User can insert” role.

Generate a token

Go to the token page.

Click on:

Select the user and click on:

The token will be generated and displayed once! Only one token can be generated per service user. Advice is to generate one token per Collector. If a token is compromised, then only one Collector need to be logged in again with a new token. Still, one token can be used multiple times.

To retract a token, delete the token.

Use token in the Collector

Copy paste the token in the Collector.

Final steps

Select the Organisation and give the Collector a name. This can be changed after.

The Collector is now ready for use. Open UpBlue Management Environment to configure the Collector.

UpBlue Management Environment

Introduction Labels