The Raspberry Pi 2 / 3 as a Sensorgnome

From $1

    Version as of 23:08, 19 Apr 2019

    to this version.

    Return to Version archive.

    View current version

    2017 April 30: a new image for RPi 2/3.  All previous images and instructions
    for this platform are unsupported and obsolete.


    • support for rtl-sdr radio dongles
    • WiFi hotspot (RPi-3) for wireless connection to the interface and data
    • support for gestures on an external pushbutton switch + LED:
      • single click: show 1s heartbeat and blink on pulse detections
      • double click: enable WiFi hotspot, showing slow blink on LED
      • hold 3 seconds: cleanly shutdown the SG to avoid loss of data

    These last two are intended to let you access your SG in the field
    without having to open the box or mess with any cables.

    • a new, simpler way to create your SD card
    • the image includes all developer tools and git repos for the main subcomponents:
      • proj/sensorgnome - master control process; nodejs javascript
      • proj/vamp-alsa-host - master data marshaller; C++
      • proj/librtlsdr - modified rtl-sdr library and rtl_tcp data grabber; C
      • proj/fcd - funcube command-line controller; C
      • proj/liwixi - tool to generate easy-to-install releases; shell script
    • stability improvements


    This release is barely tested, and aimed at high-engagement users:

      - do your own testing before deployment

      - accept the possibility of a total loss of data

      - please file bug reports as issues at

      - support will be exclusively via the sensorgnomads google group; emails
        to me (John Brzustowski) will be forwarded (and hopefully answered) there.
    Have fun!


    At long last, USB radio dongles using the Realtek chip supported by librtlsdr will now work with
    the SG.  You select a desired software frame rate in deployment.txt, and the SG software will
    automatically pick the smallest integer multiple (N) of that frame rate as the hardware sampling rate.
    Currently, subsampling is done by simple decimation:  only one out of N frames is passed from hardware
    to the pulse-detection plugin.  The parameters available for these devices now have (mostly commented-out)
    settings in deployment.txt, and there is a pop-up menu which lets you set their values live.
    The audio you hear by pressing the "Listen" button next to an rtlsdr in the device list
    on the web interface can help you determine what the various parameters do.

    WiFi Hotspot

    The RPi-3 comes with built-in WiFi.  By default, SG software leaves this off, but you can enable it in one
    of two ways:

    • wire a switch to your SG as described below, and double click on it to turn WiFi on, and then again to
      turn it off. 
      This option is meant for use in the field, when you should not leave the WiFi consuming power and
      providing access to your SG.


    • delete or rename the file GESTURES.TXT on the SD card.  If this file is not present, the WiFi hot spot
      is always on.
    Hotspot details:
    • ESSID:  the SG's serial number, e.g.  SG-26F1RPI358CC
    • passphrase:  the same SG serial number
    • security: WPA
    • network address: (web interface, ftp server, and ssh server)

    LED-Pushbutton Switch

    If you wire in a switch like this one you can use it for simple closed-box interactions with your SG:

    • single click: show a 1/second heartbeat blink, as well as fast flashes for any pulses detected on the antennas
      another single click turns this off.
    • double click: turn WiFi hotspot on (or off); while on, the LED blinks a slow on/off pattern
    • hold for 3 s: perform a clean shutdown of the SG.  The LED will light solid when shutdown begins, then turn
      off when the system has powered down.  Use this as a "Safely Remove" feature for the SD card

    The switch must be wired to the Pi like so:

    (-)   negative terminal ---------> ground
    (C1)  common switch terminal ----> ground - use the same wire as for (-)
    (+)   positive terminal ---------> GPIO#17
    (NO1) normally open terminal ----> GPIO#18

    The locations of these pins on the RPi 2/3 can be seen here.

    Create the SD card for your SG-Pi

    This release comes with a simpler way to create the SD card:


    Or in words that make it seem more complicated:

    1. insert a new 4GB (or larger) SD card into your laptop

    2. format a used SD card as VFAT using your laptop's OS or with one of the tools from here

    3. download SGPI-2017-04-30_LIWIXI.ZIP and save it to your desktop.
    4. unzip SGPI-2017-04-30_LIWIXI.ZIP to the SD card.  The top-level folder of the
      SD card should now contain a file called "config.txt", and many others.
    5. delete SGPI-2017-04-30_LIWIXI.ZIP from the SD card (if you had copied it there)
      it is not needed on the SD card.
    6. eject (e.g. via "Safely Remove...") the SD card from your laptop
    7. insert the SD card into the Raspberry Pi and power up.
    How it works

    The SD card now holds all data and the SG operating system in a single DOS ("VFAT") partition.
    Brief field guide to the contents:

    • config.txt, cmdline.txt, start*.elf fixup*.dat, kernel*.img, bcm*.dtb:
      startup files for Raspbian, the version of Linux that powers the SG
      minimal linux filesystem needed early in the SG's booting procedure
      full linux filesystem; all the code which actually runs the SG lives here.
      You can't do anything with this file from Windows or OS X without special tools,
      but it's where you will find yourself after logging in via ssh.
    • SGdata
      all data files recorded by the SG will end up here, in one subfolder per day.
      This is what you see when you connect to the SG via FTP.
    • uboot: this poorly-named folder holds miscellaneous configuration files needed by the
      SG software:  deployment.txt, SG_tag_database.sqlite, NETWORK.TXT, SENSORGNOME_VERSION.TXT

    Do not delete or move any of these files:  they must be present and in the top-level folder of the SD card for the SG to work.


    This release of SG software comes with all developer tools needed to build it.
    You will need to login to the SGPi via ssh (user:pi, password:raspberry)
    to access the code and tools.

    In /home/pi/proj are repositories for the main sensorgnome subsystems:

    • sensorgnome - master control process; nodejs javascript, shell scripts, udev rules
    • vamp-alsa-host - master data marshaller; C++
    • librtlsdr - modified rtl-sdr library and rtl_tcp data grabber; C
    • fcd - funcube command-line controller; C
    • liwixi - tool to generate easy-to-install releases; shell script

    If you make changes that you wish to install on other SGPIs, I recommend using liwixi
    to create a new installable .ZIP archive from the Pi you're working on.

    If you want to contribute changes you make back to the sensorgnome project,
    please fork the corresponding repository from and
    send me a pull request.

    USB Port Numbering

    All data acquired by a sensorgnome are labelled by the USB port 
    that the acquisition device is attached to.  It is important to be consistent
    about which antenna you have plugged into each USB port, so that your
    data can be linked to antenna metadata, such as type, azimuth, etc.

    The SG software numbers the four USB ports as so:


    Powered by MindTouch Core