README

		Nano_MCA README (fork of GammaGrapherVersion2 GGV2)


SUMMARY

This is a project to convert a DSO 201 Nano oscilloscope into a multichannel
analyzer for gamma spectrometry. This software should work with all versions of
the DSO 201. However the very earliest does not have analog input connected to
both ADC's. So sampling with that is at half the speed as with other versions.


LICENSING

See the file COPYING as well as each file for license information.

This project is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2.1 of the License, or (at your option) any
later version.

This project is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along
with this library; if not, write to the Free Software Foundation, Inc., 51
Franklin St, Fifth Floor, Boston, MA 02110-1301 USA


DEVELOPMENT ENVIRONMENT

As of 2012-10-10, CodeSourcery-maintained toolchain for ARM EABI under Linux is used:
http://static.leaflabs.com/pub/codesourcery/arm-2010q1-188-arm-none-eabi-toolchain-linux32.tar.gz
Just download the above file, extract it to some directory and add it to your
$PATH, e.g.:

mkdir -p $HOME/lbin/ARM_EABI
wget http://static.leaflabs.com/pub/codesourcery/arm-2010q1-188-arm-none-eabi-toolchain-linux32.tar.gz
tar xzvf *arm-none-eabi-toolchain-linux32.tar.gz -C $HOME/lbin/ARM_EABI
echo "export PATH=\$PATH:$HOME/lbin/ARM_EABI/arm/bin" >> $HOME/.bashrc

To upload firmware to the Nano, you'll need dfu-util-0.5 or newer:
http://wiki.openmoko.org/wiki/Dfu-util

Old (before GGV2-0.12) source code and compiled firmware is available from
http://sourceforge.net/projects/gammagrapherv2/ and in the files area of
GammaSpectrometry group at Yahoo (need registration, http://tech.groups.yahoo.com/group/GammaSpectrometry/).


HOW TO USE

To upgrade the Nano by using pre-compiled firmware (found in /releases directory):
0. Download/install dfu-util-0.5. or newer;
1. Download the firmware version you want (latest is best);
2. Connect the Nano via USB and power it off;
3. Press and hold on the "down" (\/) button and power on the Nano;
4. Confirm that you are seeing "Firmware Upgrading..." on its display;
5. From a shell `dfu-util -a 0 -D the_name_of_the_firmware`;
6. Disconnect the USB cable and power back on the Nano to confirm the firmare version.

To build your own firmware:
0. Setup your einvironment (git, dfu-util, arm-none-eabi-toolchain) as described
1. Get the source, compile it and uplod (follow onscreen instructions)
  git clone https://github.com/thinrope/Nano_MCA.git
  cd Nano_MCA/src
  make distclean release upload


HARDWARE SETUP FOR GAMMA SPECTROMETRY

1. Connect signal source to the probe connector on the Nano.
 * Input should be within ±2.8 V (both positive/negative pulses can be used)
 * To use simple scintillator/PMT, tap the signal between HVPS and PMT with a
   10nF/2kV ceramic cap and connect 22kOhm resistor between the Nano input and
   signal ground
2. To hear clicks, connect a piezo transducer to the "Signal Generator" output
of the Nano.


SETTINGS

To select operating mode and adjust parameters there is a menu feature. Press
the M key to enter and exit the menu. You can manually save parameters to flash
memory. Saved settings are restored on power up or through menu. The 4-way
button has markings that should be ignored. Buttons will be referred to as up,
down, left, and right. The button marked for pause and forward controls
acquisition of pulses. This allows you to stop the display and resume at any
time. A small symbol at lower left shows if stopped or running.

There are 2 modes: PHA and Rate 

PHA (Pulse Height Analysis) is a traditional multi channel analyzer (MCA).
Input pulses are plotted on X axis with Y axis being accumulated counts. At
this point only 2048 channels are supported. This should be sufficient. There
is a cursor that provides a readout of counts and keV. Left and right buttons
move the cursor. You can adjust width of cursor so counts display includes
multiple channels. Up and down buttons control zoom in/out. Use Input Range to
adjust for input peak voltage. 0 is lowest and represents inputs as low as 50
mv. Maximum input is 10 V. Always start from the highest range working down
until good signal is seen. Use "energy coefficient" to adjust translation of
pulse height to x axis as displayed. Display y axis is self adjusting.

Rate mode records counts over an adjustable period, then displays past counts
with a scrolling histogram. Sample periods can be adjusted through menu.
Adjusting sample period changes the scrolling speed of histogram. Display y
axis is self-adjusting. Display y axis is self adjusting. A cursor provides
readout of counts an any point in the graph.

Setup Menu:

Setup menu provides adjustment of parameters to match probe setup etc. To
increase or decrease a value use right or left button, respectively. Those
settings that have no value are executed with either left or right key. Such as
Clear All. Settings are restored from flash memory automaticaly on power up.
Changes to settings is automatically stored to flash memory on leaving menu
mode. Unimplemented parameters are not displayed or marked with an asterisk.

Communicating with Nano

The way the nano communicates with a host is it appears to be mass storage
device on the USB bus. Specifically a SCSI hard drive. This uses existing code
and is a standard means of communicating over USB. Also means you don't need
any special code on the PC, the nano looks like a generic mass storage device.

The sd card in nano is accessed on the most primitive level over USB, Just
block reads and writes. File-system code resides on the PC. However there is
also file system code in the Nano. So you have two independent pieces of
software on two different pieces of hardware accessing the same flash card at
the level of block reads and writes. This can really get things confused! Best
to use only PC or only nano when usb is connected.

Obviously the nano has to be able to be connected to USB for charging while in
use, Most devices like MP3 players lock out the device controls while USB
connected. Instead a warning will be added if USB connected and a spectrum file
created. To access new file from PC just disconnect and reconnect the usb
cable. That resets the pc code and it will see all the new files in nano.


KNOWN ISSUES (TBC)

* Flash card support is tested with FAT32 filesystem only. FAT16 code is
  included but untested.

* Number of files is very limited. This will be fixed in next release.

* Turning on the Nano with USB connected causes problems with flash card access.
  Code detects this and reminds users to disconnect USB.

* ADC is set up for overlapping sampling using both ADC's. This provides a 2 mHz
  sample rate. Very old Nano's have only 1 ADC connected to input. This will
  cause problems. If necessary software will add an option to use only 1 ADC.
  Recommended solution is to get a newer Nano.

* AUTOTUNE function is seted fix to TRUE value so don't know if this is correctly
  working but presume it is a bug. 0.9 Autotune not fully implemented yet.

* Rate measurement in CPM is about half of actual rate. This needs to be corrected.

* Coincidence detection code still needs implementation.