How to Update the Firmware - Safecast/bGeigieNanoKit GitHub Wiki

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Loading the Nano Firmware
    1. Mac OS X
      1. Build the Firmware From Scratch
      2. Use a Prebuilt Image
      3. Use the Uploader App
    2. Linux
    3. MS Windows 7
    4. Next Steps
  4. Updating the Text Files on the SD Card
    1. Editing the Safecast Text File to Set Up the Wifi Connection
    2. Other Files on the Micro-SD Card
  5. About the Safecast API

Introduction

Firmware is software that’s embedded in a device or piece of hardware. Before using your device, you will need to load Nano firmware (with latest upgrades and fixes). You'll also need to configure the device by using the text files stored the SD card.

NOTE: The Nano power switch MUST be turned OFF before connecting (the Fio board powers from the FTDI cable)!

NOTE: If you have a BLEBee or other wireless module, it MUST be removed before reprogramming, since it shares TX/RX signals!

Prerequisites

bGeigie Nano firmware loading (installation/re-flashing) requires:

Loading the Nano Firmware

Mac OS X

There are three alternative ways, please choose one that works for you.

Build the Firmware From Scratch

  1. Install the latest FTDI serial driver

  2. Install Arduino sources

  3. Install CrossPack for AVR Development (contains AVRDUDE command and AVR cross-compiler)

  4. Edit your environment $HOME/.bashrc to add the following lines:

      export ARDUINODIR=$HOME/arduino-1.0.4/
  export BOARD=fio

  5. Start a new Terminal window

  6. Download the latest software

  7. Build and upload the software:

      cp -r libraries $HOME/arduino-1.0.4/
  make
  make upload

NOTE: To learn how to compile source code in general, see Lady Ada's AVR Tutorial.

Use a Prebuilt Image

  1. Install the latest FTDI serial driver

  2. Install CrossPack for AVR Development (which contains AVRDUDE command and AVR cross-compiler)

  3. Upload the Nano firmware (type the commands in a Terminal window): NOTE: If you have more than one FTDI board, or some other USB gadgets, please disconnect anything but the FTDI/Nano.

    a. Download the latest firmware in HEX format (to be written on the Fio board):

      wget https://github.com/Safecast/bGeigieNanoKit/raw/master/bGeigieNano.hex

    b. Upload the firmware:

      /usr/local/bin/avrdude -DV -p atmega328p -P /dev/tty.usb* -c arduino -b 57600 -U flash:w:bGeigieNano.hex:i

Use the Uploader App

Download the Uploader app from the bGeigie repository on GitHub. The file for the app takes the form "bGeigeiNano_V1.#.#_uploader.app.zip". This app will retrieve all of the software necessary for the build, including the FTDI driver.

  1. With the Nano powered OFF, connect the FTDI breakout board 3.3V to your Nano Fio pins (as described in the tutorials)

  2. Connect a short USB cable to the mini-USB on the breakout board, and to the USB on your Mac.

  3. On your Mac, browse to the "bGeigeiNano_V1.#.#_uploader.app.zip" file and unzip it. Click on the executable file's view RAW button to download the app's executable self-opening zip file.

    Alternatively, if you're browsing in the Nano firmware master repo, you first need to click once on the current *_V1.#.#.uploader.app.zip file to open the executable file page to see the "view RAW" (download) button.

  4. Click on the downloaded *.uploader.app.zip executable self-opening file to unzip the app.

  5. Find and click on the unzipped file "bGeigieNano_V1.#.#_uploader.app" (e.g. the current version is "bGeigeiNano_V1.3.5_uploader.app"). The firmware will be flashed or loaded. The Nano should soon power up with the new firmware version number displayed in the top line of the splash screen "bGeigie Nano 1.#.#". If not, try again.

  6. Go to general re-initialization for GPS Reset (at top).

Linux

Most probably your distribution includes the FTDI kernel drivers, check your kernel log:

  1. In a terminal, change/login as root and issue dmesg -c command
  2. Connect the FTDI cable
  3. Repeat step 1. If you see any messages about FTDI you are probably fine.
  4. If there are no new messages or you see errors, consult your distribution help/manual or have a look at the ftdi driver installation guides, including for Linux.

