The raw radio data that the SensorGnome records consists of the individual radio pulses detected, as well as some associated information, such as the precise time each pulse was detected, the USB port (e.g. antenna) it was detected on, and the strength of the signal. The data for each pulse is written on its own line in a text file, and then at the end of each hour the text file is compressed into a .gz file. All the detection files are then moved into a folder for each day that the SG was recording (recall that the SG keeps time in UTC/GMT time).

In order to identify the tags that have been detected by the SG, the raw data must be copied from the SG and uploaded to the Motus server, where it is processed and cross-referenced against a database of known deployed tags. Many newer stations, and in particular Motus stations powered by CTT SensorStations, are connected to the internet and sync their data to the Motus server on an automated schedule. However the majority of Motus stations still require a physical visit in order to download data from the receiver.

Where does a SensorGnome save detection data?

Raspberry Pi and BeagleBone based SensorGnomes save their detection data in slightly different places. Usually, this is on the MicroSD card, but there are some subtle differences between the two that can be quite important.

Option 1: Transferring over FTP Connection

Transferring via an FTP connection is the recommended way of copying the data files. That allows you to check the live status of the SG on the Web Interface without turning the SensorGnome off, and gives you a better sense of the state you are leaving the station in. If you cannot establish an FTP connection, there are a couple other options to copy the data; these are described later in this chapter.

1) Connect to your SensorGnome using the instructions above. Confirm you are connected by accessing the Web Interface. If you cannot access the Web Interface there is a very good chance you will not be able to establish an FTP connection either.

2) Open FileZilla and establish a connection following the instructions above. In FileZilla, navigate to the SGdata folder where the detection data files are stored.

3) In the lower right panel, you should see a series of folders named for each date that the SG was recording data. Copy over all of the folders to a location on your computer so that it can be later uploaded to the Motus server to processing. Give the folder on your computer a meaningful name, such as "Site Name 2021-02-03", including the site name and the date you downloaded the data.

• To quickly determining how much of the data you should copy from the SG to your computer, can you click on the station pin on the Motus Receiver Map. The popup will tell you the last date for which there is data for this receiver. Copy over everything from today’s date back through to the “last data date”

• The Motus server will ignore any duplicate data that gets uploaded, so if in doubt about how much of the data to transfer to your computer, err on the side of copying more than you think you actually need.

• Typically you will not need to delete the data on the SG after copying over the files. And it can be helpful to leave a copy on the SG as a sort of backup in case the files on your computer are damaged or lost. But before leaving the data, refer to the available storage space on the card (in the Web Interface) to confirm there is still plenty of room. In normal circumstances, an SG will collect no more than a few gigabytes of data per year.

Option 2: Copying directly from the MicroSD card

With both Raspberry Pi and BeagleBone SensorGnomes it's possible to copy detection data files directly from the MicroSD card. Usually this isn't the preferred method since it introduces more potential for problems, but it works just fine as long as you pay attention to a few of the details.

1) Completely power down the SG by disconnecting the power source(s) from the RPi or BB. A RPi has just one power source, supplied through the micro USB; a BB can be powered by either the "barrel jack" or the mini USB so make sure both are disconnected if applicable.

2) Remove the MicroSD card from the SG. For some RPi the MicroSD is deeply recessed in the case and difficult to remove without tweezers. You may also see a sticker saying something like "Do not remove this card".

3) Insert the MicroSD card into your computer. Most computers do not have a designated slot for reading this side card so an adapter is likely needed.

4) Navigate to the appropriate folder and copy the data files. There is generally no need to delete the files on the card unless it is running low on storage space.

5) Replace the MicroSD card

6) Power on the SG. Check the Web Interface after you are done to confirm everything is working properly.

Option 3: Copying detection data stored internally (BeagleBone only)

In normal operating conditions a BeagleBone SG saves detection data on a MicroSD card. However there are occasions where the card cannot be read by the BB, or the card is absent altogether. In these cases, the BeagleBone SG will revert to storing detection data on its internal storage. This works in the short term, but the internal storage space on a BB is limited, and when the storage is full the BB may cease functioning altogether. For this reason, always delete the data stored internally after you have copied it.

There are two methods of accessing the internal storage of a BB:

1) Accessing the BeagleBone as a shared network drive in Windows Explorer or the Mac equivalent. Here you can view and manipulate files just as you would on your computer.

• Internal storage folder path

  • \\192.168.7.2\data\internal_system_memory\SGdata

2) Running the BB SG with a "Rescue Image", which is a bootable software card. Once the BB is running, you can connect to it with an FTP connection and view the Web Interface as you normally would.

• Internal storage folder path

  • /media/internal_system_memory/SGdata

Uploading data to Motus

Detection data recording by the SG represents individual radio pulses and does not include any information about the tags that might have transmitted the signals.

In order to recognize tag IDs in the data and to match those IDs up with tags currently registered to the Motus database, detection data must be uploaded to Motus for processing. At this stage, the raw radio pulses are compared to a list of all registered tags known to be active at that particular time.

Generally you will want to take all the data you just transferred from the SG and upload it in one shot. Prior to uploading, add all your detection data folders to one archive file, such as a .zip or .7z file.

Navigate to https://motus.org/data/project/sgJobs. If you are a member of multiple Motus projects, ensure that you are in the correct project. Instructions on how to upload are found on this page.

Reviewing the output

This is a complete reference of the network addresses and folder paths, organized by receiver type (RPi vs BB) and method of connection.

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.

The following checklist is broken down by receiver type. Essential, or very important, items are indicated with solid circles while optional (but often useful) items are represented by hollow circles.

In order to copy detection data from the SG, to check the SG’s live status in the Web Interface, or to apply a software patch, you must establish a connection between the SensorGnome and your computer. The actual method used will depend on whether you are using a RPi or BB SG, but the end result is similar in each case. Click on the appropriate tab below to switch between instructions for Raspberry Pi and BeagleBone SGs.

