This article will explain from a high level to a lower level how to write a simple SMS-enabled mobile application which will allow you to send “Over The Air installation messages”. After reading this article, you will be able to create a small J2ME applet which will theoretically send itself to another phone using an SMS message as the means of delivery. In fact, due to limitations in the Wireless Messaging API in J2ME (JSR 120/205) the port for WAP Push messages are “reserved” for security reasons. The ability to send content via the widely-supported SMS channel can be very useful for content providers.

What is an SMS ?

SMS messages are small number of packed bytes sent over the operator networks. Many of you have already experienced sending “text messages” from devices and many refer to sending SMS messages as “texting”.

A little technical introduction to SMS

The scope of this article is to be practical, so we will not go through all the technical and boring details of networks, but three concepts are pretty important do understand about sms.

• SMS uses the concept of “port” just as a standard internet sockets do;
• SMS messages have a limit in the body of 160 chars;
• The body is not the only thing you can play with in an SMS, there is also the User Data Header.

Ports

When you hit a URL in your browser such as http://dev.mobi, you transparently call port 80 of a web server, by convention. The connection will be initialized on port 80 and then switched to a higher port to let other users access the same port of the web server. Port 80, as stated by IANA refers to the HTTP protocol, this means that a server, which is able to understand HTTP protocol request, will be awakened and will be ready to answer and process HTTP requests. The same is happens with SMS messages. You can send an SMS to a specific port of a phone and you will wake up a specific service on that device. Now, just as not all the computers have standard services (such as a web server), also not all mobile devices have services listening to ports. This is a very “manufacturer related” stuff, so you will need to check your phone what is enabled to accept.

Body and encoding

This could be a tough topic to treat but we will just describe very basic information which can be useful. SMS default encoding uses 7 bits to handle a character. This means that you can write in a SMS only those characters that are present on a very basic char table, yes those famous 127 chars. If you want to go more complicated stuff and send more “interesting” characters, then a group of 8 bits is needed and the table of available chars gets bigger. The available space is 1120 bits per SMS, no more, no less. You can have 160 chars using 7 bits or 140 chars using 8 bits

Note: The character “É” is included in the “basic table”, while the character “È” is in the “bigger tables”. If you write a message with the second char, then you will have less space available in the message. So, pay attention to which characters you are using when sending SMS 😉

User Data Header

The User Data Header (also known as UDH) is what a “high level developer” can set while to do something more than a simple “text message”. A UDH is very useful because you can send “invisible text messages” to mobile application (where to “mobile applications” I mean those running on mobile devices for example) or you can tell a device that the message will contain special information. It’s very similar to an XML file: you have to tell the parser what you are sending, and the content following the prolog which will be handled by the parser itself.

The UDH is mainly used to specify what ports our client (phone) will send the SMS to. It’s made by a set of hex number which describe:

<how long the UDH is> <the format used to specify ports numbers> <the port number length> <destination port number> <source port number>.

As a practical example, say I want to create a UDH to send a WAP Push, where the standard destination port for WAP pushes is 2948, the UDH will be:

where:

• 06 means “hey the read the following 6 bytes”
• 05 is the format for numbers, in this case hexadecimal numbers
• 04 will tell the UDH that each port is represented using 4 character
• 0B84 is the destination port, 2948 (decimal representation) or 0B84 (hexadecimal representation)
• 23F0 is the source port, 9200 (decimal representation) or 23F0 (hexadecimal representation).

Note: Use a simple calculator to convert decimal numbers to hex; select “Dec”, put 2948 in the calculator, then press the button “Hex”. Any scientific calculator can do this and many operating systems have a little “calc” application somewhere which can do this.

Binary SMS

A “binary SMS” is an XML-formatted textual SMS which has been transformed with WBXML. WBXML is a “tag transformer”, this means that for each XML tag, a binary byte is associated. For example, the tag <SI> is converted as the binary character &#x0005;

Why WBXML?

Easy answer: the result of a WBXML transformation is smaller in the number of generated bytes than the verbose textual XML file itself.

Note: many tags are converted to bytes, but sometimes also contents (such as URL addresses) e.g the URL http://www.dev.mobi can be written in WBXML as 0Ddev.mobi , where “0D” stands for http://www.

“0C” is more generic and stands for http:// so you can write the URL in two ways:

or

The first uses 9 chars (0D is one byte), the second 13 chars! I love WBXML 🙂

Terms

To be clear, by “WAP push” we do not mean a way to send SMS using WAP. What we mean is what is technically known as SI (Service Indication). A Service Indication is a binary SMS sent to a dedicated port on a device which informs the device that there is a URL waiting to be visited. The URL can be the address of a ring-tone in a webserver, the address of a JAD file to install a J2ME application or a JPG or simply a WAP page; it’s up to the “webmaster” of the webserver to put the contents on the web site, and it’s up to the device to understand how to handle the content. For more information on this aspect of the puzzle, please refer to the our Content Adapation series of articles.

