What's inside a SensorGnome?

SensorGnomes contain the following components:

• Raspberry Pi single board computer, typ model 3B+ or 4B as of 2024. This runs the software that records the raw radio pulse data.

• FUNcube USB dongles or other "software defined radios". These take the analog radio signals coming from the antennas and convert them into a digital format, ultimately to decode Lotek tag signals.

• CTT Motus Adapter USB dongles containing radios for the CTT 434Mhz tags.

• GPS. This records the precise location of the SensorGnome, as well as ensures that the precise time is always recorded in data files.

• Associated power supply.

• rPi 3B+ is the recommended model to use for a SensorGnome due to the fact that its USB ports can directly support multiple FUNcube dongles. The rPi 3B ("non-plus") works just as well.

• rPi 4B also works, however its USB subsystem may cause difficulties as described in [link missing]. However, with some attention to where FCDs are plugged in it can work great. The performance advantage and USB 3.0 support over a rPi 3B don't really come to bear in the SensorGnome use-case.

• rPi Zero 2W can be useful in portable applications or other experiments. Due to the fact that it has only one micro-USB port it is not convenient to hook up lots of radios, but it does work.

The numbering of the USB ports is very important when attaching antennas since this information is recorded along with detection data and can be used to determine the direction and time of approach or departure of a tagged animal.

To keep installers on their toes the port numbering is reversed between models 3B/3B+ and 4B!

The Micro-SD card slot is on the opposite side from the USB and Ethernet Ports. The card is inserted with the contacts facing up, and there is no click or other indicator when the card is inserted. On some cases the the Micro-SD is so deeply recessed that it cannot be removed without tweezers.

Power is supplied to a model 3B/3B+ through the a USB port. This port only supplies power and is not used to communicate with a computer. On a model 4B a USB-C connector is used.

LED lights can be useful in determining if the unit has power and if it is functioning properly.

The RPi itself has only two primary LED lights -- one red and one green. These are visible on the bottom right hand corner of the side that hosts the Micro-SD slot. The red light indicates power, while the green light should emit from 1 to 3 flashes every 2 seconds.

The attached GPS had also has an indicator light, in this case a red LED. It does not light up consistently but instead blinks occasionally. If you are having trouble connecting and the green light never illuminates, you may need a

Lastly, there are two indicator lights on the bottom of the Ethernet port. When the Ethernet cable is attached to a computer these lights should be on or flashing consistently.

a) The Raspberry Pi. The colour of the RPi case may vary between SensorGnomes’s but they will also be roughly the same size

b) FunCUBE Dongles. A Raspberry Pi SG can accommodate up to 4 dongles plugged directly into the RPi (however, an rPi 4B can only support one directly plugged in FUNcube!). In order to accommodate additional antennas, a USB hub would be required. The cables from the antennas will plug into the free end of the dongles.

c) This is the inside view of the button used to activate the WiFi hotspot.

d) GPS antenna. When deployed in the field, this end of the antenna would be outside the SG case, and attached to something that had a clear view of the sky. The other end is attached to the Raspberry Pi by way of the gold-coloured “SMA” port on the top right corner of this particular RPi.

e) Voltage converter. If powered by a solar panel and battery, as this SG is, the power coming in will be 12V. However the RPi only requires 5V, so a voltage converter is used to downgrade the current to the acceptable level. If powered directly by AC power, the wall adapter itself should output 5V, eliminating the need for a voltage converter.

When providing power to a SensorGnome there are multiple aspects to consider:

• Powering the Raspberry Pi, which typically also powers the radios attached via USB.

• Ensuring that the Raspberry Pi can indeed power everything attached to the USB ports.

• Dealing with power when using Solar and battery systems.

Powering USB devices

While the USB specs have a lot of rules about how much power each device may use there is a simple rule for Raspberry Pis (at least for the 3B and 4B models):