Connection steps for Raspberry Pi & BeagleBone SensorGnomes

Troubleshooting the Connection

An inability to access the Web Interface may indicate issues with your SensorGnome. However there are a number of other potential causes. Here are a few suggestions as part of the troubleshooting process if you are running into issues.

• If your SensorGnome is off-grid or powered with a non-standard power supply, see Underpowered SensorGnomes.

• Check your power supply. Both the RPi and BB have diagnostic LED lights to make visual confirmation of power supply easier.

• Sometimes it takes a while for the connection to the SG to be established, especially for the RPi Ethernet connection which may take up to a minute to establish. If you do not see the Web Interface, wait several seconds before trying again.

• Ensure you are using the correct URL for that SensorGnome and connection method

• If you try to access the Web Interface before the connection to the SG has been fully established, some browsers will automatically replace the http:// prefix with https:// or add www.. Correct the URL in the address bar is before trying again.

• Try a different connection method if you have the option

• Make sure the cables you are using are connected properly. Try different cables if you have them.

• Try a different USB port if applicable

• Toggle the WiFi on your computer on/off if you are trying to connect to a RPi hotspot

• Reboot and restart both the computer and SG

• Try a different computer if you have one available. Preferably one that you've confirmed can actually connect to this type of SG

• Try a different internet browser

• Many newer Windows computers repeatedly reset BeagleBone driver settings. You can fix that following the instructions here: Restoring BeagleBone drivers on Windows

• Use Bonjour Browser to get the IP address of a connected Raspberry Pi SG

• Re-image the SG (if it's a BeagleBone) or try a clean software version (if it's a Raspberry Pi). Instructions can be found in the updating SG software section.

• If you just need to download data there a few other methods of getting this as a temporary solution (see downloading detection data section)

• If you still cannot access the Web Interface, you will not be able to confirm that the SG is running properly. Don’t leave an SG deployed in the field in this condition unless you have no other option.

  • For BeagleBone SG's you can make a "rescue image" and run the SG directly from the software card. More details on making a rescue image can be found here.

The Web Interface is where you can check the live status of your SensorGnome, to ensure that all the components are present and running as they should. As such, it’s a crucial part of any site visit, and checking it should be the first and last thing you do whenever you work with your SensorGnome.

The contents of the Web Interface is the same regardless of whether you have a BeagleBone or Raspberry Pi SensorGnome, though the layout may differ slightly depending on software version.

The Web Interface contains quite a bit of information but not everything you see here is of equal importance to the general user. The information in the top quarter of the page is most useful and we’ll go into those sections in greater detail below.

Summary

The machine ID is the unique serial number generated by each SG. We can see that this is a Raspberry Pi based SG because the letters “RPI” are found in the middle of the machine ID; a BeagleBone based SG would have the letters “BB” or “BBK” in the middle of the machine ID. The machine ID is essentially the same as the SensorGnome receiver serial number, only that it lacks the “SG-” in front. When viewing this receiver on the “Manage Receivers” page of the Motus website, or in data downloaded via the R package, it would be represented as “SG-4FE9RPI31015.”

Below that is the software version that the SensorGnome is running. This SG is running the 2018-10-12 RPI Software, which as of 2021-01-22 remains the most up-to-date full software version. If the software release is given as "UNKNOWN" then this is a BeagleBone SG running from a rescue image. Note that software patches, such as the CTT compatibility patch, will not show up here.

The SensorGnome keeps track of when and how often it reboots, and keeps an internal reboot odometer that increments each time. When you first arrive at a SG in the field, you hope to see that the SG has been running for a long period prior to your arrival, and that it has not rebooted very often during that period. It’s not necessarily a problem if you see that the SG recently rebooted prior to arrival, or that it has rebooted many times since the last visit, but it does potentially point to issues with a power supply, wiring, or perhaps gradual hardware failure.

Finally, the GPS location and time are displayed. Time is displayed in UTC/GMT time so there is a good chance it will be offset from your local time zone. In addition to logging the precise location of the receiver, the GPS also has a role in keeping time. Whenever an SG reboots, the internal clock will reset to 2000-01-01 and start counting from there. It is the GPS that corrects this to the proper current so that accurate timekeeping is maintained. Sometimes when a receiver is found to be recording data when the time and/or location are not properly set, it may be possible retroactively correct them. But often, any data recorded during this period will be lost. Therefore it is critical to confirm the status of these during site visits.

Pulses and Tags pane

The Live Pulses pane will show all radio pulses detected by the receiver in real time. Unless you have a test tag on hand this is most likely just to be background radio noise. Background radio noise is a common occurrence and most sites will show at least something here. But the amount of activity will vary; some stations are so “noisy” there is a steady stream of pulses coming in, whereas others may go minutes or even days without recording pulses. The dongle/antenna that detected the pulse is also printed to the screen. The presence of pulses can help you confirm that your receiver and all antennas/dongles are functioning properly.

The Live Known Tags pane may display two outputs:

1. The actual tag ID of any Lotek Nanotags that the receiver detects in real time if that tag ID is present in the local tag database on that particular SG. By default, only 2 tags are loaded in a placeholder database (the list is visible in the panel at the bottom of the Web Interface). This feature is most useful when deploying tags near a station and you want to get visual confirmation in real time that the tag is being detected. It is not very useful for general detections as it does not have access to the complete tag database on the Motus server.

2. CTT LifeTags/ PowerTags the receiver detects if the receiver has the CTT compatibility patch installed (and has CTT compatible dongles and antennas). Unlike with Lotek Nanotags, there is no need to load a tag database onto the SG as a compatible receiver will recognize any CTT tag IDs. This includes false positives, where random radio noise resembles a supposed tag ID, which nonetheless can be helpful in confirming that a CTT compatible antenna and receiver are working properly.

To the right of the Live Pulses and Live Known Tags panes is the Live Parameter Changes pane. This isn't generally of much use to the average user so isn't discussed here.

