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.

Raspberry Pi

Models

• 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.

• rPi 5 is not currently supported due to the fact that it requires a 64-bit operating system build and corresponding 64-bit application builds, which are not currently set-up. The rPi 5 hardware does not offer any benefits (at least none we know of) and it's more expensive and uses more power.

• rPi 1 and rPi 2 versions are not supported due to the fact that their processors cannot run the operating system version used for Sensorgnomes V2.

Ports

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!

Raspberry Pi 3B/3B+

Raspberry Pi 4B

SD-card slot

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

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

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 fresh software card.

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.

GPS

Fully assembled RPi SensorGnome

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.

For now, refer to https://www.instructables.com/Raspberry-Pi-SensorGnome/#solder. The content there will eventually be migrated over to this guide.

What is the boot number?

The boot number is a cumulative marker of how many times a SG has rebooted. It is represented in the file name as well as the web interface in the V2 SensorGnome.

The boot number is an essential component when processing detection data as it can account for bad timestamps (when the GPS reports an incorrect date/time) and for stringing together long detection runs that overlap multiple uploaded batches. Because the tagfinder algorithm works under the assumption that the boot number always increments, issues can arise when the boot number is reset.

When is the boot number reset?

When upgrading a SensorGnome's software with a newly flashed SD card, the boot number in the file names will be reset to 0. This applies to V2 SG with a card that's been flashed with the software, V1 SG where the software files have copied to a new card, and SG running on BeagleBones. Since this will violate the assumption that the boot number always increments, this may result in missing or false detections until the .

How to update the boot number

Before updating the software, connect to the SensorGnome and visit the web interface. From the landing page, you should be able to see the current boot number (as the screenshot above shows).

Navigate to the "software" tab, and on the lower right select the "edit" button (the one that looks like a pencil) to update the boot number.

Feel free to set the number slightly higher than necessary then reboot the SG and confirm that the change has persisted when you connect again.

• 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.

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.

Adafruit GPS HAT

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.

Discrete GPS unit

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!):

sudo tee /etc/sensorgnome/force-hat <<<"Ultimate GPS HAT"
sudo reboot

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...):

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.

What to bring

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)

3. Location of any hotspot-enable button

4. Network information to connect to the Sensorgnome if you will not be using the hotspot (hostname or IP address and local Wifi password, etc)

5. Information about antennas, cables, dongles/radios, and ports: which antenna corresponds to which cable, which dongle it should be connected to, and which port it should be plugged into

In addition...

• A Lotek test tag and a CTT test tag to perform an end-to-end verification of the system

• An SD-card prepared with the latest version of the Sensorgnome software

Connecting to a Sensorgnome

The Sensorgnome is managed through its web interface which is generally accessed using the Sensorgnome's hotspot. Alternatively, it is possible to use an Ethernet cable or to connect to the building's WiFi if the Sensorgnome is connected to it as well.

Blinking LEDs

If you can see the Raspberry Pi board it is helpful to first check its two LEDs. These are near the power connector (USB cable) and diagonally opposite the Ethernet jack: a red one and a green one. The red LED should be solid on indicating that power is on. The green LED should be flashing 1x, 2x, or 3x every 2 seconds:

• 1x: operating, hotspot off, and no internet access

• 2x: operating, hotspot ON, no internet access

• 3x: operating, internet access OK (hotspot may be on or off)

Hotspot connection

Many Sensorgnomes keep the Hotspot on 24x7. Open the internet or wifi settings on you laptop or phone where it scans for available networks and locate one with the Sensorgnome's ID, i.e. something of the form SG-1234RPI4ABCD.

Some Sensorgnomes turn the hotspot off and have a button to press to enable the hotspot. Typically this button is accessible from outside the enclosure.

Connect to that network, enter the password, and use the web browser that typically pops-up.

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 Hot-Spot 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 first check that your laptop/phone is still connected to the hot-spot and once it is connect to the Sensorgnome using your favorite browser at http://192.168.7.2 to avoid the system browser.

Using a WiFi or Ethernet network

Some Sensorgnomes may be connected to the local building/campus WiFi or Ethernet in which case you will need to connect your laptop/phone to that network too. You may then be able to access the Sensorgnome at http://sgpi.local but in many cases you will need to know the Sensorgnome's IP address (like http://192.168.1.1).

Over a WiFi network or Ethernet the Sensorgnome uses HTTPS, i.e. encryption. If you access it using HTTP you will see a redirect page that shows a link like:

This link, using my.local-ip.co is there to make the certificate check used by HTTPS work. However, if you r Sensorgnome is not regularly updated the certificate may be out of date and you may have to jump through hoops to make your browser proceed. (This is why it's typically easier to use the hotspot.)

Downloading the data

If the Sensorgnome is connected to the internet it automatically uploads data to Motus and manual downloads are not required, except for the paranoid ;-) . You can check the status on 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 Repeat button re-downloads the previous download (in case an error occurred)

• the Upload button kicks-off an upload to Motus, useful if the Sensorgnome has temporary internet access through your phone, for example

The downloaded ZIP files can and should be uploaded as-is to Motus using the Motus web site. If the Sensorgnome uploads directly then manual uploads are redundant but not harmful.

Checking the Sensorgnome's health

On the home (leftmost) tab:

• check that the time source is as expected, e.g. NTP (network time protocol) or GPS

• check that the boot time makes sense (some Sensorgnomes reboot daily in winter due to power constraints but generally they should remain on all the time)

• check the SD-card usage

• check that the GPS has a fix, unless the Sensorgnome doesn't have a GPS. "No-sat" means there is a GPS but it has no fix: that's often a problem

On the Radios tab

• Check that the radio number match up with what's installed and that there are no invalid ports

• Check that the ports (in the port mapping, e.g. 1, 5, 6, 7 in this screen shot) are as expected

• If you have test tags with you observe their detection in the panel on the right, here port 5 detects Lotek pulses

Troubleshooting

• If devices are missing, e.g. GPS shows no-dev or radios that are evidently plugged in are not showing up the first step should be a reboot (on the Software tab).

• ...

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.

Option 1: Wired internet over Ethernet

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.

Steps:

1. Connect an Ethernet cable that is non-password-protected to the SG.

2. Confirm that the SG has connectivity in its Web UI or on the Sensorgnome server.

Option 2: WiFi Client

Connecting over a WiFi network is also an option by configuring the network's SSID and typ. password in the SG's web UI.

Steps:

1. Connect to the Sensorgnome's web UI, e.g. using its hot-spot.

2. On the network tab enter the WiFi's SSID and password into the WiFi Client widget (and click the green checkmark). (Changing the country code from 00 to your country's two letter ISO code, e.g. US, CA, DE, et. is optional and unlikely to change anything, code 00 is a "lowest common denominator".)

3. Confirm that the SG connects to the network and obtains connectivity to motus.org.

Option 3: Cellular

Cellular connectivity is supported using the Sixfab 4G/LTE cellular modem kit/HAT 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. In the case of the Waveshare device please 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).

More information forthcoming...

Automatic uploads

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

• uploads data files to motus.org as soon as they are complete, i.e., the next file is started, which typ. happens once an hour

• uploads any old data files that have not been previously uploaded

Known issue: authentication

Authentication with motus.org is necessary to perform the uploads and the exact mechanism is still in flux. Currently three mechanisms are supported, they all "get the data to where it needs to go" but have issues. Motus server back-end functionality needs to be enhanced to remove these issues.

Note: option 1 is recommended, although you may want to implement option 2. Option 3 was coded first in the Sensorgnome software and remains available until final resolution of the authentication mechanism.

Option 1: automatic token

If you do nothing, the SG obtains a token from a Sensorgnome server and uploads data as user sg-uploader into Motus project 460. You will not be able to see the upload jobs in your project but you can verify that they occur by looking at the receiver. (Details TBD.)

Option 2: give sg-uploader access to your project

If you start with option 1 you can, at any time, add the sg-uploader user to your project and give it "update" access only to "data", all other permissions can be none:

The result of this is that the upload jobs will be part of your project and can be seen like any manual data uploads.

Option 3: enter your Motus creds

You can also enter your Motus login credentials into the SG web UI on the files tab. This causes the SG to obtain an authentication token directly from motus.org and use that to upload files. Your login user/password are not stored anywhere, only the token is. The token is periodically refreshed and remains valid for 45 days if the SG cannot connect to the internet for such a refresh. If it times out, the SG reverts to option 1 until Motus credentials are again entered.

Introduction

FUNcube Dongles are a component used in and for listening to tags developed by . They were originally developed as a teaching tool for satellite communications and have been repurposed for many custom radio projects.

