History

Setting Up Asterisk to Work with OpenBTS

OpenBTS integration with Asterisk is simple in principle: each SIM is configured in Asterisk as a SIP user, using the IMSI as the SIP user name.
So provisioning an OpenBTS subscriber has two steps: # Get the IMSI from the SIM. # Make the corresponding entries in sip.conf and extensions.conf to support the new SIP user.

Getting the IMSIs

There are several ways to get the IMSI for a SIM so that it can be programmed into Asterisk's configuration files. Which one you use will depend on the volume of SIMs you need to provision.

Getting the IMSI with OpenBTS Itself

This is the easiest approach for small numbers of SIMs.
Whenever a handset tries to register with OpenBTS, it will send a mobile identity. You can force the handset to use the IMSI as its identity and then capture the IMSI from the OpenBTS console output when the handset tries to register. Here are the steps:

  1. Be in the correct GSM band.
    1. Be sure the handset is configured to use the same band as you OpenBTS binary, and no other.
  2. Reset the handset's TMSI.
    This procedure is derived from GSM 04.08.
    1. Turn off the handset.
    2. Remove the battery and SIM.
    3. Replace them and turn the phone back on. This will clear any TMSI stored in the phone.
  3. Let the phone try to register.
    What happens next depends on the version.

For releases prior to "Jean Lafitte": Start running the full OpenBTS (OpenBTS + transceiver + Asterisk). Pipe out output of the OpenBTS binary through "| grep Control" and watch for something like this:

FACCHDispatch.cpp:53 [[ControlLayer]] FACCHDispatcher waiting for ESTABLISH [[RadioResource]].cpp:87 [[ControlLayer]] AccessGrantResponder RA=27 when=0:7734
[[RadioResource]].cpp:127 [[ControlLayer]] AccessGrantResponder sending [[PageMode]]=(0)  [[DedicatedModeOrTBF]]=(TMA=0 Downlink=0 DMOrTBF=0) [[ChannelDescription]]=(typeAndOffset=SDCCH/4-3 TN=0 TSC=0 ARFCN=29) [[RequestReference]]=(RA=27 T1'=5 T2=12 T3=33) [[TimingAdvance]]=0
SDCCHDispatch.cpp:101 [[ControlLayer]] SDCCHDispatcher got MM Location Updating Request [[MobileIdentity]]=(IMSI=310410186585294)
[[MobilityManagement]].cpp:111 [[ControlLayer]] LocationUpdatingController MM Location Updating Request [[MobileIdentity]]=(IMSI=310410186585294)
[[MobilityManagement]].cpp:121 [[ControlLayer]] LocationUpdatingController waiting for registration
[[MobilityManagement]].cpp:137 [[ControlLayer]] LocationUpdatingController : SIPRegistration -> FAIL
SDCCHDispatch.cpp:136 [[ControlLayer]] SDCCHDisptacher waiting for RELEASE
SDCCHDispatch.cpp:97 [[ControlLayer]] SDCCHDisptacher waiting for ESTABLISH

For "Jean Lafitte" and later: Start OpenBTS and Asterisk with the OpenBTS logging level set to "INFO" and watch for something like this in the log:
[[RadioResource]].cpp:152: [[AccessGrantResponder]] RA=0x15 when=0:1192710 age=25 TOA=0.0000
[[RadioResource]].cpp:196: [[AccessGrantResponder]] sending [[PageMode]]=(0) [[DedicatedModeOrTBF]]=(TMA=0 Downlink=0 DMOrTBF=0) [[ChannelDescription]]=(typeAndOffset=SDCCH/4-0 TN=0 TSC=0 ARFCN=975) [[RequestReference]]=(RA=21 T1'=3 T2=12 T3=24) [[TimingAdvance]]=0
[[MobilityManagement]].cpp:119: [[LocationUpdatingController]] MM Location Updating Request  LAI=(MCC=901 MNC=55 LAC=0x29b) [[MobileIdentity]]=(TMSI=0x49ffcddd)
[[MobilityManagement]].cpp:172: [[LocationUpdatingController]] registration FAIL: IMSI=234100223456161

In either version, the SIP registration attempt will return "FAIL" because this IMSI is not yet provisioned in Asterisk.

If you're really clever, you'll write some kind of Python script to catch the log output and automatically update the Asterisk configuration files. If you do that, please share your scripts with the rest of us. That would make this technique applicable to very large numbers of SIMs in situations where acceptance rules can be applied based on the upper digits of the IMSI.

Use the GSM "AT" Interface

Many GSM devices support a Hayes-style "AT" command interface, defined in GSM 07.07. This interface supports the "AT+CIMI" command, described in GSM 07.07 Section 5.6, which will return the IMSI of the device's installed SIM.
This is a good approach if you have a device that affords easy SIM changes, like a MultiTech GSM modem and need to provision a few dozen subscribers.

Again, if you're really clever you'll write a script to automate that. And if you're a good person you'll share it with the rest of us.

Order Lots of SIMs

If you need even larger numbers of SIMs provisioned you might consider ordering a batch of them with sequential IMSIs that can be easily programmed into Asterisk with a script.

Programming IMSIs Into Asterisk

To provision an IMSI into Asterisk you will need to modify two files: sip.conf and extensions.conf. These files are normally located in /etc/asterisk.

Creating a SIP User in sip.conf

The minimal entry for the IMSI in sip.conf looks like this:

r310410186585294
canreinvite=no
type=friend
allow=gsm
context=sip-external
host=dynamic

This defines a SIP user called "310410186585294".

For OpenBTS 2.5 and later use this entry. We have SIM with IMSI 310410186585287 that just we assigned telephone number 5287

[IMSI310410186585287]
callerid=5287 ; this is number which called side shall see
canreinvite=no
type=friend
context=sip-external
allow=gsm
host=dynamic
dtmfmode=info

Assigning an Address in extensions.conf

We recommend this macro for dialing OpenBTS users:

[macro-dialGSM]
exten => s,1,Dial(SIP/${ARG1})
exten => s,2,Goto(s-${DIALSTATUS},1)
exten => s-CANCEL,1,Hangup
exten => s-NOANSWER,1,Hangup
exten => s-BUSY,1,Busy(30)
exten => s-CONGESTION,1,Congestion(30)
exten => s-CHANUNAVAIL,1,playback(ss-noservice)
exten => s-CANCEL,1,Hangup

(And if any Asterisk expert has improvements to that, please feel free to submit them.)

With that macro in place, the GSM handset can be assigned an extension just like any other Asterisk terminal device.
For example, this macro assigns extension "2103" to the handset with ISMI "310410186585291":

;; the name in the brackets is the context, it should be the same with the context line in sip.conf
[sip-external]
exten => 2103,1,Macro(dialGSM,310410186585291)

;; following extension for use with OpenBTS 2.5 and later
exten => 5287,1,Macro(dialGSM,IMSI310410186585287) ; with the macro (I haven't tested it)
exten => 5287,1,Dial(SIP/IMSI310410186585287) ; or pure Dial without macro

And this macro allows a specific block of 1,000 AT&T SIMs (310410186585000-310410186585999) to be dialed by the last 4 digits of the IMSI:
exten => _5XXX,1,Macro(dialGSM,310410186585${EXTEN:-3})

Note: For mobile-to-mobile SMS to work, SMQueue requires SIP/ to immediately precede your IMSI in the extensions.conf file. This is because the current implementation of the OpenBTS HLR relies on a "hack" to get the extension-to-IMSI mapping. It asks the Asterisk server for the dialplan line containing the SM sender's extension and scans the line for the substring SIP/. It then interprets the remaining text before the closing parenthesis ) as the IMSI. If you use the dialGSM macro above, you need to edit several lines as follows. Remove SIP/ from the macro and move it in front of every instance of an extension-to-IMSI line:
[macro-dialGSM]
exten => s,1,Dial(${ARG1})

...

[sip-external]
exten => 2103,1,Macro(dialGSM,SIP/310410186585291)

Also, please note that the extension block code above may break SMQueue due to the presence of ${EXTEN:-3} where the HLR expects a valid IMSI. (I will confirm this and update accordingly. It's possible that Asterisk will expand the shell variable before displaying the dialplan line.)