Project

General

Profile

CalypsoBTS » History » Version 12

fixeria, 07/19/2018 08:45 PM

1 6 fixeria
h1. CalypsoBTS
2 1 fixeria
3 12 fixeria
{{>toc}}
4
5 6 fixeria
This tutorial describes how to turn cheap Calypso based phone(s) into a GSM BTS. We will consider both [[OsmoBTS:]] and "OpenBTS":http://openbts.org/ projects as GSM network front-ends. Due to some hardware limitations, the CalypsoBTS setup cannot provide normal quality of service and can only be used to learn how do the base stations work.
6 1 fixeria
7 6 fixeria
h2. Requirements
8 3 fixeria
9 6 fixeria
First of all, you need to understand what are you doing and any possible consequences. Please note, that you can only use the frequencies you have a valid license for. In many countries you cannot operate any GSM RF equipment until a proper license from the regulatory authority is obtained. Running a BTS without such license and/or interfering with the commercial networks is out of law and may be punished! 
10 1 fixeria
11 6 fixeria
This tutorial assumes that you already have a [[Software_Getting_Started|working setup]] of [[OsmocomBB]]. Some things (package names, etc.) can be different in your distribution, so you should be able to resolve possible problems yourself.
12 1 fixeria
13 6 fixeria
h2. Transceiver preparation
14 1 fixeria
15 6 fixeria
Transceiver is a software that performs some low-level GSM L1 operations, such as burst detection, modulation and demodulation, abstracting a BTS or MS from doing that. There are two [[OsmocomBB]] branches implementing the transceiver firmware and host application: 'sylvain/testing' and 'jolly/testing'. The last one is based on the first, but additionally allows to use multiple phones, so I advice you to choose it. 
16 1 fixeria
17 6 fixeria
h3. Dependences
18 1 fixeria
19 6 fixeria
Excepting [[libosmocore:]], the signal processing library [[libosmo-dsp:]] is also required.
20 1 fixeria
21 6 fixeria
1. Make sure you have the latest version of [[libosmocore:]]:
22 1 fixeria
23 6 fixeria
If you don't have the library:
24 1 fixeria
25 6 fixeria
<pre>
26
$ git clone git://git.osmocom.org/libosmocore
27
$ cd libosmocore/
28
</pre>
29 1 fixeria
30 6 fixeria
If you do, but need to update:
31
32 1 fixeria
<pre>
33 6 fixeria
$ cd libosmocore/
34
$ sudo make uninstall
35
$ make distclean
36
$ git pull --rebase
37
</pre>
38 1 fixeria
39 6 fixeria
Then:
40 1 fixeria
41
<pre>
42 6 fixeria
$ autoreconf -f -i
43
$ ./configure
44
$ make
45
$ sudo make install
46
</pre>
47 1 fixeria
48 6 fixeria
2. Install [[libosmo-dsp:]]:
49 1 fixeria
50 6 fixeria
<pre>
51
$ git clone git://git.osmocom.org/libosmo-dsp.git
52
$ cd libosmo-dsp/
53
$ autoreconf -i
54
$ ./configure
55
$ make
56
$ sudo make install
57
</pre>
58 1 fixeria
59 6 fixeria
h3. Firmware and host software
60 1 fixeria
61 6 fixeria
1. Clone the 'jolly/testing' branch:
62 1 fixeria
63 6 fixeria
<pre>
64
$ git clone git://git.osmocom.org/osmocom-bb.git -b jolly/testing trx
65
$ cd trx/src/
66
</pre>
67 1 fixeria
68 6 fixeria
2. Enable TX support in firmware:
69 1 fixeria
70 6 fixeria
Uncomment 'CFLAGS += -DCONFIG_TX_ENABLE' in 'target/firmware/Makefile'.
71 1 fixeria
72
73 6 fixeria
3. Compile OsmocomBB with transceiver support:
74 1 fixeria
75 6 fixeria
<pre>
76
$ make HOST_layer23_CONFARGS=--enable-transceiver
77
</pre>
78 1 fixeria
79 6 fixeria
At this step your transceiver should be ready.
80 1 fixeria
81 6 fixeria
82
h3. Clock source
83
84
Time-division (TDMA) systems require very accurate counting of the time segments (frames and timeslots) and when they start and stop. Also, multiple base stations within a network must be time-synchronized between themselves to make subscribers able to perform handover operation (switching from one BTS to another). If the towers clocking were out of sync, then communications would falter as each node would be trying to deal with segments that were slightly offset and this would introduce errors. This is why a good clock source is required to operate a base station.
85
86
The satellite systems, such as GPS and Iridium, do have pretty accurate clock that is being distributed in addition to the prime services (location, calls, etc). They could be used (and often used in commercial networks) for synchronization purposes. This approach would require one to have a corresponding receiver and a direct sky view, but there is a simpler way. We can use the SCH clock indications from existing base stations, eventually a phone is designed to do that!
87
88
So, use [[rssibin|RSSI]] or [[cell_log]] applications to find cells with good signal and remember the ARFCN numbers. One of them will be used as a clock source for our own base station.
89
90
h3. Usage
91
92
1. First, you need to run the transceiver firmware:
93
94 3 fixeria
<pre>
95 6 fixeria
$ cd trx/src/
96
$ host/osmocon/osmocon -m c123xor -p /dev/ttyUSB0 -c target/firmware/board/compal_e88/trx.highram.bin
97
</pre>
98
99
Additionally, if you have two (or more) phones, load the firmware to a second phone (optional):
100
101
<pre>
102
$ cd trx/src/
103
$ host/osmocon/osmocon -m c123xor -p /dev/ttyUSB1 -s /tmp/osmocom_l2.2 -c target/firmware/board/compal_e88/trx.highram.bin
104
</pre>
105
106
2. The host application could be found in 'src/host/layer23/transceiver/':
107
108
<pre>
109
$ cd trx/src/host/layer23/src/transceiver/
110
$ ./transceiver -h
111
</pre>
112
113
<pre>
114 1 fixeria
Usage: ./transceiver -a arfcn_sync
115
Some useful options:
116
  -h   --help             this text
