Update:New version of Mercurio is now available - read post here.
Update: Installation instructions for Mercurio S60 were added.
I promised at MobileCampNYC to give away the code I showed during my Poor Man's SMS Gateway talk. To give the app a name shorter than "Poor Man's SMS Gateway", and to avoid using an acronynm like "PMS Gateway", I've decided to rename it under the codename Mercurio. Below are the files and instructions you'll need to get it going on Mac OS X. Instructions for Linux are very similar and I can write a post for it if people request it.
So what's Mercurio?
Mercurio is a barebones SMS framework that can run locally on any machine as well as on a server to send and receive sms messages. It includes a Rails based application as well as a Python script for Symbian S60 users.
The goal is to give everyone the chance to create a mobile application without the hurdles usually associated with mobile development.
Mercurio Web App:
Sends SMS messages
Receives SMS messages
RSS feed for Received messages
Written in a RESTful manner
Client that sends incoming messages to Mercurio Web without user intervention
Makes any Symbian S60 phone into a little sms receiving gateway
A Mac - it works with Linux as well.
A phone or GSM modem compatible with UltraSMS or a Symbian Series 60 phone
Instructions for Mercurio Web and UltraSMS on Mac OS X:
Download and install MySQL. Make sure you install the Preference Pane that comes with the installation files.
Run Cocoa UltraSMS and click on the Setup button. It will create a new database for you
if you don't have one or you can use your own settings if you have previous experience with
Here are the steps for a new MySQL installation:
- For Hostname type: 127.0.0.1 or localhost
- For Port: 3306
- For Database: ultrasms
- Username: root
- Password: leave it blank
To make sure everything is working ok, click on the Test button. If it gives you an
error, you probably don't have MySQL running. Go to System Preferences and look for the
MySQL Preference Pane. Your MySQL Server Status should be green and running. If it isn't,
well... what are you waiting for? Start it up. Running? Cool. Moving on.
Back to Cocoa UltraSMS.
Once your Test is successful, we need to tell it what phone to use. Turn on Bluetooth on your Mac
and on your phone. Make sure your phone is compatible with UltraSMS by checking the list, if
you don't see it, try it anyway. It may work. If you've never paired your phone with your Mac go to
System Preferences -> Bluetooth and click on the Devices tab on the top. Click on the
"Setup New Device..." button and follow the instructions. Come back when you're done.
Now that you have your phone paired, go to the Phone section of the Cocoa UltraSMS Setup and click
on the Select button to pick your phone. Check the Save Settings box and hit the OK button to close
Are you still alive? Great. Go back to the small UltraSMS window and click on Start this time. To
test it, go to here and type in your number and carrier. If everything is working ok you'll receive a message and the UltraSMS "SMS In:" counter will change to 1.
Now that Cocoa UltraSMS is installed and running, we can get Mercurio running and installed. To do that we
need to install Mercurio and Ruby on Rails. If you're a developer and you don't have Rails, follow these instructions. If when you hear of "Rails" you think of trains, download this application here and you'll be up and running
in no time.
Locomotive - the app you just downloaded - contains a full Ruby on Rails environment for Mercurio to work. Add Mercurio to Locomotive by going to the Menu bar->Applications->Add existing. When it asks you to choose an application, point it to the mercurio folder right under Mercurio Web - here's the file path: Mercurio->Mercurio Web->mercurio. Make the port number 3000 and click the Add button.
Still there? Good. A few more things and we're done.
Via the Finder, go to mercurio->db->database.yml and add the database name and the username. Leave password blank if you just installed MySQL and save the file. What we're doing here is telling Mercurio Web where the SMS will be stored.
What we need to do now is add one more table to the database. Go back to Locomotive's toolbar->Applications->Open in Terminal. Type the following command in the same Terminal window: rake db:migrate and you're done.
To test Mercurio Web, go to Locomotive and start mercurio by clicking on the "Run" green circle. If you see
a shebang warning from Locomotive, don't worry about it, tell it to "Continue without changing." Then
open your browser and go this URL http://localhost:3000/inboxes You should see the message you sent your phone at the beginning of these instructions. You're now ready receive messages.
Testing the command line version of UltraSMS and outgoing messages:
Close Cocoa UltraSMS and make sure MySQL is running. Then go to UltraSMS folder and look for the ultrasms.conf file.
Open it up and add the following settings:
DEVICE = "/dev/tty.LOOK AT BLUETOOTH PREFERENCES" - follow the steps below
DAEMON = "FALSE"
DEBUG = "FALSE"
MYSQL_HOST = "localhost"
MYSQL_DB = "name of the database"
MYSQL_USER = "root"
MYSQL_PASS = "leave it blank if this is a fresh MySQL install"
To get the DEVICE setting for your ultrasms.conf go to System Preferences->Bluetooth->Devices->Edit Serial Ports.
Copy the Port Name that has as a Device Service Serial Port 1 - it could also be 2. In my case, my Port Name is Jose-2 and my Device Service is Serial Port 1. As a result my ultrasms.conf file has this setting:
DEVICE = "/dev/tty.Jose-2".
Save your ultrasms.conf file and open a Terminal window by going to
Finder->Applications->Utilities->Terminal. Go to the directory that has the UltraSMS command
line utility and issue the ./UltraSMS command.
This is what it looks like on my machine:
"Jet:/Applications/Utilities/UltraSMS jose$ ./UltraSMS /dev/tty.Jose-2 localhost:3306 smsgateway root"
"Jet" is the name of my machine. "/Applications/Utilities/UltraSMS" is the path to the directory where
I saved the command line version of UltraSMS. To get there I had to "change directory" by using the
following Unix command in the Terminal:
jose$ cd /Applications/Utilities/UltraSMS
Once you get to the UltraSMS directory you have, issue the command that runs UltraSMS.
"./UltraSMS" is the command that runs UltraSMS and
"/dev/tty.Jose-2 localhost:3306 ultrasms root" is how I tell UltraSMS what device I'm using (from DEVICE in ultrasms.conf), the name of the database and the database user, which is root.
Once you issue the ./UltraSMS command, you'll see a few [Initialising] lines in the Terminal. Something
[Initialising] - Connected to MySQL database
[Initialising] - Initialising phone
[Initialising] - Changing phone memory settings
[Initialising] - Phone initialised
You can now go to http://localhost:3000/outboxes in your browser and click on "Send a new message."
Add a cell phone number and message and let it rip. The message will be sent in a few seconds.
Installation instructions for Mercurio S60:
Mercurio S60 works hand in hand with Mercurio Web. It was built as an altenative for those that don't have a phone that's compatible with UltraSMS. Using Mercurio S60, if you have a Symbian S60 phone, it will forward all incoming SMS directly to Mercurio Web.
You'll need to have Python for S60 interpreter and scriptshell installed. You can download both files for 2nd and 3rd Edition phones here.
Which version of Python should you install?
If you have a 2nd Edition phone: models such as: 6600, 6630, 6670, 7610
If you have a 2nd Edition phone: models such as: N70, N90
For a 3rd Edition phone: model such as: N80, N93, E61, E62, N95
Once you have Python installed, go to the Mercurio S60 folder and open up the mercurio.py file. Change line 78 from conn = httplib.HTTPConnection("peoplelab.gotdns.com", 80) to conn = httplib.HTTPConnection("YOUR MERCURIO WEB URL", 80). Save the file and send it to your phone via Bluetooth or cable - for 3rd Edition phones, you'll need to save the file in your phone's E:/Python folder.
To run it, locate the Python interpreter in your Applications folder of your phone, hit the "Options" softkey and choose "Run Script". Look for mercurio.py and your phone will be ready to receive SMS messages. To test it for the first time, send a message to your own phone and go through the setup screen. Immediately you'll see the phone fowarding messages to Mercurio Web.
That's all folks!
Please let me know if there's something I need to change or any recommendations you may have.