To flash the firmware, consult Use a Prebuilt Image for Mac OS X.

MS Windows 7

  1. To install the firmware on MS Windows, you will need to have the FTDI driver. The driver allows for communication between the Nano Fio and the computer over the breakout board and a USB cable.
  2. Plug the FDTI breakout board onto the 6-pin header, and then plug the recharging USB cable into your computer. The Nano will power up by itself (even though the Nano power switch is off). Note that you must use the 3.3V FTDI cable and insert it properly at the angled header pins on the FIO board. Make sure to follow the pinout labels for which end is for the black wire, and which is green.
  3. Then run X-loader, select COM port, and browse to HEX file (the current version of the Nano firmware which is the bGeigieNano.hex file in the bGeigieNanoKit repository.

Notes:

  • Leave the Nano power switch OFF when connecting the USB to the PC.

  • Make sure you have disconnected any additional modules (such as BLEBee) before programming.

  • If you have the kind of FTDI cable that places the LED at the USB end, you will see a light flashing when there's power, and also during uploads.

  • Restart after the drivers load automatically on Windows 7 Pro after first connecting the FTDI cable and the Nano. You may not need the drivers from the mini-CD that came with cable.

  • The hex file contains the firmware. The Xloader uses a copy of that file on your drive. Click the RAW button to see the text in the file only. With Notebook or a plain ASCII text editor, copy all of the text into a new text file on your drive, and give it the file extension “.hex”. It's best to save the hex file in the same XLoader folder.

  • The Arduino Fio uses ATmega328 microcontroller: Arduino list.

  • If you need more help, try reviewing Arduino's guides and help documentation.

Next Steps

Reset the GPS Unit

Note that for v.1.3.2 and higher, you will need to reset the GPS unit to factory settings after you've applied the new firmware.

  1. Remove the SD card and power on the Nano.
  2. Wait one minute, then switch off the Nano. The display will show a warning "No SD Card/GPS reset."
  3. Insert the SD card, and then switch the Nano on and take it outside.

It will typically take the Nano a few minutes to obtain its first GPS lock. Afterward, GPS locks should be immediate.

Updating the Text Files on the SD Card

The SD card comes with two preloaded files, config.txt and safecast.txt.

If the files are corrupted or deleted from the micro-SD card, the Nano will not work properly. A new micro-SD card has to have FAT format, as well as the two text files in the root. We recommend maintaining a backup of those files. The default settings for the files are available online at https://github.com/Safecast/bGeigieNanoKit/tree/master/SD%20card.

You do not need to make any changes to config.txt. In the next step, you will edit the safecast.txt file to configure your Wi-Fi connection. You will also need to enter your Safecast account information and API key.

Editing the Safecast Text File to Set Up the Wi-Fi Connection

  1. Insert the SD card into your computer.
  2. Open the safecast.txt file in a text editor that uses ASCII encoding (UTF-8 encoding will cause errors). We recommend using Textmate for Mac and EditPad Lite for Windows. Both of these editors are free.
  3. Edit the safecast.txt to include your:
    • Safecast username
    • Wifi ID and password
    • Safecast API key
  4. Save the file.

After completing these steps, your safecast.txt file should look like this:

The second to last line, opcn2_ids, contains information about the particulate sensor. The last line contains IDs for the humidity and temperature sensors.

Other Files on the Micro-SD Card

The micro-SD card comes with Apple disc system files and folders. The file names for these begin with a dot. [Non-Apple devices users can delete these Apple system files.]

About the Safecast API

Your device is designed to submit data to the Safecast database through the Safecast API. To enable data submission, you’ll need to obtain an API key. The key is a credential that gives you access to the API, much like a username and password give you access to an email account. Register on the Safecast site to get an API key.

You can learn about how the Safecast API works by visiting the API documentation. *Expert users may edit the calibrated nuclide efficiency fields like CPMF (counts per minute factor Cs137) with CPMN (counts per minute nuclide Cs137), but not for submitting data -- not without first consulting the Safecast API dataset.