Skip to main content
Version: Next

Building your own Tracker

Requirements#

Two build your own tracker, you only need a few things:

A Small Computer to run the nzyme Tracker software on#

A Raspberry Pi 3 works very well and there is no need to use the more powerful Raspberry Pi 4 if you still have older models somewhere collecting dust in a box.

A supported and compatible Uplink Device#

As described in the Trackers Introduction, every tracker communicates with the nzyme leader instance via an uplink device. Currently, only LoRa via a Waveshare SX1261 is supported. You'll need one uplink device for each tracker and one uplink device for your nzyme leader instance.

One or more WiFi Adapters that support Monitor Mode#

You can pick one from the Requirements of a nzyme leader instance page.

An External Battery#

A external battery will be required to allow you to move around with the device.

Possibly additional hardware for the HIDs you choose#

Depending on the HIDS you want to run, you might need to purchase additional hardware.

Photo of a tracker

Building a Tracker using a Raspberry Pi#

This guide assumes that you have a freshly installed, recent Raspberry Pi OS (previously called Raspbian) in front of you and that you have gone through your standard hardening and configuration procedure to set up things like user accounts, timezones and locales.

The guide is based on the Raspberry Pi OS Lite release based on Debian Buster (Released on August 08 2020).

Hardware Setup#

Start by plugging in your uplink device and WiFi adapter(s) using USB. There is currently no case available. Please reach out if you are familiar with, for example, 3D printing and would like to help build a case.

Software Setup#

We start by installing Java 11 (OpenJDK) and libpcap (for capturing WiFi frames):

Step 1: Install dependencies#

$ sudo apt update && sudo apt update && sudo apt install -y libpcap0.8 openjdk-11-jre-headless wireless-tools

Step 2: Download and install nzyme#

Now download the nzyme Debian from the downloads page to your server:

$ wget [http-url-to-nzyme-debian-package]

Install nzyme using the deb file you just downloaded:

$ sudo dpkg -i nzyme-1.0.0-beta.6.debSelecting previously unselected package nzyme.(Reading database ... 42572 files and directories currently installed.)Preparing to unpack nzyme-1.0.0-beta.1.deb ...Unpacking nzyme (1.0.0~beta.1) ...Setting up nzyme (1.0.0~beta.1) ...

Step 3: Configure nzyme#

We can start by deleting the example configuration file because it is made for nzyme LEADER instances and not for the TRACKER type we are setting up here:

$ sudo rm /etc/nzyme/nzyme.conf.example

Instead, create the file /etc/nzyme/nzyme.conf with the following content and make sure to replace the placeholders with your own values:

# General nzyme configuration.general: {  role: TRACKER
  # The ID or name of this nzyme tracker. Must be unique and contain only alphanumeric characters, underscores and dashes.  id: nzyme-tracker-01
  # Path to directory that nzyme will use to store some temporary information. (must be writable)  data_directory: /usr/share/nzyme
  # HIDs (human interface device) to run. Default is LogHID. The documentation lists all available HIDs.  hids: [ LOG ]}
# Please consult the nzyme documentation to find out supported tracker devices.uplink_device {  type: SX126X_LORA  parameters: {    # Set the encryption key to your own 32 character string of letters and numbers.    # Must be the same on all trackers and nzyme nodes or communication will fail.    encryption_key: YOUR_ENCRYPTION_KEY
    # Will usually be /dev/ttyUSB0 except if you have multiple devices connected.    # You can find out by looking at `dmesg` after plugging it in.    serial_port: /dev/ttyUSB0  }}
# 802.11/Wifi adapters that are designated to read traffic.# These interfaces will be used to track bandits.802_11_monitors: [  {    # The 802.11/WiFi adapter name. (from `ifconfig` or `ip link`)    device: YOUR_WIFI_ADAPTER_NAME
    # WiFi interface and 802.11 channels allowed to use. The nzyme leader decides which channels to tune into.    # Consider local legal requirements and regulations.    # See also: https://en.wikipedia.org/wiki/List_of_WLAN_channels    channels: [1,2,3,4,5,6,7,8,9,10,11]
    # There is no way for nzyme to configure your wifi interface directly. We are using direct operating system commands to    # configure the adapter. Examples for Linux are in the documentation.    channel_hop_command: "sudo /sbin/iwconfig {interface} channel {channel}"
    # Channel hop interval in seconds. Leave at default if you don't know what this is.    channel_hop_interval: 1  }]

The placeholders are:

  • uplink_device.parameters.encryption_key: Set to a random, 32 character long encryption key. This key will be used to AES encrypt uplink communication. This key is also used for authentication: All nzyme instances with the same encryption key will communicate with each other.
  • 802_11_monitors.*.device: Replace the device name with the name of your WiFi adapter as listed in iwconfig. It is strongly recommended to enable Predictable Interface Names.

Make sure to look at and change other parameters as well. Especially the channels used by your WiFi adapters will be of interest.

Step 4: Configure the LoRa adapters#

The LoRa adapter has to be configured to some specific settings to be able to communicate effectively. There is no need to change the configuration parameters, but if, for some reason, you do change them, make sure to configure all your LoRa adapters to the same values or they might not be able to communicate with eacht other.