Note: When I say “web server” I mean both web and WAP server since most web servers can be configured to deliver WAP content. By “OTA Configuration SMS” I mean a binary SMS which contains APN details (but can contain more) also known as “Internet Access Configuration”.

Note: There are special “Service Indication” messages which are normally called SL (Service Load) which are similar to “SI”. An SI asks the permission to the user before fetching the content over the network connection, SL download contents automatically without asking permission to the user. “SL” are very similar to MMS messages: the content is on a web server and the SMS tells the phone to download the message.

So Let’s Start

First of all, we need to read some papers (alas) to read some specifications on how to write XML content to be sent over SMS. A good start point could be the Nokia’s “Smart Messaging Specification 3.0.0” which can be downloaded from www.forum.nokia.com and also more technical docs from the Open Mobile Alliance (OMA) from www.openmobilealliance.org/tech/affiliates/wap/wapindex.html

So our steps will be:

• Decide what we want to send
• Find the docs about that topic
• Find the XML structure of the message to be sent
• Customize the XML
• Convert the XML to WBXML
• Prepare the UDH
• Send the UDH and the BODY

As we want to send a J2ME application to a new phone, then we need to send a “Service Indication” message, also known as “WAP push”. This “SI” can be used to push an SMS that will be read as a link to download something. Any content-type (image/jpeg, application/java-archive, …) is valid if the phone can open it.

So, who can tell which content-types can a device open ? DeviceAtlas can help us here! (see References)

Find the docs about that topic

Ok, let’s open the OMA link and lets go to the “Functional area” denoted “push”. Let’s get the “WAP Service Indication Specification “. In order to understand how does WBXML works, I would suggest to read paragraph 8.3.2 “Attribute Start Tokens”.

Find the XML structure of the message

For those of you that more like DTDs, look at section 7.2. All others can skip all the doc and go to the read example at section 9. The XML there is pretty self explanatory so I will do some customization directly.

Convert to WBXML

* These are strings used to pass contents to the SI, each character in the string is converted to its hexadecimal representation.
** "6532" is to be considered a string of characters and not a number, so don't use the calculator to convert this number

Our body is, putting all the numbers together:

(which is 130 chars)

Prepare the UDH

Preparing the UDH is pretty easy. Just start with “06 05 04” and then add the port numbers. WAP Push messages uses “destination port” 2948 while source port is 9200. Convert decimal port numbers to hexadecimal formats, so 2948 becomes 0B84 and 9200 becomes 23F0. Magically, the UDH is: 06 05 04 0B 84 23 F0

Send the SMS and the UDH

Now, what you need to do with this? Pretty simple, just put everything together and the SMS is ready to be sent.

<UDH> + <BODY>

The complete message is then:

Which is 137 chars long (hey, it’s a binary SMS, Java uses UTF-8 encoding for binary messages, so the limit for 1 SMS is 140 chars, aren’t we cool ?)

The J2ME application

To be as practical as possible, we will need an environment to be used to send SMS messages and to describe the real world but as not everybody has access to an SMS gateway with UDHs and an interface where to enter binary code, we will be describing how to do the same with a J2ME application.

Disclaimer: As to WMA specifications, J2ME applications can’t access to special reserved ports to send binary SMS so unluckily the J2ME application in the phone will get a security exception and the message will not be delivered.

MIDP2.0 has two methods which enable to send messages: one requires a String, one requires an array of bytes. Yes, the first one is used to set text contents, the second one to set binary contents.

Text method: setPayloadText(String textualSMS);
Binary method: setPayloadData(byte[] binarySMS);

In order to be able to intall the J2ME application "Over The Air", compile it with your favourite J2ME environment (I like NetBeans with the Mobility Pack), copy the .JAD and .JAR files to your webserver and customize the URL in the Wap Push message.

Let’s now write a simple J2ME class that sends the message:

Using an online SMS gateway

As J2ME blocks many binary messages, you can try an online gateway to send your binary messages. Many companies provide SMS gateway services, and most of them have an interface to send raw binary SMS messages (these are a “plus” to me) while some other companies just give you an interface to set the customized fields and make the binary stuff for you.

If you want to use a online SMS gateway, just remember to read their technical specifications. If you want to install yourself a SMS gateway which connects to external services (carriers/operators), I suggest Kannel, which is a free SMS gateway software and it is spread all over the world; Kannel likes to have the UDH and the body to be separated.

References

1. Reserved ports and more: J2ME “Wireless Messaging API” specifications
   http://java.sun.com/products/wma/index.jsp
2. standard format for OTA contents: Open Mobile Alliance
   http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html
3. How to send OTA configs, ring tones and operator logos: NOKIA
   http://www.forum.nokia.com (seach for the “Smart Messaging Specification”)
4. How to detect a mobile phone: WURFL
   http://deviceatlas.com
5. Sms gateway software: Kannel
   www.kannel.org