Once the power limit is exceeded the USB power is cut and devices misbehave. FUNcube dongles consume 100mA-200mA, CTT radios less than 30mA. This means that 4 FCDs and 4 CTT radios can be powered by the rPi directly. A USB GPS can also be added. The majority of cellular modems have power consumption spikes that exceed 1.2A or at least come close to it, so they cannot be powered reliably from the rPi ports. To connect a cellular modem use a HAT (printed circuit board that mounts on the rPi's 40-pin connector) or attach the dell modem to a powered USB hub.

The power consumption of rPis is very spiky, consuming 1A-2A at peak. All the devices attached to the USB ports and potentially a cellular HAT must be powered as well. The result is that you need to use a power adaptor that can deliver more than the typical 2.1A claimed by many power adapters. Most el-cheapo "2A" or "2.1A" adapters lead to problems sooner rather than later.

When a SensorGnome isn't receiving enough power -- that is, the voltage and/or current is lower than the device is rated for -- it can result in a malfunctioning station that doesn't collect data.

While Raspberry Pis don't have power-over-ethernet (PoE) built-in it is possible to use PoE with "splitters" that separate the power and ethernet at the device end. For reference, a good page about PoE is https://en.wikipedia.org/wiki/Power_over_Ethernet and it's ... confusing... The table at the end of the page in the Pinouts section is a good summary.

The recommended set-up with PoE is to use a PoE switch (which will most likely use "gigabit mode A" in the table) and a splitter with a built-in voltage converter. The splitter to use depends on the rPi model: for an rPi3 get a splitter that provides 5V on a micro-USB connector (example ), for an rPi4 get a USB-C splitter (example ), for a SensorStation get a splitter that provides 12V (example ). For a rPi4 it may be advantageous to use a splitter that supports PD (power delivery) so it outputs 5.1V, but those are more pricey and possibly overkill. The above links are intended as suggestions not recommendations as the longevity of these devices has not been tested, there are definitely more "industrial" versions available.

Overall, the important part is to ensure that the switch/injector and splitter match. Virtually all PoE switches in 2024 are Gigabit 802.3af (48V) compliant (or more advanced 803.2at/bt) and use "mode A" (see Wikipedia table). Using a "gigabit" and/or "802.3af" splitter ensures compatibility assuming it's properly made.

A common alternative that historically predates 802.3af is to use 2 wire pairs for 100Mbit ethernet and 2 pairs for 24V. This is still common in Ubiquiti equipment as well as that of other vendors, which perpetuates the confusion. In addition, this mode of operation is "covered" by 802.3af mode B, except that 802.3af requires 48V, not 24V. But 802.3af splitters as mentioned above should work fine with 24V too.

One catch with non-gigabit splitters (e.g. the 24V set-up) is that if they are used to connect two gigabit devices (switch and rPi) then it is often necessary to force the use of 100Mbps at one of the two ends, i.e. either using the switch web interface (in the case of a managed switch) or ethtool on the rPi.

Underpowered SensorGnomes typically work fine when set-up and it's later that problem crop up. Sometimes they reboot but more often some peripheral malfunctions. Often USB-attached devices restart on their own. In some situations the SensorGnome just seems "flaky" and a different problem crops up every time.

The easy cases to troubleshoot are due to inadequate components and installation problems because they tend to show up quickly. Check components, have spares to swap-in to verify against, check all connections and connectors.

The troublesome cases are when general wear and tear triggers the problem. This is because USB cables and power cables experience a fair bit of strain over their lifetime from repeated bending. The following problems have been identified at Motus stations in the past:

• The connection to the screw terminals on the DC-DC voltage converter is loose

• Individual copper strands within the USB cable are broken. This can occur from repeated bending of the cable.

• The microUSB port of the Raspberry Pi is damaged (lifts from the circuit board slightly when force is applied).

• Due to nightly deep discharges the off-grid battery can no longer reliably power the SensorGnome through the night.

The behaviour of underpowered devices can be inconsistent and hard to diagnose. In some cases, it is not possible to connect to the device because both Ethernet and Wi-Fi are malfunctioning, however it may still appear as though the device is on as the indicator LEDs will be blinking. This can also be due to corrupted data on the SD card or a physical connection problem with the SD card, so it's not always obvious.

In most cases, fixing the issue is as simple as replacing the Micro USB cable which plugs into the Raspberry Pi. It is also possible to swap out the DC-DC voltage converter to a device that is rated for more current and/or voltage (no more than 5.1 V, however!), but these have not been tested. See: .

Currently available (as of Nov 3, 2021) cables are listed below:

Currently available (as of Nov 3, 2021) DC-DC converters are listed below. Please note that these models have not been tested, but are expected to perform better the default model.

• The original SensorGnome software was written and maintained by John Brzustowski from 2016 to 2018 and was designed for Beaglebone and Raspberry Pi models 1 and 2 single board computers. It used an ingenious but very non-standard "liwixi" filesystem organization and was based on Linux Debian Buster. Communication with Motus servers used SSH tunnels in an effective but unconventional configuration.

• The SensorGnome V2 software is a complete rewrite of the system with the goal of supporting current Raspberry Pi models and using standard filesystem and communication methods.

• The V2 software:

  • uses a standard current Raspberry Pi OS image (based on Debian Bullseye as of 2023) that has SensorGnome software pre-installed

  • runs on Raspberry Pi3, Pi4, Zero-2W, and SensorStation V1 (more coming)

  • exclusively uses HTTPS for Internet communication (SSH commandline access over the LAN is also supported),

  • implements a new automatic upload mechanism that uploads data files directly to motus.org,

  • implements a new web UI with more functionality and security to manage the SensorGnome,

  • the new web UI provide easy options to download data files to a laptop or phone,

  • implements remote monitoring and management,

• The V2 software uses unmodified software to process radio data and detect tags in the local tag database, thus the data processing path is unchanged.

In this document you will find how to:

• assemble SensorGnome hardware

• install the SensorGnome V2 software

• connect to a running SensorGnome and perform maintenance tasks

• troubleshoot when things don't work

• Avoid getting frustrated: if it doesn't work, double-check, try again, perhaps try an alternative, but then ask for help! Don't waste hours of time.

• If you can, connect your SensorGnome to the internet and leave it running & connected: most of time the best troubleshooting happens using the log files it uploads.

• To get help:

A SensorGnome is an automated radio receiver, designed to detect and record radio signals transmitted by wildlife tracking tags, without the need for any person to be present.

At its core, a SensorGnome is powered by a Raspberry Pi (RPi). The RPi runs the software that listens for and records the radio data picked up by the antennas. In addition to the RPi, a SensorGnome will have one or more USB dongles -- "software-defined radios" -- that take the raw radio signals from the antennas and convert it into a digital form that can be recognized and recorded by the RPi. Finally, the SensorGnome will include a GPS and power supply, all of which is typically housed in a heavy-duty plastic case.

This guide is divided into three sections:

• Setup and operation: Initial software installation, configuration, data downloading, etc

• Hardware components: misc information about radios, USB, HATs, how to assemble an SG

• Appendix with additional information, resources, and troubleshooting tips

1. Install the software and configure the SensorGnome password

2. Connect to your SensorGnome

   1. verify GPS and time source

   2. Configure radios and their ports, verify operation using test tags.

The SensorGnome software runs off a MicroSD card. In order to install the software, it is "flashed" to the SD card using an imaging software such as Raspberry Pi Imager. After it is booted for the first time, it needs to be "initialized" by setting a password. The basic sequence is:

• Flashing the MicroSD card with the SensorGnome software

• Initial configuration, where you boot up the SG and set a password

• Connect to the SG and access its web interface, where you can confirm that it's running and configured properly. This last step is described in the

For now, refer to . The content there will eventually be migrated over to this guide.

The SensorGnome is best equipped with a GPS although this is not a hard requirement. The GPS performs two functions:

• it provides accurate time to timestamp tag detections

• it provides accurate station location even if the SG is relocated and no-one updates the metadata manually (common...)

If no GPS unit is present the SensorGnome can obtain the time from the network using NTP (network time protocol). This assumes an always-on internet connection. If neither GPS nor NTP are available the date&time will be completely unusable at the first reboot as the Raspberry Pi hardware does not have any real-time clock.

Cell modem GPS

If the SensorGnome is equipped with a cell modem then in the vast majority of cases it uses the generally built-in GPS unit. This does require connecting a GPS antenna to the cell modem and ensuring it has good sky view (and is not inside of a metal enclosure).

If the SensorGnome does not detect the GPS (check the Web UI overview tab) please post on the forum (ensure the SG is connected to the internet so it can upload log files).

If the SensorGnome detects the GPS unit but does not get a fix the problem most likely is the antenna or its placement. Note that some GPS units require an "active" antenna which has an amplifier (LNA) built-in and some don't.

The hardware installation of the Adafruit GPS should be documented in the "How to build a Sensorgtnome" section (which is empty at the moment).

From the point of view of making the GPS work: the GPS HAT contains a small eeprom chip that identifies the HAT to the operating system and the SensorGnome software sets everything up automatically. Note that stacking two HATs is not supported by the rPi as it breaks the HAT detection.

It is possible to connect a "generic" GPS breakout board to the SensorGnome. Please purchase from a reputable seller as many "U-Blox" GPS breakouts are fake and contain knock-off devices. A (genuine) U-Blox GPS is a good choice because it supports a fast binary protocol which gives good time synchronization without PPS (pulse per second) signal.

You can connect a GPS either via USB or serial. Connecting via USB is recommended and "it should just work", although if the web UI shows "no-dev" 5 minutes after boot then post for help on the forum. (It does sometimes take a couple of minutes for gpsd to detect and configure the GPS device and then the Web UI to figure that out, use gpsmon on the commandline to get quicker feedback.)

You can also connect via serial using 4 jumper wires. You will need to connect to the Raspberry Pi's GND, 5V, Uart-TX/gpio14, and Uart-RX/gpio15. Search for "raspberry pinout" and you will find many pictures that show the rPi connector pin assignment. The 4 pins you need to connect to are all next to each other on the outer row. Note that TX on the rPi goes to RX on the GPS module and RX on the rPi to TX on the GPS. In addition, if the GPS provides a PPS pin (Pulse Per Second) it can be connected to pin 7 / GPIO4.

After hooking up the GPS hardware you need to boot your rPi and SSH in. Then issue the commands (this will reboot the SG!):

To troubleshoot the GPS log in via SSH and run gpsmon, if you just get a couple of lines then gpsd (the GPS management daemon) is not talking to the GPS. Double-check your connections (especially RX-TX cross-over), ensure the SensorGnome is connected to the internet so it can upload its log files and contact the sensorgnomads mailing list with the ID of your SensorGnome. If gpsmon shows lots of GPS info that updates every second or two then your GPS is working fine.

Another troubleshooting avenue is /var/log/syslog: restart gpsd (sudo systemctl restart gpsd) and look at what it prints in /var/log/syslog. It goes through a number of devices, including /dev/ttyUSB0 and /dev/serial0. If you see an error for the device your GPS is using that may provide clues about what is going wrong.

For USB-connected GPS modules the tty device created may not be in the list scanned by GPSD. Use lsusb to verify the presence of your GPS device and ls -l /dev/serial/by-id to glean which ttyXXX port is used. Then edit /etc/default/gpsd to make sure it's in the list and restart gpsd (sudo systemctl restart gpsd).

In the US, the author has been successful with 2 purchases of the following GPS module available on Amazon: https://www.amazon.com/gp/product/B07P8YMVNT and the serial connection looks something like this (please use pinout diagrams! and oops, should have connected the PPS pin as well...):

Occasionally it's useful to "SSH into" your SensorGnome so you can run commands directly against the operating system, copy files and logs, and perform other tasks not possible from the SG web interface. Below are two examples for Windows.

Option 1: Using PuTTY

Most, but not all, newer versions of Windows include SSH capabilities without the need for additional software installation (technically, this is because it often comes with OpenSSH preinstalled.)

Why a disk image for the software?

The reason the SensorGnome release is distributed as disk images is that the system requires 2 disk partitions (two filesystems). One small FAT32 partition which the boot loader understands and can load the initial program from. And then one large partition that has a proper Linux filesystem that is way too complex for a bootloader and that the entire system runs from (and that "gets started" by that "initial program"). The image packs everything together (and is the standard way of doing these things).

Previous versions of SensorGnome had only one large FAT32 partition occupying the entire SDcard and instead of having a second partition for the linux filesystem they put that inside one big file within the FAT32 partition. So it was a bit like nested dolls. Technically that works, but the performance suffers because every filesystem access requires two levels of mapping and access, and it's very unconventional though creative.

Why does flashing require root/admin/superuser permissions?

In order to write an image to a disk one has to read/write to the raw disk, which inherently provides access to all the data that may be on the disk. That's a security issue in that it circumvents all the access controls that the operating system normally imposes on disk access. For this reason the operating system only allows the super-user/root/admin to access raw disk. And that's why Etcher (and any program that writes an image) has to ask for this permission.

Does the hot-spot turn on at boot time?

Currently the hot-spot always turns on at boot time. It can be turned on/off on the network tab of the web UI. It is planned to provide a switch to enable/disable it at boot, but for the moment to facilitate debugging the hot-spot is always on at boot.

What are hostnames of the form 192-168-0-18.my.local-ip.co for?

The local-ip.co host names have to do with HTTPS. A host name of the form A-B-C-D.my.local-ip.co resolves to the IP address A.B.C.D, this is how the connection is routed to the SensorGnome. The SensorGnome's web server holds a wildcard TLS certificate for *.my.local-ip.co which allows the user's web server to connect without warning or issues.

The wildcard certificate is issued by Lets Encrypt and has a validity duration of 3 months. This means that the certificate needs to be updated by some means, this is not currently implemented.

Browser support for self-signed certificates has been steadily shrinking. The warnings have been getting more dire and some browsers on some operating systems have eliminated support entirely. Initial testing with self-signed certificates resulted in lots of difficulties and confusion.

When the SDcard is initially flashed from the image there are two partitions/filesystems:

• a 256MB boot partition holding a FAT32 filesystem that is used in the initial boot stage.

• an approx 4GB rootfs partition holding an EXT4 Linux filesystem with the operating system, this partition cannot (easily) be mounted on a Windows system and may show up as empty or unused, but it certainly isn't!

• the rest of the SDcard is empty/unpartitioned.

When the SDcard is first booted a third partition is created:

• a large data partition filling the rest of the SDcard (e.g. about 26GB on a 32GB card) holding a FAT32 filesystem that is used to store the SensorGnome's config and data.

The Raspberry Pis do not have a real-time clock (RTC) chip that retains the time between system reboots or power cycles. Time is only kept while the operating system is running. The operating system writes the current time to a file every 11 minutes. At boot time, time is initialized to the last thus saved timestamp. As a result, until a fresh time synchronization happens (whether Network Time Protocol NTP or GPS) the SensorGnome thinks it did a quick reboot right after saving the time.

There are three ways the SensorGnome can synchronize time: NTP, GPS, or RTC chip. If the SG has internet connection it will start trying to synchronize via NTP. If the SG has a GPS (such as the Adafruit GPS HAT) it will synchronize as soon as the GPS signals a fix. If the SG has an Adafruit GPS HAT and the RTC built into that HAT's GPS module has the time (i.e. power was not lost or the battery is functioning) then the RTC time will be used.

Radio tag/pulse detections occur independently of time synchronization, i.e., the SG does not wait for time sync before starting the radios. For any detections that are made the name of the file in which the detections are save has a letter that indicates the time sync state. Specifically, if the letter at he end of the ISO timestamp in the filename is the std 'Z' then the time is synchronized, if the letter is a 'P' then it is not.

Note that in older versions of the software the timestamps of a SensorGnome without time syn were way in the past, such as pre-2010. This is no longer the case because it prevents HTTPS communication due to the fact that all certificates are flagged as invalid.

Introduction

If you are installing a station that detects Lotek tags, it is often useful to know whether it is able to detect tags in real time, particularly if you are deploying tags in the vicinity. Thankfully this is possible by loading a local tag database on to the internal storage of the device. When the SensorGnome boots up, it checks for a tag database and will display any of those tags it "hears" on its web interface.

Viewing your live tag detections can also be useful when deploying tags or as a make-shift manual tracking device when a Lotek receiver is unavailable.

This works by using a local version of the tag finder algorithm (find_tags_unifile) in comparison with the tag recordings provided during registration.

The local tagfinder differs from the version found on Motus, in some key respects:

• It is only aware of the tags that you have provided, so its candidate list is minimal. It might therefore assign raw data to one of your tags even if a more suitable candidate exists in the Motus database

• It does not use deployment period or estimated battery life to assign data to candidate tags so it might "detect" a tag that has been dead for many years

• It uses none of the on the Motus website (and in the R data)

All of this means that you will very often get different results on the local tagfinder as with data processed by the Motus server. Despite this, uploading a local tag database is recommended any time you are deploying tags.

1. Navigate to your and click the "Download tag database" button

2. Download the first option. This will contain all the tags currently registered to your project.

1. Connect to your SensorGnome via the WiFi hotspot and navigate to the "Radios" tab. Click "Upload new tag database" and select the .sqlite file you just downloaded. You should now see an updated summary including the new project and the number of tags you added.

In order to upgrade a SensorGnome an Internet connection is required as the SensorGnome pulls packages from a server on the Internet. Some thoughts about upgrades:

• if it ain't broke, don't fix it

• the standard upgrade process only updates SensorGnome software, almost all system software is left unchanged, this avoids ending up with a completely non-functional system due to a problem during the upgrade

• it is possible to perform a full system upgrade, but perhaps swapping in an SD-card with a fresh clean image is a better option, in any case, unless there is a specific problem this is supposed to fix see the first bullet point...

In order to detect CTT 434 MHz tags on a SensorGnome, you will need the appropriate dongle as FunCubes will not work for these tags. These are often referred to as "CTT Motus dongles."

1) Acquire the necessary components and files

