Skip to content

Latest commit

 

History

History
331 lines (253 loc) · 16.8 KB

README.md

File metadata and controls

331 lines (253 loc) · 16.8 KB
Raw

Safecast bGeigie Library

SafecastBGeigie is the code for the firmware needed to run the bGeigie devices from Safecast. The necessary building blocks such as SD card logger, GPS parser, power management, etc, are included in the form of an Arduino library. The firmwares for the different devices are given as examples of this library.

bGeigie NX

Data log file format

The data is formatted similarly to NMEA sentences that GPS uses. It always starts with a $ and ends with a *. Following the star is a checksum.

Radiation data sentence

This is the basic message containing the geo-located radiation measurement.

Example:

$BNXRDD,300,2012-12-16T17:58:24Z,31,9,115,A,4618.9996,N,00658.4623,E,587.6,A,77.2,1*1A
$BNXRDD,300,2012-12-16T17:58:31Z,30,1,116,A,4618.9612,N,00658.4831,E,443.7,A,1.28,1*1D
$BNXRDD,300,2012-12-16T17:58:36Z,32,4,120,A,4618.9424,N,00658.4802,E,428.1,A,1.27,1*18
$BNXRDD,300,2012-12-16T17:58:41Z,32,2,122,A,4618.9315,N,00658.4670,E,425.5,A,1.27,1*1B
$BNXRDD,300,2012-12-16T17:58:46Z,34,3,125,A,4618.9289,N,00658.4482,E,426.0,A,1.34,1*13
  1. Header : BNXRDD
  2. Device ID : Device serial number. 300
  3. Date : Date formatted according to iso-8601 standard. Usually uses GMT. 2012-12-16T17:58:31Z
  4. Radiation 1 minute : number of pulses given by the Geiger tube in the last minute. 30
  5. Radiation 5 seconds : number of pulses given by the Geiger tube in the last 5 seconds. 1
  6. Radiation total count : total number of pulses recorded since startup. 116
  7. Radiation count validity flag : 'A' indicates the counter has been running for more than one minute and the 1 minute count is not zero. Otherwise, the flag is 'V' (void). A
  8. Latitude : As given by GPS. The format is ddmm.mmmm where dd is in degrees and mm.mmmm is decimal minute. 4618.9612
  9. Hemisphere : 'N' (north), or 'S' (south). N
  10. Longitude : As given by GPS. The format is dddmm.mmmm where ddd is in degrees and mm.mmmm is decimal minute. 00658.4831
  11. East/West : 'W' (west) or 'E' (east) from Greenwich. E
  12. Altitude : Above sea level as given by GPS in meters. 443.7
  13. GPS validity : 'A' ok, 'V' invalid. A
  14. HDOP : Horizontal Dilution of Precision (HDOP), relative accuracy of horizontal position. 1.28
  15. Fix Quality : 0 = invalid, 1 = GPS Fix, 2 = DGPS Fix. 1
  16. Checksum. *1D

Device status sentence

This is an extra sentence containing information about the sensor status.

Example:

$BNXSTS,300,2012-12-16T17:58:24Z,4618.9996,N,00658.4623,E,3,v3.0.3,22,49,3987,,1,1,1*7D
$BNXSTS,300,2012-12-16T17:58:31Z,4618.9612,N,00658.4831,E,5,v3.0.3,22,50,3987,,1,1,1*7F
$BNXSTS,300,2012-12-16T17:58:36Z,4618.9424,N,00658.4802,E,6,v3.0.3,22,50,3987,,1,1,1*7F
$BNXSTS,300,2012-12-16T17:58:41Z,4618.9315,N,00658.4670,E,6,v3.0.3,22,50,3987,,1,1,1*71
$BNXSTS,300,2012-12-16T17:58:46Z,4618.9289,N,00658.4482,E,6,v3.0.3,22,49,3987,,1,1,1*75
  1. Header : BNXSTS
  2. Device ID : Device serial number. 300
  3. Date : Date formatted according to iso-8601 standard. Usually uses GMT. 2012-12-16T17:58:24Z
  4. Latitude : As given by GPS. The format is ddmm.mmmm where dd is in degrees and mm.mmmm is decimal minute. 4618.9996
  5. Hemisphere : 'N' (north), or 'S' (south). N
  6. Longitude : As given by GPS. The format is dddmm.mmmm where ddd is in degrees and mm.mmmm is decimal minute. 00658.4623
  7. East/West : 'W' (west) or 'E' (east) from Greenwich. E
  8. Number of Satellites : Number of satellites in view. 3
  9. Firmware version number. v3.0.3
  10. Temperature in degree Celsius.
  11. Relative humidity in %.
  12. Battery voltage in millivolts.
  13. High voltage in volts, if available. Empty otherwise.
  14. SD inserted status. 1=present, 0=missing.
  15. SD initialization status. 1=ok, 0=failed.
  16. SD last write status. 1 = ok, 0 = last write failed.
  17. Checksum. *7D