117
  -d   --debug MASK       Enable debugging (e.g. -d DL1C:DTRX)
118
  -e   --log-level LOGL   Set log level (1=debug, 3=info, 5=notice)
119
  -D   --daemonize        For the process into a background daemon
120
  -s   --disable-color    Don't use colors in stderr log output
121
  -a   --arfcn-sync ARFCN Set ARFCN to sync to
122
  -p   --arfcn-sync-pcs   The ARFCN above is PCS
123
  -2   --second-phone     Use second phone for TS 1
124
  -r   --realtime PRIO    Set realtime scheduler with given prio
125 6 fixeria
</pre>
126 1 fixeria
127 6 fixeria
The --arfcn-sync or --arfcn-sync-pcs are used to specify the ARFCN of a clock source cell. The high priority scheduling is recommended for low-performance PCs.
128 1 fixeria
129 6 fixeria
3. Let's try to synchronize with a BTS:
130 1 fixeria
131 6 fixeria
If you have two (or more phones), add '-2' option.
132 2 fixeria
133 6 fixeria
<pre>
134
$ ./transceiver -a <ARFCN>
135
</pre>
136 2 fixeria
137 6 fixeria
You should see something like this:
138
139 2 fixeria
<pre>
140 1 fixeria
<0012> l1ctl.c:383 Reset received: Starting sync.
141
<0012> l1ctl.c:338 Sync acquired, setting BTS mode ...
142 3 fixeria
<0011> trx.c:194 TRX CLK Indication 1255520
143
<0011> trx.c:194 TRX CLK Indication 1255571
144 2 fixeria
<0011> trx.c:194 TRX CLK Indication 1255622
145 3 fixeria
<0011> trx.c:194 TRX CLK Indication 1255673
146 1 fixeria
<0011> trx.c:194 TRX CLK Indication 1255724
147 3 fixeria
<0011> trx.c:194 TRX CLK Indication 1255775
148 1 fixeria
<0011> trx.c:194 TRX CLK Indication 1255826
149
<0011> trx.c:194 TRX CLK Indication 1255877
150
<0011> trx.c:194 TRX CLK Indication 1255928
151 3 fixeria
<0011> trx.c:194 TRX CLK Indication 1255979
152 1 fixeria
<0011> trx.c:194 TRX CLK Indication 1256030
153 3 fixeria
<0011> trx.c:194 TRX CLK Indication 1256081
154 5 laforge
...
155 6 fixeria
</pre>
156 2 fixeria
157 3 fixeria
If something goes wrong, find another ARFCN and try again.
158 6 fixeria
As soon as you get the transceiver synchronized, just keep it running.
159 2 fixeria
160 6 fixeria
h2. CalypsoBTS with [[OsmoNITB:]]
161 2 fixeria
162 6 fixeria
The simplest way to setup a GSM network is to use [[OsmoBTS:]] with [[OpenBSC:]] in [[OsmoNITB:]] mode. [[OsmoNITB:]] is a simple core network implementation - network in the box. It emulates basic core elements like MSC, HLR, VLR, etc. [[OsmoBTS:]] is a part of Osmocom GSM core network implementation, that supports a variety of different hardware back-ends, including [[TRX Interface]] transceivers like [[OsmoTRX:]]. Unlike "OpenBTS":http://openbts.org/, this software stack is well maintained, so I would recommend you to choose it.
163 2 fixeria
164 6 fixeria
h3. Installation
165 3 fixeria
166 6 fixeria
This guide is not about building the core network software, so please follow [[openbsc:Building_OpenBSC|Building OpenBSC]]. Feel free to browse the wiki and check out the official documentation http://ftp.osmocom.org/docs/.
167 2 fixeria
168 6 fixeria
You will need to build / install the following components:
169 3 fixeria
170 6 fixeria
* openbsc (legacy Network in the Box)
171
* osmo-bts (with --enable-trx flag)
172 3 fixeria
173 6 fixeria
h3. Configuration
174 2 fixeria
175 6 fixeria
Almost each program has the configuration examples. Just look for 'doc/examples/'. I recommend you to customize them as you need and put the updated files in a separate directory. Let's use the '~/.osmocom/' for such purposes:
176
177 3 fixeria
<pre>
178 6 fixeria
$ mkdir ~/.osmocom/
179 2 fixeria
</pre>
180
181 6 fixeria
You can use the following configuration examples:
182 2 fixeria
183 6 fixeria
* [[OsmoNITB:]]: 'doc/examples/osmo-nitb/sysmobts/openbsc.cfg'
184 7 fixeria
* [[OsmoBTS:]]: 'doc/examples/calypso/osmo-bts.cfg'
185 2 fixeria
186 1 fixeria
There are some important things you need to pay attention.
187 7 fixeria
The recommended values are listed below.
188 3 fixeria
189 7 fixeria
h3. OsmoNITB configuration
190 1 fixeria
191 7 fixeria
h4. Network identification
192
193 1 fixeria
<pre>
194 7 fixeria
network
195
  ...