• (2-3) (or similar), for securing Feather to case

Before you visit a SensorGnome, it's important to have a few key items and software on hand or on your computer. Some of these are absolutely essential while others can save you time and headaches in the future if you already have them with you.

1. A web browser device: either a laptop with WiFi or a smartphone (or laptop with Ethernet and cable)

2. The SensorGnome's password (SensorGnomes have one single password)

Wherever possible, SG's should be connected to the Internet for three benefits:

• Automatically upload data to Motus, resulting in more up-to-date data, fewer trips to visit a station, and more timely identification (and resolution) of any issues with the receiver.

• Remote monitoring of the SG's operation, including radio operation, SD-card usage, upload progress, detections, etc.

• Remote administration of the SG to perform necessary upgrades, enable/disable the hot-spot, reboot, etc.

The SensorGnome can connect to any standard WiFi network using the Raspberry Pi's built-in WiFi client. This is accessed and configured on the SG's web interface.

The simplest method of syncing data over the internet is to plug the RPi into the Internet via an Ethernet cable. If the internet is not password-protected and the SG can obtain an address via DHCP the SensorGnome should connect to the Motus server within minutes and begin syncing data.

Cellular connectivity is supported using the as well as the Waveshare SIM7600 series USB dongles.

Simply installing the HAT or plugging the SIM7600 device in should cause everything to magically function, provided the SIM you are using is activated and has a valid data plan. The SixFab modem kit has an integrated GPS, though in the case of the Waveshare device you'll need to purchase a simple (passive) GPS antenna with a u.Fl connector and plug it into the GPS port (you have to open the device as shown in the instructions provided by Waveshare).