The firmware loaded onto the FUNcube Dongles by default is incompatible with the SensorGnome software. Differences in hardware and plugin frame rates result in odd behaviour that often goes uncaught. Sometimes it will take a minute or two before this can be seen on the SensorGnome Web Interface. The image below shows FUNcubes with the wrong firmware tuned to the incorrect frequency.

Here I will explain how to correct this problem by reimaging the FUNcube dongle.

This guide is a simplified form of .

FUNcube Dongles tuned to the wrong frequency (left; ports 1 and 2) compared to after they were fixed (right).

Supplies

• FUNcube Dongle Pro Plus.

• Laptop or desktop computer.

Downloads

Steps

1. Download and unzip the above software.

2. Plug the FUNcube dongle in and run the frequency control program.

3. You should see something like this:

4. Click on ‘Switch to bootloader’. You should get an error in the box, but ignore it and just close the program.

5. Open the bootloader program you downloaded and unzipped previously. You should see the following text acknowledging the FUNcube dongle has been recognized:

6. Click ‘Open file’ and select the FUNcube dongle firmware you downloaded previously.

7. Click ‘Write firmware’. The program may freeze for a moment as firmware is being written.

8. Once complete, you should see the following message:

9. Click ‘Exit’ and unplug the FUNcube dongle from your computer.

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. Note that this local version differs from the version found on Motus, mainly in that Motus searches for tags from all projects across the network (but only those known to be actively deployed during the given time period) whereas this method will only compare raw radio data with the tag patterns it has been provided, regardless of deployment period.

Steps

1. Download the tag database from your project's tag management pages on Motus.

   • If there are multiple files to choose from, pick the last file in the list for the most recent set of tags.

2. Connect to your SensorGnome with a computer using 'root' as both the username and password and navigate to the ubootfolder.

3. Rename the files SG_tag_database.sqlite with the suffix ‘old’, or delete them all together.

4. Copy the tag database you just downloaded from motus.org into the uboot folder. Rename the file to SG_tag_database.sqlite

5. Reboot the SensorGnome.

6. Load the SensorGnome's web interface and scroll down to near the bottom of the page where it says "Tag Database" and verify the list of tags includes tags from your project.

You are done! You can now view the "live known tags" pane at the top of the page to check whether your tags are being detected by this station.

Merging multiple tag databases into one

Tag database files are organized by yearly quarter, so tags that were registered in different quarters of the year will be provided in different files. As only one tag database can be loaded at a time, multiple databases will have to be merged into one prior to loading on to the SensorGnome. You can use or modify the script below to merge multiple databases in R.

### merge tag databases ####
# This function accepts a vector of file names 
# corresponding to the various tag databases to be merged. 
# It saves one tag database containing all the source dbs
# named 'SG_tag_database.sqlite' for copying onto a SG
# It also returns a data frame with the results for visual overview

merge_dbs <- function(db_list, out_db = 'SG_tag_database.sqlite'){
  library(RSQLite)
  
  out_df <- data.frame()
  
  # loop through the list of tag dbs to be merged
  for (i in db_list) {
    message('Processing ', i)
    # establish SQLite connection to the current tag database
    con <- dbConnect(SQLite(), i)
    # select all from the tags table of the tag database, as a data frame
    df <- dbGetQuery(con, 'SELECT * FROM tags')
    # bind (append) the resulting rows to the consolidated out_df data frame
    out_df <- rbind(out_df, df)
    # disconnect from the source tag database
    dbDisconnect(con)
  }
  
  # open a SQLite connection to your output file
  outdb <- dbConnect(SQLite(), out_db)
  # write the results to the new consolidated tag database
  # This will overwrite any existing SG_tag_database.sqlite file 
  # if one already exists in the target directory
  dbWriteTable(outdb, 'tags', out_df, overwrite = T)
  # close the connection to the new consolidated tag database
  dbDisconnect(outdb)
  
  message(length(db_list), " tag sqlite files merged into ", out_db)
  
  return(out_df)
}

# An example of how to use this function...
# Call the function and pass in the paths of the tag databases to be merged.
merged_db <- merge_dbs(c('D:/Downloads/project_322_2020-2_tag_database.sqlite',
                         'D:/Downloads/project_322_2021-2_tag_database.sqlite'))

View(merged_db)

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.

Powering the Raspberry Pi

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.

