add page explaining how to test with emulator; faq for reverse tunnels; screenshot of pending messages

2025-07-06 15:04:04 +00:00 · 2011-10-01 15:47:55 -07:00
parent ba94500c10
commit 6781f9aa85
32 changed files with 385 additions and 81 deletions
--- a/.phrozn/entries/faq/index.twig
+++ b/.phrozn/entries/faq/index.twig
@ -2,6 +2,7 @@ id: faq
 title: Frequently Asked Questions
 q_alternative: Instead of implementing a SMS gateway as an Android app, why not use X instead? (where X = Twilio, Tropo, Clickatell, FrontlineSMS, RapidSMS, Kannel, etc.)
 q_rate: How fast can EnvayaSMS send SMS messages?
+q_tunnel: EnvayaSMS can't connect to my dev server! What's wrong?
 q_phones: What phones are compatible with EnvayaSMS?
 q_servers: Does EnvayaSMS use envaya.org's servers?
 q_envaya_org: What is the relationship between EnvayaSMS and envaya.org?
@ -17,6 +18,9 @@ q_smssync: What is the difference between EnvayaSMS and SMSSync?
    <li>
        <a href='#q_rate'>{{ this.q_rate }}</a>
    </li>    
+    <li>
+        <a href='#q_tunnel'>{{ this.q_tunnel }}</a>
+    </li>    
    <li>
        <a href='#q_phones'>{{ this.q_phones }}</a>
    </li>
@ -128,6 +132,45 @@ To increase the rate at which you can send SMS messages, you can install EnvayaS
 In order to send more than 100 messages per hour with a single phone, it is necessary to install <a href='/install/#expansion'>EnvayaSMS Expansion Packs</a>.
 </p>

+<h4 id='q_tunnel'>{{ this.q_tunnel }}</h4>
+
+<p>
+EnvayaSMS may be unable to connect to your development web server if it is blocked by a firewall on your computer,
+or if your computer has a IP address that's inaccessible from your phone's network.
+</p>
+
+<p>
+If your Android phone is on the same Wi-Fi network as your development web server, configure the firewall on 
+your development computer to allow incoming connections to your web server, then simply enter your computer's IP address 
+in EnvayaSMS as the Server URL.
+</p>
+<p>
+If you're testing with the phone's mobile data connection, or if your phone and development computer are on different
+Wi-Fi networks, the IP address of your development web server is likely inaccessible to the phone.
+</p>
+<p>
+To allow the phone to connect to your development computer, you can set up a reverse SSH tunnel between your 
+development computer and a server with a public IP address. 
+</p>
+<p>
+To set up a reverse SSH tunnel, you can either:
+
+<ul>
+    <li>use a hosted service like <a href='http://progrium.com/localtunnel/'>localtunnel</a>, or</li>
+    <li>use <code>ssh -R</code> to connect to your own server accessible from the public internet. For example:
+<pre>ssh -R 0.0.0.0:8765:localhost:80 [user]@[host]</pre>
+<p>
+This sets up port 8765 on <code>host</code> to forward to port 80 on your local development computer. 
+Then you can use <code>http://[host]:8765/</code> as the Server URL in EnvayaSMS, and it will be 
+forwarded to <code>http://localhost</code> on your development server.
+</p>
+<p>
+Note: In order for SSH port forwarding to work, you will need to set <code>GatewayPorts yes</code> in the <code>/etc/sshd_config</code> file
+on the public server.
+</p>
+</li>
+</ul>
+
 <h4 id='q_phones'>{{ this.q_phones }}</h4>

 <p>
--- a/.phrozn/entries/history/index.twig
+++ b/.phrozn/entries/history/index.twig
@ -2,27 +2,25 @@ id: history
 title: History
 ---

-Version 2.0-rc2 (2011/09/29)
+Version 2.0 (2011/10/01)

 <ul>
    <li>
        Automatic failover between Wi-Fi and mobile data connection if server is unreachable
        (e.g. when Wi-Fi router is on, but it has no internet access)
    </li>
+    <li>
+        User can see all pending messages, and retry/delete individual messages
+    </li>
    <li>
        Send timestamp of incoming messages to server
-    </li>    
-</ul>
-
-Version 2.0-rc1 (2011/09/28)
-
-<ul>
+    </li>  
    <li>
        Allow outgoing SMS messages to be sent in priority order
    </li>
    <li>
        Reschedule outgoing messages when the Android outgoing SMS limit would be exceeded
-    </li>    
+    </li>     
 </ul>

 Version 2.0-beta (2011/09/23)
--- a/.phrozn/entries/how/index.twig
+++ b/.phrozn/entries/how/index.twig
@ -22,7 +22,7 @@ work over the phone's mobile data connection, but Wi-Fi is likely to be faster,
 <p>
 Then your network would look like this:
 <br />
-<img src='/media/topology.png' width='690' height='284' />
+<img src='/media/topology.png' width='650' height='262' />
 </p>

 <p>
