LEAPS Gateway

LEAPS Gateway serves as a bridge between the UWB and the TCP/IP networks.

Key Features

  • The LEAPS Gateway communicates on one side with the LEAPS UWBS via the generic LEAPS API, SPI, or USB and on the other side with the LEAPS Server via the TCP/IP.

  • Depending on the LEAPS UWB networking profile, it provides a medium for transferring the uplink and downlink location and telemetry data of the Anchors and Tags to and from the MQTT Broker.

  • The interconnection with the UWBS is done via the SPI on a dedicated LEAPS Gateway embedded device. When the interconnection with the LEAPS UWBS is done via the USB, like in the case of the UDK1 devices, LEAPS Gateway runs on a Linux platform as a daemon service.

Installation

System Requirements

Docker’s system requirements vary based on the operating system.

  • For Linux, you need a 64-bit architecture, a compatible kernel version, and specific kernel features.

  • On Windows, use Docker Desktop on Windows 10 with virtualization enabled.

  • On macOS, use Docker Desktop with macOS 10.13 or newer. In terms of hardware, a minimum of 2GB RAM is recommended, along with sufficient CPU and disk space.

Note

Refer to Docker official documentation for up-to-date details.

Instructions

  1. Install Docker on your PC

Install Docker Desktop on Linux

Additionally, you can refer to the following commands to install:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh
sudo usermod -aG docker $USER

Install Docker Desktop on Windows

  1. Create folder leaps_gateway_hub and subfolder data. Then, add the leaps-gateway.conf configuration file in leaps_gateway_hub/data.

#######################################################################
# LEAPS Gateway settings
#

# -----------------------------------------------------------------
# Logging
# -----------------------------------------------------------------
log_level = 0 #  Logging level, default is 0 (0=none, 1=fatal, 2=error, 3=warning, 4=info, 5=debug, 6=verbose)

# Path to log file. Comment out to disable logging to file (log to stdio instead).
# log-file = leaps-gateway.log


# LEAPS Server host
# Default: localhost
leaps-server-host = localhost # Or your Computer's IP Address

# LEAPS Server port
# Default: 7777
leaps-server-port = 7777

# -----------------------------------------------------------------
# UWBS USB Device VID/PID
# -----------------------------------------------------------------
#

# Vendor ID, default is 0x1915, possible values are (0x1915-Nordic, 0x04d8-Microchip)
# Allowed values: 16-bit number in decimal, hexadecimal or octal format
# uwbs-usb-dev-vid = 0x04d8
uwbs-usb-dev-vid = 0x1915

# Product ID, default is 0xe8e3 for LEAPS RTLS devices
# Allowed values: 16-bit number in decimal, hexadecimal or octal format
uwbs-usb-dev-pid = 0xe8e3

# -----------------------------------------------------------------
# UWBS device configurations
# -----------------------------------------------------------------
#

# Bridge mode
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
# uwbs-bridge = 0

# Initiator mode
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
# uwbs-initiator = 0

# UWBMAC Profile ID
# Default: (keep-current)
# uwbs-profile-id = 0

# LEDs mode
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
# uwbs-led = 1

# UWB encryption
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
# uwbs-enc = 0

# UWB firmware update
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
# uwbs-fwup = 0

# UWB mode
# Allowed values: 0=Off 1=Passive 2=Active
# Default: (keep-current)
# uwbs-uwb = 2

# UWB Backhaul Routing
# Allowed values: 0=Off 1=On 2=Auto
# Default: (keep-current)
uwbs-bh = 1

# BLE
# Allowed values: 0=Off 1=On
# Default: (keep-current)
# uwbs-ble = 1

# UWB encryption key
# Allowed values: 128-bit number in hexadecimal format
# Default: (keep-current)
# uwbs-enc-key = 11111111222222223333333344444444

# UWB network PANID
# Allowed values: 16-bit number in decimal, hexadecimal or octal format
# Default: (keep-current)
# uwbs-panid = 0x0000

# Device label
# Default: (keep-current)
# uwbs-label = gw-uwbs

# Device position in mm [x, y, z]
# Default: (keep-current)
# uwbs-pos-x = 0
# uwbs-pos-y = 0
# uwbs-pos-z = 0

  1. Open a command prompt or terminal window on your PC.

  • Navigate to the folder where you created the configuration file.

For example, on Ubuntu (Linux):

cd leaps_gateway_hub/

  1. Install the LEAPS Gateway Docker packages, run:

Note

LEAPS Gateway requires the use of a USB port. Therefore, users need to run with admin rights to mount and use USB on the docker container.

sudo docker run -d -it --name some_name --privileged -v /dev/bus/usb:/dev/bus/usb -v /path/to/data/data/:/app/data/ leapslabs/leaps_gateway:tag /app/leaps_gateway --cfg /app/data/leaps_gateway.conf

