The Raspberry Pi 2 / 3 as a Sensorgnome

From $1

    Version as of 22:14, 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
    • a new, simpler way to create your SD card
    • support for gestures on an external pushbutton switch + LED:
      • single click: show a 1/sec heartbeat and pulse detections on the LED
      • double click: enable WiFi hotspot
      • hold 3 seconds: shutdown the SG so the SD card can be safely removed.

    These last three are intended to let you access your SG in the field
    without having to open the box or mess with any cables.  Alternatively,
    if you're just trying to grab your data quickly and are willing to open
    the box, then with safe shutdown, you can swap out the micro SD card
    for a fresh one.

    • the image includes all developer tools and sensorgnome-specific git repos
      so you can customize in-place.
    • reliability 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!

    Connecting to the SGPi

    - via WiFi hotspot:  (web)  (data)

    - via Ethernet cable:  http://sgpi.local  (web)     ftp://sgpi.local (data)

    I'm collecting a list of which machines these things work with here.

    MAC address

    Users setting up an SGPi on a wired network often need to know the MAC address to allow operation
    behind a firewall.

    For the RPI3, at least, the MAC address of the wired (ethernet) network adapter can be determined directly
    from the serial number.  For example:

    Serial number: F783RPI36B63
                     ^^    ^^^^
    MAC address:   B8:27:EB:83:6B:63
                            ^^ ^^ ^^

    i.e. the MAC address always begins with B8:27:EB, followed by the 3rd and 4th digits/letters of the
    serial number, then the 9th,10th,11th, and 12th digits/letters of the serial number.


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

    To disable pushbutton/LED gesture support, delete or rename the file
    GESTURES.TXT on the SD card  (also visible in /boot when logged into the SG via ssh).

    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.  This might take several minutes.
      The top-level of the SD card should now contain files (e.g. config.txt) and folders (e.g. overlays).
      It should not consist of a single folder called "SGPI-2017-04-30_LIWIXI".  Here's what it looks like
      in a file browser when done correctly:
      micro SD card in file browser after unzipping SG software release.png

    5. delete SGPI-2017-04-30_LIWIXI.ZIP from the SD card (if you had accidentally copied it there)
      it is not needed on the SD card, and occupies space that could be needed for data.
    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.

    CAUTION:  make sure the unzip process is not creating a folder on the SD card called "SGPI-2017-04-30_LIWIXI" and
    extracting files into that folder.  The files such as config.txt and cmdline.txt must be in the top level of the SD card, not in
    a folder.  (Of course, there are also folders such as overlays which must be present there too.)
    Here's how it looks when it's wrong because items are all in a folder on the SD card:



    What's on the SD card

    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-Pi
      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 of the SD card for the SG to work.

    For more details on simple install, see the liwixi repo at github.


    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++
    • vamp-plugins - pulse-detection plugin to vamp-alsa-host
    • librtlsdr - modified rtl-sdr library and rtl_tcp data grabber; C
    • fcd - funcube command-line controller; C
    • liwixi - tool to generate easy-to-install linux blobs; 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