Installation

This page guides you through the installation of a Lorabridge bridge and gateway device. First, you need to ensure your Raspberry devices fulfill the Requirements. Then you can either use the mostly automated Ansible setup or perform the steps manually.

Requirements

Hardware

You can find the necessary hardware here

Software

You need to:

  • install Raspberry Pi OS (Lite is fine)
  • make sure to enable ssh and ensure the raspi is connected to the Internet
  • Install docker and docker compose [manual setup]
  • install git (via sudo apt-get install git) [manual setup]
  • enable spi (via sudo raspi-config nonint do_spi 0) [manual setup]

Ansible Setup

This setup method automates several steps of the installation process of bridge and gateways devices. You need to clone the lorabridge-setup github repository. The repository provides an ansible project for setting up LoRaBridge devices via ssh.

You need to prepare the Raspberry Pi devices as described in Requirements.

Clone Setup Repository

Download the code for the Ansible setup and switch inside the folder:

git clone https://github.com/lorabridge/lorabridge-setup.git
cd lorabridge-setup

Ansible Controller Requirements

You need to install the requirements listed in following files inside the repository on the host running the setup:

  • apt-requirements.txt
  • Pipfile
  • requirements.yml

Installing Requirements

Install requirements with e.g.

xargs apt install -y < apt-requirements.txt
# apt-get install $(cat apt-requirements.txt | tr '\n' ' ')
pipenv install
ansible-galaxy install -r requirements.yml

Inventory file

Copy the inventory.sample file, name it inventory and Replace the placeholders with the actual values of the bridge and gateway devices.

[bridges]
<bridges ip address> hostname=<desired hostname>

[gateways]
<gateway ip address> hostname=<desired hostname>

Configuration Variables

Configuration variables are defined in following places:

group_vars/all/all.yaml
group_vars/bridges/*
group_ars/gateways/*
roles/<role name>/defaults/main.yaml

You can overwrite them by creating a new yaml file (e.g. myconfig.yaml) inside group_vars/all/, group_vars/bridges/ or group_vars/gateway/ and configuring the desired value in there. Doing this inside group_vars/all/ affects all devices, group_vars/bridges/ affects only bridge devices and group_vars/gateways/ affects only gateway devices.

Usually you will not need to change the configuration unless you changed the default user name.

Example for changing the user name to user1

  • Create a custom configuration file group_vars/all/custom.yaml
  • Insert the following content: 
    ---
pi_user: "user1"

Executing the setup

Start the setup with the following command:

ansible-playbook -i inventory lorabridge.yaml --ask-become-pass --ask-pass

Manual Setup

Preparation of bridge unit

Step 1 - Cloning

Clone our top-level repository lorabridge/lorabridge either via ssh per
git clone --recursive git@github.com:lorabridge/lorabridge.git
or via https per
git clone --recursive https://github.com/lorabridge/lorabridge.git

Info

You can also use the new github cli tool gh repo clone lorabridge/lorabridge -- --recursive (prior config necessary - see manual)

Step 2 - Navigation

Navigate into the repository with cd lorabridge.
If you are setting up a bridge do cd bridge.

Step 3 - Configuration

Copy env.example to .env and modify variables in .env as necessary, see config for further details.

Following variables need to be changed for a bridge device:

  • LORA_DEV_EUI
  • LORA_DEV_KEY
  • BASIC_AUTH

Info

variables are automatically substituted in docker-compose.yml file

Step 4 - Container creation

Pre-built images

All images are pre-built via github actions on every commit and every sunday. Use those image with:

docker compose pull
docker compose up -d
Self-built images

You can build your own images for development purposes via:

docker compose -f docker-compose.dev.yml build --pull
docker compose -f docker-compose.dev.yml up -d

Preparation of gateway unit

Step 1 - Cloning

Clone our top-level repository lorabridge/lorabridge either via ssh per
git clone --recursive git@github.com:lorabridge/lorabridge.git
or via https per
git clone --recursive https://github.com/lorabridge/lorabridge.git

Info

You can also use the new github cli tool gh repo clone lorabridge/lorabridge -- --recursive (prior config necessary - see manual)

Step 2 - Navigation

Navigate into the repository with cd lorabridge.
If you are setting up a bridge do cd gateway.

Step 3 - Configuration

Copy env.example to .env and modify variables in .env as necessary, see config for further details.

Following variables need to be changed, when setting up a gateway:

  • CHIRPSTACK_DEV_EUI
  • CHIRPSTACK_DEV_KEY
  • CHIRPSTACK_API_SECRET

Info

variables are automatically substituted in docker-compose.yml file

Step 4 - Container creation

Pre-built images

All images are pre-built via github actions on every commit and every sunday. Use those image with:

docker compose pull
docker compose up -d
Self-built images

You can build your own images for development purposes via:

docker compose -f docker-compose.dev.yml build --pull
docker compose -f docker-compose.dev.yml up -d

Adding another bridge device to the gateway

Device setup

Follow the instructions for setting up a bridge for the additional bridge.

When copying env.example to .env and modifying the default values, choose a unique identifier for LORA_DEV_EUI (has to be unique for every bridge).

Info

LORA_DEV_KEY needs to be the same as on the gateway.

Add device to gateway

Open the ChirpStack webinterface inside the browser via http://<ip-or-hostname>:8080.

Go to Applications and press on the name of the application LoRaBridge_DataPipe.

application

On the next page (Devices) press on Create.

Fill in the device name and description, enter the new bridges' LORA_DEV_EUI in the Device EUI field and choose the LoRaBridge Device Profile as Device-profile. Then press on Create Device.

newdevice

The webinterface redirects you to the page of your new device, the current tab should now be KEYS (OTAA). Enter the LORA_DEV_KEY value of your .env file in the Application key field and press SET DEVICE-KEYS.

app_key

Your device should now be up and running. It might take a while until device has connected to the gateway and sends packets.

Verify system functionality

Pair a sensor with the bridge unit following the instructions here.
After the sensor transmits data (either after waiting or manually triggering it), the data should show up in the Home Assistant interface as shown here.