Collectively, these three panes will only be displayed if a recognized Lotek compatible dongle is attached to the receiver. In other words, if you only have a CTT compatible dongle plugged in, and no FUNcube or Lotek-compatible dongle attached, you will not see these panes.

If you do have Lotek compatible dongles attached and you do not see these panes, there is either a problem with the dongle(s), with one of the USB connections, or something else is preventing the SG from recognizing the dongles. Adjusting the connections, as well as rebooting the SG may help. The SG generally will recognize a dongle if it is hot-plugged (plugged in while the SG is running) but it’s best to plug the dongles in while the SG is off, and then power it on when all the peripherals attached.

What I'm Doing Now and Devices panes

The What I’m doing now section displays important information about the dongles connected. You should see each of the dongles (e.g. FUNcube dongles) in these two sections. Also note the frame rate and frequency. The frame rate should be 48 and the frequency should match your local region (166 MHz in the Western Hemisphere, 150.1 in Europe, and 151 MHz in Australia).

CTT dongles (434 MHz worldwide) will only be shown in the lower section when plugged in; they will not be displayed in the top section, whereas FUNcube dongles should be displayed in both sections.

You’ll also see the amount of storage space that has been filled on the MicroSD card. In the example above, only 7% of the nominal 32 GB has been used. In normal operating conditions it will take multiple years to fill up a 32 GB card with data, but it’s important to keep an eye on.

Raspberry Pi SGs only save detection data on the MicroSD card as they have no internal storage. BeagleBone SGs do have internal memory; this is what the SG software is installed on. However in most cases, a MicroSD card is used to store the detection data since the BB only has 2GB or 4GB of internal storage. There are situations where the BB SG does not recognize the MicroSD card and will save detection data to the internal memory. In these cases, you will see the storage reported as 2 GB or 4 GB, depending on how much onboard storage that particular SG has.

The Web Interface on a SensorStation

The SensorStation (SS) has its own web interface feature that allows you to view various aspects of the SS status including live CTT tag "beeps", location and time, as well as many other controls and diagnostic tools. For more information, refer to CTT's documentation.

The SS also allows you to view a version of the SensorGnome Web Interface described above. This is accessed by first visiting the SS web interface at http://sensorstation.local while connected with an Ethernet cable, and then clicking the button at the bottom of the page. The general layout is very similar to what you would see on a SensorGnome, with a couple key differences:

• The SS will also say "PPS missing" next to the time. On an SG this would be cause for concern, but on an SS it can be ignored.

• Currently it is not possible to load a local tag database onto an SS, so there will never be anything in the Live Known Tags pane.

Overview of entire page

Below is a screenshot of the entire Web Interface to give you a sense for how it appears it with all sections present.

The recommended method of transferring the detection data and other files between the SG and your computer is with an FTP connection. We suggest the free and open-sourced FTP client FileZilla, which is what these instructions here are based on, though any FTP client will do.

1) Connect to your SensorGnome using the instructions above. Confirm you are connected by accessing the Web Interface. If you cannot access the Web Interface there is a very good chance you will not be able to establish an FTP connection either.

2) Open FileZilla and enter the following credentials in the top left bar, depending on what type of SG you have and how you connected.

3) Click “Quickconnect”

• The first time you connect to a particular SG you may see a pop-up warning that the “server’s host key is unknown.” If you entered the connection credentials correctly, click “OK” and continue.

4) Once connected, you’ll need to navigate to the appropriate folder on the Remote site (aka the SensorGnome) for the next step. There are two main locations you’ll be working with: the SGdata folder, where the detection data files are stored, and the uboot folder, where certain configuration files are stored. You can click around through the folders in the right hand panes to get to these locations but it’s easier to cut and paste the address directly into the location bar on the top right panel.

In FileZilla, select File > Site Manager

Select “New Site” and give it the name and credentials specific to that site. In the example below, there are three sites saved, one for each of SG/connection type combinations

Then under the desired site, click “New Bookmark” and assign the desired path. The paths for downloading detection data or modifying configuration files are found in the relevant sections below. for detection data, you may also want to assign the folder on your computer where you’ll be saving detection data, as in the example below.

Once configured, you can connect to the SG and navigate to the proper folders on your computer and the SG with just one click.

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.

However, the frequency saved in the SG is not actually the true frequency of the tag, but rather that value minus 4 kHz. This is because the FunCubes actually resolve the tag signals better if tuned slightly below the actual frequency. For example, you'll notice that if the frequency is set for 166.380, the value here will be 166.374 and if the frequency set in the UI is 150.1, the value here will be 150.096.

How to set the frequency

On a SensorGnome

The current frequency setting is displayed in the web interface. However the interactive control to change this here does not always work.

Instead, the frequency setting usually has to be modified directly in the configuration file stored on the SG called deployment.txt.

1)

2)

3) Navigate to the configuration folder (/dev/sdcard/uboot on Raspberry Pi or /boot/uboot on BeagleBone

4) Download the deployment.txt file to your computer and modify the frequency setting. There are four places where this is set. Three settings for the various dongles (FunCube Pro, FunCube Pro Plus, and RTL-SDR). These are set to the actual frequency minus 4 kHz, as described above. The fourth setting is at the very bottom of the file and is set to the actual frequency. These settings should be found on or around lines 52, 218, 314, and 364 of the deployment.txt file.

5) Save the file and re-upload the file back to the uboot folder, overwriting the existing file.

6) Power down the SG and reboot, then connect it to your computer and open the deployment.txt file on the SG to ensure that the changes were persistent. You should also see the change reflected in the web interface.

On a SensorStation

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 mini computer – either a Raspberry Pi or a BeagleBone. The mini computer runs the software that listens for and records the radio data picked up by the antennas. In addition to the mini computer, 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 mini computer. Finally, the SensorGnome will include a GPS and power supply, all of which is typically housed in a heavy-duty plastic case.

For a more detailed description of the components of a SensorGnome, and how they fit together, please refer to the .

How to use this guide