--- a/.phrozn/entries/index.twig
+++ b/.phrozn/entries/index.twig
@ -6,7 +6,8 @@ layout: default.twig
 <img src='/media/screenshot-main.png' width='212' height='350' />  
 <br />
 <img src='/media/screenshot-settings.png' width='212' height='350' />
-
+<br />
+<img src='/media/screenshot-pending.png' width='212' height='350' />
 </div>

 EnvayaSMS is a SMS and MMS gateway running entirely as an Android app.
@ -51,9 +52,13 @@ It works wherever the phone can receive SMS messages and access the Internet
 </p>
 <p>
    In order to deploy EnvayaSMS, you will need a messaging plan for your phone, and the phone itself. 
-    EnvayaSMS is compatible with many old or inexpensive Android phones, e.g. the LG GT540, currently $120 on Amazon.com.
+    EnvayaSMS is compatible with many old or inexpensive Android phones, e.g. the LG GT540, currently $120 on Amazon.com.    
 </p>       
+<p>
+    Before deploying EnvayaSMS, you can test EnvayaSMS without an Android phone
+    by installing EnvayaSMS on an emulated phone on your computer. <a href='/test/'>Learn more...</a>
+</p>
    
-<a href='/install/' class='button'>
+<a href='/install/' class='button' style='margin-left:110px;'>
 Install EnvayaSMS Now
 </a>    
--- a/.phrozn/entries/install/index.twig
+++ b/.phrozn/entries/install/index.twig
@ -1,21 +1,26 @@
 id: install
 title: Installing EnvayaSMS
 ---
-Before installing EnvayaSMS, ensure that you have the following prerequisites:
+In order to install and deploy EnvayaSMS, you will need the following prerequisites:

 <ul>
-    <li>One or more Android phones (1.6 Donut or higher) that are
-    registered on a mobile network. </li>
+    <li>One or more Android phones (1.6 or higher),
+    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  />
+    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>
+    <li>A web server accessible from the public internet</li>
 </ul>

-Using an Android phone, open <a href='https://market.android.com/details?id=org.envaya.sms'>EnvayaSMS on Android Market</a> by clicking the link from your phone's browser, or scanning the barcode with a QR code app. Then, follow the steps shown below to install EnvayaSMS on your phone.<br />
+<p>
+Note: If you don't have these prerequisites yet, you can <a href='/test/'>test EnvayaSMS on your computer</a>.
+</p>

-<div style='float:left;padding-right:10px;padding-top:30px'>
+To install EnvayaSMS on an Android phone, open EnvayaSMS on Android Market by clicking the link below from your phone's browser, or scanning the barcode with a QR code app.<br />
+
+<div style='float:left;padding-right:10px;padding-top:20px'>
 <div style='font-size:16px;font-weight:bold; text-align:center'>
 <a href="https://market.android.com/details?id=org.envaya.sms">Open Android Market</a>
 </div>
@ -25,7 +30,7 @@ Using an Android phone, open <a href='https://market.android.com/details?id=org.
 </div>

 <div style='float:left;padding-top:10px'>
-<img src='/media/screenshot-market.png' style='border:1px solid black' width='484' height='240' />
+<img src='/media/screenshot-market.png' style='border:1px solid black' width='440' height='218' />
 </div>

 <div style='clear:both;padding-top:10px'>
@ -80,6 +85,9 @@ After your server is configured, configure EnvayaSMS on your phone to connect to
 <li><em>Recommended:</em> under Wi-Fi sleep policy, select "always stay connected".
    (Otherwise, EnvayaSMS will be unable to forward messages after the phone goes to sleep.)
 </li>
+<li><em>Optional:</em> enable Network Failover so that the phone will automatically switch 
+to mobile data if the Wi-Fi network stops working.
+</li>
 <li>Check "Enable EnvayaSMS"</li>
 <li>Click the Back button to return to the main screen</li>
 </ol>
@ -93,8 +101,11 @@ then click "Test Connection".
 <p>
 <strong>Important:</strong> After EnvayaSMS is enabled, it will forward all SMS messages regardless of whether the
 EnvayaSMS app is open. If you want to use SMS normally again, return to EnvayaSMS' settings screen
-and uncheck "Enable EnvayaSMS". 
-</p>
+and uncheck "Enable EnvayaSMS".</p>
+
+<p>If you're testing EnvayaSMS with an Android phone that you're also using for normal communication, 
+you can enable "Test mode" on the settings screen so that EnvayaSMS only handles SMS messages
+from particular phone numbers.</p>

 <h3 id='expansion'>Installing Expansion Packs</h3>

--- a/.phrozn/entries/serverapi/index.twig
+++ b/.phrozn/entries/serverapi/index.twig
@ -32,12 +32,13 @@ HTTP Request Format
 <pre>
 POST /sg/app HTTP/1.1
 X-Request-Signature: sAemG31uRllk/K9xck2WRNaF/WI=
-Content-Length: 96
+Content-Length: 120
 Content-Type: application/x-www-form-urlencoded
 Host: 192.168.70.1:3000
 Connection: Keep-Alive

