Tech HowTo

Complete AT Command reference for the Multimodem Line is

1. First connect to the modem from the terminal with
> screen /dev/ttyUSB0 115200,ctsrts
2. Run the AT Command for Unstructured Supplementary Service Data +CUSD
> AT+CUSD=1,*556# [enter]
Here I’m using the check balance command MTN Nigeria. You can use this to reload credit as well with the *555*CODE# command.

I spent half a day setting up a demo RapidSMS system using Ubuntu 10.04, a Multitech MTCBA-G-U-F4 modem, and the RapisSMS-XForms application.  I’m new to RapidSMS and revisiting DJango after many years so this will be the first of several posts documenting how I setup RapidSMS to accomplish various needs for mobile data collection in Nigeria.

Visit the Google Doc: RapidSMS on Ubuntu 10.04 with MultiTech MTCBA-G-U-F4 for the most up-to-date version.

RapidSMS on Ubuntu 10.04 with MultiTech MTCBA-G-U-F4

  1. Connect and Configure MultiTech Modem
  2. Install the Python Environment
  3. Installing pyGSM
  4. Installing RapidSMS
  5. Configure RapidSMS and RapidSMS-XForms
  6. Add a RapidSMS Project
  7. Add the MultiModem GSM Backend
  8. Add the XForms App
  9. Starting Up RapidSMS
  10. Getting Stated Collecting Data
  11. References

Connect and Configure MultiTech Modem

Connecting to the MultiModem from Ubuntu is easy using the screen command.
screen /dev/ttyUSB0 115200,ctsrts
From here you can issue AT commands to view the modems status, configuration, as well as read and send messages.
AT+CREG? [enter] will tell you the status of the modem. The response 0,1 is typically what you are looking for.
To use the modem in Nigeria I needed to change the GSM band.
AT+WMBS=5,1 [enter]
After this step I needed to disconnect and reconnect the modem for it to receive and send SMS messages.
Confirming that you can send and received SMS messages or even establish voice calls is a good next step before proceeding to installing and configuring pyGSM and RapidSMS.  See the MultiModem guide referenced below for the SMS Examples (pg 27) and Establishing a Voice Call (pg 26) sections.
To end the MultiModem terminal issue the ctrl+a k and press y to confirm the killing of the session.

Install the Python Environment

sudo apt-get install python-setuptools python-dev build-essential
sudo easy_install pip
sudo pip install –upgrade pip
You will also need git installed (sudo apt-get install git-core) and the sqlite3 packages (sudo apt-get install sqlite3 sqlite3-doc).

Installing pyGSM

sudo pip install pytz (an additional library needed by pygsm)
Retrieve the pygsm sources from the rapidsms repository on github and unpack to the /usr/local area for easy system access.
cd /usr/local
sudo git clone
Compile and Install pygsm
cd /usr/local/pygsm
sudo python install
To check to make sure pygsm is working normally you can run the pygsm_demo program.
pygsm_demo /dev/ttyUSB0 baudrate=115200 rtscts=1

Installing RapidSMS

I installed the RapidSMS from the github repository using
pip install git+git://
To be able to quickly create forms in installed the rapidsms-xforms app
pip install django-uni-form
sudo pip install rapidsms-xforms

Configure RapidSMS and RapidSMS-XForms

TODO: Understand what virtualenv settings are for

Add a RapidSMS Project

> cd ~
> mkdir ~/workspace
> startproject myproject
> cd myproject

Add the MultiModem GSM Backend

Edit (gedit and add the following to the INSTALLED_BACKENDS section
“mtn_ng”: {
“ENGINE”: “rapidsms.backends.gsm”,
“PORT”: “/dev/ttyUSB0”,
“baudrate”: 115200,
“rtscts”: 1

Add the XForms App

In you need to add the following to the INSTALLED_APPS section:
INSTALLED_APPS = ( “rapidsms”,
.. other apps ..
“rapidsms_xforms” )

In the instructions for XForms the is a step to configure the TABS section.  However neither of the two configurations available in the documentation work without errors. TODO: Find a fix for this or find the correct configuration.

TABS = [
(‘rapidsms.views.dashboard’, ‘Dashboard’),
.. other tabs ..
(‘xforms’, ‘XForms’),

TABS = [
(‘rapidsms.views.dashboard’, ‘Dashboard’),
.. other tabs ..
(‘rapidsms_xforms.views.xforms’, ‘XForms’),

Starting Up RapidSMS

To configure and setup the database (default is sqlite3):
python syncdb
Run the the RapidSMS/DJango development server
python runserver (starts a server on the localhost using port 8000, this is only accessible on the local machine)
python runserver ipaddr:port (will run the development server on the specified ip address and port, allowing connection from other machines on the local network).
Startup the Message Router in a different terminal or screen session.
python runrouter

Getting Stated Collecting Data

You should now be able to send and SMS to your Modem’s number and receive a response (most likely “Sorry, RapidSMS could not understand your message”).
These messages will show up in the Message Log (ie To get data into the RapidSMS using the XForms app we need to visit the XForms ADMIN area (ie

  1. Add a New XForm. (ie ‘friends’, with the response ‘Your friend added!’)
  2. Add several XForm fields. (ie ‘name’, ‘age’, ‘phone’)

When these fields are added you can now send an SMS to your modem and have the input received successfully.
SMS: friends +name Adam Thompson +age 27 +phone 123456789
You can check the Message Log and ‘x form submissions’ to see if your data was successfully received and you should also receive your confirmation SMS.


  1. Installing RapidSMS on Ubuntu 9.04 Jaunty
  2. Multi-Tech Wireless Modems Getting Started
  3. MultiModem® GPRS USB Wireless Modem MTCBA-G-U-F4
  4. Installing RapidSMS in Debian Based Linux for development
  5. RapidSMS-XForms github repository README
  6. RapidSMS-XForms Documentation