Generally each time you work with a SensorGnome – either deployed in the field or as a test on your desktop – you will perform the same basic steps below.

1. the SensorGnome to your computer

2. Open in a browser to check the SG's initial status

3. Establish an to download detection data or modify configuration files.

4. Confirm status once again on the Web Interface (and take a photo or screenshot)

5. Disconnect from the SensorGnome.

There are many similarities between Raspberry Pi and BeagleBone based SensorGnomes – in terms of the hardware, the software that powers them, and the process of using them typically follows the same outline. But there are also some key differences, particularly as it relates to the method of connecting to them and transferring data.

The steps above are described in detail in this guide, with an effort to presenting the commonalities between the two receiver types. Where differences are found between RPi and BB SensorGnomes, they will be broken down into sub-sections. Additional tasks, which aren't necessarily performed on a regular basis, are provided in various appendices.

What kind of SensorGnome do I have?

The BeagleBone and Raspberry Pi computers may be housed in a variety of cases that may have different colours and labels on them. However they are easily differentiated by the ports that they have, as shown in the images below.

A Raspberry Pi (below) has one Ethernet port on the left, with 4 standard USB ports to the right of the Ethernet port.

A BeagleBone (below) has one Ethernet port in the centre flanked by a Mini USB port on its left, and a circular “barrel jack” on its right.

What's inside a SensorGnome?

Both RPi and BB SensorGnome consists of the same core components:

• Raspberry Pi or BeagleBone mini computer. This runs the software that records the raw radio pulse data. A BeagleBone SG will also include a USB hub as the BB only has one standard USB port.

• 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

• GPS. This records the precise location of the SG, as well as ensures the the precise time is always set on the SensorGnome

• Associated power supply

Raspberry Pi SensorGnome

Raspberry Pi

Ports and slots

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

The MicroSD card slot is on the opposite side as 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 MicroSD is so deeply recessed that it cannot be removed without tweezers.

Power is supplied to a RPi through the Micro USB port. This port only supplies power and is not used to communicate with a computer.

Lights

LED lights can be useful in determining if the unit has power and if it is functioning properly. The RPi has fewer lights and they are less information than a BeagleBone, but they can still be helpful.

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 MicroSD slot. The red light indicates power, while the green light indicates CPU activity. The red light should always be on if sufficient is supplied, whereas the green light will flash sporadically

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

BeagleBone SensorGnome

BeagleBone

Ports and slots

a) SMA port for attaching GPS antenna. This particular BeagleBone is outfitted with an integrated "GPS hat" and requires an external antenna. Some older BeagleBones lack an integrated GPS and will not have this port

b) 5V barrel jack port. This is where the primary power supply is plugged in when deployed in the field

c) Ethernet port. Most often used for automatic syncing of detection data to the Motus server.

d) Mini USB port. This is the main port used to connect a BB to your computer. It also supplies enough power to power the BB on its own if needed

a) Standard USB port. Typically the USB Hub will be attached here as the BB only has one standard USB port. FUNcubes and other dongles are then plugged in to the USB hub. This port is not used for communication between the computer and BB.

b) MicroSD card slot. In the BB the card is inserted with the contacts facing down, and there is a slight click when properly inserted.

Lights

GPS

Fully assembled BB SensorGnome

a) BeagleBone mini computer. The colour of the case may vary but it will always be roughly the same size.

b) GPS antenna. This BB has a "GPS hat" attached to the BeagleBone itself, and only requires an external antenna. Many BB last the integrated GPS and require a USB GPS, which is plugged into the USB hub

c) FUNcube dongles plugged into ports 1 and 2 of the USB hub. The antenna cables would be attached to the loose ends. Note that the antennas must be plugged into a USB hub as the BB only has one standard USB port.

d) USB hub. The USB hub is supplied with power by via a splitter coming from the main power source, with the other end supplying the BeagleBone. It is attached to the BB's only standard USB port.

e) Voltage converter and cable junction. 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.

By default a SensorGnome is capable of detecting only Lotek Nanotags. However by applying a software patch a SensorGnome can also detect CTT LifeTags/ PowerTags. We refer to SGs that are listening for both tag types as “dual-mode” SensorGnomes.

1) Download the CTT compatibility patch from the link below

• Raspberry Pi. 2021-07-09-rpi_ctt.tar.bz2

• BeagleBone. 2018-12-06_sensorgnome_beagle_ctt_update.tar.bz2. Dual-mode function for BB SG's has not been fully implemented. It works, but there are some steps required on the back-end to enable this. If you wish to make a BB SG dual-mode, please contact Motus and we will assist you.

2) Rename the downloaded file to sensorgnome_update.tar.bz2

3) Connect to the SG and navigate to the ubootfolder

4) Copy the renamed software patch into this folder

5) Power down and reboot the SG.

6) Once powered up, connect to the SG and open the Web Interface

If the process was successful you should see any attached CTT dongles in the "Devices" pane of the Web Interface. However, they will not be displayed in the "What I'm doing now" pane. Additionally, both of these panes will only be displayed if there is a Nanotag-compatible dongle, such as a FUNcube dongle, attached.

It's possible that you will also see CTT tag IDs in the Live Known Tags section. These may be the signals of actual tags in the vicinity, or they be the product of background radio noise that happens to resolve to a tag ID, which is still useful in confirming that the SG is in fact listening for CTT tags. CTT tag hits will never show up in the Live Pulses Pane as this pane only displays radio pulses consistent with Lotek tag signals.

What is an underpowered SensorGnome?

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.

This typically occurs in off-grid stations due to the non-standard power supply that is used; however, this is also possible if an incorrect AC adaptor is used. The AC adaptor should output 5.1 Volts and 2.5 Amps (2500 mA).