Where some_name is the name you want to assign to your container, and the tag specifies the leaps-gateway version you want.

  • Recommended run options

    • --user $(id -u):$(id -g) Run the instance under a specific user and group.

    • --restart unless-stopped Restart automatically the instance in case the server would crash.

  1. The LEAPS Gateway installation process will begin.

For example, on Ubuntu (Linux):

sudo docker run -d -it --name leaps_gateway --privileged -v /dev/bus/usb:/dev/bus/usb -v "$(pwd)"/data/:/app/data leapslabs/leaps_gateway:latest /app/leaps-gateway -c /app/data/leaps-gateway.conf

Unable to find image 'leapslabs/leaps_gateway:latest' locally
latest: Pulling from leapslabs/leaps_gateway
a458657ccc71: Pull complete
Digest: sha256:a19b127656d41d8607f043c2c83924e5b9a5cbd4dc23cfbed070be3b9cfc6b9a
Status: Downloaded newer image for leapslabs/leaps_gateway:latest
320d3768289874e063619f75faca7a24dd75a08884df8cd8fb2cc9b54c6f0a46

  1. Verify that the installation is successful, run:

For example, on Ubuntu (Linux):

sudo docker ps

CONTAINER ID   IMAGE                    COMMAND                  CREATED          STATUS                          PORTS     NAMES
b1145b72db35   leapslabs/leaps_gateway:latest   "sh -c 'cd /app &&  …"   37 seconds ago   11 seconds ago                           leaps_gateway

So, you have successfully installed and started LEAPS Gateway on PC.

Getting started

LEAPS Gateway Docker

  • Start LEAPS Gateway, run: sudo docker start leaps_gateway

  • Stop LEAPS Gateway, run: sudo docker stop leaps_gateway

  • Restart LEAPS Gateway, run: sudo docker restart leaps_gateway

  • Remove LEAPS Gateway, run sudo docker rm --force leaps_gateway

Network Configuration

  • Logging

    # Logging level, default is 3 (0=none, 1=error, 2=warning, 3=info, 4=debug, 5=verbose).
log-level = 0

# Path to log file. Comment out to disable logging to file (log to stdio instead).
log-file = leaps-gateway.log

  • LEAPS Server host

    # Default: localhost
leaps-server-host = 192.168.1.1 # Your Computer's IP Address

# LEAPS Server port
# Default: 7777
leaps-server-port = 7777

  • UWBS USB Device VID/PID

    # Vendor ID, default is 0x1915, possible values are (0x1915-Nordic, 0x04d8-Microchip)
# Allowed values: 16-bit number in decimal, hexadecimal or octal format
# uwbs-usb-dev-vid = 0x04d8
uwbs-usb-dev-vid = 0x1915

# Product ID, default is 0xe8e3 for LEAPS RTLS devices
# Allowed values: 16-bit number in decimal, hexadecimal or octal format
uwbs-usb-dev-pid = 0xe8e3

  • UWBS device configurations

    # Bridge mode
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
uwbs-bridge = 0

# Initiator mode
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
uwbs-initiator = 0

# UWBMAC Profile ID
# Default: (keep-current)
uwbs-profile-id = 0

# LEDs mode
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
uwbs-led = 1

# UWB encryption
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
uwbs-enc = 0

# UWB firmware update
# Allowed values: 0=Disable 1=Enable
# Default: (keep-current)
uwbs-fwup = 0

# UWB mode
# Allowed values: 0=Off 1=Passive 2=Active
# Default: (keep-current)
uwbs-uwb = 2

# UWB Backhaul Routing
# Allowed values: 0=Off 1=On 2=Auto
# Default: (keep-current)
uwbs-bh = 1

# BLE
# Allowed values: 0=Off 1=On
# Default: (keep-current)
uwbs-ble = 1

# UWB encryption key
# Allowed values: 128-bit number in hexadecimal format
# Default: (keep-current)
uwbs-enc-key = 11111111222222223333333344444444

# UWB network PANID
# Allowed values: 16-bit number in decimal, hexadecimal or octal format
# Default: (keep-current)
uwbs-panid = 0x0000

# Device label
# Default: (keep-current)
uwbs-label = gw-uwbs

# Device position in mm [x, y, z]
# Default: (keep-current)
uwbs-pos-x = 0
uwbs-pos-y = 0
uwbs-pos-z = 0

Troubleshooting

  • Use the following command sudo docker restart leaps_gateway to restart LEAPS Gateway.

  • On windows, repeat the USB/IP attach WSL 2 to connect the USB device. (usbipd wsl attach --busid <busid>)