Using Power over Ethernet (PoE)

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 https://www.amazon.com/gp/product/B07CNKX14C), for an rPi4 get a USB-C splitter (example https://www.amazon.com/UCTRONICS-PoE-Splitter-USB-C-Compliant/dp/B087F4QCTR), for a SensorStation get a splitter that provides 12V (example https://www.amazon.com/gp/product/B0CL2CBS75/). 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 Sensorgnome - how does it occur?

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.

• Due to humidity and heat-cycling connectors become unreliable.

Identifying an underpowered Sensorgnome

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.

Fixing power supply issues

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: DC-DC Voltage Converters for Raspberry Pi (not tested).

USB Micro B Male cables for power delivery

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

DC-DC Voltage Converters for Raspberry Pi (not tested)

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.

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...

• If updating with a fresh image, be sure to update the boot number to maintain the proper sequence.

Upgrade Process

The upgrade process is managed using the SG Web UI's software tab shown below. The functionality first needs to be enabled with the enable buttons toggle. The next step is to run a software update check (red check button). In the situation shown one Sensorgnome package can be updated and many operating system packages. The red sg upgrade button starts the upgrade of just the Sensorgnome packages, which is the recommended action. Upgrading all the OS packages can have unintended issues.

Upgrading from V2.0-RC12 or prior to later versions

Due to the expiration of the software repository signing key manual intervention is required in order to upgrade from V2.0-RC12 or prior (version 2023-XXX on the software tab) to the latest versions. In order to update the repository key the following command must be executed on the Sensorgnome (i.e. SSH to the Sensorgnome):

sudo curl -L -o /etc/apt/trusted.gpg.d/sensorgnome.gpg https://sensorgnome.s3.amazonaws.com/sensorgnome.gpg

Note that this command is one line even though it may appear wrapped in this manual!

After issuing this command (you should see messages showing the key being downloaded) the regular upgrade procedure will work.

Upgrading from v2.0-RC8 or v2.0-RC6

This upgrade requires patience because the code in those versions could not deal with some of the changes that are required and thus a "double-upgrade" happens under the covers. Please follow this process:

1. On the software tab, "enable changes"
2. Run "check", have a minute of patience and you should see available updates. If it doesn't seem to complete run "check" again
3. Run "sg-upgrade" and monitor the log (or get a tea/coffee for 2-3 minutes), after a couple of minutes the log will seem to be done (scroll down in the widget), showing:
4. Wait another minute and you may notice the green LED on the rPi stop blinking for a bit as it reboots, then reload your browser tab (you may have to reconnect to the hot-spot if you're using that to access the Sensorgnome), you should see a prompt to verify the SG password, if not, wait another minute and reload the browser tab again:
5. After entering the password the web UI should load, however, it may take a while (20-30 secs) and you may have to reconnect to the hot-spot again (sorry). On the software tab confirm that you are now running version 2023-115 or later

Updating the boot number

What is the boot number?

The boot number is an incremental marker of how many times a SG has rebooted. It is represented in the file name as well as the web interface in the V2 SensorGnome.

The boot number is an essential component when processing detection data as it can account for bad timestamps (when the GPS reports an incorrect date/time) and for stringing together long detection runs that overlap multiple uploaded batches. Because the tagfinder algorithm works under the assumption that the boot number always increments, issues can arise when the boot number is reset.

When is the boot number reset?

When upgrading a SensorGnome's software with a newly flashed SD card, the boot number in the file names will be reset to 0. This applies to V2 SG with a card that's been flashed with the software, V1 SG where the software files have copied to a new card, and SG running on BeagleBones. Since this will violate the assumption that the boot number always increments, this may result in missing or false detections until the receiver data is reprocessed.

How to update the boot number

1. Before updating the software, connect to the SensorGnome and visit the web interface. From the landing page, you should be able to see the current boot number (as the screenshot above shows). Write this number down or otherwise commit it to memory.

2. After you have upgraded and initiated the new software, connect to the SG and navigate to the "Software" tab to update the boot number. Recalling the previous value, set the new number higher higher than necessary then reboot the SG and confirm that the change has persisted when you connect again.

3. Reboot the SG and connect to it to confirm that the change is persistent.

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.

• SensorStation V1: the built-in CTT radios at the bottom of the board are ports 1-5, the USB connectors labeled USB1 through USB5 are ports 6-10, USB6 & USB7 should not be used for radios (plug the WiFi dongle into one of them and a cellular modem into the other).

Steps

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,

• Watch the device appearing in the Web UI's "Devices" widget, note the port path shown as well as the port selected. If it's not red, then it's probably OK.

• To change the port selected, edit the Port Mapping (pencil icon at the top), edit the mapping and save it.

• Plug each remaining USB device in one at a time and repeat.

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.

Setting the correct frequency for Lotek radios

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.

Verifying successful reception

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.

Verify the reception of Lotek tags

• 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 PLS: p5,1665900923.6625,3.989,-47.62,-61.01 PLS stands for pulse, p5 refers to "pulse on port 5", this is followed by the time-stamp, the frequency offset in kHz from the nominal frequency, the RSSI (dBm) and the noise (dBm).

• It takes 2 bursts of 4 pulses to detect a tag if the tag is found in the local tag database. A tag detection is hown as follows: TAG: 00:01:14.346 p3 2.812 kHz -39.57 / -53.8 dB where the p3 refers to USB port 3

• If you loaded a tag database and the tag is in that database then after 2 radio bursts (i.e. 8 PLS lines) you should see a tag detection in the log: L5,1665900923.5965,TestTags#[email protected]:25.1,3.971,0.02,-48.1,11.1,-60.9,3223,95,1.97e-07,-4.96e-05,166.38 The L5 refers to a Lotek tag detected by the radio on port 5. This is followed by the tag name and ID, the nominal frequency, the pulse interval (25.1s in this case), the freq offset in kHz, and further details about the pulse burst.

• Note that if you have multiple radios plugged in you should see live pulses and live known tags from all of them, so you should see more than 4 lines appear at once.

Verify the reception of CTT tags

• 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).

