1 Hardware

That's the device this page is all about:

This is a picture of the "Gamma Scout with Alert" Geiger Counter. It has a USB interface on the bottom which can be used to connect the device to a PC in order to query the logged radiation data. There are also other members of the Gamma Scout Family:

1. Gamma Scout without Alert ("Gamma Scout Basic")
2. Gamma Scout with Alert ("Gamma Scout Alert")
3. Gamma Scout with Alert and Online Mode ("Gamma Scout Online")

The devices most likely differ only in their firmwares, the hardware seems quite identical. Some of the devices have a RS232 interface via a 9-pin SUB-D connector and others (most new ones) have USB. There also are at least two different protocol versions around (from hereon referred to a protocol v1 and protocol v2) which are both supported by the GammaScoutUtil. There seems to be a correlation between the firmware version, the number of digits in the display and the protocol version. As someone suggested on the Internet (I'm unsure how reliable that information is), all Gamma Scouts with firmware version <= 5.43 have a 3-digit display and use protocol version v1. All Gamma Scouts with firmware version >= 6.02 have a 4-digit display and use protocol version v2. You can find out the firmware version by pressing the "Battery" button and then the "Enter" button. For the "Gamma Scout Online", the GammaScoutUtil only supports the features that the "Gamma Scout Alert" also has (i.e. Online Mode is not supported at the moment). This is only because I have no access to a online device -- if anybody has such a device and wants to get it running, drop me a note with some details and I'll try to include support for it.

For the USB versions, the hardware which is used is a FTDI FT232RL is used which is nicely supported by Linux already:

joequad joe [~]: lsusb -v
[...]
Bus 001 Device 017: ID 0403:d678 Future Technology Devices International, Ltd 
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass            0 (Defined at Interface level)
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0         8
  idVendor           0x0403 Future Technology Devices International, Ltd
  idProduct          0xd678 
  bcdDevice            6.00
  iManufacturer           1 Dr Mirow
  iProduct                2 GammaScout USB
  iSerial                 3 GSNJR316
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength           32
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0 
    bmAttributes         0x80
      (Bus Powered)
    MaxPower              500mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           2
      bInterfaceClass       255 Vendor Specific Class
      bInterfaceSubClass    255 Vendor Specific Subclass
      bInterfaceProtocol    255 Vendor Specific Protocol
      iInterface              2 GammaScout USB
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            2
          Transfer Type            Bulk
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0040  1x 64 bytes
        bInterval               0
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x02  EP 2 OUT
        bmAttributes            2
          Transfer Type            Bulk
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0040  1x 64 bytes
        bInterval               0
Device Status:     0x0000
  (Bus Powered)
joequad joe [~]: dmesg
[...]
usb 1-3.2: new full speed USB device using ehci_hcd and address 17
ftdi_sio 1-3.2:1.0: FTDI USB Serial Device converter detected
usb 1-3.2: Detected FT232RL
usb 1-3.2: Number of endpoints 2
usb 1-3.2: Endpoint 1 MaxPacketSize 64
usb 1-3.2: Endpoint 2 MaxPacketSize 64
usb 1-3.2: Setting MaxPacketSize 64
usb 1-3.2: FTDI USB Serial Device converter now attached to ttyUSB0

It therefore appears as a serial interface (/dev/ttyUSBn). A query I did with the vendor (Dr. Mirow) in order to get access to the protocol details remained unanswered. Therefore I re-engineered the v2-protocol and wrote a device driver with which you can use the device. Luckily, the protocol was quite easy to understand. For the protocol v1 some info could be found on the net and I had the help of Jörg Wartenberg, who kindly provided the test data from his device (since I do not own a protocol v1 Gamma Scout)

2 Communication Protocol v1

2.1 Commands and Responses

Older models of the Gamma Scout family use the v1 protocol. This is, as the v2, based on ASCII communication, but a little bit more limited. Most notably, the PC cannot initiate the connection, but the "PC mode" has to be activated first by pressing the according button of the Gamma Scout. This makes the Gamma Scout with a v1-protocol virtually useless for continuous data logging. Communication is performed with 2400 baud, 7E1, no echo. Note that every response (in contrast to the v2 protocol) is not only preceded by "\r\n", but also by a space character (denoted explicitly as \s for more clarity). Here's the command list:

v
 Version 5.43

d021011
 Datum gestellt

u1234
 Zeit gestellt

z
 Protokollspeicher wieder frei

i

b
 GAMMA-SCOUT Protokoll 

 0000 03 02 01 ff ff ff ff ff ff ff ff ff ff ff ff ff
 0010 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 0020 31 01 ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 0030 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 0040 ff ff ff ff ff ff ff ff de ad be ef ff ff ff ff
 0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
[...]
 0100 fe 40 08 28 06 11 f2 04 07 03 ae 03 c6 ff 0f 00
 0110 00 f8 f0 3c 22 3c 2a 3c 2a 3c 2f 3c 21 3c 1a 3c
 0120 12 37 f4 37 ed 37 ee 3c 08 3c 05 3c 05 37 f7 37
 0130 ff 02 da 02 ef 02 e3 02 bd 02 b6 02 fe 02 f4 02
 0140 c6 02 ce 02 f6 02 db 02 e4 02 b9 02 e5 02 eb 02
 0150 dd 02 eb 02 e6 02 e4 02 e4 02 bc 02 d3 02 e2 02
 0160 a6 03 08 02 dd 02 d1 02 c9 02 bd 02 e1 03 03 03
 0170 02 02 e2 02 e7 02 ee 02 da 02 e4 02 d3 02 e0 02
 0180 f1 02 ef 02 d0 02 ba 02 d5 02 c0 03 0a 02 e4 02
 0190 f0 02 ee 02 e8 02 be 02 f8 02 cd 02 c1 02 e7 02
 01a0 f6 02 c7 02 ea 02 c8 02 f5 02 f0 02 c7 02 a2 02
 01b0 e8 02 d8 03 03 02 d8 02 ee 02 cb 02 98 02 bb 02
 01c0 bf 03 00 02 f7 03 23 02 c6 02 c3 02 e0 02 dd 02
 01d0 d1 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 01e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
[...]
 07f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff

2.2 Log Interpretation

In contrast to the protocol version 2, special command codes are slightly different. The first three bytes of the log encode the serial number of the device in little endian using the "decimal interpreted as hexadecimal" representation (i.e. for the above device, that serial would be 10203). At position 0x20 a uint16 value is stored in little endian byte order indicating the first invalid address in the log. The actual log then starts at 0x100. For the example above, the first invalid log address is 0x131 (the uint16 value at position 0x20), therefore the log is from 0x100 to 0x130 (inclusively). The log itself contains encoded command codes and impulse counts. The command codes always have 0xf in the first nibble of the first byte (i.e. every hex-sequence that starts with 0xf? is a command code, everything else is a impulse count):

3 Communication Protocol v2

3.1 Commands and Responses

The communication protocol v2 the Gamma Scout uses is trivially easy to understand and implement. Communication is done with 9600 baud, 7E1, no echo. The protocol is ASCII-based, you can use for example picocom to play around with it a little. Here is a list of commands that you can issue and the according responses:

v
Standard

v
Version 6.05 012345 000d 02.10.11 20:11:26

P
PC-Mode gestartet

X
PC-Mode beendet

t021011201900
Datum und Zeit gestellt

c
00000000000000000000
00000000000000000000
00000000000000000000
00000000000000000000
00000000000000000000

b
GAMMA-SCOUT Protokoll
f5ef5719021011f508007a0084007e007cf5ef11200210110087f5ee0600002236
f50c00010006000600040004000400010006000600010004000400020005000239
0002000300057700840077f5ee05000012f501f5ee890c1ec9f5080074007c00b8

z
Protokollspeicher wieder frei

i

3.2 Log Interpretation

The log that is issued upon sending the "b" command is also quite easy to understand. First it is necessary to know that the log does not get reset when it is cleared, only the pointer gets reset to the beginning. Therefore it is necessary to query how much data is valid by using the "v" command before issuing "b". Each line contains 33 bytes of data (i.e. 66 characters + "\r\n", so 68 bytes per line). The first 32 bytes in each line are actual protocol data. The last byte is the checksum, which can be calculated by taking the sum of the preceding 32 bytes modulo 256. Then while traversing the log, if the first byte is 0xf5, it indicates a special command and has variable length. If it does not start with 0xf5, it is a impulse count, coded in big endian format. Here's the list of special commands:

4 Floating Point Representation

Impulse counts are encoded in floating point represenation with a 6 bit exponent and 10 bit mantissa. First, the value is converted using big endian decoding (most significant byte first):

value = (data[0] << 8) | data[1]

exponent = (value & 0xfc00) >> 10
mantissa = (value & 0x03ff)

exponent = (exponent + 1) // 2

if exponent == 0:
    counts = mantissa
else:
    counts = (mantissa + (2 ** 10)) * (2 ** (exponent - 1))

4.1 Examples

00 aa = 170
01 bb = 443
02 cc = 716
03 dd = 989
04 ee = 1262
05 ff = 1535
12 34 = 3176
ab cd = 2094006272

For the last example (ab cd), converting to big endian yields 0xabcd. The exponent and mantissa therefore are 42 and 973. After mangling the two least significant bits of the exponent together, the exponent is 21. Therefore, the result is: (973 + 1024) * 2²⁰ = 1997 * 2²⁰ = 2094006272.

Thanks to Martin Bönsch, who noticed an error in the above calculation and corrected it.

5 Linux Software: GammaScoutUtil

5.1 Prerequisites

Here's what's required to get GammaScoutUtil running:

• Python 3.0 or greater
• pyserial

For Ubuntu:

joequad joe [~/GammaScoutUtil-0.04]: sudo apt-get install python3 python-serial

5.2 Getting Started

After plugging in the Gamma Scout into your USB port, check with dmesg which device it is recognized as. Usually this will be /dev/ttyUSB0. Then, you can call gammascoututil to check if it finds your Gamma Scout. Putting the Gamma Scout into PC mode beforehand is actually not necessary, the software takes care of that.

joequad joe [~/GammaScoutUtil-0.04]: ./gammascoututil
Nothing to do.

./gammascoututil (-d Device) (-p Protocol) (-v) [Cmd1] ([Cmd2]) ([Cmd3]) ...
   -d Device     Specifies the serial device that the Gamma Scout is
                 connected to. Default is /dev/ttyUSB0
   -p Protocol   Specifies the device protocol the connected Gamma Scout
                 uses. Either 'v1' or 'v2'. Default is 'v2'.
   -v            Outputs debug information
   --help        Displays this help page

  Commands:
     identify
         Displays information like the Gamma Scout software version and
         serial number of the device
     synctime
         Synchronizes the time with the current local system time
     syncutctime
         Synchronizes the time with the current time in UTC (GMT+0)
     settime:YYYY-MM-DD-HH-MM-SS
         Sets the time to the user defined value
     readlog:[txt|sqlite|csv|xml|bin]:[Filename]
         Reads out Gamma Scout log in text format, sqlite format, CSV, XML
         or binary format and writes the results to the specified filename
     clearlog
         Deletes the Gamma Scout log
     readcfg:Filename
         Reads out the configuration blob and writes it in the specified
         file in binary format
     devicereset
         Completely resets the device to its factory defaults. Do not perform
         this operation unless you have a good reason to.

  Examples:
     ./gammascoututil -p v1 -d /dev/ttyS0 identify
     ./gammascoututil -d /dev/ttyUSB3 identify
     ./gammascoututil readlog:sqlite:/home/joe/foobar.sqlite clearlog
joequad joe [~/GammaScoutUtil-0.04]: ./gammascoututil identify
Current date and time: 2011-10-02 19:53:49
Serial number        : 12345
Software version     : 6.05
Log buffer fill      : 75 bytes

Then, let's first read out the internal log into a text file:

joequad joe [~/GammaScoutUtil-0.04]: ./gammascoututil readlog:txt:counter.txt
joequad joe [~/GammaScoutUtil-0.04]: cat counter.txt
From                   To                    Counts Seconds    CPM     CPS
--------------------------------------------------------------------------------
2011-10-02 18:23:00    2011-10-02 18:28:00      105     300   21.0   0.350
2011-10-02 18:28:00    2011-10-02 18:33:00      181     300   36.2   0.603
2011-10-02 18:33:00    2011-10-02 18:38:00      126     300   25.2   0.420
2011-10-02 18:38:00    2011-10-02 18:43:00      104     300   20.8   0.347
2011-10-02 18:43:00    2011-10-02 18:48:00      120     300   24.0   0.400
2011-10-02 18:48:00    2011-10-02 18:53:00      100     300   20.0   0.333
2011-10-02 18:53:00    2011-10-02 18:58:00      112     300   22.4   0.373
2011-10-02 18:58:00    2011-10-02 19:03:00      125     300   25.0   0.417
2011-10-02 19:03:00    2011-10-02 19:08:00      129     300   25.8   0.430
2011-10-02 19:08:00    2011-10-02 19:13:00      118     300   23.6   0.393
2011-10-02 19:13:00    2011-10-02 19:18:00      121     300   24.2   0.403
2011-10-02 19:18:00    2011-10-02 19:23:00      115     300   23.0   0.383
2011-10-02 19:23:00    2011-10-02 19:28:00      116     300   23.2   0.387
2011-10-02 19:28:00    2011-10-02 19:33:00      119     300   23.8   0.397
2011-10-02 19:33:00    2011-10-02 19:38:00      117     300   23.4   0.390
2011-10-02 19:38:00    2011-10-02 19:43:00      119     300   23.8   0.397
2011-10-02 19:43:00    2011-10-02 19:48:00      132     300   26.4   0.440
2011-10-02 19:48:00    2011-10-02 19:53:00      119     300   23.8   0.397

What you might want to do if your have the tool running via a cronjob (i.e. have the setting log in a small interval and clear the data nightly) is log into a database. For this you can directly query into a sqlite database. Also note that you can supply multiple commands on one command line (for example, readout and clear the database afterwards):

joequad joe [~/GammaScoutUtil-0.04]: ./gammascoututil readlog:sqlite:counter.sqlite clearlog
joequad joe [~/GammaScoutUtil-0.04]: sqlite counter.sqlite .dump
PRAGMA foreign_keys=OFF;
BEGIN TRANSACTION;
CREATE TABLE data (
			id integer PRIMARY KEY,
			tfrom timestamp NOT NULL,
			tto timestamp NOT NULL,
			counts integer NOT NULL,
			CHECK(tto > tfrom),
			CHECK(counts >= 0)
		);
INSERT INTO "data" VALUES(1,'2011-10-02 18:23:00','2011-10-02 18:28:00',105);
INSERT INTO "data" VALUES(2,'2011-10-02 18:28:00','2011-10-02 18:33:00',181);
INSERT INTO "data" VALUES(3,'2011-10-02 18:33:00','2011-10-02 18:38:00',126);
INSERT INTO "data" VALUES(4,'2011-10-02 18:38:00','2011-10-02 18:43:00',104);
INSERT INTO "data" VALUES(5,'2011-10-02 18:43:00','2011-10-02 18:48:00',120);
INSERT INTO "data" VALUES(6,'2011-10-02 18:48:00','2011-10-02 18:53:00',100);
INSERT INTO "data" VALUES(7,'2011-10-02 18:53:00','2011-10-02 18:58:00',112);
INSERT INTO "data" VALUES(8,'2011-10-02 18:58:00','2011-10-02 19:03:00',125);
INSERT INTO "data" VALUES(9,'2011-10-02 19:03:00','2011-10-02 19:08:00',129);
INSERT INTO "data" VALUES(10,'2011-10-02 19:08:00','2011-10-02 19:13:00',118);
INSERT INTO "data" VALUES(11,'2011-10-02 19:13:00','2011-10-02 19:18:00',121);
INSERT INTO "data" VALUES(12,'2011-10-02 19:18:00','2011-10-02 19:23:00',115);
INSERT INTO "data" VALUES(13,'2011-10-02 19:23:00','2011-10-02 19:28:00',116);
INSERT INTO "data" VALUES(14,'2011-10-02 19:28:00','2011-10-02 19:33:00',119);
INSERT INTO "data" VALUES(15,'2011-10-02 19:33:00','2011-10-02 19:38:00',117);
INSERT INTO "data" VALUES(16,'2011-10-02 19:38:00','2011-10-02 19:43:00',119);
INSERT INTO "data" VALUES(17,'2011-10-02 19:43:00','2011-10-02 19:48:00',132);
INSERT INTO "data" VALUES(18,'2011-10-02 19:48:00','2011-10-02 19:53:00',119);
COMMIT;

5.3 Downloads