-from=6505551234&message_type=sms&message=test&version=2&phone_number=16505551212&action=incoming
+from=6505551234&message_type=sms&message=test&version=2&phone_number=16505551212
+&action=incoming&timestamp=1317506831000
 </pre>

 <p>An incoming MMS message with an <code>image/jpeg</code> part and a <code>text/plain</code> part with message 'Test':</p>
@ -46,53 +47,61 @@ from=6505551234&message_type=sms&message=test&version=2&phone_number=16505551212
 POST /sg/app HTTP/1.1
 X-Request-Signature: OgpiQet9guVhEp+0klrONR8qGNs=
 Content-Length: 13087
-Content-Type: multipart/form-data; boundary=i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+Content-Type: multipart/form-data; boundary=i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Host: 192.168.70.1:3000
 Connection: Keep-Alive

--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="from"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

 +16505551234
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
+Content-Disposition: form-data; name="timestamp"
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+1317506831000
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="message"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

 Test
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="message_type"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

 mms
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="mms_parts"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

-[{"type":"application/smil","filename":"01smil","cid":"<0000>","name":"part0"},{"type":"text/plain","filename":"Text01.txt","cid":"<569>","name":"part1"},{"type":"image/jpeg","filename":"Image0001.jpg","cid":"<570>","name":"part2"}]
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+[{"type":"application/smil","filename":"01smil","cid":"<0000>","name":"part0"},
+{"type":"text/plain","filename":"Text01.txt","cid":"<569>","name":"part1"},
+{"type":"image/jpeg","filename":"Image0001.jpg","cid":"<570>","name":"part2"}]
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="version"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

 3
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="phone_number"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

 16505551212
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="action"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: 8bit

 incoming
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="part0"; filename="01smil"
 Content-Type: application/smil; charset=UTF-8
 Content-Transfer-Encoding: binary
@ -113,19 +122,19 @@ Content-Transfer-Encoding: binary
  &lt;/body&gt;
 &lt;/smil&gt;

--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="part1"; filename="Text01.txt"
 Content-Type: text/plain; charset=UTF-8
 Content-Transfer-Encoding: binary

 Test
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG
 Content-Disposition: form-data; name="part2"; filename="Image0001.jpg"
 Content-Type: image/jpeg
 Content-Transfer-Encoding: binary

 <em>BINARY IMAGE DATA</em>
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO--
+--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RG--
 </pre>

 <p>Checking for outgoing SMS messages:</p>
--- a/.phrozn/entries/test/index.twig
+++ b/.phrozn/entries/test/index.twig
@ -0,0 +1,46 @@
+id: test
+title: Testing EnvayaSMS
+---
+
+<p>
+<img src='/media/avd.png' width='242' height='227' style='float:right;padding-left:10px;' />
+If you don't yet have an Android phone, you can test EnvayaSMS in an emulated phone on your computer. 
+</p>
+<p>
+With this method, you can test EnvayaSMS for free
+and figure out if EnvayaSMS will work for your project
+without needing to get an actual phone or subscribe to mobile service.
+</p>
+<p>
+The following steps explain how to set up EnvayaSMS on an Android Virtual Device:
+</p>
+<ol>
+   <li>Install the <a href='http://developer.android.com/sdk/'>Android SDK</a> on your computer (where you are running a "dev" copy of your website)</li>
+   <li>Create a new Android Virtual Device with a target of Android 1.6 or higher. Specify a size for the SD card (necessary to download EnvayaSMS via the browser)</li>
+   <li>Start the virtual device</li>
+   <li>Open the Browser app and go to <a href='/install/'>sms.envaya.org/install</a></li>
+   <li>Click on the EnvayaSMS-release.apk link to download EnvayaSMS.<br />
+   <small>Note: Android Market does not work in the emulator.</small></li>
+   <li>Install EnvayaSMS</li>
+   <li>Configure EnvayaSMS with the settings of your development server. <br />
+   <small>Note: Do not enter <code>localhost</code> as the Server URL (since this would refer to the AVD itself). Instead, use your computer's IP address on the local network, as shown by the <code>ipconfig</code>
+   or <code>ifconfig</code> utilities.</small>
+   </li>
+    <li>
+        <img src='/media/telnet.png' width='216' height='85' style='float:right' />
+    To simulate incoming SMS on the emulator:
+        <ul>
+        <li>using telnet from your host computer, connect to <code>localhost:5554</code><br />
+        <small>Note: on Windows, you can install <a href='http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html'>puttytel</a>.</small>
+        </li>
+        <li>type <code>sms send [phonenumber] [text message]</code> to send messages to the emulator.<br/>
+        <small>Note: the emulator cannot receive MMS messages.</small>
+        </li>
+        </ul>
+    </li>    
+</ol>
+
+<p>
+Of course, you can also test EnvayaSMS by connecting a real Android phone to your development web server.
+For more information, see the <a href='/faq/#q_tunnel'>FAQ</a>.
+</p>