We need to set the LoRa channel, speed and some other parameters. There are script available in the nzyme repository. Download the following three scripts:

$ wget https://raw.githubusercontent.com/lennartkoopmann/nzyme/master/misc/SX126X/set_channel.py$ wget https://raw.githubusercontent.com/lennartkoopmann/nzyme/master/misc/SX126X/set_speeds.py$ wget https://raw.githubusercontent.com/lennartkoopmann/nzyme/master/misc/SX126X/set_misc.py

The scripts require Python 3 and assume that your SX126X LoRa uplink is at /dev/ttyUSB0 (it will be by default). They will configure the uplinks to use LoRa channel 65.

Before we can execute the scripts, we need to install dependencies:

$ sudo apt install -y python3-pip...$ pip3 install pyserialLooking in indexes: https://pypi.org/simple, https://www.piwheels.org/simpleCollecting pyserial  Downloading https://files.pythonhosted.org/packages/0d/e4/2a744dd9e3be04a0c0907414e2a01a7c88bb3915cbe3c8cc06e209f59c30/pyserial-3.4-py2.py3-none-any.whl (193kB)    100% |โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ| 194kB 1.1MB/sInstalling collected packages: pyserialSuccessfully installed pyserial-3.4

On many Linux distributions, including Ubuntu, your user has to be in the dialout group or you will see a Permission denied error:

$ sudo usermod -a -G dialout YOUR_USERNAME

You have to log out and log in again after adding the user to the group. Some users reported a strange behavior where a full restart on the system was required for the changes to take effect.

To set the SX126X LoRa uplinks into configuration mode, you have to remove the yellow jumper that connects M1 and GND. You can do this while the uplink is plugged in.

Now run the scripts:

$ python3 set_speeds.py$ python3 set_channel.py$ python3 set_misc.py

Each command should finish within a second or so and show you the previous and new value of the configuration, like this:

Connected to serial port.Reading current channel configuration...Current Channel: 11Setting channel...Current Channel: 65Complete.

Change back the jumpers to their default position. (connect M1 and GND)

IMPORTANT: Repeat the configuration with the SX126X LoRa uplink you will be using on your nzyme LEADER instance. If you do not do this, your tracker won't be able to communicate with your nzyme installation.

Step 5: Start nzyme#

That's it! We are ready to enable and start nzyme.

This will configure nzyme to start automatically when the system boots:

$ sudo systemctl enable nzymeCreated symlink /etc/systemd/system/multi-user.target.wants/nzyme.service โ†’ /usr/lib/systemd/system/nzyme.service.

Now start nzyme like this:

$ sudo systemctl start nzyme

Check if it started successfully:

โ— nzyme.service - Nzyme   Loaded: loaded (/usr/lib/systemd/system/nzyme.service; enabled; vendor preset: enabled)   Active: active (running) since Sun 2020-10-18 00:22:43 BST; 22s ago     Docs: https://github.com/lennartkoopmann/nzyme Main PID: 648 (nzyme)    Tasks: 23 (limit: 2065)   CGroup: /system.slice/nzyme.service           โ”œโ”€648 /bin/sh /usr/share/nzyme/bin/nzyme           โ””โ”€649 /usr/bin/java -jar -Dlog4j.configurationFile=file:///etc/nzyme/log4j2-debian.xml /usr/share/nzyme/nzyme.jar -c /etc/nzyme/nzyme.conf
Oct 18 00:22:43 raspberrypi systemd[1]: Started Nzyme.Oct 18 00:22:58 raspberrypi nzyme[648]: WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.Oct 18 00:23:03 raspberrypi sudo[686]:     root : TTY=unknown ; PWD=/ ; USER=root ; COMMAND=/sbin/iwconfig wlx00c0ca95683e channel 2Oct 18 00:23:03 raspberrypi sudo[686]: pam_unix(sudo:session): session opened for user root by (uid=0)Oct 18 00:23:04 raspberrypi sudo[686]: pam_unix(sudo:session): session closed for user root

If the status command does not show nzyme as running (Active: active (running)), there is an issue with the configuration. You can check the nzyme log file with tail -n 200 /var/log/nzyme/nzyme.log. If that log file does not exist, there is an issue with starting nzyme. Run journalctl -xe to find out what happened.

Step 6: Configure the nzyme LEADER#

The last step is to configure your nzyme LEADER instance to recognize your tracker(s). All you need to do is to add the following configuration to your nzyme.conf on your LEADER device:

groundstation_device {  type: SX126X_LORA  parameters: {    encryption_key: YOUR_ENCRYPTION_KEY    serial_port: /dev/ttyUSB0  }}

Make sure a SX126X LoRa adapter is plugged in to the LEADER and that you configured that adapter just like the one connected to your TRACKER.

Restart the LEADER nzyme (sudo systemctl restart nzyme) and open the web interface. You should now see your tracker(s) on the Bandits page in the Trackers table. Every tracker you spin up will show up there if it shares the same encryption_key.

Screenshot

To learn how to use your trackers, follow the Using your Tracker page. Also make sure to check out and configure another HID.