Troubleshooting

• 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.

• If you see pulses but no tag detections re-upload your tag database and reboot.

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).

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).

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: 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:

2b. SensorStation (LifeTag) format

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

2c. Lotek format

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.

The initial installation consists of:

1. flashing a microSD card with a Sensorgnome release image,

2. booting the rPi and connecting to it.

Prerequisites

• MicroSD-card with at least 16 GB and an adapter/reader to plug into your computer.

• A computer with Windows/Mac OS/Linux.

• The latest Sensorgnome software release downloaded from https://www.sensorgnome.net/download

• Raspberry Pi Imager installed on your computer, it can be downloaded from https://www.raspberrypi.com/software/ (alternate SD card flashing software can be used as well, such as WinDiskImager, Batena Etcher, and others).

• RaspberryPi 4B, 3B+, 3B, Zero-2W, or SensorStation V1.

• Highly recommended: internet access for the RaspberryPi either via WiFi or ethernet.

Multiple paths to success

There are multiple options for installing and configuring the software. The steps outlined here follow the recommended route. If something is not working for you: try an alternate route.

In any case: don't spend more than 10 minutes being blocked! If it just doesn't work and you double-checked your steps: ask for help.

Flashing the SD-card

Steps

1. Plug the microSD-card into your laptop/computer.