196
  network country code 901
197
  mobile network code 70
198
  short name OpenBSC
199
  long name OpenBSC
200 1 fixeria
</pre>
201
202 7 fixeria
h4. Network access
203 1 fixeria
204 7 fixeria
Warning! Setting the access policy to 'accept-all' may be dangerous. It's recommended to use the 'closed' policy, adding your test subscriber(s) info to the HLR database.
205
206 1 fixeria
<pre>
207 7 fixeria
network
208
  ...
209
  auth policy (closed | accept-all | regexp | token)
210
  authorized-regexp .*
211 6 fixeria
</pre>
212 1 fixeria
213 7 fixeria
h4. Encryption
214 2 fixeria
215 1 fixeria
To be able to use any encryption algorithm, you need to know the Ki of subscribers. So, it's recommended not to use any encryption (A5/0) for testing.
216
217 7 fixeria
<pre>
218
network
219
  ...
220
  encryption a5 (0 | 1 | 2 | 3)
221
</pre>
222 1 fixeria
223 7 fixeria
h4. Channel configuration
224
225 1 fixeria
Set a proper ARFCN for running BTS (don't confuse with a clock source). Also, set a corresponding band name.
226 3 fixeria
227 1 fixeria
<pre>
228 7 fixeria
network
229
  ...
230
  bts 0
231
    ...
232
    band (GSM900 | DCS1800)
233
    ...
234
    trx 0
235
      ...
236
      arfcn ARFCN
237 1 fixeria
</pre>
238
239 7 fixeria
h4. MS power control
240 1 fixeria
241 7 fixeria
If the normal phones are only one or few meters away, the maximal power should be set to 0. In case of long distance test it can be set to 30 (DCS) or 33 (GSM 900).
242
243
<pre>
244
network
245
  ...
246
  bts 0
247
    ...
248
    ms max power 0
249
</pre>
250
251
h4. Logical channel mapping
252
253 1 fixeria
I recommend you to use the combined channel configuration (CCCH+SDCCH4) for TS0, because CalypsoBTS at the moment cannot serve all timeslots.
254
255
<pre>
256 7 fixeria
network
257
  ...
258
  bts 0
259
    ...
260
    trx 0
261
      ...
262
      timeslot 0
263
        phys_chan_config CCCH+SDCCH4
264
        hopping enabled 0
265 1 fixeria
</pre>
266 6 fixeria
267 1 fixeria
If you have two or more Calypso based phones, it's also possible to serve the second timeslot (TS1). For example, 'TCH/H' channel could be used to serve one voice call between two subscribers.
268
269
<pre>
270 7 fixeria
network
271
  ...
272
  bts 0
273
    ...
274
    trx 0
275
      ...
276
      timeslot 1
277
        phys_chan_config TCH/H
278
        hopping enabled 0
279 1 fixeria
</pre>
280
281 11 fixeria
h4. Subscriber management policy
282
283
Of course, you can manually edit HLR database and configure as much subscribers as you need. But the simplest way is to create subscriber records on fly, during the Location Update Request.
284
285
<pre>
286
network
287
  ...
288
  bts 0
289
    ...
290
    trx 0
291
      ...
292
nitb
293
  subscriber-create-on-demand
294
  assign-tmsi
295
</pre>
296
297 7 fixeria
h3. OsmoBTS configuration
298 1 fixeria
299 7 fixeria
h4. GSM band configuration
300
301 1 fixeria
The band value should match one in the [[OsmoNITB:]] configuration.
302
303 7 fixeria
<pre>
304
bts 0
305
  ...
306
  band (900 | 1800)
307
</pre>
308 1 fixeria
309 7 fixeria
h4. A-bis link configuration
310
311 1 fixeria
In the most cases both [[OsmoNITB:]] and [[OsmoBTS:]] are working on the same host. So, the loopback address should be used for 'remote-ip'. The 'unit-id' should be the same as in the [[OsmoNITB:]] configuration.
312
313 7 fixeria
<pre>
314
bts 0
315
  ...
316
  oml remote-ip 127.0.0.1
317
  ipa unit-id 1801 0
318
</pre>
319 6 fixeria
320 7 fixeria
h4. Transceiver configuration
321
322
In order to prevent the input saturation, 'ms-power-loop' should be set to -65.
323
324
<pre>
325
phy 0
326
  ...
327
  osmotrx ms-power-loop -65
328
</pre>
329
330
Since the CalypsoBTS transceiver is obsolete, it still requires BSIC to be set instead of TSC.
331
332
<pre>
333
phy 0
334
  ...
335
  osmotrx legacy-setbsic
336
</pre>
337 6 fixeria
338 3 fixeria
h3. Running
339 6 fixeria
340 3 fixeria
_Tip: feel free to use tmux or screen to avoid a mess with multiple windows_
341 6 fixeria
342 2 fixeria
0. Make sure your transceiver is still runing...
343
344 6 fixeria
1. Start [[OsmoNITB:]]:
345 1 fixeria
346
<pre>
347 6 fixeria
$ osmo-nitb -c ~/.osmocom/openbsc.cfg -l ~/.osmocom/hlr.sqlite3 -P -C --debug=DRLL:DCC:DMM:DRR:DRSL:DNM
348 2 fixeria
</pre>
349
350 6 fixeria
2. Start [[OsmoBTS:]]:
351 3 fixeria
352 2 fixeria
<pre>
353 6 fixeria
$ osmo-bts-trx -c ~/.osmocom/osmo-bts.cfg
354 2 fixeria
</pre>
355
356 6 fixeria
Congratulations! Now you should get the network running. You can use telnet interface to control both [[OsmoNITB:]] and [[OsmoBTS:]]:
357
358 3 fixeria
<pre>
359 6 fixeria
# OsmoNITB telnet interface
360
$ telnet localhost 4242
361 3 fixeria
362 2 fixeria
# OsmoBTS telnet interface
363 6 fixeria
$ telnet localhost 4241
364 3 fixeria
</pre>
365 6 fixeria
366 2 fixeria
You should hopefully see the BTS by performing a manual network search with your phone. Monitor the output of osmocon and the transceiver to see if all goes well. If anything should fail, reboot the phone and start over.
367 6 fixeria
368 2 fixeria
h2. CalypsoBTS with "OpenBTS":http://openbts.org/
369 6 fixeria
370 3 fixeria
"OpenBTS":http://openbts.org/ is another open source software project aimed to replace legacy telecommunication protocols and traditionally complex, proprietary hardware systems by IP a flexible software architecture. It implements the BTS side protocol stack and also some important core network elements.
371 6 fixeria
372 3 fixeria
h3. Installation and configuration
373 6 fixeria
374 1 fixeria
Follow this "howto":https://github.com/RangeNetworks/dev/wiki in the project wiki.
375 6 fixeria
376 3 fixeria
By default, the stock transceiver is used by "OpenBTS":http://openbts.org/. It's designed to work on SDR based hardware (like USRP), but this is not our case. So, we need to replace it by OsmocomBB transceiver.
377 6 fixeria
378 1 fixeria
1. Replace the stock transceiver
379
380 6 fixeria
Make sure that "OpenBTS":http://openbts.org/ in not running. In the folder where the "OpenBTS":http://openbts.org/ executable resides, create a script with the filename 'transceiver' with the following content:
381
382 5 laforge
<pre>
383 1 fixeria
#!/bin/bash
384 6 fixeria
exec <your path to osmocom-bb>/src/host/layer23/src/transceiver/transceiver -a <ARFCN>
385 1 fixeria
</pre>
386 6 fixeria
387 1 fixeria
Where ARFCN is the channel of clock source cell. If you have two (or more phones), add '-2' option.
388
389 6 fixeria
2. And make it executable:
390 1 fixeria
391
<pre>
392 6 fixeria
sudo chmod +x ./transceiver
393 1 fixeria
</pre>
394 6 fixeria
395 1 fixeria
h3. Running
396 6 fixeria
397 10 fixeria
Run the TRX firmware on the phone as described above. No need to start transceiver, "OpenBTS":http://openbts.org/ will run it automatically.
398 1 fixeria
399
The "OpenBTS":http://openbts.org/ CLI allows you to monitor system status and change many operating parameters of "OpenBTS":http://openbts.org/ and the Transceiver in real time.
400 6 fixeria
401
h2. Demo
402
403 1 fixeria
https://www.youtube.com/watch?v=Aj1A6F-FAGU
404 6 fixeria
https://www.youtube.com/watch?v=FifvFov3RsI
405 1 fixeria
https://www.youtube.com/watch?v=PZ4-UCH2ED8
406 6 fixeria
407
h2. References
408 1 fixeria
409
https://www.youtube.com/watch?v=xFjVcxMpA6c
410 6 fixeria
https://events.ccc.de/congress/2012/Fahrplan/attachments/2244_29c3_further_hacks_on_the_calypso_platform
411 1 fixeria
412 6 fixeria
413 1 fixeria
h2. Known limitations and issues
414 6 fixeria
415 1 fixeria
* Two timeslots limitation. Due to some DSP limitations and the non-BTS nature of CalypsoBTS, one phone can serve only one timeslot. Moreover, despite the current transceiver code was extended to support multiple phones ('jolly/testing' branch), this feature is still incomplete. So, for now, up to two phones could be used to serve up to two physical timeslots.
416
417
* Non-continuous C0 transmission. According to the GSM specifications, a C0 base station should keep transmission on all timeslots even if there is nothing to transmit. This makes the mobile stations able to detect them and measure the power levels. Again, a phone isn't BTS. It takes some time to tune between DL and UL frequencies.
Add picture from clipboard (Maximum size: 48.8 MB)