If you are experiencing issues with cell connectivity, please refer to the section.

SG Hub, at , provides a convenient way to check on an internet-connected SensorGnome. Along with the most recent check-in time, there are a variety of other diagnostic and status plots to help asses the "health" of the various SensorGnomes.

Generally, within a minute or two of connecting for the first time, a SensorGnome will show up in the "Recently installed Sensorgnomes" list. You can sort this list by any of the columns, and click on any of the SGs for more detailed info about that particular SG.

When the SensorGnome connects to a WiFi, Ethernet, or cellular network it expects to obtain an IP address for itself and the address of a default gateway via DHCP. This is standard DHCP configuration but of course can be disabled/changed by the administrator of the local network.

Whenever the SensorGnome has a default gateway it:

• displays "internet via xxx" in the "internet via" widget on the network tab, where xxx designates the type of interface

• checks general internet connectivity and displays the result in the "Internet" widget

• checks connectivity to motus.org and displays the result in the "Motus.org" widget

• obtains an upload authentication token from a SensorGnome server

Once the SensorGnome operating system is up and running the various radio dongles need to be plugged in, configured, and their proper operation verified.

The configuration consists of mapping each radio to a "port" such that Motus can exactly identify which antenna received a tag transmission.

The verification consists of validating that a test tag transmission is detected, sent to Motus, and classified correctly.