2. Launch RaspberryPi Imager and:

   • click on operating system, choose use custom (it's the last option), locate the Sensorgnome software ZIP you downloaded

   • click on storage and locate the microSDcard to flash

   • Important and easy to overlook: click on the gear icon at the bottom right

   • Focus on the settings outlined in green

     • Set a hostname you will use to recognize your SG during the initial set-up (not used after that so use your initials, for example).

     • Set gnome as username and select a good password: it is used for all access to your Sensorgnome (web UI, hotspot, remote management, SSH).

     • If you will use your local WiFi to give the Sensorgnome internet access configure it here, if you will use Ethernet then skip this portion.

     • Uncheck "enable SSH" unless you have an SSH key you'd like to use, in which case you can enter it here (note that SSH is always enabled regardless of the setting here).

     • The locale setting is ignored.

   • Save the settings and click on 'write', wait for the microSD-card to be written

Booting your Sensorgnome

During the boot process the RaspberryPi green LED provides feedback. Proceed as follows:

1. Insert the microSD card into the RaspberryPi and apply power

2. The red LED on the RaspberryPi indicates power

3. The green LED comes on solid when the Pi boots, thereafter it blinks about every 2 seconds:

   • 1 flash: operating, hotspot off, and no internet access

   • 2 flashes: operating, hotspot ON, no internet access

   • 3 flashes: operating, internet access OK (hotspot may be on or off)

Once you see the 2 or 3 flashes pattern you can proceed.

Timing

• you will see a few erratic blinks the first 40 seconds

• 2 flashes should start after 1 minute

• 3 flashes should start after 1:20 to 2 minutes

• it can take 3 minutes 'til the 3 flashes show up (e.g. due to lost DHCP packets), but after 2 minutes you're probably best off starting to pull out your phone and looking for the hot-spot...

Locating the green LED

Raspberry Pi 3B/4B (here with a cellular HAT):

Raspberry Pi Zero-2W:

SensorStation:

Troubleshooting

• If you never get to a blinking green LED try the following:

  • use a different power supply

  • unplug any attached USB devices

  • reflash the microSD card,

  • use a different microSD card.

• If you only see 2 flashes but expected the RaspberryPi to have internet access, try the following options:

  • wait another minute

  • proceed using the hotspot

  • ensure you used the correct SSID and password in the RaspberryPi Imager configuration (i.e., reflash the card)

  • use your phone to check that the WiFi works and provides internet access

Choosing how to connect to your Sensorgnome

You have two options for connecting to your Sensorgnome: hotspot and internet. Both have advantages and disadvantages. One works better for some users, others are more successful with the other... Pros and cons:

WiFi Hot-Spot

• pro: local, no internet required

• pro: quicker to be ready than internet

• con: connecting can be tricky and confusing depending on laptop/phone, for some users it just works for others it never does

Internet

• pro: if your RaspberryPi shows 3 flashes it's almost guaranteed to work

• con: requires internet access for both RaspberryPi and laptop/phone

• con: currently requires that both the RaspberryPi and laptop/phone are connected to the same local network (i.e., that the RaspberryPi can be accessed directly by the laptop/phone, this doesn't work, for example, if the phone is on cellular and the RaspberryPi on local WiFi)

Connect to your Sensorgnome via Internet

First: verify that your RaspberryPi's green LED shows 3 flashes every 2 seconds.

• If it doesn't your RaspberryPi does not have internet access: use the hotspot method or double-check the internet access (e.g. if using WiFi reflash and triple-check the WiFi settings).

Open the Sensorgnome Hub (SGhub) website at https://www.sensorgnome.net (provisionally, the username and magic word are motus and manygnomes, respectively).

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.

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

You should see a set-up page for your Sensorgnome to confirm the password, this is needed to set the hot-spot password:

After verifying the password the web UI should load, but it may take 20-30 seconds and show "odd transitional" views, please have patience and/or reload your browser tab. (There is room for improvement here!) In the end, you should see the login box into which you have to enter the password you entered into the RaspberryPi Imager:

You are now connected to the web UI:

Connect to your Sensorgnome via its WiFi hot-spot

1. Open the WiFi/internet control panel on your computer/phone and connect to a network named something like SG-1234RPI4ABCD-init that is not secure/encrypted, i.e. no password.

2. After connecting, a browser should pop-up showing a Sensorgnome page:

   • if you did not use the RaspberryPi Imager and set a password there, you will be asked to configure a password

   • if you did use the RaspberryPi Imager and set a password you will be asked to confirm the password Note: this is currently broken: you will just be redirected to the web UI login and you will be disconnected from the hot-spot 10 seconds after you log in and you will have to reconnect

3. After submitting the password, you will see a confirmation page after which the hot-spot temporarily turns off and you will thus be disconnected.

4. You now need to reconnect to the "real" hot-spot which has the same SG-1234RPI4ABCD type of id but without trailing -init. This hot-spot is now secured with the password, so you will need to enter it (again...).

5. A browser should again pop-up and display a simple redirect page that leads you to the web UI's login page.

In the future you will be able to get to the web UI via the hot-spot just using steps 4 & 5. The prior steps are only for the first time to set the hot-spot password.

Next steps

You now have access to the Sensorgnome web UI. Proceed with the next section to set-up the radios and network connections.

FAQ

How does the hot-spot captive portal work?

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.

• 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 http://192.168.7.2 or http://sgpi.local.

• If the captive portal ends up being broken or too confusing turn it off on the landing page at http://192.168.7.2, http://sgpi.local. Then possibly disconnect and reconnect to the hot-spot and navigate to one of the those two URLs explicitly by bringing up a browser. Your device operating system will warn about "no interenet access" and some "stay connected anyway" setting may be necessary.

Why a disk image?

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.

Why doesn't the Sensorgnome use a self-signed certificate?

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.

What are all the partitions on the SDcard for?

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.

What time is reported for detections that occur before time synchronization?

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.

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

Getting help

• 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:

  • Search or post on the Motus Community Forum

  • Post in the Motus slack (sensorgnome channel)

  • Email tve at voneicken point com

• Things that really help us help you:

  • Screen shots

  • Info about your hardware

  • Having your SG connected to the internet

  • Sensorgnome ID (or the hostname used during configuration)

  • Motus project number and station ID and/or deployment ID (if applicable)

  • Log files using the web UI or /var/log/syslog and /var/log/sg-control.log grabbed via SSH

What is a Sensorgnome?

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.

About this guide

This guide is divided into four sections:

• Hardware components and configuration, i.e. misc information about radios, USB, HATs, etc.

• Initial software installation and configuration, i.e., how to get started

• Data download and station maintenance, i.e., checking things when on-site

• Appendix with additional information

Initial deployment checklist

1. Install the software, configure Sensorgnome password, verify access via hot-spot or internet.

2. Verify detection of GPS and optional hardware button/LED.

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

4. Verify network configuration and file upload, alternatively verify downloading files to phone/laptop.

5. Create/verify connection of Sensorgnome to Motus receiver deployment.

6. Perform an end-to-end check from test tags to uploaded data.

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"

Operating system image and updates

• 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.

Passwords

• 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 same password is used to log in as user gnome and to access the web interface (the web interface uses a PAM plugin to auth)

Network interfaces

• 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 wifi client interface can be configured through the SG web interface and supports WPA2 PSK. It should be possible to configure WPA2 EAP or WPA3, but not through the web interface. The interface expects a DHCP server for configuration.

• The wifi hot-spot can be enabled/disabled through the web interface or by pressing a button on the SG. It runs a WPA2 secured network, the password is configured when first deploying a Sensorgnome.

• The cellular interface currently supports only the Sixfab LTE HAT.

Data upload

• 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.

• Users can also manually download data to their laptop/phone via the web interface.

• It is planned for the Sensorgnome to connect to a Motus server to send status and monitoring data and to present a portion of the web interface through a Motus web site.

Open ports

• 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.

HTTPS certificates

• 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 http://local-ip.co for details and rationale.

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's 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.

Cell HATs and USB

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.

Resetting the cell modem

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.

SIM-o-rama

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...

Why initiating cell service can be very slow

• 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...

Try your cell phone's SIM!

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.

SIM activation

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.

What the Sensorgnome software does

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.

What to look for in the Web UI

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.

Cellular Panel

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".

APN, ip-type, and roaming

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.

Command-line troubleshooting

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):

gnome@SG-7F5ERPI46977 ~> mmcli -L                                                              
    /org/freedesktop/ModemManager1/Modem/0 [Telit] LE910C4-NF                                  

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

gnome@SG-7F5ERPI46977 ~> mmcli -m 0                                  
  ----------------------------------
  General  |                   path: /org/freedesktop/ModemManager1/Modem/0
           |              device id: 69b580f5cb29c45e584c21118098565c831ab3a6
  ----------------------------------
  Hardware |           manufacturer: Telit
           |                  model: LE910C4-NF
           |      firmware revision: 25.21.660  1  [Mar 04 2021 12:00:00]
           |         carrier config: default

[... about 30-40 lines ...]                                                

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

  Status   |                   lock: sim-pin2
           |         unlock retries: sim-pin (3), sim-puk (10), sim-pin2 (3), sim-puk2 (10)
           |                  state: connected
           |            power state: on
           |            access tech: lte
           |         signal quality: 92% (recent)

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:

  Bearer   |                  paths: /org/freedesktop/ModemManager1/Bearer/1

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

...
  ------------------------------------
  Status             |      connected: yes
                     |      suspended: no
                     |    multiplexed: no
                     |      interface: wwan0
                     |     ip timeout: 20
...
  ------------------------------------
  IPv4 configuration |         method: static
                     |        address: 100.64.0.2
                     |         prefix: 30
                     |        gateway: 100.64.0.1
                     |            dns: 8.8.8.8, 8.8.4.4
                     |            mtu: 1430
  ------------------------------------
  Statistics         |     start date: 2024-11-27T00:17:26Z
                     |       duration: 19949
...

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

gnome@SG-7F5ERPI46977 ~> ip route
...
default via 100.64.0.1 dev wwan0 proto dhcp src 100.64.0.2 metric 10001 mtu 1430 
...

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:

gnome@SG-7F5ERPI46977 ~> ping -I wwan0 1.1.1.1
PING 1.1.1.1 (1.1.1.1) from 100.64.0.2 wwan0: 56(84) bytes of data.
64 bytes from 1.1.1.1: icmp_seq=1 ttl=58 time=324 ms
64 bytes from 1.1.1.1: icmp_seq=2 ttl=58 time=212 ms

Checking the cell phone's GPS

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:

gnome@SG-7F5ERPI46977 ~> mmcli -m 0 --location-status                                       
  ------------------------
  Location | capabilities: 3gpp-lac-ci, gps-raw, gps-nmea, agps-msa, agps-msb
           |      enabled: 3gpp-lac-ci, gps-nmea
           |      signals: no
  ------------------------
  GPS      | refresh rate: 30 seconds

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:

gnome@SG-7F5ERPI46977 ~> ls -ls /dev/ttyGPS
0 lrwxrwxrwx 1 root root 12 Nov 27 00:17 /dev/ttyGPS -> /dev/ttyUSB2

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

gnome@SG-7F5ERPI46977 ~> gpsmon
tcp://localhost:2947          NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2024-11-26T23:03:52.000Z   Lat: 34 29.940000' N   Lon: 119 49.070000' W │
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GPGGA GPGLL GPRMC GPGSA                                                │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌───────────────────────┌─────────────────────────┌────────────────────────────┐
│ SVID  PRN  Az El SN HU│Time:     230352.00      │Time:      230352.00        │
│GP  2    2  94 13 22  Y│Latitude:  3429.940000 N │Latitude:  3429.940000      │
│GP  5    5 271  7 34  Y│Longitude:11949.070000 W │Longitude: 11949.070000     │
│GP  7    7  91 45 32  Y│Speed:    0.0            │Altitude:  636.6            │
│GP  8    8  40 13 36  Y│Course:   308.2          │Quality:   1   Sats: 12     │
│GP  9    9 158 10 33  Y│Status:   A        FAA:A │HDOP:      0.5              │
│GP 13   13 312 35 36  Y│MagVar:   14.1 E         │Geoid:     -22.0            │
│GP 14   14 296 66 33  Y└───────── RMC ───────────└─────────── GGA ────────────┘
│GP 17   17 180 37 36  Y┌─────────────────────────┌────────────────────────────┐
│GP 19   19 194 11 36  Y│Mode: A3 Sats: 2 5 7 8 + │UTC:           RMS:         │
│GP 21   21  75 11 36  Y│DOP H=0.5  V=0.6  P=0.8  │MAJ:           MIN:         │
│GP 22   22 264 50 37  Y│TOFF:  0.025676591       │ORI:           LAT:         │
│GP 30   30  32 70 33  Y│PPS: N/A                 │LON:           ALT:         │
└───↓──── GSV ──────────└────── GSA + PPS ────────└─────────── GST ────────────┘
(82) {"class":"VERSION","release":"3.22","rev":"3.22","proto_major":3,"proto_min
or":14}
(293) {"class":"DEVICES","devices":[{"class":"DEVICE","path":"/dev/ttyGPS","driv
er":"NMEA0183","activated":"2024-11-26T23:03:49.023Z","flags":1,"native":0,"bps"
:9600,"parity":"N","stopbits":1,"cycle":1.00},{"class":"DEVICE","path":"/dev/pps
0","driver":"PPS","activated":"2024-11-26T23:03:10.224Z"}]}
(122) {"class":"WATCH","enable":true,"json":false,"nmea":false,"raw":2,"scaled":
false,"timing":false,"split24":false,"pps":true}
(72) $GPGSV,4,1,15,02,13,094,23,05,07,271,34,07,45,091,31,08,13,040,36,1*6F
(72) $GPGSV,4,2,15,09,10,158,33,13,35,312,36,14,66,296,33,15,05,320,21,1*68
(72) $GPGSV,4,3,15,17,37,180,36,19,11,194,36,21,11,075,36,22,50,264,37,1*6D
(52) $GPGSV,4,4,15,30,70,032,32,20,00,241,,46,,,37,1*67
(77) $GPGGA,230350.00,3429.940000,N,11949.070000,W,1,12,0.5,636.6,M,-22.0,M,,*56
...

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.