cwinfo/envayasms
5
0
Fork 0
mirror of https://github.com/cwinfo/envayasms.git synced 2025-04-10 10:26:21 +00:00
Code Releases Activity

updated kalsms website using phrozn static site generator

Browse Source
This commit is contained in:
Jesse Young 2011-09-18 20:45:09 -07:00
parent e6e50a7a40
commit 771244b8e1
27 changed files with 1385 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.phrozn/archive/README Executable file
View File

@ -0,0 +1,3 @@
Phrozn treats "archive" and "entries" folders the same way.
The purpose of separate folder is to have less items in entries, thus keeping
it manageable even for sites having many entries.

6
.phrozn/config.yml Executable file
View File

@ -0,0 +1,6 @@
--- # Site configuration
entries:
layout: default.twig
# Files to skip - list of preg expressions is expected
skip: [/\.swp$/, /\.bak$/, /.DS_Store/]

64
.phrozn/entries/comparison.twig Executable file
View File

@ -0,0 +1,64 @@
<h2>Comparison to Alternative Methods</h2>
<p>
SMS gateways can be created using several alternative methods, including hosted services (e.g. Twilio, Tropo, Clickatell),
connecting GSM phones/modems to a computer (e.g. FrontlineSMS, RapidSMS, Kannel),
and partnering directly with mobile operators.
</p>
<table class='comparison_table'>
<thead>
<tr>
<td>&nbsp;</td>
<th>Benefits</th>
<th>Drawbacks</th>
</tr>
</thead>
<tbody>
<tr>
<th>Hosted services</th>
<td>
<ul><li>High message throughput
<li>Easy to deploy</ul>
</td>
<td>
<ul><li>No local numbers in many countries
<li>Usually no MMS support</ul>
</td>
</tr>
<tr>
<th>Connecting modem<br /> to computer</th>
<td>
<ul><li>Can work with inexpensive phone</li></ul>
</td>
<td>
<ul><li>Expensive hardware costs
<li>Lots of moving parts to keep working
<li>Very difficult for non-technical users to deploy
<li>Low message throughput
<li>No MMS support</ul>
</td>
</tr>
<tr>
<th>Partnering with<br /> Mobile Operators</th>
<td>
<ul>
<li>High message throughput
<li>Can provide free service to users via shortcode</ul>
</td>
<td>
<ul><li>Usually very expensive
<li>Requires operator approval
<li>Long setup time</li></ul>
</td>
</tr>
</tbody>
</table>
<p>
KalSMS is ideal for situations where no hosted services with local numbers are available in
a particular country, or when it is necessary to receive MMS messages.
</p>
<p>
KalSMS likely has lower throughput than hosted services or partnering with mobile operators, but should
be able to forward up to a few thousand messages per phone per day.
</p>

3
.phrozn/entries/how.twig Executable file
View File

@ -0,0 +1,3 @@
<h2>How it Works</h2>
<p>TODO</p>

64
.phrozn/entries/index.twig Executable file
View File

@ -0,0 +1,64 @@
layout: default.twig
---
<p>
<div style='float:right;padding-left:10px;padding-bottom:10px'>
<img src='media/screenshot-main.png' width='213' height='350' />
<br />
<img src='media/screenshot-settings.png' width='211' height='350' />
</div>
KalSMS is a SMS/MMS gateway running entirely as an Android app.
<p>
It enables web services to send and receive SMS and MMS messages
by forwarding incoming messages to a server on the Internet, and sending
outgoing messages to other phones.
</p>
<p>
People with any type of mobile phone can send SMS and MMS to a phone
running KalSMS, without needing their own Android phone.
</p>
<p>
It works wherever the phone can receive SMS messages and access the Internet
(via Wi-Fi or mobile data connection).
</p>
<h2>Why KalSMS?</h2>
<p>
KalSMS can be used nearly anywhere in the world. In particular, it is useful
in countries where obtaining a local virtual phone number
or SMS shortcode is difficult, expensive, or impossible. A phone running KalSMS
connects to the phone network in the same way as any other mobile phone,
so it can be set up without needing approval from anyone else.
</p>
<p>
KalSMS is designed to to be maintainable even when deployed in remote locations
that cannot easily be accessed by your organization's technical staff. KalSMS is simple
enough for non-technical users to do all setup and maintenance of deployed phones.
</p>
<h2>Price</h2>
<p>
KalSMS is free to install on as many phones as you'd like.
</p>
<p>
In order to deploy KalSMS, you will need a messaging plan for your phone, and the phone itself.
KalSMS is compatible with many old or inexpensive Android phones, e.g. the LG GT540, currently $120 on Amazon.com.
</p>
<p>
Typically your organization will need only one phone running KalSMS in a
particular country. However, it is possible to use multiple phones to load-balance requests
for higher throughput, to offer different user services, or to serve different mobile networks.
</p>
<a href='install.html' class='button'>
Install KalSMS Now
</a>

110
.phrozn/entries/install.twig Executable file
View File

