Usage
There are following applications based on gr-gsm:
-
grgsm_decode(old name:airprobe_decode.py) - program for decoding C0 channel which is most close in terms of functionality to the old gsm-receiver from Airprobe project with ability to decode signalling channels and traffic channels with speech (analysis of the data can be performed in Wireshark, decoded sound is stored to an audio file), -
grgsm_livemon(old name:airprobe_rtlsdr.py) - interactive monitor of a single C0 channel with analysis performed by Wireshark, -
grgsm_scanner(old name:airprobe_rtlsdr_scanner.py) - an application that scans GSM bands and prints information about base transceiver stations transmitting in the area,
There are following helper programs for grgsm_decode application:
-
grgsm_capture(old name:airprobe_rtlsdr_capture.py) - program for capturing GSM signal to a file that can be later processed by grgsm_decode, -
grgsm_channelize(old name:gsm_channelize.py) - splits wideband capture file into multiple files - each contain single GSM channel.
The grgsm_livemon decodes in realtime C0 GSM channel selected by the user. C0 channel is transmitted by every BTS and carries synchronization information, configuration of the cell and user data (such as short messages and voice). The program uses cheap RTL-SDR receivers as a source of the signal. Other SDR receivers supported by gr-osmosdr (like USRPs, HackRF, BladeRF) might work as well. The application can be started by running from a terminal:
grgsm_livemon
The window of the program contains amplitude spectrum of the signal drawn in real-time. The central frequency of the signal can be changed by moving fc slider. The GSM signal has bandwidth of around 200kHz. By looking for constant hills on the spectrum of such width you can find a GSM broadcasting channel. After setting the fc slider to a carrier frequency of a broadcasting channel the program should immediately print content of subsequent messages on the standard output.
If it doesn't happen, set ppm slider into different positions. The slider is responsible for setting devices clock offset correction. If the clock offset is too large the clock offset correction algorithm that is implemented in the program won't work. There is intentionally added upper of allowable clock offset - it was done in order to avoid adaptation of the algorithm to neighbour channels that would inevitably lead to instability. You can use the value set later by passing it as argument of the program:
grgsm_livemon -p <correction>
This program provides capability to save captured data to file. It supports both raw data in cfile format and gr-gsm's burst format, which are pre-processed GSM-bursts instead of raw signal data:
grgsm_capture
We will add more information about capturing using this program later, for more information about the available options you can start the program with the -h flag:
grgsm_capture -h
grgsm_decode program provides capability to decode GSM messages from saved captures, for example recorded with grgsm_capture:
grgsm_decode
The program supports both cfile and burst captures, and decoding of BCCH, SDCCH, TCH/F. Supported A5 ciphers for decryption are A5/1, A5/2 and A5/3. grgsm_decode is able to decode full-rate voice codecs GSM-FR, GSM-EFR, AMR 12.2, AMR 10.2, AMR 7.95, AMR 7.4, AMR 6.7, AMR 5.9, AMR 5.15, AMR 4.75.
For more information about the available options you can start the program with the -h flag:
grgsm_decode -h
A more detailed how to on the usage of grgsm_decode can be found in the Decoding How To
The Gr-gsm applications send GSM messages in GSMTAP format to the UDP port number 4729. Wireshark interprets packets coming on this port as GSM data with GSMTAP header and it is able to dissect messages.
On Debian like systems Wireshark can be installed with:
sudo apt-get install wireshark
To start Wireshark straight to analysis of the GSMTAP packets obtained from grgsm_decode use following command:
sudo wireshark -k -f udp -Y gsmtap -i lo
If you want to avoid the risks caused by running Wireshark with root privileges follow this short howto:
https://ask.wireshark.org/questions/7976/wireshark-setup-linux-for-nonroot-user
Decoding hopping channels can be achieved by feeding one input stream per hopping channel into the GSM Receiver block and connecting the CX port to a CX Channel Hopper block. At the current stage of development however, it is computationally expensive to split a wideband capture into multiple streams in real time. Therefore, the grgsm_channelize app should be used to perform this task as a preprocessing step.
As an example, the following command will channelize my_wideband_capture.cfile, in this case a cfile captured at 925.2 MHz centered (ARFCN 975) and 20 Msps. As a result, 12 files will be generated for ARFCNs 975 - 1023 at 1 Msps each:
grgsm_channelize -s 20e6 -c my_wideband_capture.cfile -f 925.2e6 990 991 992 993 994 995 1019 1020 1021 1022 1023