Gm4Lin - Radiation detector driver for Linux

This is the very begining of a documentation for gm4lin (for version 1.2.12)

Goal

The goal of that software is to enable people to use the GM-45 radiation detector manufactured by "Black Cat Systems" under Linux. That detector connects to the computer using the serial interface. More informations about the detector can be found on http://www.blackcatsystems.com or on http://www.lndinc.com/gm/alpha/7317.htm (LND Inc. is the maker of the chamber ref 7317 used in that detector).

Simple mode of operation

If the detector is connected on the first serial port (by default, I considered it to be /dev/tts/1, /dev/tts/0 beeing used by a serial mouse), then open a terminal window and enter:
bash#> gm4lin
It is then going to write on the screen every 10 seconds the particules count and dump the same data to a file. The location of that data logging file can be given using the option '--log-path' followed by the path to this (or these) file(s).

Seeing defaults parameters, looking for help

open a terminal window and enter:
bash#> gm4lin --help
It is going to show you the available options and the default values for them.

Path to the serial device

if your serial ports have to be accessed a device name different than the default one, simply specify on the command line the root of these device names:
bash#> gm4lin --device /dev/tts/
Then, probe number '1' is going to be accessed as /dev/tts/1. If you want to access /dev/ttyS1, then enter
bash> gm4lin --device /dev/ttyS If you want to access /dev/ttyS0, you need to tell it that the first available serial port is not number 1 but 0, use the option "--start":
bash> gm4lin --device /dev/ttyS --start 0

Running with multiple detectors

You can do the acquisition of several detectors simultaneously. The maximum number is currently fixed to 16 in 'my_limits.h' but could go up to 65536 simply by changing that constant in this file and recompiling! (if you can find a PC with that number of serial ports, please call me!). So, imagine you would like to record simultaneously detectors located on /dev/ttyS2, /dev/ttyS3 and /dev/ttyS4. The starting number is then 2 and we want to record 3 probes. That means that you have to enter at the command line:
bash#> gm4lin --device /dev/ttyS --start 2 --number 3

Using usb/serial adapters

You can connect the serial port version of the detectors to your usb port using a USB/SERIAL cable (make sure your cable is compatible with Linux/osX !). Then, the devices are going to be something like /dev/usb/tts/0. So, simply use the --device command line argument for gm4lin:
bash> gm4lin --device /dev/usb/tts/ -s 0

Changing detectors sensitivities:

You can change the default detector sensitivity (because you want to use a GM10 instead of the GM45, or because you want an activity measurement with Cs137 instead of Co60, ...) with the option "--default-sensitivity" followed by a keyword. For example, if you are using one GM10 detector to measure CO60 activity, you would use the following command line:
bash#> gm4lin --default-sensitivity=GM10_CO60
The list of available keywords can be displayed with the option "--list-sensitivities" (the list will be displayed and the program will exit immediatelly). If you are using different detectors connected to the same computer, then you need to specify individual sensitivities. This can be done with the "--sensitivity" keyword. For example, if you have three detectors using the default sensitivity and one detector beeing a GM10 located in second position, then you could use the following command line:
bash#> gm4lin --number 4 --sensitivity=GM45_CO60,GM10_CO60,GM45_CO60,GM45_CO60
You can also use the following shortcut:
bash#> gm4lin --number 4 --sensitivity=GM45_CO60,GM10_CO60
(it means that the first detector will be reaffected to GM45_CO60, the second to GM10_CO60 and the last ones will be left at the default value)

Pulse mode versus activity count mode

If the activity you are measuring is quite low, then it could be more interesting to look at each particule at a time. This is the goal of the pulse mode: it shows you every 1 seconds (default value) the charge density decay of the chamber. The decay time has been calibrated in order to be equivalent to the Bicron RSO-50E detector which seems to be ~1.7 seconds. What you are going to see is the equivalent to the signal displayed by the needle of such an analog detector. The option to specify "pulse recording" is '--pulse'. The calibration has been done in order to be fully equivalent to the Bicron detector. On the other hand, if the activity is quite high, counting the number of particules going through the chamber is going to be more interesting. This is the default behavior of the software (calibrated for 60 cps of Co60=1 mR/h).

Logging data to a MySQL database

In order to save data into a MySQL database, you simply need to give the '--mysql' option on the command line. So, if you want to save data to the table "radiation" in database "experiment" on host "recorder", you simply need to enter:
bash#> gm4lin --mysql user@recorder:experiment:radiation:gm45_ --passwd secret_password
Where user is the user name you are using to connect to the database, secret_password is the associated password (from the database point of view) and gm45_ is the generic name of the fields associated with the detectors into the table. That means that detector 1 would go into gm45_1, detector 2 would go into gm45_2, ... If you don't want to log data to a file at the same time, add the option --no-file-log. If you want to use another port (ie: not MySQL default port), add the option "--port port_number".

Logging errors using syslog

In order to let syslog log the errors, enable the command line option '--syslog'. For example, enter something like:
bash#> gm4lin --syslog
The logs will be somewhere like /var/log/daemons/errors (it may vary, depending on your system).

Running as a daemon

If you want gm4lin to run as a daemon (that means, in the background, detached from terminals, logging error messages using syslog), simply use the option '--daemon' (it implies logging error messages using syslog). For example, run
bash#> gm4lin --daemon --mysql user@recorder:experiment:radiation:gm45_ --passwd secret_password
in order to do the acquisition, logging data to a remote mysql database, logging errors to syslog, all of that quietly in the background ! If you want it to be automatically started every time you start your computer, copy the shell script nammed 'gm4lind' in /etc/rc.d/init.d/ (for RedHat, Mandrake...) and add a symbolic link to it nammed S99gm4lin in /etc/rc.d/rc3.d/ as well as a symbolic link nammed K09gm4lind in /etc/rc.d/rc6.d/. Then, it will be started as a daemon from runlevel 3 and killed when shuttingdown the machine.
For security reasons, you can use the option '--uid' followed by a uid number in order to let gm4lin run using that given uid (this is mostly useful for running as a daemon, launched by root but which should run as another user).

Timer resolution

In "initializations.h", the constant PULSE_PARTICULE_SUB_SAMPLING is defined. This is the timer resolution used in pulsed mode. The minimum value is 10 ms, but if you want to run several gm4lin process in parallel on the same computer, you have to remember that this timer resolution is the machine resolution: if you want to run two gm4lin in parallel, the timer (machine-wide) won't be able to go below 10 ms, that means 20 ms for each process (10 ms multiplied by the number of simultaneous gm4lin process is the minimum value for that constant). Otherwise, the machine can't handle such small values and "miss" some readings on the probes (because it is already working on the other process). Since the value you asked for (in the .h file) is the value used for the calibration, that means that if you miss some readings, the measurement is going to be wrong.

Testing the software with dummy probes

In order to test the load running the software on the computer is going to be, you can declare that the probes are going to be dummy probes: that means that the typical serial port initializations are not going to be done (for example, powering on the detector won't be done). Then, simply create a pipe, and use the --device command line argument in order to tell gm4lin to use that pipe. Every time you send something in that pipe, one particule is going to be detected ! For example, in order to try the pulse mode with the pipe "my_pipe0" located in your home directory, enter:
bash#> gm4lin --device ~/my_pipe -s 0 -p

Mathias Bavay, CRT Holdings Inc., 2004-03