Sopranica generalizes your phone number so that you can send and receive calls
and SMS from any other phone, while only providing people with a single number,
or multiple numbers (ie. one per country) if you wish.

Sopranica is currently in the early stages of development.  It will send and
receive SMS using the SMS Mapper forwarding table, which has been tested with a
reasonably-sized forwarding list, though with just two usernums so far.  It does
not yet support call forwarding or DISA.  These are next on the list to add.


The Sopranica source tree includes black-box tests that exercise Sopranica's
functionality.  To run the test suite: checkout Sopranica, install the
dependencies (see bottom of this file) and then execute the following commands
in a POSIX shell from the Sopranica directory:

$ cd test
$ ./generate_config.sh
$ cd sms
$ ../run_tests.sh

The tests will print basic information to standard output with more detailed
information saved in a test/out_$DATE directory.  If the tests fail on your
system, instructions for reporting this will be printed.  Please do send in the
report as it will help improve Sopranica.

(Note that the "sms" directory name is incidental - because of the way Vitelity
works (it is the only supported XMPP carrier, for now), the domain used by the
XMPP server must be "sms".  Since Vines prefers a configuration directory named
after its domain, the configuration directory is thus called "sms".)


Sopranica has 4 main parts: SMS Relay, which will accept XMPP messages on a
particular JID and forward them to other JIDs given a set of forwarding rules.
This is intended to be used with an SMS provider that offers an XMPP account for
sending and receiving SMS.  Currently the SMS Relay tool receives SMS, logs
them, and passes these received messages on to SMS Mapper, which does a number
translation and then passes them on to SMS Dispenser.  The dispenser makes an
HTTP POST request to the API endpoint, which causes an SMS to be sent (using the
numbers defined in the mapper).  Messages coming back go through SMS Acceptor.

SMS Relay has been tested with Vitelity's SMS-to-XMPP service.  SMS Dispenser
has been tested with Plivo's SMS sending REST API.  Other services will be added
in the future and the code generalized to not assume any particular service.

Note that an experimental SMS dispenser/acceptor for Vitelity is now available.
It is configured in the same way as SMS Relay (see below); the settings file is
at settings-sms_relay-pubsub-<user_number>.rb .

To configure SMS Relay, put the following lines in
settings-sms_relay-<forward_number>.rb:

	LOGIN_USER = <jid_of_number_you_own>
	LOGIN_PWD = <password_for_above_user>

The value of <forward_number> would be 16475550199 in the below example.  Note
that multiple SMS Relay processes can be run, one for each <forward_number>.
The SMS Mapper settings must include entries for each Relay's <forward_number>.

To configure SMS Mapper, put the following lines in settings-sms_mapper.rb:

	OTHER_AND_USERNUM_TO_FWD = {
		['12125550199', '19175550199'] => '16475550199'
	}
	USERNUM_TO_DEVICES = {
		'19175550199' => ['14165550199', '15145550199']
	}
	DEFAULT_FWD = '16475550199'

The 212 number is the recipient, the 917 number is your Plivo number, the 647
number is your Vitelity number, and the 416 number is one of your cell numbers
(you send messages from your cell to the Vitelity number and then SMS Dispenser
will send them from your Plivo number to the recipient).  Recipient numbers that
aren't in OTHER_AND_USERNUM_TO_FWD will have their messages routed from
DEFAULT_FWD to all devices for the given USERNUM (ie. the 416 and 514 numbers).
The 514 number is another cell number of yours, which you can use just like the
416 number to send and receive SMS through the forwarding number.

To configure SMS Dispenser put the following in settings-sms_dispenser-plivo.rb:

	AUTH_ID = <Plivo_AUTH_ID>
	AUTH_TOKEN = <Plivo_AUTH_TOKEN>

Once all three are configured, you can start them up in any order.  After they
have all started, SMS sent to your Vitelity number should be forwarded to the
recipient via your Plivo number, as configured in the SMS Mapper settings file.

WARNING: For now, you must modify sms_mapper.rb to add any numbers that the
Plivo dispenser will be using.  Specifically, the "if" block under "remove hack"
must include the numbers in its expression so that the hack is performed.  This
is a temporary measure to support the experimental Vitelity dispenser/acceptor
(see above).  Once we've updated the original Dispenser to support the new
naming scheme, this will not be needed (the hack allows it to work unchanged).

A fourth component, SMS Acceptor, accepts SMS from outside numbers.  It will
pass messages from an external user through to your cell phone (via the Mapper
and Relay).  In the current iteration, it acts as a Plivo "message url", which
accepts POST requests from Plivo when Plivo receives an SMS.  For now it just
prints the values that Plivo gives it and passes them onto the SMS Mapper, which
routes SMS to the corresponding Relay.  Eventually it'll also support non-Plivo.

In order to run SMS Relay/Mapper/Dispenser, you need the following dependencies:
 * Ruby 1.9+ (older versions may work) - "apt-get install ruby" or similar
 * Blather - "gem install blather" or similar
 * FFI bindings for ZeroMQ - "gem install ffi-rzmq" or similar

If using the Plivo frontend you also need (not required in Vitelity-only setup):
 * Sinatra - "gem install sinatra" or similar

To run the tests, you also need the following (for now Sinatra is not required):
 * Vines - "gem install vines" or similar

--
  Copyright (C) 2014  Denver Gingerich <denver@ossguy.com>

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.