Radio port configuration

The purpose of USB port mapping is to establish a clean correspondence between (human-readable) labels on USB ports, port numbers reported to Motus, and the port designations used by the SensorGnome software.

Background

Motus identifies ports using single digit integers from P1 through P9 and P0 (which stands for 10). It is recommended to physically label the ports on a SensorGnome in the same way from 1 through 10 (e.g. using marker pen, sticky labels, etc).

The Operating System uses an entirely different port numbering, which consists of the path through ports and hubs to reach a device. For example, a radio plugged into port 3 of a hub, itself plugged into port 4 of an rPi ends up with the path 1.4.3 (the leading 1 refers to the first root hub). We need to establish a mapping from these paths to port numbers 1..10.

The Motus conventions for the ports depend on the device:

• rPi3B: port 1 is the upper port next to the Ethernet jack, port 2 is below, 3 is the upper outer port, and 4 is the lower outer port. Typically a SensorGnome uses a USB hub plugged into port 4 (bottom outer port) and the hub's ports are numbered 4 through 7 or 4 through 10 depending on whether it's a 4-port or a 7-port hub.

• rPi4B: the numbering should be reversed so the USB hub is plugged into a USB3 port (the blue ports): port 1 is the lower outer port, port 2 above it, port 3 the lower port next to the ethernet jack, and port 4 above it. Plug a hub into this last port, i.e. top blue USB3 port.

• rPi Zero-2W: there is only one micro-USB port and the port numbering will depend on the type of hub used.

To perform the mapping follow these steps:

• Ensure all USB ports are labeled and all devices to be plugged in are also labeled.

• Bring up the SensorGnome's web UI and locate the "Port Mapping" section on the Radios tab.

• Unplug all USB devices (leaving any hub plugged in).

• Plug one device into the desired port,

The port mappings are deterministic when using the same model rPi and the same hub models, so the port mapping can be copied between identical devices.

In the end it is highly recommended to double check the correct port mappings:

• Verify in the Web UI "Devices" that all devices are assigned a port 1 through 10 (no port should be shown in red)

• Unplug each device in turn, watch the correct line disappear, plug it back in and watch the correct line with the correct port number reappear.

There are three frequencies worldwide that Motus-compatible Lotek tags broadcast on. The default configuration is set to the Western Hemisphere frequency so any SG or SensorStation deployed elsewhere needs to be configured to listen to the appropriate frequency for that region if listening for Lotek tags.

The frequency can easily be set via the Radios tab in the UI. Following the change, you can reboot using the buttons in the UI to confirm that the setting change is persistent.

To verify the correct end-to-end operation of radios some test tags are necessary. For Lotek tags a tag database with the test tags is recommended but not essential.

• Ensure at least one FunCube or RTLSDR radio is plugged in and shows in the Web UI Devices section with a port numbered 1 through 10 (i.e. not shown in red).

• Ensure the test tag is activated.

• On Web UI's radio tab watch the "Detection log" widget in the Web UI, when the tag transmits next you should see 3-4 lines of the form PLS: p5,1665900923.5965,3.96,-48.31,-60.86 PLS: p5,1665900923.6185,3.948,-48.76,-60.92 PLS: p5,1665900923.6380,3.986,-47.99,-60.94

• Ensure at least one CTT MOTUS adapter or equivalent is plugged in and shows in the Web UI Devices section with a port numbered 1 through 10 (i.e. not shown in red).

• Ensure the test tag is activated, or in the case of a solar LifeTag that it has bright light shining on it.

• On Web UI's radio tab watch the "Detection log" widget and you should see tag transmissions appear of the form TAG: T6,1665900910.226,78664C33,-95 The T6 refers to CTT radio on port 6, 1665900910.226 is the timestamp (seconds since 1970-1-1) 78664C33 is the CTT tag ID and -95 is the RSSI (dBm).

• As you plug radios into USB ports they should appear in the Web UI Devices section within 2-3 seconds. If they don't, reboot the SensorGnome. If that doesn't make them show up there is a software or hardware problem. Compare with what happens as you plug/unplug other identical devices if you have any.

• If a FUNcube is shown in the Devices section with a frequency other than the expected one (166.376 for north America) press the "Refresh Devices List" button. If that doesn't fix it TBD

• If the Devices look correct but the Live Pulses do not show anything first ensure your test tag is active. Some test tag intervals are long, e.g. 25 seconds, so have some patience. If nothing happens, reboot the SensorGnome.

In order to check the status of a SensorGnome, download data, or modify the configuration, you must first connect to it using a laptop or phone. The primary method is by connecting to a WiFi hotspot that the SG broadcasts (Option 1).

Option 1: Connect via WiFi hotspot

By default, a SensorGnome broadcasts a WiFi hotspot whenever it is powered on, assuming it is functioning normally. The WiFi hotspot only serves to establish a connection between the SG and your computer or phone; it does not connect the SG to the internet.

The hot-spot acts as a "captive portal", which means that it looks to your computer/phone like a WiFi network typical of airports or hotels where you have to enter credentials or accept an agreement to get internet access. However, the SensorGnome never actually provides internet access...