@ -0,0 +1,110 @@
layout: default.twig
---
<h2>Installing KalSMS</h2>
Before installing KalSMS, ensure that you have the following prerequisites:
<ul>
<li>One or more Android phones (1.6 Donut or higher) that are
registered on a mobile network. </li>
<li>A way for the phones to connect to the internet, either via Wi-Fi
or the mobile data service. <br />
(Even if using Wi-Fi, mobile data
service is necessary to receive MMS messages.) </li>
<li> A web server accessible from the public internet </li>
</ul>
To install the current release version of KalSMS on an Android phone,
either scan the barcode below with a QR code app,
or click the link from your phone's browser. <br />
<div style='text-align:center'>
<img src='media/qr.png' width='175' height='175' style='vertical-align:middle' />
&nbsp; &nbsp; <em>or</em> &nbsp; &nbsp;
<span style='font-size:20px;font-weight:bold'>
<a href="http://envaya.org/_media/KalSMS-release.apk">Install KalSMS</a>
</span>
</div>
<p>
Alternatively, software developers may <a href="https://github.com/youngj/KalSMS">download the source code from GitHub</a>
and build KalSMS themselves.
</p>
<h2>Configuring KalSMS</h2>
<h3>Server Configuration</h3>
<p>
It is assumed that you or your organization already has a HTTP server that you want to connect to KalSMS.
</p>
<p>
Follow the instructions in the <a href='serverapi.html'>API Reference</a> page to learn how to construct a
resource on your HTTP server that can communicate with KalSMS.
</p>
<h3>Phone Configuration</h3>
<p>
After your server is configured, configure KalSMS on your phone to connect to your server as follows:
</p>
<ol>
<li>Open the KalSMS app</li>
<li>Click the Menu button, then "Settings"</li>
<li>Configure KalSMS to work with your server by entering:</li>
<ul>
<li>your server URL (including <code>http://</code> or <code>https://</code>)</li>
<li>your phone number</li>
<li>the password shared with the server</li>
</ul>
<li>Choose an interval to poll for new outgoing messages</li>
<li>Check "Enable KalSMS?"</li>
<li>Click the Back button to return to the main screen</li>
</ol>
<p>
To test if KalSMS has been configured properly and can connect
to your server, open the KalSMS app, click the Menu button,
then click "Test Connection".
</p>
<p>Finally, prevent Wi-Fi from turning off when the phone sleeps, by
going to Settings > Wireless & Networks > Wi-Fi settings >
Menu key > Advanced > Wi-Fi sleep policy and select "Never".
(Otherwise, you will get connection timeout errors when forwarding
messages after the phone goes to sleep.)
</p>
<p>
<strong>Important:</strong> After KalSMS is enabled, it will forward all SMS messages regardless of whether the
KalSMS app is open. If you want to use SMS normally again, return to KalSMS' settings screen
and uncheck "Enable KalSMS?".
</p>
<h3>Installing Expansion Packs</h3>
<p>
By default, Android prevents KalSMS from sending more than 100 outgoing SMS messages per hour.
However, that limit can be increased by installing KalSMS Expansion Packs.
</p>
<p>
Each Expansion Pack allows KalSMS to increase its sending limit by an additional 100 outgoing SMS messages
per hour. For example, if you install 14 expansion packs, KalSMS will be able to send up to 1500 outgoing SMS messages
per hour.
</p>
<p>
(TODO: Link to Expansion Pack installers)
</p>
<p>
With Expansion Packs, KalSMS is limited only by how fast your phone can send and receive SMS,
and by your mobile provider's usage limits and terms of service.
</p>
<p>
</p>

265
.phrozn/entries/serverapi.twig Executable file
View File

@ -0,0 +1,265 @@
layout: default.twig
---
<h2>Server API Reference</h2>
<p>
KalSMS communicates with the server via HTTP POST requests that expect an XML response.
</p>
<p>
For convenience, KalSMS includes <a href='https://github.com/youngj/KalSMS/tree/master/server'>server libraries and example code</a>
for certain languages to simplify handling its POST requests and generating response XML.
</p>
<p>
If a server library is not yet available for your programming language, you can still use
KalSMS by implementing code in accordance with the API reference below.
We encourage you to contribute new libraries and example code back to the KalSMS project!
</p>
<h3>
HTTP Request Format
</h3>
<p>
The following parameters are sent by all POST requests from KalSMS:
</p>
<dl>
<dt>"version" ::= &lt;integer&gt;</dt>
<dd>
The API version of the POST requests (currently <code>"2"</code>).
<br />
<br />
This number will be incremented whenever the format of POST requests changes significantly.
This allows the server to support phones running different API versions at the same time.
If a deployment has many phones running with KalSMS, the server should update its code first,
then the phones can be upgraded to the new version of KalSMS as convenient.
</dd>
<dt>"phone_number" ::= &lt;text&gt;</dt>
<dd>
The phone number of the phone running KalSMS, as entered under Menu &gt; Settings.
<br /><br />
This allows the server to differentiate between KalSMS clients if multiple phones
are running KalSMS.
</dd>
<dt>"action" ::= "outgoing" | "incoming" | "send_status"</dt>
<dd>
The request action determines the purpose of the HTTP request:
<dl>
<dt>"outgoing":</dt>
<dd>
Poll the server for outgoing messages
</dd>
<dt>"incoming":</dt>
<dd>
Forward an incoming SMS or MMS message to the server
</dd>
<dt>"send_status":</dt>
<dd>
Update the server on the status of sending an outgoing message
</dd>
</dl>
The other POST parameters sent depend on the request action.
</dd>
</dl>
The following HTTP Headers are sent in all POST requests from KalSMS:
<dl>
<dt>"X-Kalsms-Signature" ::= &lt;text&gt;</dt>
<dd>
A signature of the request to verify the phone and the server share the same password
(though it doesn't protect against MITM snooping or replay attacks).
<br />
<br />
The signature is calculated by the following algorithm:
<ol>
<li>Sort all POST parameters (not including file uploads)
in alphabetical order by the name of the field.</li>
<li>Generate an input string by concatenating:
<ul>
<li>the server URL,</li>
<li>each of the sorted POST parameters with their corresponding values, and</li>
<li>the password,</li>
</ul>
with a comma in between each element, like so:
<br /><br />
<code>"&lt;serverURL&gt;,&lt;name1&gt;,&lt;value1&gt;,&lt;...&gt;,&lt;nameN&gt;,&lt;valueN&gt;,&lt;password&gt;"</code>
</li>
<li>Generate the SHA-1 hash of the input string in UTF-8</li>
<li>Encode the SHA-1 hash using Base64 with no line breaks.</li>
</ol>
</dd>
</dl>
Additional parameters sent in POST requests with action=incoming:
<dl>
<dt>"from" ::= &lt;text&gt;</dt>
<dd>
The phone number of the message sender.
</dd>
<dt>"message_type" ::= "sms" | "mms"</dt>
<dd>
Whether this message is an SMS or MMS.
</dd>
<dt>"message" ::= &lt;text&gt;</dt>
<dd>
The message body of the SMS, or the content of the <code>text/plain</code> part of the MMS.
</dd>
</dl>
Additional parameters sent in POST requests with action=incoming and message_type=mms:
<dl>
<dt>"mms_parts" ::= &lt;json_array&gt;</dt>
<dd>
Metadata for each part of the MMS. Each item in the JSON array is an object
with the following keys and values:
<dl>
<dt>"name" ::= &lt;text&gt;</dt>
<dd>
The name of an additional form field where the content of the MMS part
is sent as an attached file.
</dd>
<dt>"cid" ::= &lt;text&gt;</dt>
<dd>
The Content ID of the MMS part. This allows the server to resolve
references in the SMIL part of the MMS
(e.g. <code>&lt;img region="Image" src="cid:805"/&gt;</code>).
</dt>
<dt>"type" ::= "application/smil" | "text/plain" | "image/jpeg" | ...</dt>
<dd>
The Content Type of the MMS part.
</dd>
<dt>"filename" ::= &lt;text&gt;</dt>
<dd>
The filename of the MMS part, as sent by the sender phone,
e.g. <code>"Image001.jpg"</code>.
</dt>
</dl>
(Additional fields with the content of each MMS part. Text parts
are encoded in UTF-8.)
</dt>
</dl>
Additional parameters sent in POST requests with action=outgoing:
<dl>
<dt>
(None)
</dt>
</dl>
Additional parameters sent in POST requests with action=send_status:
<dl>
<dt>"id" ::= &lt;text&gt;</dt>
<dd>
The Server's ID for the outgoing message (from the <code>id</code> attribute
of an <a href='#sms'>sms</a> tag in a previous XML response from the server).
</dd>
<dt>"status" ::= "queued" | "failed" | "sent"</dt>
<dd>
The current status of the outgoing message.
</dd>
<dt>"error" ::= &lt;text&gt;</dt>
<dd>
A description of the reason for the error, if the message
failed to send; or, an empty string if the message
has been sent successfully.
</dd>
</dl>
<h3>
HTTP Response Format
</h4>
<p>
For a successul request, the server should return HTTP status code 200.
If the signature check failed, the server should return status code 403.
Other status codes may be used to signify errors.
</p>
HTTP response format for action=incoming and action=outgoing:
<blockquote>
The Content-Type header should be text/xml, with the content as follows:
<dl>
<dt>&lt;messages&gt;</dt>
<dd>
The root XML element.
<br />
<br />
Attributes:
<dl><dt>none</dt></dl>
Content:
<dl>
<dt>&lt;sms&gt;*</dt>
<dd>The SMS messages to send.</dd>
</dl>
</dd>
<dt id='sms'>&lt;sms&gt;</dt>
<dd>
Describes an outgoing SMS to send.
<br /><br />
Attributes:
<dl>
<dt>"id" ::= &lt;text&gt; (optional)</dt>
<dd>
An ID for this outgoing message. (KalSMS will send this
back to the server as the id field in a send_status request.)
</dd>
<dt>"to" ::= &lt;text&gt; (optional for incoming, required for outgoing)</dt>
<dd>
The phone number to send the SMS to. If omitted for
action=incoming, it will be sent as a reply to the original
sender.
</dd>
</dl>
Content:
<dl>
<dt>CDATA</dt>
<dd>
The content of the SMS message to send.
</dd>
</dd>
</dl>
Example:
<pre>
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;messages&gt;
&lt;sms id='42' to='5551212'&gt;Message One&lt;/sms&gt;
&lt;sms&gt;Message Two&lt;/sms&gt;
&lt;/message&gt;
</pre>
</blockquote>
Response format for action=send_status:
<blockquote>
The response content is currently undefined and ignored.
</blockquote>

42
.phrozn/layouts/default.twig Executable file
View File

@ -0,0 +1,42 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
</head>
<body>
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="index.html">KalSMS</a>
<span class="small">
SMS/MMS gateway for Android
</span>
</h1>
<div class='menu'>
<a href='index.html'>Home</a>
&middot;
<a href='install.html'>Install</a>
&middot;
<a href='how.html'>How it Works</a>
&middot;
<a href='serverapi.html'>API Reference</a>
&middot;
<a href='comparison.html'>Comparison</a>
</div>
{{ content }}
<div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div>
</div>
</body>
</html>

BIN
.phrozn/media/qr.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 512 B

0
screenshot-main.png → .phrozn/media/screenshot-main.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 33 KiB

0
screenshot-settings.png → .phrozn/media/screenshot-settings.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

1
.phrozn/plugins/README Executable file
View File

@ -0,0 +1 @@
Phrozn plugins

0
.phrozn/scripts/default.js Executable file
View File

71
.phrozn/styles/site.css Executable file
View File

@ -0,0 +1,71 @@
body {
margin-top: 1.0em;
background-color: #fff;
font-family: Helvetica, Arial, FreeSans, san-serif;
color: #333;
}
dt
{
font-family:monospace;
}
dd
{
padding-bottom:10px;
}
.menu
{
font-weight:bold;
}
.menu a
{
text-decoration:none;
}
.comparison_table
{
font-size:12px;
}
.comparison_table tbody th
{
white-space:nowrap;
text-align:right;
}
.comparison_table tbody td
{
border:1px solid #ccc;
}
.comparison_table ul
{
}
#container {
margin: 0 auto;
width: 700px;
}
h1 { margin-top:0; font-size: 3.8em; color: #678bf0; margin-bottom: 3px; }
h1 .small { font-size: 0.4em; color:#666; }
h1 a { text-decoration: none }
h2 { font-size: 1.5em; color: #678bf0; }
h3 { color: #678bf0; }
a { color: #678bf0; }
.description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
.download { float: right; }
pre { background: #000; color: #fff; padding: 15px;}
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.footer { text-align:center; padding-top:30px; font-style: italic; }
.button
{
text-decoration:none;
display:block;margin:0 auto;width:200px;background:#68f;color:white;padding:8px;font-weight:bold;text-align:center;
}
a.button:hover
{
text-decoration:underline;
}

105
comparison.html Executable file
View File

@ -0,0 +1,105 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
</head>
<body>
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="index.html">KalSMS</a>
<span class="small">
SMS/MMS gateway for Android
</span>
</h1>
<div class='menu'>
<a href='index.html'>Home</a>
&middot;
<a href='install.html'>Install</a>
&middot;
<a href='how.html'>How it Works</a>
&middot;
<a href='serverapi.html'>API Reference</a>
&middot;
<a href='comparison.html'>Comparison</a>
</div>
<h2>Comparison to Alternative Methods</h2>
<p>
SMS gateways can be created using several alternative methods, including hosted services (e.g. Twilio, Tropo, Clickatell),
connecting GSM phones/modems to a computer (e.g. FrontlineSMS, RapidSMS, Kannel),
and partnering directly with mobile operators.
</p>
<table class='comparison_table'>
<thead>
<tr>
<td>&nbsp;</td>
<th>Benefits</th>
<th>Drawbacks</th>
</tr>
</thead>
<tbody>
<tr>
<th>Hosted services</th>
<td>
<ul><li>High message throughput
<li>Easy to deploy</ul>
</td>
<td>
<ul><li>No local numbers in many countries
<li>Usually no MMS support</ul>
</td>
</tr>
<tr>
<th>Connecting modem<br /> to computer</th>
<td>
<ul><li>Can work with inexpensive phone</li></ul>
</td>
<td>
<ul><li>Expensive hardware costs
<li>Lots of moving parts to keep working
<li>Very difficult for non-technical users to deploy
<li>Low message throughput
<li>No MMS support</ul>
</td>
</tr>
<tr>
<th>Partnering with<br /> Mobile Operators</th>
<td>
<ul>
<li>High message throughput
<li>Can provide free service to users via shortcode</ul>
</td>
<td>
<ul><li>Usually very expensive
<li>Requires operator approval
<li>Long setup time</li></ul>
</td>
</tr>
</tbody>
</table>
<p>
KalSMS is ideal for situations where no hosted services with local numbers are available in
a particular country, or when it is necessary to receive MMS messages.
</p>
<p>
KalSMS likely has lower throughput than hosted services or partnering with mobile operators, but should
be able to forward up to a few thousand messages per phone per day.
</p>
<div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div>
</div>
</body>
</html>

42
download.html Executable file
View File

@ -0,0 +1,42 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
</head>
<body>
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="http://github.com/youngj/KalSMS">KalSMS</a>
<span class="small">
SMS/MMS gateway for Android
</span>
</h1>
<div class='menu'>
<a href='index.html'>Home</a>
&middot;
<a href='download.html'>Download</a>
</div>
<h2>Download</h2>
<ul>
<li><a href="http://envaya.org/_media/KalSMS-release.apk">Current release (apk)</a></li>
<li><a href="http://github.com/youngj/KalSMS/zipball/master">Latest development source (zip)</a></li>
<li><a href="http://github.com/youngj/KalSMS/tarball/master">Latest development source (tar)</a></li>
</ul>
<div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div>
</div>
</body>
</html>

44
how.html Executable file
View File

@ -0,0 +1,44 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
</head>
<body>
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="index.html">KalSMS</a>
<span class="small">
SMS/MMS gateway for Android
</span>
</h1>
<div class='menu'>
<a href='index.html'>Home</a>
&middot;
<a href='install.html'>Install</a>
&middot;
<a href='how.html'>How it Works</a>
&middot;
<a href='serverapi.html'>API Reference</a>
&middot;
<a href='comparison.html'>Comparison</a>
</div>
<h2>How it Works</h2>
<p>TODO</p>
<div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div>
</div>
</body>
</html>

184
index.html Normal file → Executable file
View File

@ -2,50 +2,8 @@
<html> <html>
<head> <head>
<meta charset='utf-8'> <meta charset='utf-8'>
<title>KalSMS</title> <title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
<style type="text/css">
body {
margin-top: 1.0em;
background-color: #fff;
font-family: Helvetica, Arial, FreeSans, san-serif;
color: #333;
}
.comparison_table
{
font-size:12px;
}
.comparison_table tbody th
{
text-align:right;
}
.comparison_table tbody td
{
border:1px solid #ccc;
}
.comparison_table ul
{
}
#container {
margin: 0 auto;
width: 700px;
}
h1 { font-size: 3.8em; color: #678bf0; margin-bottom: 3px; }
h1 .small { font-size: 0.4em; color:#666; }
h1 a { text-decoration: none }
h2 { font-size: 1.5em; color: #678bf0; }
h3 { text-align: center; color: #678bf0; }
a { color: #678bf0; }
.description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
.download { float: right; }
pre { background: #000; color: #fff; padding: 15px;}
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.footer { text-align:center; padding-top:30px; font-style: italic; }
</style>
</head> </head>
<body> <body>
@ -53,33 +11,44 @@
<div id="container"> <div id="container">
<h1><a href="index.html">KalSMS</a>
<h1><a href="http://github.com/youngj/KalSMS">KalSMS</a>
<span class="small"> <span class="small">
SMS/MMS gateway for Android SMS/MMS gateway for Android
</span> </span>
</h1> </h1>
<h2>About</h2> <div class='menu'>
<a href='index.html'>Home</a>
<p> &middot;
<div style='float:right;padding-left:10px;padding-bottom:10px'> <a href='install.html'>Install</a>
<img src='screenshot-main.png' width='213' height='350' /> &middot;
<br /> <a href='how.html'>How it Works</a>
<img src='screenshot-settings.png' width='211' height='350' /> &middot;
<a href='serverapi.html'>API Reference</a>
&middot;
<a href='comparison.html'>Comparison</a>
</div> </div>
KalSMS is a SMS/MMS gateway running entirely as an Android app.
<p>
<div style='float:right;padding-left:10px;padding-bottom:10px'>
<img src='media/screenshot-main.png' width='213' height='350' />
<br />
<img src='media/screenshot-settings.png' width='211' height='350' />
<p> </div>
It enables web services to send and receive SMS/MMS messages
by forwarding incoming messages to a server on the Internet, and sending KalSMS is a SMS/MMS gateway running entirely as an Android app.
outgoing messages to other phones.
</p>
<p> <p>
People with any type of mobile phone can send SMS/MMS to a phone It enables web services to send and receive SMS and MMS messages
by forwarding incoming messages to a server on the Internet, and sending
outgoing messages to other phones.
</p>
<p>
People with any type of mobile phone can send SMS and MMS to a phone
running KalSMS, without needing their own Android phone. running KalSMS, without needing their own Android phone.
</p> </p>
@ -107,103 +76,28 @@ It works wherever the phone can receive SMS messages and access the Internet
<h2>Price</h2> <h2>Price</h2>
<p> <p>
The KalSMS app itself is free to install on as many phones as you'd like. KalSMS is free to install on as many phones as you'd like.
</p> </p>
<p> <p>
In order to deploy KalSMS, the only monetary costs are the cost of a messaging In order to deploy KalSMS, you will need a messaging plan for your phone, and the phone itself.
plan for your phone, and the price of the phone itself. KalSMS is compatible with KalSMS is compatible with many old or inexpensive Android phones, e.g. the LG GT540, currently $120 on Amazon.com.
many old or inexpensive Android phones, e.g. the LG GT540, currently $120 on Amazon.com. </p>
</p>
<p> <p>
Typically your organization will need only one phone running KalSMS in a Typically your organization will need only one phone running KalSMS in a
particular country, although you could have multiple phones to load-balance requests particular country. However, it is possible to use multiple phones to load-balance requests
for higher throughput, to offer different user services, or to serve different mobile networks. for higher throughput, to offer different user services, or to serve different mobile networks.
</p> </p>
<h2>Comparison to Alternative Methods</h2>
<p>
SMS gateways can be created using several alternative methods, including hosted services (e.g. Twilio, Tropo, Clickatell),
connecting GSM phones/modems to a computer (e.g. FrontlineSMS, RapidSMS, Kannel),
and partnering directly with mobile operators.
</p>
<table class='comparison_table'>
<thead>
<tr>
<td>&nbsp;</td>
<th>Benefits</th>
<th>Drawbacks</th>
</tr>
</thead>
<tbody>
<tr>
<th>Hosted services</th>
<td>
<ul><li>High message throughput
<li>Easy to deploy</ul>
</td>
<td>
<ul><li>No local numbers in many countries
<li>Usually no MMS support</ul>
</td>
</tr>
<tr>
<th>Connecting modem<br /> to computer</th>
<td>
<ul><li>Can work with inexpensive phone</li></ul>
</td>
<td>
<ul><li>Expensive hardware costs
<li>Lots of moving parts to keep working
<li>Very difficult for non-technical users to deploy
<li>Low message throughput
<li>No MMS support</ul>
</td>
</tr>
<tr>
<th>Partnering with<br /> Mobile Operators</th>
<td>
<ul>
<li>High message throughput
<li>Can provide free service to users via shortcode</ul>
</td>
<td>
<ul><li>Usually very expensive
<li>Requires operator approval
<li>Long setup time</li></ul>
</td>
</tr>
</tbody>
</table>
<p>
KalSMS is ideal for situations where no hosted services with local numbers are available in
a particular country, or when it is necessary to receive MMS messages. KalSMS likelly has
lower throughput than hosted services or partnering with mobile operators, but should
be able to forward up to a few thousand messages per phone per day.
</p>
<h2>Contributors</h2>
<p>
Jesse Young (youngj@envaya.org) - Current Maintainer<br />
Nir Yariv (niryariv@gmail.com) - Initial Developer
</p>
<h2>Download</h2>
<ul>
<li><a href="http://envaya.org/_media/KalSMS-release.apk">Current release (apk)</a></li>
<li><a href="http://github.com/youngj/KalSMS/zipball/master">Latest development source (zip)</a></li>
<li><a href="http://github.com/youngj/KalSMS/tarball/master">Latest development source (tar)</a></li>
</ul>
<a href='install.html' class='button'>
Install KalSMS Now
</a>
<div class="footer"> <div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a> get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div> </div>
</div> </div>
</body> </body>
</html> </html>

149
install.html Executable file
View File

@ -0,0 +1,149 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
</head>
<body>
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="index.html">KalSMS</a>
<span class="small">
SMS/MMS gateway for Android
</span>
</h1>
<div class='menu'>
<a href='index.html'>Home</a>
&middot;
<a href='install.html'>Install</a>
&middot;
<a href='how.html'>How it Works</a>
&middot;
<a href='serverapi.html'>API Reference</a>
&middot;
<a href='comparison.html'>Comparison</a>
</div>
<h2>Installing KalSMS</h2>
Before installing KalSMS, ensure that you have the following prerequisites:
<ul>
<li>One or more Android phones (1.6 Donut or higher) that are
registered on a mobile network. </li>
<li>A way for the phones to connect to the internet, either via Wi-Fi
or the mobile data service. <br />
(Even if using Wi-Fi, mobile data
service is necessary to receive MMS messages.) </li>
<li> A web server accessible from the public internet </li>
</ul>
To install the current release version of KalSMS on an Android phone,
either scan the barcode below with a QR code app,
or click the link from your phone's browser. <br />
<div style='text-align:center'>
<img src='media/qr.png' width='175' height='175' style='vertical-align:middle' />
&nbsp; &nbsp; <em>or</em> &nbsp; &nbsp;
<span style='font-size:20px;font-weight:bold'>
<a href="http://envaya.org/_media/KalSMS-release.apk">Install KalSMS</a>
</span>
</div>
<p>
Alternatively, software developers may <a href="https://github.com/youngj/KalSMS">download the source code from GitHub</a>
and build KalSMS themselves.
</p>
<h2>Configuring KalSMS</h2>
<h3>Server Configuration</h3>
<p>
It is assumed that you or your organization already has a HTTP server that you want to connect to KalSMS.
</p>
<p>
Follow the instructions in the <a href='serverapi.html'>API Reference</a> page to learn how to construct a
resource on your HTTP server that can communicate with KalSMS.
</p>
<h3>Phone Configuration</h3>
<p>
After your server is configured, configure KalSMS on your phone to connect to your server as follows:
</p>
<ol>
<li>Open the KalSMS app</li>
<li>Click the Menu button, then "Settings"</li>
<li>Configure KalSMS to work with your server by entering:</li>
<ul>
<li>your server URL (including <code>http://</code> or <code>https://</code>)</li>
<li>your phone number</li>
<li>the password shared with the server</li>
</ul>
<li>Choose an interval to poll for new outgoing messages</li>
<li>Check "Enable KalSMS?"</li>
<li>Click the Back button to return to the main screen</li>
</ol>
<p>
To test if KalSMS has been configured properly and can connect
to your server, open the KalSMS app, click the Menu button,
then click "Test Connection".
</p>
<p>Finally, prevent Wi-Fi from turning off when the phone sleeps, by
going to Settings > Wireless & Networks > Wi-Fi settings >
Menu key > Advanced > Wi-Fi sleep policy and select "Never".
(Otherwise, you will get connection timeout errors when forwarding
messages after the phone goes to sleep.)
</p>
<p>
<strong>Important:</strong> After KalSMS is enabled, it will forward all SMS messages regardless of whether the
KalSMS app is open. If you want to use SMS normally again, return to KalSMS' settings screen
and uncheck "Enable KalSMS?".
</p>
<h3>Installing Expansion Packs</h3>
<p>
By default, Android prevents KalSMS from sending more than 100 outgoing SMS messages per hour.
However, that limit can be increased by installing KalSMS Expansion Packs.
</p>
<p>
Each Expansion Pack allows KalSMS to increase its sending limit by an additional 100 outgoing SMS messages
per hour. For example, if you install 14 expansion packs, KalSMS will be able to send up to 1500 outgoing SMS messages
per hour.
</p>
<p>
(TODO: Link to Expansion Pack installers)
</p>
<p>
With Expansion Packs, KalSMS is limited only by how fast your phone can send and receive SMS,
and by your mobile provider's usage limits and terms of service.
</p>
<p>
</p>
<div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div>
</div>
</body>
</html>

1
media/img/README Executable file
View File

@ -0,0 +1 @@
image data

BIN
media/qr.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 512 B

BIN
media/screenshot-main.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
media/screenshot-settings.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

0
scripts/default.js Executable file
View File

305
serverapi.html Executable file
View File

@ -0,0 +1,305 @@
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title>KalSMS</title>
<link rel='stylesheet' type='text/css' href='styles/site.css' />
</head>
<body>
<a href="http://github.com/youngj/KalSMS"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="index.html">KalSMS</a>
<span class="small">
SMS/MMS gateway for Android
</span>
</h1>
<div class='menu'>
<a href='index.html'>Home</a>
&middot;
<a href='install.html'>Install</a>
&middot;
<a href='how.html'>How it Works</a>
&middot;
<a href='serverapi.html'>API Reference</a>
&middot;
<a href='comparison.html'>Comparison</a>
</div>
<h2>Server API Reference</h2>
<p>
KalSMS communicates with the server via HTTP POST requests that expect an XML response.
</p>
<p>
For convenience, KalSMS includes <a href='https://github.com/youngj/KalSMS/tree/master/server'>server libraries and example code</a>
for certain languages to simplify handling its POST requests and generating response XML.
</p>
<p>
If a server library is not yet available for your programming language, you can still use
KalSMS by implementing code in accordance with the API reference below.
We encourage you to contribute new libraries and example code back to the KalSMS project!
</p>
<h3>
HTTP Request Format
</h3>
<p>
The following parameters are sent by all POST requests from KalSMS:
</p>
<dl>
<dt>"version" ::= &lt;integer&gt;</dt>
<dd>
The API version of the POST requests (currently <code>"2"</code>).
<br />
<br />
This number will be incremented whenever the format of POST requests changes significantly.
This allows the server to support phones running different API versions at the same time.
If a deployment has many phones running with KalSMS, the server should update its code first,
then the phones can be upgraded to the new version of KalSMS as convenient.
</dd>
<dt>"phone_number" ::= &lt;text&gt;</dt>
<dd>
The phone number of the phone running KalSMS, as entered under Menu &gt; Settings.
<br /><br />
This allows the server to differentiate between KalSMS clients if multiple phones
are running KalSMS.
</dd>
<dt>"action" ::= "outgoing" | "incoming" | "send_status"</dt>
<dd>
The request action determines the purpose of the HTTP request:
<dl>
<dt>"outgoing":</dt>
<dd>
Poll the server for outgoing messages
</dd>
<dt>"incoming":</dt>
<dd>
Forward an incoming SMS or MMS message to the server
</dd>
<dt>"send_status":</dt>
<dd>
Update the server on the status of sending an outgoing message
</dd>
</dl>
The other POST parameters sent depend on the request action.
</dd>
</dl>
The following HTTP Headers are sent in all POST requests from KalSMS:
<dl>
<dt>"X-Kalsms-Signature" ::= &lt;text&gt;</dt>
<dd>
A signature of the request to verify the phone and the server share the same password
(though it doesn't protect against MITM snooping or replay attacks).
<br />
<br />
The signature is calculated by the following algorithm:
<ol>
<li>Sort all POST parameters (not including file uploads)
in alphabetical order by the name of the field.</li>
<li>Generate an input string by concatenating:
<ul>
<li>the server URL,</li>
<li>each of the sorted POST parameters with their corresponding values, and</li>
<li>the password,</li>
</ul>
with a comma in between each element, like so:
<br /><br />
<code>"&lt;serverURL&gt;,&lt;name1&gt;,&lt;value1&gt;,&lt;...&gt;,&lt;nameN&gt;,&lt;valueN&gt;,&lt;password&gt;"</code>
</li>
<li>Generate the SHA-1 hash of the input string in UTF-8</li>
<li>Encode the SHA-1 hash using Base64 with no line breaks.</li>
</ol>
</dd>
</dl>
Additional parameters sent in POST requests with action=incoming:
<dl>
<dt>"from" ::= &lt;text&gt;</dt>
<dd>
The phone number of the message sender.
</dd>
<dt>"message_type" ::= "sms" | "mms"</dt>
<dd>
Whether this message is an SMS or MMS.
</dd>
<dt>"message" ::= &lt;text&gt;</dt>
<dd>
The message body of the SMS, or the content of the <code>text/plain</code> part of the MMS.
</dd>
</dl>
Additional parameters sent in POST requests with action=incoming and message_type=mms:
<dl>
<dt>"mms_parts" ::= &lt;json_array&gt;</dt>
<dd>
Metadata for each part of the MMS. Each item in the JSON array is an object
with the following keys and values:
<dl>
<dt>"name" ::= &lt;text&gt;</dt>
<dd>
The name of an additional form field where the content of the MMS part
is sent as an attached file.
</dd>
<dt>"cid" ::= &lt;text&gt;</dt>
<dd>
The Content ID of the MMS part. This allows the server to resolve
references in the SMIL part of the MMS
(e.g. <code>&lt;img region="Image" src="cid:805"/&gt;</code>).
</dt>
<dt>"type" ::= "application/smil" | "text/plain" | "image/jpeg" | ...</dt>
<dd>
The Content Type of the MMS part.
</dd>
<dt>"filename" ::= &lt;text&gt;</dt>
<dd>
The filename of the MMS part, as sent by the sender phone,
e.g. <code>"Image001.jpg"</code>.
</dt>
</dl>
(Additional fields with the content of each MMS part. Text parts
are encoded in UTF-8.)
</dt>
</dl>
Additional parameters sent in POST requests with action=outgoing:
<dl>
<dt>
(None)
</dt>
</dl>
Additional parameters sent in POST requests with action=send_status:
<dl>
<dt>"id" ::= &lt;text&gt;</dt>
<dd>
The Server's ID for the outgoing message (from the <code>id</code> attribute
of an <a href='#sms'>sms</a> tag in a previous XML response from the server).
</dd>
<dt>"status" ::= "queued" | "failed" | "sent"</dt>
<dd>
The current status of the outgoing message.
</dd>
<dt>"error" ::= &lt;text&gt;</dt>
<dd>
A description of the reason for the error, if the message
failed to send; or, an empty string if the message
has been sent successfully.
</dd>
</dl>
<h3>
HTTP Response Format
</h4>
<p>
For a successul request, the server should return HTTP status code 200.
If the signature check failed, the server should return status code 403.
Other status codes may be used to signify errors.
</p>
HTTP response format for action=incoming and action=outgoing:
<blockquote>
The Content-Type header should be text/xml, with the content as follows:
<dl>
<dt>&lt;messages&gt;</dt>
<dd>
The root XML element.
<br />
<br />
Attributes:
<dl><dt>none</dt></dl>
Content:
<dl>
<dt>&lt;sms&gt;*</dt>
<dd>The SMS messages to send.</dd>
</dl>
</dd>
<dt id='sms'>&lt;sms&gt;</dt>
<dd>
Describes an outgoing SMS to send.
<br /><br />
Attributes:
<dl>
<dt>"id" ::= &lt;text&gt; (optional)</dt>
<dd>
An ID for this outgoing message. (KalSMS will send this
back to the server as the id field in a send_status request.)
</dd>
<dt>"to" ::= &lt;text&gt; (optional for incoming, required for outgoing)</dt>
<dd>
The phone number to send the SMS to. If omitted for
action=incoming, it will be sent as a reply to the original
sender.
</dd>
</dl>
Content:
<dl>
<dt>CDATA</dt>
<dd>
The content of the SMS message to send.
</dd>
</dd>
</dl>
Example:
<pre>
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;messages&gt;
&lt;sms id='42' to='5551212'&gt;Message One&lt;/sms&gt;
&lt;sms&gt;Message Two&lt;/sms&gt;
&lt;/message&gt;
</pre>
</blockquote>
Response format for action=send_status:
<blockquote>
The response content is currently undefined and ignored.
</blockquote>
<div class="footer">
get the source code on GitHub : <a href="http://github.com/youngj/KalSMS">youngj/KalSMS</a>
</div>
</div>
</body>
</html>

0
styles/default.css Executable file
View File

71
styles/site.css Executable file
View File

@ -0,0 +1,71 @@
body {
margin-top: 1.0em;
background-color: #fff;
font-family: Helvetica, Arial, FreeSans, san-serif;
color: #333;
}
dt
{
font-family:monospace;
}
dd
{
padding-bottom:10px;
}
.menu
{
font-weight:bold;
}
.menu a
{
text-decoration:none;
}
.comparison_table
{
font-size:12px;
}
.comparison_table tbody th
{
white-space:nowrap;
text-align:right;
}
.comparison_table tbody td
{
border:1px solid #ccc;
}
.comparison_table ul
{
}
#container {
margin: 0 auto;
width: 700px;
}
h1 { margin-top:0; font-size: 3.8em; color: #678bf0; margin-bottom: 3px; }
h1 .small { font-size: 0.4em; color:#666; }
h1 a { text-decoration: none }
h2 { font-size: 1.5em; color: #678bf0; }
h3 { color: #678bf0; }
a { color: #678bf0; }
.description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
.download { float: right; }
pre { background: #000; color: #fff; padding: 15px;}
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.footer { text-align:center; padding-top:30px; font-style: italic; }
.button
{
text-decoration:none;
display:block;margin:0 auto;width:200px;background:#68f;color:white;padding:8px;font-weight:bold;text-align:center;
}
a.button:hover
{
text-decoration:underline;
}