Raspberry Pi based SensorGnomes in off-grid setups are most susceptible to underpowered situations due to the higher voltage requirements in comparison to BeagleBone computers (5.1 V required for Raspberry Pi; 5.0 for BeagleBone). The DC-DC voltage converter used in the SensorGnome, which converts the batteries 12 Volts down to something the computer can use, outputs just 5.0 Volts and 2.0 Amps. This alone isn't enough for the SenorGnome to malfunction, but over time wear and tear to the USB cable and its connections can increase the resistance to the flow of electricity and can eventually result in a malfunctioning system.

How does it occur?

It most cases, general wear and tear triggers the problem. This is because the USB 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).

Identifying an underpowered SensorGnome

The behaviour of underpowered devices can be inconsistent and hard to diagnose. In most 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.

When trying to connect to Wi-Fi, there are a few different reasons why it may not work:

• Button never lights up

• Button lights up, but no Wi-Fi network is visible

• Wi-Fi network is visible, but can't connect to it

If swapping out the computer and Wi-Fi button (if applicable) doesn't change the behaviour, it's likely it is an underpowered SensorGnome and the issue lies with the power supply/USB Cable.

Fixing power supply issues

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.

One of the first steps in troubleshooting is to ensure that you have the most up-to-date software installed on your SensorGnome. Aside from ensuring your SG is up-to-date – this entire guide as based on the premise that you are using the most recent software – reinstalling the most recent software can resolve many issues.

Once you have the SensorGnome loaded with the necessary software to detect CTT LifeTags/ PowerTags (i.e., it's "dual-mode"), you will require a USB receiver dongle for each antenna listening at 434 MHz. 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

• (a shorter, more flexible cable is preferred)

• or , depending on your computer's USB port availability. If you can use a USB-A cable with your computer, and get a short one similar to the example linked, you can use it later when installing the CTT Dongle as part of the SensorGnome.

• Arduino Feather Programmer and CTT Dongle firmware bundle below. NOTE: The firmware currently included in the below bundle is the last commercially-used firmware on the CTT dongle. Thus it does NOT require the jumper wire described and referenced elsewhere in Motus mailing list to function properly. If the firmware provided here is updated to the newest release requiring the jumper wire, these instructions will be modified to reflect that change.

• CTT Dongle case 3D printing STL files below

2) Connect the AdaFruit Feather board to a USB port on your computer. The Feather board has a microUSB connection, so you'll need the USB cable.

3) Unzip the Arduino Feather Programmer and CTT Dongle firmware bundle to your computer. You will have to extract or copy the entire CTT_dongle_Feather_programmer_w_firmware folder contained in the zip file to a new, physical location on your computer. You cannot run the firmware installation program from within the zipped file.

4) Within the newly unzipped directory, run the Feather32u4Programmer.exe program. It should look something like this:

5) Once the program window opens, from the drop-down box, select the COM port that the Feather device is connected to. If you have multiple COM ports listed, you can identify the correct port by (a) noting which COM ports are listed, (b) unplugging the device, (c) pressing theRefresh button, (d) see which port has disappeared from the list of COM ports, (e) plugging the device back in, and (f) refreshing again and selecting the new COM port.

6) Press the Select File button and navigate to the station_radio_last_commercial.hex file located in the Firmware directory of the bundle you unzipped in Step 2.

7) Press the Program button at the bottom of the window and wait until the program indicates the firmware installation is done. You may then close the program and disconnect the Feather device.

9) Print the body and lid of the CTT dongle case with your 3D printer.

10) Install the SMA bulkhead first, tightening it securely and helping the bulkhead to fit into the hexagonal opening that fits its base.

11) Attach the uFL connector to the newly-installed uFL surface mount connector on the bottom of the Feather. This connection can easily come undone, so secure with some liquid electrical tape or high temperature hot glue.

12) Insert the Feather into the case, carefully maneuvering the SMA to uFL cable under the board and around the 3D printed board support, aligning the corner mounting holes with the screw mounts in the bottom of the case. Install 2-3 of the M1 screws in the corner, securing the board to the base.

13) Attach the case lid. It may be easiest to insert one long side in first and then press firmly on the opposite side until the lid snaps into place.

Configuring your SensorGnome to sync detection data automatically results in more up-to-date data, fewer trips to visit a station, and more timely identification (and resolution) of any issues with the receiver. Wherever possible, SG's should be connected to the Internet.

Option 1: Wired internet over Ethernet

The simplest method of syncing data over the internet is to plug the BB or RPi into the Internet via an Ethernet cable. If the internet is not password-protected, and the software on the SG is up-to-date, the SensorGnome should connect to the Motus server within minutes and begin syncing data an hour later.

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

2)

Option 2: Wi-Fi

Connecting over a Wi-Fi network is also an option. In this case a bit of configuration is needed. The Raspberry Pi comes with a Wi-Fi adapter already on-board. Wi-Fi connectivity is also possible with a BeagleBone, though it requires a USB Wi-Fi adapter. The BeagleBone software is configured to work with the . This is an affordable and reliable Wi-Fi adapter that is available from multiple retailers.

1) Connect to the SG and navigate to the ubootfolder

2) Open the network.txt file and follow the instructions in the file for adding the network name and password.

3) Ensure that the changes have been saved to the SG, then power down and reboot

Note: Activating the WiFi hotspot will temporarily disable the connection to the Internet. One the WiFi hotspot turns off, the connection to the Internet will be re-established.

Checking sync status on sensorgnome.org/status

The list is is long as it includes receivers from all projects, and deployment names don't always appear (especially if the deployment is a test deployment) so the simplest way of finding your SensorGnome is to hit CTRL F in the browser and then type in the receiver serial number.

The middle column shows the time of the most recent data sync (in UTC/GMT time). For a properly functioning station, this should be within the last few hours.

The first column -- most recent connect/disconnect time -- is most useful immediately after powering up or connecting an SG for the first time. Within a minute or so of connecting to the Internet, an SG will show up on this list and you should see the recent time displayed. The first sync won't be attempted for another hour or two (the time displayed in the last column), so check back in later to confirm that data is actually being synced.

The drivers for BeagleBone SensorGnomes can be found in the table below (copied from the ).

If installation fails

