Step 6: Connect Your First Device

1:34

The Network Challenge

Your ControlBird node runs in the cloud, but your devices (thermostats, PLCs, sensors) are on your local network. The cloud can't directly reach 192.168.1.100: that address only exists inside your home or facility.

To bridge this gap, you'll create a reverse TCP tunnel from your local network to your cloud node. This tunnel makes your local devices appear as if they're directly connected to the node.

Understanding Device Connections

Connecting a device in ControlBird involves three parts:

Step 1: Create a Tunnel Key on Your Node

Tunnel access uses an API key created on the node itself. Open your node's web UI, the same address you use every day, and open the API Keys window. You need the Owner role.

• Create a key and give it Tunnel access.
• List the ports the key may use, for example 502, 503 and 1883. The node's own web and data ports (3000, 3443 and 9100) cannot be listed.
• Copy the key when it is shown. It starts with cbk_.

A key works only on the node that issued it and only for its listed ports. To revoke it, disable or delete it in the same window.

Step 2: Establish the Tunnel

From a computer or gateway device on your local network, start the tunnel adapter. This creates reverse port forwards that expose your local devices to the cloud node.

Docker Tunnel (Recommended)

The easiest way to set up a persistent, auto-reconnecting tunnel is with the controlbird/tunnel Docker image. One command is all you need:

docker run -d --name tunnel \
  --restart always \
  -e TUNNEL_HOST=node.example.com \
  -e TUNNEL_API_KEY="cbk_your-api-key" \
  -e TUNNEL_LOCAL=192.168.1.100:502 \
  -e TUNNEL_REMOTE_PORT=502 \
  controlbird/tunnel

Forwarding Multiple Devices

Each container forwards one device, so run one container per device, each with its own name and TUNNEL_REMOTE_PORT:

docker run -d --name tunnel-thermostat \
  --restart always \
  -e TUNNEL_HOST=node.example.com \
  -e TUNNEL_API_KEY="cbk_your-api-key" \
  -e TUNNEL_LOCAL=192.168.1.100:502 \
  -e TUNNEL_REMOTE_PORT=502 \
  controlbird/tunnel

docker run -d --name tunnel-plc \
  --restart always \
  -e TUNNEL_HOST=node.example.com \
  -e TUNNEL_API_KEY="cbk_your-api-key" \
  -e TUNNEL_LOCAL=192.168.1.101:502 \
  -e TUNNEL_REMOTE_PORT=503 \
  controlbird/tunnel

docker run -d --name tunnel-mqtt \
  --restart always \
  -e TUNNEL_HOST=node.example.com \
  -e TUNNEL_API_KEY="cbk_your-api-key" \
  -e TUNNEL_LOCAL=192.168.1.50:1883 \
  -e TUNNEL_REMOTE_PORT=1883 \
  controlbird/tunnel

Docker Compose

If you prefer Docker Compose, add one service per device to your docker-compose.yml:

services:
  tunnel-thermostat:
    image: controlbird/tunnel
    restart: always
    environment:
      TUNNEL_HOST: node.example.com
      TUNNEL_API_KEY: cbk_your-api-key
      TUNNEL_LOCAL: 192.168.1.100:502
      TUNNEL_REMOTE_PORT: 502

  tunnel-mqtt:
    image: controlbird/tunnel
    restart: always
    environment:
      TUNNEL_HOST: node.example.com
      TUNNEL_API_KEY: cbk_your-api-key
      TUNNEL_LOCAL: 192.168.1.50:1883
      TUNNEL_REMOTE_PORT: 1883

Step 3: Open the Device Manager

With the tunnel established, open ControlBird and click the logo in the taskbar, then select Device Manager. This app manages all your device connections and data mappings.

Click to enlarge

Supported Protocols

ControlBird supports multiple industrial and IoT protocols:

Step 4: Create a Controller

Click "Add Controller" and select your protocol type. We'll use Modbus TCP as an example.

Click to enlarge

Controller Configuration

Since your tunnel forwards device ports to localhost on the node, configure the controller to connect locally:

Click to enlarge

Connection Status

After saving, the controller will attempt to connect through your tunnel. Watch the status indicator:

Step 5: Create a Mapper

With the controller connected, add a Mapper to read specific data points. Click "Add Mapper" under your controller.

Mapper Configuration

Each mapper reads one piece of data from your device and stores it in ControlBird:

Common Modbus Data Types

Step 6: Verify the Data

Once your mapper is active, you'll see live values in the Device Manager. The Value column updates in real time as your device reports data.

Confirm in Database Browser

Open the Database Browser and navigate to your target entity. You should see the field value updating at your configured poll interval.

Troubleshooting

Architecture Summary

Here's how data flows from your local device to ControlBird: