gssm

1. Install GNU Radio. Any relatively recent GNU Radio build should work. I've been testing on revision 5220.
2. Now build gssm. It should be as simple to install as:

   		jl@hackphoo ~ $ cd ~/src/gssm
   		jl@hackphoo ~/src/gssm $ ./bootstrap && ./configure && make && sudo make install
   		[...]
   		jl@hackphoo ~/src/gssm $ 
   		

3. Get the latest version of Wireshark and apply the patch in the patch directory and then build Wireshark as usual. Note that the current version of this patch is for wireshark-0.99.5 and may not apply cleanly to newer versions.

   		jl@hackphoo ~ $ cd ~/src/wireshark-0.99.5
   		jl@hackphoo ~/src/wireshark-0.99.5 $ patch -p1 < ~/src/gssm/patch/wireshark-0.99.5-gssm.patch
   		patching file epan/dissectors/packet-gsm_a.c
   		jl@hackphoo ~/src/wireshark-0.99.5 $ ./configure && make && sudo make install
   		[...]
   		jl@hackphoo ~/src/wireshark-0.99.5 $
   	

4. gssm uses a TUN interface to send packets to Wireshark. You must have the tun.ko kernel module loaded.

   		jl@hackphoo:~$ lsmod | grep tun
   		tun                    12032  0 
   		jl@hackphoo:~$ 
   	

   If the tun.ko kernel module is not loaded, you can try and load it by hand.

   		jl@hackphoo:~$ lsmod | grep tun
   		jl@hackphoo:~$ sudo modprobe tun
   		jl@hackphoo:~$ lsmod | grep tun
   		tun                    12032  0 
   		jl@hackphoo:~$ 
   	

   If that doesn't work and you get a "FATAL: Module tun not found", you are most likely going to have to rebuild your kernel and make sure that you enable support for the TUN device.

   It appears that Ubuntu 7.04 supports the TUN device by default.

5. It is possible to configure the TUN device so that any user, or users in a certain group, can create and delete interfaces. Unfortunately, it appears that no matter who creates the interfaces only root can mark these interfaces up.

   Rather than require gssm to run as root, we instead use another simpler program to create the interface and mark it up. This program, mktun, was installed with gssm.

   		jl@hackphoo:~$ /usr/local/bin/mktun --help
   		note: you must be root (except perhaps to delete the interface)
   		usage: mktun [--help | -h] | [--delete | -d] 
   		jl@hackphoo:~$ sudo /usr/local/bin/mktun gsm
   		jl@hackphoo:~$ ifconfig
   		[...]
   		
   		gsm       Link encap:Ethernet  HWaddr 22:07:3F:7F:6A:EC  
   		          inet6 addr: fe80::2007:3fff:fe7f:6aec/64 Scope:Link
   		          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
   		          RX packets:33324 errors:0 dropped:0 overruns:0 frame:0
   		          TX packets:0 errors:0 dropped:6 overruns:0 carrier:0
   		          collisions:0 txqueuelen:500 
   		          RX bytes:1199664 (1.1 MiB)  TX bytes:0 (0.0 b)
   		
   		[...]
   		jl@hackphoo:~$ 
   	

   You can always delete the interface when you want to get rid of it.

   		jl@hackphoo:~$ sudo /usr/local/bin/mktun -d gsm
   		jl@hackphoo:~$ ifconfig | grep gsm
   		jl@hackphoo:~$ 
   	

Now, you can demod traffic.

1. Since this program doesn't scan the GSM frequency ranges for you, you must locate your closest tower by hand.

   Essentially, use usrp_fft.py in the GSM frequency ranges (http://en.wikipedia.org/wiki/GSM_frequency_ranges) and look for a peak roughly 300kHz wide. The main channel on a base station, channel 0, does not use frequency hopping so the peak of the signal you are looking for should be constant.

   The M&M clock recovery occasionally fails to synchronize with bursts and so you need a fairly strong signal to get good results with the current code. Look for signals that are at least 20dB above the noise floor. (!)

2. The USRP daughterboards have a frequency offset error which differs from board to board. Normally this error ranges from 4kHz to 32kHz. The current code will demodulate data with offsets up to 32kHz but will perform much better if you compensate for the offset.

   I've written a program called kalibrate which will tell you the offset of your local GSM tower.

   http://thre.at/kalibrate/kal-v0.4.tar.bz2.

   Alternatively, you can do this by hand as follows.

   1. Use usrp_fft.py and set the decimation rate to 112. When the frequency correction burst is transmitted it forms a peak in the signal 1625/24 kHz above the center of the channel.
   2. Locate the 67.7kHz peak and eyeball the offset. You should be able to estimate the offset within 10kHz or so.
3. Enter in the frequency and the offset above into the script gssm-v0.1/src/python/gssm_usrp.py.
4. Start Wireshark and monitor the gsm interface.

5. Start the gssm_usrp.py script.

   You should see a bunch of errors start flying by. This is expected even when we aren't receiving bad data because of the fairly brain-dead way the code determines if channels have data. Any data displayed in Wireshark has been successfully Viterbi decoded and has survived a FIRE parity check and is therefore, with extremely high-probability, valid. So, don't worry about all the errors. There aren't really that many and it doesn't affect the valid data anyway.

   If it is displayed incorrectly in Wireshark it is because I haven't implemented frame types besides Bbis.

   You can expand most of the packets you see and you can use the Wireshark filter functionality on quite a few of the GSM information elements.