Checksum computation

The checksum is a XOR of all the ASCII characters bytes between '$' and '*' (these excluded). Sample C code to compute the checksum is given.

/* Compute checksum of input array */
char GPS_checksum(char *s, int N) 
{             
  int i = 0;  
  char chk = s[0];

  for (i=1 ; i < N ; i++)                                                                
    chk ^= s[i];

  return chk;
}

The checksum is then always encoded as a string of two ASCII characters giving the hexadecimal value of the checksum.

System Setup

Software

Optional: FTDI USB-Serial drivers (macosx: x64 x86 PPC)

Libraries

  • SafecastBGeigie (this library), use branch NextGeneration download
  • chibiArduino modified to use with Atmega1284p (included with patched Arduino IDE) download
  • CmdArduino (included with patched Arduino IDE) download
  • Mighty 1284p core files (included with patched Arduino IDE) download
  • [Option] SparkFun's Pro Micro core files, if you want to use the Atmega32u4 with a bootloader download

Hardware

  • USB male A to male mini B cable such as this one
  • A Pocket AVR Programmer from SparkFun. [Using another programmer type than USBTiny type requires editing a makefile.]
  • A bGeigie3 board. The PCB design files are available under CC-BY-SA 3.0 license.

Optional: FTDI breakout board 3.3V, for example this one or this one

Install

A comprehensive firmware upgrade environment can be found here.

Environment

  1. Download and install the CrossPack for AVR toolchain.
  2. Download and install Patched Arduino IDE Arduino's website provides help getting started, if needed.
  3. Download and install SafecastBGeigie library in the Arduino library folder. Arduino libraries help.

As an alternative to 1. it is possible to obtain avr-gcc and avrdude through homebrew. The package is not available directly but can be obtained from a third party. This assumes you already have homebrew installed.

brew tap larsimmisch/avr 
brew install avr-libc
brew install avrdude --with-usb

(Source. Tested on Mac OS X Mountain Lion 10.8.4))

Upload bGeigie3 firmware to main microcontroller

  1. Launch the Arduino-Safecast IDE
  2. Connect Pocket AVR Programmer to the ISP Pin header. Pin 1 of the ISP is marked on the PCB. Make sure the switch on the programmer is set to No power. Make sure the battery it attached to the board and has some charge. Make sure no SD card is inserted. ISP setting
  3. Pull low (off) the left switch on the small black dual switch on the board. Switch Setting 1284p
  4. In Arduino IDE, open File -> Examples -> SafecastBGeigie -> bGeigie3.
  5. Select Tools -> Programmer -> USBtinyISP (or whatever ISP you are using), and Tools -> Board -> Mighty 1284p 8MHz using Optiboot.
  6. Finally, launch programming by File -> Upload Using Programmer.
  7. Pull back up the left small switch. Both switches should be up (on) now. Switch normal mode

Upload USB controller firmware

  1. Connect Pocket AVR Programmer to the ISP Pin header. Pin 1 of the ISP is marked on the PCB. Make sure the switch on the programmer is set to No power. Make sure the battery it attached to the board and has some charge. Make sure no SD card is inserted. ISP setting

  2. Pull low (off) the small switch on the right of the black dual switch. Switch Setting 32u4

  3. In a terminal, go to SDReader32u4/USBtoSerialMassStorage.

     cd <arduino_libraries_path>/SDReader32u4/USBtoSerialMassStorage

  4. Compile and upload SD reader firmware to USB microcontroller. If not using a USBtinyISP kind of AVR programmer, the makefile needs to be modified before this step.

     make avrdude

  5. Pull back up the left small switch. Both switches should be up (on) now. Switch normal mode

Device configuration

It is possible to configure the device by placing a file called BGCONFIG.TXT at the root of the SD card. Its content is something like this.

ID:301
SerialOutput:1
CoordTrunc:0
HVSense:0
SDRW:0