Some of the issues users have encountered are:

• a web browser automatically opens to show the SensorGnome's web UI, but it may be a special system browser and not your regular browser (on iOS that browser seems not to show certain charts)

• your computer/phone may become "impatient" about not getting internet access and decide to switch back to your regular WiFi

• if using Android, your phone may use the cellular network instead of the hotspot and you most likely have to turn cellular/mobile off

In many cases the hot-spot "just works" but being aware of the potential issues helps.

If you get stuck and "it doesn't work" check that your computer/phone is still connected to the hot-spot. You can also connect to the SensorGnome using your favorite browser at http://192.168.7.2 to avoid the system browser.

When a device connects to the hot-spot it detects that there is no internet connection (because the hot-spot only provides access to the SensorGnome ). It then assumes that this is a "captive portal", which means that the user has to connect to a specific web site to log in or agree to some legal terms before getting internet access. This is typical of WiFi in public locations, e.g. airport, hotel, or coffee shop.

In order to facilitate the required login or acceptance of terms your device starts a web browser which connects to the SensorGnome's web UI. This usually works well and allows you to use the UI. However, depending on the device and on other available WiFi networks you may run into issues. The main cause for issues is that your device expects to eventually get internet access but the SensorGnome will never provide that, so your device may take actions in an effort to restore internet access. Specifically, your device may decide to disconnect from the SensorGnome hot-spot and connect to some other network, such as a previously working one.

Tips:

• If your device prompts you with a message stating that this network does not provide internet access and whether you want to stay connected anyway choose the option to stay connected.

• If the web UI stops working, check whether your device disconnected from the hot-spot and connected to a different network. If so, reconnect to the hot-spot.

• Ensure you have no VPN active

• The web browser used in the captive portal mode (i.e. to allow you to log-in or accept terms) may not be the regular web browser you use on your device. If it does not work well or is closed on you open your standard browser and try

With a computer, you can connect directly to your SensorGnome with an Ethernet cable. This can be helpful if you are having difficulties with the WiFi hotspot, but the SG itself still seems to be running properly based on the green LED pattern.

If your computer and/or smartphone are connected to the same local network as your SG (e.g. connected to the same router, whether by WiFi or Ethernet) you should be able to access your SensorGnome by the hostname sgpi.local.

If your SensorGnome and your laptop/phone are both connected to the internet and on the same WiFi or Ethernet network, you can connect to it this way. This can be helpful in cases where the WiFi hotspot method described above is not working.

1. First: verify that your SG's green LED shows 3 flashes every 2 seconds. If it doesn't, your RPi SG does not have internet access.

2. Open the SensorGnome Hub (SGhub) website at , logging in with your Motus user name and password when prompted.

3. The table at the top shows the most recently initialized SensorGnomes: yours may already be at the top! You can identify it using the label column which should show the hostname you entered.

1. Click on the row with your SensorGnome, this switches to the station tab; at the top-right is a link to the web UI:

1. If you have already configured your SG with a password, enter it when prompted. If this SG has not yet been initialized, you'll have the opportunity to set its password here.

You are now connected to the web UI

1. File types

1a. SensorGnome format

This format is the default for units running the SensorGnome software (including for the SensorGnome component of the SensorStation). Each file contains individual pulses, gps readings, etc. The data can also be separated for each antenna, as well as for LifeTag detections only (type = ctt).

Filename format: <site_label>-<receiver_number>-<boot_num>-<datetime><prec>-<type>-<ext>.gz

Example:    changeMe-3114BBBK2178-000074-2018-01-22T00-29-13.3300T-all.txt.gz
        changeMe-3114BBBK2178-000074-2018-01-22T00-29-13.3300T-ctt.txt.gz

site_label: user-entered site label (default: changeMe)
receiver_number: for SensorGnomes, receiver serial number (without the SG prefix, e.g. 3114BBBK2178)
         for SensorStation, receiver serial number (with the CTT prefix, e.g. CTT-123456789012345)
boot_num: boot number
datetime: yyyy-mm-ddTHH:MM:ss.ssss
prec: single digit representing the clock precision:
    P: clock not set by GPS
    Z: 1 second
    Y: 0.1 second
    X: 0.01 second
    W: 0.001 second
    V: 0.0001 second
    U: 0.00001 second
    T: 0.000001 second
type:     all (for all antennae), specific antenna number or ctt (ctt and gps data only)
ext: extension (typically txt)            
gz: indicates compressed files (other types of compressions are also supported: bz2, etc.)

1b. SensorStation format

This format is the default for units running the SensorStation software. Data components are divided separate files: data, node data and gps. Data contains the 32-bit codes interpreted by the CTT dongles, node data contains detections from external node units and gps includes gps readings (only for the base station so far, not for nodes).

File format: CTT-<serial>-<data_type>.<datetime>.<ext>.gz

Example :    CTT-867459049219777-data.2019-07-18_191832.csv.gz
        CTT-867459049219777-node-data.2019-07-18_191832.csv.gz
        CTT-867459049219777-gps.2019-07-18_191832.csv.gz

serial : 15 digit numeric (old) or 12  digit alphanumeric value (new)
data_type : one of data, raw-data (same as data), data-node or gps
datetime : <yyyy-MM-dd_HHmmss>
ext : csv only so far
gz : indicates compressed files

1c. Lotek format

This is the default format used by Lotek units. Each file contains a header and individual tag detections (not pulses, only putative tags). There are other formats available for export from the Lotek units (e.g. binary), but we require the DTA format.

Filename format: <filename>.DTA

Example : OldCut0001.DAT

filename : any arbitrary value provided by the user

Filename: the file name is entirely determined by the user and doesn't contain useful information about its content.

2. File content

2a. SensorGnome format

The following prefix can be found in SensorGnome files. Files of type ctt will only contain T and G prefix.

C : (GPS clock setting precision record: outlines the time the GPS was set (ts), the precision it was set to (prec), and the time elapsed in running the time (elapsed))