On many newer computers, such as those with Windows 10, the operating system blocks the installation of the BeagleBone drivers as they are “unsigned.” The process may simply fail without an informative message.

1) Hold down the Shift key while you click the “Restart” option in Windows. Your computer will restart into the Advanced Boot menu

2) Select the “Troubleshoot” tile on the Choose an option screen that appears

3) Select “Advanced options”

4) Click the “Startup Settings” tile

5) Click the “Restart” button to restart your PC into the Startup Settings screen

6) Type “7” or “F7” at the Startup Settings screen to activate the “Disable driver signature enforcement” option

Your PC will boot with driver signature enforcement disabled and you’ll be able to install unsigned drivers. However, the next time you restart your computer, driver signature enforcement will be disabled—unless you go through this menu again.

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

Format : C,<ts>,<prec>,<elapsed>
Example : C,1528750333.246,1,0.399892479
Example : C,1561257097.681,6,8.6e-7

G : GPS data entry

Format : G,<ts>,<lat>,<lon>,<alt>
Example : G,1526683597,-23.002083333,118.931118333,736.4

p : individual pulse on FunCube Dongles

Format : p<port_num>,<ts>,<dfreq>,<sig>,<noise>
Example : p3,1526683680.8316,0.4,-35.4,-42.56

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

Format : S,<ts>,<port_num>,<name>,<value>,<rc>,<err>
Example : S,1366227448.192,5,-m,166.376,0,
Example : S,946684811.244,3,frequency,151.496,0,
Example : S,946684811.249,3,gain_mode,1,0,
Example : S,946684811.25,3,tuner_gain,40.2,0,
Example : S,946684811.25,3,test_mode,0,0,
Example : S,946684811.251,3,agc_mode,0,0,

T : LifeTag hit on CTT/CVRX dongle or SensorStation

Format : T<port_num>,<ts>,<tag_code>
Example : T4,1557450282.889,04452182

Fields:

-m : antenna listening frequency (FunCube and FunCubePro)
-w : FunCube and FunCubePro parameter settings
(see https://github.com/sensorgnome-org/sensorgnome-control/blob/77d8ba9b2cf1ba6d3eef895fe7e2155c3f6ccd73/master/usbaudio.js#L32)
alt : altitude (m)
dfreq : frequency offset (KHz)
err : blank on success, else error message (frequency setting)
freq : nominal frequency
lat : latitude (degrees)
lon : longitude (degrees)
name : arbitrary parameter name
noise : noise level (dB?)
port_num : port number (antenna)
rc : response code (?). E.g. zero if frequency setting succeeded, else non-zero error code
sig : signal strength (dB)
tag_code : 32-bit tag code (e.g. LifeTag)
ts : Unix timestamp (seconds)
value : arbitrary parameter value

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:

Format : <Time>,<RadioId>,<TagId>,<TagRSSI>,<NodeId>
Format : <Time>,<RadioId>,<TagId>,<TagRSSI>,<NodeId>,<Validated>

Example : 2019-07-16 20:18:39.845,3,6161527F,-96,

Time : datetime (UTC) yyyy-MM-dd HH:mm:ss.sss
RadioId : Port number (numeric). Those ports are saved with a L prefix in the metadata and the data tables
TagId : tag number (e.g. AF7709D3)
TagRSSI : Received Signal Strenght Indication
NodeId : hex ID of the node that originally captured the signal (3-digit for old models. Should be unique in more recent models)
Validated : 0 or 1 to indicate whether the tag was considered valid by CTT algorithms (details unknown).

node-data files: meta information about the nodes

Format : <Time>,<RadioId>,<NodeId>,<NodeRSSI>,<Battery>,<Celcius>
Format : <Time>,<RadioId>,<NodeId>,<NodeRSSI>,<Battery>,<Celcius>,<RecordedAt>,<Firmware>,<SolarVolts>,<SolarCurrent>,<CumulativeSolarCurrent>,<Latitude>,<Longitude>

Time : datetime (UTC) yyyy-MM-dd HH:mm:ss.sss when the data was received at the base station
RadioId : Port number (numeric). Those ports are saved with a L prefix in the metadata and the data tables
NodeRSSI : Received Signal Strenght Indication (node signal on the base station)
Battery : battery power level
Celcius : node temperature
RecordedAt : datetime (UTC) when the data was recorded on the node
Firmware : node firmware
SolarVolts : solar voltage
SolarCurrent : solar current
CumulativeSolarCurrent :  cumulative solar current
Latitude : node latitude
Longitude : node longitude

gps files: gps readings of the base station

Format : <recorded at>,<gps at>,<latitude>,<longitude>,<altitude>,<quality>
Format : <recorded at>,<gps at>,<latitude>,<longitude>,<altitude>,<quality>,<mean lat>,<mean lon>,<n fixes>

Example : 2019-08-17T03:09:27.458Z,2019-08-17T03:09:26.000Z,38.240977833,-75.1360325,2.7,3

recorded at : datetime (UTC) yyyy-MM-ddTHH:mm:ss.sssZ
gps at :  datetime of gps clock (UTC) yyyy-MM-ddTHH:mm:ss.sssZ
latitude : latitude (degrees)
longitude : longitude (degrees)
altitude : altitude (m)
quality : signal quality (units?)
mean lat : mean latitude
mean lon : mean longitude
n fixes : number of fixes used to calculate mean

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.

Format: <Date> <Time>    <Channel>  <Tag ID>    <Antenna>   <Power>
Example: 06/05/15  12:43:10.6489         0     393    A1+A2+A3+A4     131

If you are unable to re-image your BeagleBone Black using the regular method, try these steps.

The BeagleBone Black keeps its operating system in its internal storage which is more robust than an external SD card; however, sometimes it can get filled up with error logs and detection data if the SD card malfunctions. This causes critical processes to no longer function, resulting in no data collection. In this state, the BeagleBone cannot be fixed by re-imaging it. Instead, files must first be deleted off its internal storage.

1. If you are able to connect via FileZilla

2. If you can't connect via FileZilla

3. If all else fails

If you are able to connect via FileZilla

1. In FileZilla, navigate to the folder: ./var/log

2. In this folder, look for very large files (>100 MB) and delete them.

3. Navigate to the folder: ./media/system_internal_memory/SGdata

4. This folder may contain VALID data that hasn’t previously been downloaded – if the files appear normal (and are not empty), download them to your laptop and upload them to Motus as you normally would. Once data has been downloaded, delete the contents of this folder.

5. In FileZilla, navigate to the folder (if it exists): ./boot/uboot/SGdata

6. Again, this folder may contain VALID data that hasn’t previously been downloaded – if the files appear normal (and are not empty), download them to your laptop and upload them to Motus as you normally would. Once data has been downloaded, delete the contents of this folder.

7. Disconnect from the FTP server, unplug the SensorGnome, and power it off.

8. Insert a regular BeagleBone imaging card and power on the SensorGnome.

9. You should now see the regular pattern of LEDs, with the heartbeat lasting several minutes as the software is installed.

10. Once the heartbeat stops and all LEDs are solid, power off the SensorGnome and remove the SD card.

11. Power on the SensorGnome and plug it into a computer once it boots up.

12. You should now be able to connect to the SensorGnome via FileZilla and view its web interface.

13. In FileZilla, navigate to the folder (if it exists): ./boot/uboot/SGdata

14. Again, this folder may contain VALID data that hasn’t previously been downloaded – if the files appear normal (and are not empty), download them to your laptop and upload them to Motus as you normally would.

15. Once data has been downloaded, delete the contents of this folder.

If you are unable to connect via FileZilla

2. Image a microSD card with this image (must be at least 4 GB)

3. With the BBBK powered off, insert the microSD card and then power it on.

4. After booting, connect the BBBK using FileZilla.

5. Navigate to the folder: ./tmp/introot/var/log

6. In this folder, look for very large files (>100 MB) and delete them.

7. Navigate to the folder: ./tmp/introot/media/system_internal_memory/SGdata

8. This folder may contain VALID data that hasn’t previously been downloaded – if the files appear normal (and are not empty), download them to your laptop and upload them to Motus as you normally would.

9. Once data has been downloaded, delete the contents of this folder.

10. Disconnect from the FTP server, unplug the SensorGnome, and power it off.

11. Remove the rescue image SD card and insert a regular BeagleBone imaging card.

12. Power on the SensorGnome. You should now see the regular pattern of LEDs, with the heartbeat lasting several minutes as the software is installed.

13. Once the heartbeat stops and all LEDs are solid, power off the SensorGnome and remove the SD card.

14. Power on the SensorGnome and plug it into a computer once it boots up.

15. You should now be able to connect to the SensorGnome via FileZilla and view its web interface.

16. In FileZilla, navigate to the folder (if it exists): ./boot/uboot/SGdata

17. Again, this folder may contain VALID data that hasn’t previously been downloaded – if the files appear normal (and are not empty), download them to your laptop and upload them to Motus as you normally would.

18. Once data has been downloaded, delete the contents of this folder.

Running a BB SG from the rescue image

Sometimes none of the above steps will work in which case you will have to resort to using the rescue image long term. This is undesirable because storing the operating system on the SD card makes the system more vulnerable to permanent crashes. Nonetheless, it does work for an indeterminate amount of time (days, weeks, maybe months) and works well if you're in a pinch.

Making a rescue image

This is done in much the same way as a regular software image for the BeagleBone, it's just a different file.

3. Select the MicroSD card in the next step, and then click “Flash!”.

4. Once flashing has completed, safely remove the card from your computer.

5. Make sure the BeagleBone is powered off and then insert the SD card.

6. Power on the BeagleBone and give it a minute or two to boot.

7. After a minute or two, connect to the BB SG and check the Web Interface

A BB SG with a rescue image will record data to same path on the MicroSD card as a normal BB will. But if the card fails or can no longer be read, there is no backup internal memory to use and the BB will simply stop recording.

Once a BeagleBone is connected to your computer, you can access it as a shared network drive either in Windows Explorer or the Mac equivalent. Through this method you can copy detection data as well as modify configuration files. It may also be possible to access data files on a BB even if you cannot access the Web Interface or create an FTP connection.

This uses a connection protocol called SMBv1, which on newer versions of Windows has been disabled in favour of more secure version. You will likely have to re-enable this feature in order to access a BeagleBone as a networked drive.

There are instructions on doing that for Windows here: https://www.windowscentral.com/how-access-files-network-devices-using-smbv1-windows-10.

Once configured, you can navigate the file structure as you would any other drive by entering the following in the address bar: \\192.168.7.2

The folder structure will look a bit different than in FileZilla and you will see three folders: boot, data, root. There is overlap between these folders and you will find the same detection data in both data and root folders. However configuration files can only modified in the root folder.

• Detection data (SGdata) folder on the MicroSD card

  • \\192.168.7.2\root\media\internal_SD_card\SGdata

• Internal detection data folder (when MicroSD card is absent or can't be read)

  • \\192.168.7.2\root\media\internal_system_memory\SGdata

• uboot folder (configuration files)

  • \\192.168.7.2\root\boot\uboot\

Mapping the networked drive

You can save time in the future by "mapping" this new drive so it can be accessed more easily. Ensure that the BeagleBone is connected to your computer then open Windows Explorer. Click "This PC", then click "Map network drive".

After selecting "Map network" drive you will be be able to assign a drive letter as shortcut to drive. It's most convenient to map the drive to \\192.168.7.2\root as that will allow you to download detection and modify configuration files.

Once configured, you can access the folder by clicking on the link in Windows Explorer.

It is also possible to connect to a BB SG using an Ethernet cable. However results with this method are less reliable and some users report it rarely succeeds. Additionally it usually requires modifying your computer settings whenever you connect, then changing them back when finished.

Newer versions of Windows will occasionally reset the drivers for BeagleBones, making it impossible to connect to them. You can reset the driver selection using the following steps.

1. Connect the BeagleBone to the computer using USB and confirm it's powered on

2. Open "Device Manager" on your computer. Under the "View" menu, ensure that "Show hidden devices" is checked
3. Expand the Ports section. If the BB is connected and powered on you should see one of these indicating "active" with the darker shading

4. Right click on the active port and select "Update Driver"

1. Select "Browse my computer for drivers"

2. Select "Let me pick from a list of available drivers"

3. You should see a option for "Linux USB Ethernet/RNDIS Gadget". Select that.

Requirements

• MicroSD card with at least 16 GB (we recommend 32 GB, but more is also fine).

• A computer with Windows/Mac OS/Linux.

• MicroSD card adapter and an SD card reader (most MicroSD cards come with an adapter).

• The latest (as of 2024-06-06 this is )

• Raspberry Pi Imager installed on your computer. Software is here:

• A Raspberry Pi 2, 3, 4, or Zero 2 W.

Flashing the software image to SD card

1. Insert the MicroSD card into the adapter and then in to the SD card reader.

   • If you’re using an external SD card reader, plug it in to your computer!

2. Open the Raspberry Pi Imager software and click on ‘Choose OS’. Scroll down to the bottom, click "Use custom", and navigate to the latest software that you just downloaded. You can select the .zip file even if you haven't yet unzipped it as the Imager will do that part for you.

3. After selecting the software, click on ‘Choose Storage’ and select the drive which corresponds to the SD card you plugged in.

4. Click ‘Write’. If the card is not empty, you will get a warning saying that all data will be erased. If you are okay with this, click ‘OK’. Once writing and verification is complete, you will be prompted to remove the card.

Initial configuration

1. Ensure the Raspberry Pi is powered off and then insert the microSD card into the card slot and power it on.

3. You will be prompted to enter a password which will apply to both the SensorGnome itself and the WiFi network. We recommend using the same password for the device and Wi-Fi for simplicity, but feel free to make them different.

4. Once you submit the form, you will be disconnected from the WiFi network and a new WiFi network will be seen, again comprised of the serial number, but lacking "-init" at the end. Connect to this new network, using the password you just assigned.

6. When prompted, enter the password you previously assigned. The username is always gnome but should be pre-populated when you load the page.

7. Once configured, you can connect to the WiFi hotspot broadcast by the SG with a computer or smartphone to check status and modify any additional configuration.

Basic management and configuration

1. After logging in you will be presented with dashboard with several ‘tabs’ at the top. These include:

   • Overview: selected by default

   • Radios: View and configure the radios attached other SG (e.g. FunCube dongles or CTT motus adapters)

   • Files: download data here

   • Network: Check or configure internet connection here

   • Config: Set the SensorGnome name and password here. Also enter your Motus credentials here if internet connected.

   • Software: check software version and update it. Also download logs here.

Configure Wi-Fi

1. On the web interface, select the ‘Network’ tab.

2. 1. SSID: the name of the Wi-Fi network (must match exactly)

   2. Passphrase: The Wi-Fi network password.

4. Next, select the ‘Config’ tab.

• Upload username: your Motus username.

• Upload password: your Motus password.

7. If any data exist on the SensorGnome, you can upload it now by selecting the ‘Files’ tab and clicking the ‘Upload’ button.

Introduction

FUNcube Dongles are a component used in SensorGnomes and CTT SensorStations for listening to tags developed by Lotek Wireless. 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 the guide provided on the FUNcubed dongle website.

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.

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

[placeholder section]

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

Introduction

If you are installing a SensorGnome or SensorStation 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

Download the Tag Database

1. Navigate to your project's Manage Tags page and click on the blue "Download tag database" button on the right hand side

2. Download the .sqlite tag database. The first link contains all tags currently registered to this project, whereas the links below are older format that summarized by yearly quarter. In nearly all cases you will want the first link.

Upload the tag database to your station

The following steps will differ depending on whether you are you using a SensorGnome or SensorStation

SensorGnome

1. Connect to your SensorGnome with a computer using 'root' as both the username and password and navigate to the uboot folder. If using the V2 SensorGnome software, you can simply upload this via the web UI.

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

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

4. 5. Reboot the SensorGnome.

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

SensorStation

1. Connect to the SensorStation with an Ethernet cable.

2. Navigate in a browser to sensorstation.local

3. Once the SensorStation web interface loads, scroll down to the very bottom and select "Browse" to choose the file on your computer. There is no need to rename the .sqlite file.

4. Click the red "Upload Tag Database File" button

5. After seeing the confirmation message scroll up and click the blue button "SensorGnome Interface" to confirm that your tags are there.

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

As only one tag database can be loaded onto a SensorGnome at any given time, it is sometimes necessary to merge multiple tag databases together. 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)

Typically a Raspberry Pi SG can be connected to using an Ethernet cable by visiting http://sgpi.local in either Firefox or a Chrome-based browser.

This method relies on networking software called Bonjour to establish the network connection between the RPi and your computer. Bonjour is installed as part of iTunes, but can also be downloaded separately from Apple. Mac computers come with Bonjour already pre-installed.

Sometimes, though, navigating to http://sgpi.local does not work, even with Bonjour installed. In these cases, you can use a third party software called Bonjour Browser to find the actual IP address of the RPi SG and access the Web Interface using that.

1) Connect the Raspberry Pi SG to your computer using an Ethernet cable and ensure the RPi has power supplied to it.

2) Download Bonjour Browser from here and launch the program.

3) Allow enough time for the connection to establish (usually 30-60 seconds) then hit the "Refresh" button in the top right hand corner of Bonjour Browser.

4) Look for an entry whose name begins with "sgpi" and click on it.

5) Copy the IP address in the bottom pane

6) Paste the IP address into the address bar of Firefox or Chrome without the port number (the colon and the numbers following it)

7) You should now see the Web Interface.