If such a file is present on the SD card, the device will change its configuration according to it. It will then save the new configuration in EEPROM. If the file should disappear or be corrupted, it is recreated from EEPROM.

  • ID The serial number of the device. A maximum 4-digits hex number. For the bGeigie-NX, the convention is to use a 3-digits hex number starting with 3. The id 0xFFFF is reserved for unconfigured devices.
  • SerialOutput: [0/1] This enables display of log lines through the serial connection.
  • CoordTrunc: [0/1] When set to one, this enables the truncation of GPS coordinates to a 100x100m grid.
  • HVSense: [0/1] When set to one, the high-voltage sensing is activated. This is useful for HV boards that have a sensing output.
  • SDRW: [0/1] When set to one, the SD card is writable through the USB reader. Otherwise it is read-only.

It possible to modify these options by changing the file, or by connecting through the serial port and use the config command described in the following secton.

Serial interface

When connecting the device to a computer with a USB mini-B cable, a serial interface with the main controller is available for configuration and debugging.

  • The config command can be used to change the configuration of the device.

      *************** CMD *******************
  CMD >> config help
  Usage: config <cmd> [args]
  List of commands:
    config show                    Show current configuration.
    config show [eeprom/file]      Show eeprom/file configuration.
    config ID [id]                 Set device serial number. This is a 4-digit hex number
    config SerialOutput [on/off]   Toggle serial output on or off.
    config CoordTrunc [on/off]     Enable or disable coordinate truncation to 100x100m grid.
    config HVSense [on/off]        Enable or disable high-voltage output sensing.
    config SDRW [on/off]           Enable or disable write permission to SD card through reader.
    config save                    Writes configuration to EEPROM and SD card.
    config save [eeprom/file]      Writes configuration to EEPROM or SD card.
    config copy [eeprom/file]      Copy configuration from EEPROM or SD card to memory.
    config help                    Show this help.

    To make any configuration change permanent, do not forget to type config save.

  • The gpsfullcold command forces the GPS to do a full cold restart, meaning the current almanach, as well as any setting or configuration are dismissed. This can sometimes be necessary to ensure that the GPS module has a predictable behavior.

  • The diagnostics command run a diagnostic of the device and display the result.

      *************** CMD *******************
  CMD >> diagnostics
  --- Diagnostic START ---
  Version,3.2.6
  Device ID,301
  Radio enabled,yes
  Radio initialized,yes
  Radio address,3301
  Radio channel,20
  GPS type MTK,yes
  GPS system startup,yes
  SD inserted,yes
  SD initialized,yes
  SD open file,yes
  SD read write,yes
  SD reader enabled,yes
  SD reader initialized,yes
  Temperature,24C
  Humidity,52%
  Battery voltage,4088mV
  HV sense enabled,no
  System free RAM,13569B
  Power management enabled,yes
  Command line interface enabled,yes
  Coordinate truncation enabled,yes
  --- Diagnostic END ---

  • The help command gives a summary of the commands available through the serial interface.

      *************** CMD *******************
  CMD >> help
  List of commands:
    config <cmd> [arg]  Configure device.
    diagnostics         Run diagnostic of device.
    gpsfullcold         Do a full cold restart of the GPS.
    help                Show this help

Prepare the SD card to be used with Mac OS X

Mac OS X creates a number of hidden files for indexing and other esoteric stuff. When the SD card is in read/write mode (SDRW=1), this can slow down communication quite a bit. To prevent indexing and trash, and logging, one can add a number of files at the root of the SD card (source).

.metadata_never_index
.Trashes
.fseventsd/no_log

Example Sketches

The sketches given in examples are the actual firmware of the different Safecast bGeigie devices:

  • bGeigie3
  • bGeigieMini
  • bGeigieClassic
  • bGeigieNinja
  • bGeigieNinja2
  • bGeigieConfigBurner

License

Copyright (c) 2013-2014, Robin Scheibler aka FakuFaku
Copyright (c) 2011-2012, Robin Scheibler aka FakuFaku, Christopher Wang aka Akiba
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the <organization> nor the
   names of its contributors may be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Acknowledgement

  • Bunnie Huang for a lot of help and patience helping setting up the production.
  • Freaklabs for a lot of help in general, and more particularly for the design of the radio and the great chibiArduino library for 802.15.4 communication.
  • Maniacbug for his port of the arduino environment for the Atmega1284p that got me started.
  • ElasticSheep for the basis of the SD mass storage reader.
  • LUFA for the SD mass storage reader.
  • Adafruit for the design around the Atmega32U4 inspired from their breakout board.
  • SparkFun for the Li-Poly charger inspired by their basic charger.