G : GPS data entry

p : individual pulse on FunCube Dongles

S : frequency setting record (see fields below for possible name values)

T : LifeTag hit on CTT/CVRX dongle or SensorStation

Fields:

SensorStation (LifeTag) files will contain headers specifying their content. No assumptions should be made about the order or the list of fields included within those files. The formats below are those currently in use at the time of this document.

data (or raw-data) files:

node-data files: meta information about the nodes

gps files: gps readings of the base station

Data segment: individual tag detections. We request that users export their DTA file using GMT times, but there is no guarantee. Hopefully, newer versions will format dates as ISO 8601 to include the time zone.

Cell modem power

Almost all cell modems compatible with SensorGnomes use a lot of peak power and they exceed the power capabilities of RPi 3B and 4B USB ports. You must:

• use a cell HAT or a USB cell modem plugged into a powered USB hub, never attempt to power the cell modem from the RPi USB ports (a cell HAT needs to be plugged into USB for data, it doesn't receive power through the cable, however)

• use a 20W power adapter (a good 15W may work)

• use short, quality USB power cables

If the cell modem does not have enough power it will seem to work fine but not connect to the network. This is because it has plenty of power while idle but experiences voltage sags when trying to transmit causing the output signal to drop or fail to modulate correctly.

If you use a cell HAT it is easy to overlook that it came with a short USB cable. The 40-pin connector of the RPi provides power and some low-level controls (e.g. to detect that a cell HAT is installed). However, the cell modem is fundamentally a USB device: all the data goes over USB. Thus you must use the USB cable to connect the HAT to one of the USB ports.

You can reset all the software on the SensorGnome by rebooting, however, this has only a minor impact on the cell modem. It can help if there are errors at the USB level in communicating with the cell modem. The only way to fully reset a cell modem is to power cycle it, which in the case of a HAT means power cycling the rPi.

Most problems occur when starting cell service, i.e., placing a fresh SIM card into a cell modem and powering it up. When a connection does not get established quickly there may be a problem or you may simply be underestimating how slow things can be. Have enough coffee or tea handy to keep you awake, or better, plan on a couple of brief testing sessions per day over a couple of days. Or at least plan your day so you can let the modem do its thing for an hour a couple of times. Letting it noodle away over-night when it's in an enabled/registering or enabled/searching loop is not an unreasonable strategy...

• Many SIMs sold for SensorGnome type of usage work globally or continent-wide across many providers and many frequencies. This is a large space for the modem to scan and attempt to get service, either from "native" networks or via roaming.

• The cell modems used for SensorGnomes and the software are not as sophisticated as cell phones. Things take more time.

• The "Super SIM" made by Twilio (and resold by SixFab among others) has multiple personalities used for different regions of the world. It switches personality after failing to connect for a number of minutes. You may be waiting for it to fail using the AsiaPac personality, then the China personality, then the South America personality, then...

In order to properly cycle between the various regional profiles (IMSI) the modem requires SIM Toolkit (STK) to be enabled. This is the service that "listens" for when the SIM requests a new IMSI after failing to with the previous one. If Sim Toolkit is not enabled, a cell modem may indefinitely try to connect with the same unsupported IMSI. For many modems, Sim Toolkit is disabled by default.

The command differs somewhat depending if you are using a Quectel or Telit modem. If you can see the SG and the modem, you'll be able to see the name of the modem manufacturer printed on it.

The following commands are made via an SSH session. Copy and paste the code as needed into the terminal, entering the SG password when prompted.

For information SSH'ing into your SensorGnome, visit .

If your cell phone uses a physical SIM (as opposed to an eSIM) and your SensorGnome cell modem is in a enabled-searching-registering endless loop (i.e. doesn't manage to connect) you can try your cell phone's SIM in the SensorGnome. You probably need one of those cut-out SIM size adapters because your phone most likely uses the nano size while the modem uses the micro size. If your phone's SIM provides service you know that the SIM or it's service is the issue (or the carriers it has access to don't cover your spot).

Note that in the US the phone SIM may not work or only work briefly if it uses the Verizon network 'cause of "approved devices" nonsense. AT&T may have some such issues too.

You did activate your SIM, right? Most SIMs used for data-only service as typically used in SensorGnomes have some form of activation performed on some web site.

The SensorGnome software does not interact with the cell modem a whole lot. The sg-control service, which is the main data processor and also provides the web-ui, primarily queries the ModemManager every few seconds to update the state of the cell modem in the web ui.

A check-modem service also checks on the modem state and if it is not connected asks it to connect every few minutes. It tries to balance the need to let the modem "do its thing" trying to find a cell provider vs. ensuring that the cell modem doesn't give up and just sits there idle. Unfortunately there is no status indication for when it's still trying vs. has given up.

Once the cell modem connects everything happens automagically through a set of standard Linux services and the ModemManager. An IP address is acquired, a route to the internet is established, and its priority is such that Ethernet and then WiFi take precedence if they're available.

The Web UI has fairly simple info about the cellular connection. It does not allow any actions to be taken. The reason is that there isn't much that can be done without a lot of information and knowledge. Cell modems are very complex (they run a full Linux operating system) and do their thing on their own. For the SensorGnome use-case they either work, or take time to work, or don't work and when they don't work it's very difficult to figure out where the problem lies.

The SensorGnome Web UI's network tab has a panel for cellular connections:

This screen shot shows a modem that is successfully connected. The first item to look at is that state: the (i) brings up a brief explanation of common states. If the modem doesn't connect it often says "enabled" but then cycles through "registering" or "searching" over the course of a minute or two.

When connected ensure that the SensorGnome got an IP address:

In some situations the modem may also show a list of providers at the bottom of the panel. This at least indicates that "something is working".

Ensure that the config box has the correct APN for your SIM provider. You should have gotten the APN when you purchased the SIM or it may be available on the SIM provider's web site.

The cell modem initially connects to a cell network and then it needs to tell the network where to route the packets so they can be billed before they enter the internet at large. This is what the APN does. For example, you may have a French Orange SIM and use it in the US. The modem may connect to AT&T's cell network on roaming and AT&T needs to be told to route packets to/from Orange in France. Orange will count the bytes for billing before forwarding to the internet and may apply rate limiting depending on the contract. Often, however, the SIM works even if an incorrect APN is specified because it has a default APN built-in...

The roaming flag should be on in almost all cases. It is only useful if you need to ensure the SIM doesn't roam due to cost ramifications.

The ip-type should be ipv4v6 in almost all cases, allowing both IPv4 and IPv6. There are some budget IPv4-only SIMs that may need an "ipv4" setting.

Some more detailed information can be obtained via the command line through SSH. (From bitter experience, it is also easy to get lost in undecipherable LTE details and not accomplish much of anything...)

The modem is managed by the Linux ModemManager. The first step is to list the modems (there should be only one) to get the numeric ID of the one installed (typ. zero but can be other if it gets reset or the USB cable is messed with):

The number of interest is after /Modem/. The general info and state of the modem can be queried using its id:

Other than info like the specific cell modem model the status section reveals whether it thinks its connected:

Also of interest is the operator info as well as whether a bearer is connected. The bearer "carries the internet packets" over the cell connection:

The bearer can then be queried for specifics (the bearer ID increments each time the cell modem looses service and reconnects):

To check that Linux has hooked everything up the best is to check that it has a route and then try it out:

This means linux thinks it can route to the internet at large (the "default") via the cellular network device (wwan0, or for some modems usb0). You can now try it out by pinging 1.1.1.1 (cloudflare dns service) using that device/interface:

The GPS in most cell modems has to be explicitly activated. This is something done at boot time by a SensorGnome script, which also finds out which USB serial device corresponds to the GPS and then allows gpsd, the GPS daemon, to listen to it.

Warning: due to a mis-feature in ModemManager it is not possible to activate the cell phone's GPS if no SIM is present in the cell modem. A cell connection is not required but a SIM is.

The ModemManager can provide info on the GPS status and activation from the modem's perspective:

The key is to see gps-nmea as enabled. It is unclear what "signals: no" means as in this case the GPS has a 3D fix...

In the status result of the mmcli -m 0 command mentioned above there is a section System > ports which lists all the serial ports provided by the modem and one of them should say gps, often it's /dev/ttyUSB2. If all went well then /dev/ttyGPS should be a symlink to that serial port:

The best way to check further is to run the gpsmon utility which connects to gpsd to query GPS data:

This shows that the GPS has a fix and the lines with a $GPG prefix scroll by as the GPS reports position and time updates. If gpsmon just shows some cryptic info (JSON) and stops it may be worthwhile to restart gpsd using sudo systemctl restart gpsd.service

Note that the GPS info in the web interface is entirely dependent on gpsd so if gpsd (e.g. observed via gpsmon) doesn't know about the GPS then the web UI can't show anything. Gpsd only knows about a GPS after it receives and can parse some stanzas.

If the SensorGnome is connected to the internet, it automatically uploads data to Motus and manual downloads are not required. For non-internet-connected SGs, there are two main methods of manually downloading the data to your computer in order to upload it to Motus.

Both methods are possible on either a computer or smartphone. You must first connect to SG via its WiFi hotspot.

On the SG web interface, navigate to the Files tab. The SensorGnome keeps track of which files have been uploaded to Motus servers and which files have been downloaded to a computer using the web UI.

• the red Download button produces a ZIP archive with all files that have not been previously downloaded

• the All button produces a ZIP with all files

The SensorGnome (SG) software is open source and available for audit at:

• https://github.com/tve/sensorgnome-control (web interface and uploader)

• https://github.com/tve/sensorgnome-support (system services)

• https://github.com/tve/sensorgnome-build (system image build)

The overall strategy employed can be summarized as follows:

• leverage as standard an OS image as possible

• limit protocols to SSH and HTTPS

• enforce the selection of a reasonably strong password at configuration time

• use a single password for the system to avoid "password fatigue"

• The SG base image is a standard Raspberry Pi OS image, i.e. Debiean Bullseye as of 2022.

• The image uses the standard repositories, plus and additional repository for the SensorGnome software.

• The Raspberry Pi foundation does not publish security updates like Ubuntu does, for example. Thus it is not possible to auto-install just security updates. However, security fixes are promptly made available in the general repo. It is thus possible to enable automatic "full" updates, but the system stability of doing so is unknown.

• SensorGnomes use a non-standard 'gnome' linux user and users are forced to provide a password when first deploying a SensorGnome (the software does not work unless a password is set).

• The password is checked against a "top 100k passwords" list.

• It is possible to use SSH keys and disable password login using standard linux procedures.

• The SensorGnome supports or four network interfaces: ethernet, wifi client, wifi hot-spot (access point), and, if installed, cellular.

• The SG never forwards (routes) packets between the interfaces.

• The ethernet interface uses DHCP and is the preferred interface for internet access.

• The SG uploads new data automatically approximately every hour via HTTPS to a Motus server (port 443). This assumes internet connectivity via one of the ethernet, wifi client, or cellular interfaces.

• Network connectivity (when a default route is provided via DHCP) is probed by connecting to http://connectivitycheck.gstatic.com/generate_204, which is one of the standard Android connectivity check addresses.

• Users can manually trigger an upload using the web interface.

• port 22 (SSH): SSH access, root login disabled, only user 'gnome' access.

• port 80 (HTTP): redirect to port 443 (HTTPS), except on the hot-spot interface where the Web UI is accessible via HTTP (security being provided by WiFi WPA2).

• port 443 (HTTPS): web interface to monitor SensorGnome status and perform configuration changes.

• Due to the fact that a SensorGnome needs to operate without having a public DNS name it cannot use "normal" public HTTPS certificates (e.g. from Let's Encrypt). Instead a wild-card certificate *.my.local-ip.co is used and HTTPS links have the form https://1-2-3-4.my.local-ip.co where 1.2.3.4 is the SG's local IP address. See for details and rationale.