Month: March 2015

Ushahidi

Announcements

  • New Version of FrontlineSMS – upgrade from 2.5 to 2.6
  • Wearables in Aid and Development
  • This week, 3/30 – Vision Documents due today
  • This week, 3/30 – Ushahidi overview
  • Next week (4/6-4/10) – Present Vision Documents to Partner Organizations
  • Next week, 4/6 – Freedom Fone overview

Vision Documents

Let’s take a few minutes to share a few of your Vision Documents.

Ushahidi

Ushahidi means “testimony” or “witness” in Swahili.

What is it?

Ushahdi is a Company.

Ushahidi is a platform.

Ushahidi is open source software for information collection, visualization & interactive mapping.

Who uses it?

Types of Maps

A Quick Demo

Here’s an example Ushahidi instance we can try out.

Main UI

  • The Map
  • The Timeline
  • Reports

Admin UI

  • Dashboard
  • Reports
  • Messages
  • Stats
  • Addons
  • Settings
  • Manage
  • Users
  • Help

The Apps

Challenge

  • Break up into your groups.
  • Download the appropriate app onto each team member’s phone.
  • Configure your app by inputing the ushahidi.smithandthompson.net map address
  • Optionally configure your app by inputting your contact information to be included in your reports
  • Have every team member submit at least one report, try sending a picture or video with your report
  • Try submitting a report online through the form on ushahidi.smithandthompson.net
  • Try submitting a report by sending an email to ushahidi@smithandthompson.net
  • Try submitting a report through SMS by texting to 267-536-3902 (Twilio number) or 856-571-9434 (Huawei dongle)

Assignment

Vision Document

  • Revise your Vision Document based upon the feedback given in class or through email
  • Get together with your group and create a ‘master’ Vision Document to serve as a Design Brief/roadmap for your project concept
  • Email me a link to your master Vision Document and I’ll post it to your partner organization’s Parter Page on the class blog.
  • Prepare to present your Vision Document to your Partner Organization next week (the week of April 6th)

Design Notebook

  • Create a new Design Notebook page and label it “Regional SMS Providers for “, the country name of your partner organization and today’s date.
  • Create a list of cellphone companies that service your partner’s region – these are the companies from which you may need to secure sim cards.
  • Create another list of Twilio alternatives for your team to consider using for your project that will give you access to local phone numbers.
  • Keep in mind alternatives can be “cloud” service providers like Clickatell, 3/4g GSM modems like the Huawei e173, or a cell phone with a local sim card using FronlineSync or SMSsync
  • Each team should identify one (or more) computer(s) upon which to install FrontlineSMS, and acquire one or more 3/4g GSM modems. Double check the FrontlineSMS device compatibility database to make sure you get devices that are known to work with FrontlineSMS.

*Assignments are due before class begins on Mondays. Be prepared to present your work in class for discussion.

FrontlineSMS

Announcements

  • Today, Bridget McGraw will join us as our guest speaker
  • Doctors Without Borders using Twilio in Zimbabwe
  • Clickatell, another cloud-based SMS alternative to Twilio in South Africa, used by Freedom Fone for SMS features
  • Next week, March 30th – Vision Documents due, Ushahidi overview
  • April 6, Teams present Vision Documents to Partner Organizations, Freedom Fone overview

Design Notebooks

Let’s review your User Personas from before the break.

Vision Documents

  • Your Vision Documents (aka Design Briefs) are due next week, March 30. Use this Vision Document Template as a guide to creating your Vision Documents for your project concepts.
  • Each team member will create their own Vision Document, emphasizing their own particular contribution to the team’s project, but including much of the same material, which you’ll work out together with your team.
  • After receiving feedback from me, you’ll present a unified team version of your Vision Document to your partner organization the week of April 6 for feedback before beginning your project prototype development the following week.

FrontlineSMS

What is FrontlineSMS?

"FrontlineSMS is a desktop software created to lower barriers to positive social change using mobile technology. By leveraging basic tools already available to most organizations, including those in ‘last-mile’ settings — computers and low-cost modems — FrontlineSMS enables instantaneous two-way communication to any mobile handset. It’s easy to implement, simple to operate, and best of all, the software is free; you only pay for the messages you send. Using FrontlineSMS with FrontlineSync, you can also track missed calls for the first time." - FrontlineSMS Overview

Let’s listen to Laura Walker Hudson’s video overview of FrontlineSMS.

Here are some additional info and case studies on FrontlineSMS.

What You’ll Need

A Quick Demo of a Macbook Pro Setup

  1. Register and load up your sim card with minutes
  2. Install the sim card in the Huawei e173 dongle
  3. Plug in the Huawei e173
  4. Load the driver using the MobilePartner app
  5. Quit MobilePartner and launch FrontlineSMS
  6. Once the light is green n the FrontlineSMS Connections tab, you’re ready to go

A Tour of Features

Receiving SMS Messages

Text the service at (856) 571-9434, Frontline will automatically add callers’ phone numbers to the system contact database. We can use to create Groups later.

Sending SMS Messages

Now let’s send a message from FrontlineSMS to everyone on our contact database.

Working with Groups

  • Creating Groups Manually – let’s create separate groups for each project team
  • Smart Groups – let’s create another set of groups based on area code

Using Activities

  • Auto-replying to received messages – let’s create an auto-reply activity
  • Auto-forwarding received messages
  • Subscribing & unsubscribing to groups – let’s manually create another group and try subscribing and unsubscribing to it
  • SMS Polls – let’s create a simple poll
  • Forwarding received messages to URLs – we’ll demonstrate this next week when we introduce Ushahidi

Managing Data & Tracking Usage

  • Importing & exporting contacts and messages
  • Monitoring usage & reading log files

Guest Presentation

Bridget McGraw – Bridget is an Educational Technologist, digital artist and entrepreneur. She lived and worked in Africa for almost a decade, assisting organizations including TICAH, CEWOD, iHub and Ni Sisi! to develop interactive multimedia solutions for communicating with their communities.

Assignment

Vision Documents

Meet with your team to discuss your project concept. Use this Vision Document Template as a guide to creating your own Vision Documents for your project concepts. These will be due next week, and you’ll the present them as a team to your respective partner organizations the following week after getting feedback from me.

Each team member will create their own Vision Document, emphasizing your own contributions to your team’s project. When you present to your partner organizations, you’ll present a unified Vision Document for your team.

Post your Vision Document as a comment to this page!

*Assignments are due before class begins on Mondays. Be prepared to present your work in class for discussion.

Data: Databases & APIs

Announcements

  • Twilio Alternatives: Grapevine in South Africa, Africa’s Talking in East Africa, possibly Vumi across most of Africa
  • This week, Databases & APIs
  • Next week, Spring Break
  • March 23, User Personas & User Stories due, overview of Frontline SMS
  • March 30, Vision Documents due, overview of Ushahidi
  • April 6, Overview of Freedom Fone

Design Notebooks

Let’s take a few minutes to share some of your Design Notebook entries from this week.

User Personas & User Stories

Let’s take a few minutes to discuss User Personas & User Stories and to create a couple of examples on Google Drive.

For more info on writing great User Personas, check out this blog post.

For more info on writing User Stories, check out this one.

Databases & APIs

Databases

Over the last couple of weeks, whenever we need to store data for our apps, we wrote it to or read it from comma separated flat text files. This week we’ll have a look at PostgreSQL, “the world’s most advanced open source database”.

PostgreSQL is an object-relational database, which means it can ‘relate’ information together in the form of tables. It used a query language called SQL, or Structured Query Language, to create, update and delete data in the database.

PostgreSQL is used by thousands of organizations, including Etsy, Moby Games, the National Weather Service, Greenpeace, Apple & Skype.

TCNJ PostgreSQL

As it turns out, you all have access to a PostgreSQL instance at database.tcnj.edu. Let’s log in and create our database.

For our purposes, we’ll need to do three things to database-enable our apps:

  1. Create the table for our data
  2. Insert records into our data table
  3. Retrieve data from our table

Phonebook

Let’s create a phone book we can use for some of the apps we developed earlier in the semester.

  • Log into the TCNJ postgreSQL database and create a new schema called phonebook.
  • Now open up the phonebook.sql file from the examples in a text editor and add in your own phone numbers.
  • Click the SQL icon in the menu along the top of phpPgAdmin and let’s feed it your updated phonebook.sql file.
  • Now upload hello_mom_psql.php onto your TCNJ web account and update your Twilio phone number message url to point to it.
  • Text your Twilio phone number from your or a friend’s cell phone. Try calling from a number that’s in your phonebook database, and from a number that is not.
  • What happened?

Let’s have a look at the code for hello_mom_psql.php.

Incident Database

Let’s update the incident reporting app we made last week to use a database instead of a file to store our data.

  • Log into the TCNJ postgreSQL database and create a new schema called incidents.
  • Now open up the incidents.sql file from the examples in a text editor and add in your own phone numbers.
  • Click the SQL icon in the menu along the top of phpPgAdmin and let’s feed it your updated incidents.sql file.
  • Now upload sms_map_psql.php, map_incidents.php, and postgresql_map.html onto your TCNJ web account, and update your Twilio phone number message url to point to it.
  • Text your Twilio phone number from your or a friend’s cell phone, keying in a location name, and its latitude and longitude coordinates, in a comma-separated list like so: Trenton, 40.2162772, -74.7741221
  • Now, in your web browser, navigate to your postgresql_map.html map that you uploaded; e.g http://www.tcnj.edu/~username/imm470-03/databases/postgresql_map.html
  • What happened?

Let’s have a look at the code for sms_map_psql.php, map_incidents.php, and postgresql_map.html

APIs

API stands for Application Programming Interface and refers to hooks some applications have that allow other applications to connect to them.

For example, Twitter is an application that allows users to share short status updates through a web or mobile interface. But what if you wanted to show your latest tweets on your blog? You’d need to have some way to allow your blog to communicate with Twitter, application to application, to filter, collect, and present just the appropriate tweets on your blog. Since Twitter has an API, this is a fairly straight-forward thing to do.

Let’s work through a couple of examples of why we might want to use APIs in our applications:

Geocoding

Geocoding for Feature Phones

For our geocoding API needs today, we’ll use the Google GeoCoder.

  • Upload the geocoder.php file to your TCNJ web account, and update your Twilio number’s messaging request url to point to it.
  • Using your cellphone, text your Twilio phone number with address information of some sort; a zip code, a city name, a street address, etc.
  • What happened?

Let’s have a look at the code for geocoder.php.

Geocoding for Smartphones

Smartphones come with GPS capabilities built in. The trick is to integrate those capabilities into a sensible user interface that suits your application.

For SMS-based incident reporting, an elegant solution would be to allow users to geocode SMS messages using their phone’s GPS feature:

Cordova SMS plugin + Cordova GPS plugin = Smartphone GPS-enabled SMS client

Alternatively, you could develop a native app that posts directly to an incident database though the internet protocol (wifi or 3g /4g).

A Weather App

Let’s create an SMS app that let’s the user send an SMS with their Zip Code, City, or other address info and receive back the current weather conditions for that location.

  • Upload current_weather.php to your TCNJ web account.
  • Update your Twilio phone number’s message request url to point to that file
  • Text your Twilio number an address of some sort, a zip Code, a city name, a street address, etc.
  • What happened?

To accomplish this, we needed a couple of things:

  1. First we needed to implement a geocoder pattern to convert the address info into latitude & longitude.
  2. Then, we needed to find an API we can use to get the current weather conditions for our location.

Since we’ve got a working geocoder pattern, we went ahead and reused that to geocode user input. And since we were looking for a solution that will work reasonably well internationally, we used Forecast.io for our weather data.

Let’s have a look at the code for current_weather.php.

Challenge

  • Break up into your teams.
  • Using sms_map_psql.php, map_incidents.php, postgresql_map.html and current_weather.php as your starting place, recreate the incident mapping app to include geocoding for the location input data.
  • Whereas before you had to look up the lat, lon info and input it along with a name in a comma separated line before, now you should only have to type in a zip code, city name or address for the incident to appear on the map.

Assignment

Partner Organization Research

With your group, complete & deliver your second round of questions to your partner organization. I’d recommend you use Qualtrix for this second round, and strongly urge you to request your partner organization complete the survey by the end of the week so you can use the data in your User Personas and User Stories.

User Personas & User Stories

  • Meet with your group and identify one user type your partner organization might have per member of your group.
  • Each member should create a User Persona for one user type, along with three User Stories for this user type.
  • Each team member should create a new Design Notebook entry and title it “User Persona” and today’s date. The User Persona should fit on this one slide.
  • Each team member should create a second Design Notebook entry and title it “User Stories” and today’s date. Write out three User Stories for the User Type you documented in the previous slide. The User Stories should fit on this one slide.
  • At the beginning of our next class, we’ll break into our groups, combining your User Persona & User Stories Design Notebook entries into a new, group presentation. We’ll the go around the room and present them by team.

When researching your User Personas, make use of resources such as AudienceScapes and/or MSU’s globalEDGE. These resources can help find answers regarding languages spoken, religions practiced, education levels, as well as information patterns including device & internet usage.

Try to include the following data points in your User Personas:

  • age
  • family structure
  • type of home
  • location of home
  • size of municipality
  • languages spoken, and in what context (circles of trust)
  • education level
  • employment status
  • marital status
  • health concerns
  • access to information
  • device & internet usage
  • etc

*Assignments are due before class begins on Mondays. Be prepared to present your work in class for discussion.

Maps & Location Data

Announcements

  • HACKTCNJ15 $15.00 promo code – courtesy of Kerrin and HackTCNJ
  • Twilio Cookbook – courtesy of Kerrin and HackTCNJ
  • Next week, March 2 – Data: Databases & APIs, User Personas & User Stories
  • March 12, Initial User Personas & User Stories due
  • March 23 – Project Vision Documents will be due after we return from Spring Break

Partner Interviews

  • 1000 Hills Community Helpers
  • CEWOD
  • TICAH Status
  • DramAide Status

Maps

Maps are a kind of infographic, they can communicate a great deal of data visually. They’re also great for presenting data in layers.

As an aside, aligning data can be challenging, and, because of the challenges of projecting spherical geographic data onto flat surfaces, can be distorted:

The True Size of Africa

  1. Download the source code for this week’s examples from the class Github Organization.
  2. Unzip the  repository on your local machine and upload the contents to a new folder in the ‘www’ folder on your TCNJ web account.
  3. Let’s try out the examples one by one.

Leaflet.js

Leaflet.js is an open-sourced Javascript mapping library. Because it is open-sourced, it is ideal for open or non-for-profit applications. Let’s take it for a test drive:

Basic Map

  1. After you’ve uploaded the basic_map.html file to your TCNJ web account, fire up a web browser and point it to the file: http://www.tcnj.edu/~username/directory/basic_map.html
  2. What happened?
<!-- basic_map.html -->
<!doctype html>
<html lang="en">
 
 <head>
 <meta charset="utf-8">
 <title>Hello Leaflet!</title>
 
 <!-- link in the leaflet.js style sheet -->
 <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.css" />
 
 <style>
 #map { 
 height: 650px; 
 margin: 0 auto;
 }
 </style> 
 
 </head>
 
 <body>
 <div id="map"></div>
 
 <!-- link in the leaflet.js library -->
 <script src="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.js"></script>
 <script>
 
 // initialize our map
 var map = L.map('map').setView([40.268835, -74.78091], 13);
 
 // layer in the base map tile
 L.tileLayer('http://otile4.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png', {
 attribution: '&copy; <a href="www.openstreetmap.org/copyright">OpenStreetMap</a>'
 }).addTo(map);
 
 </script>
 </body>
</html>

Adding Markers

Ok. now let’s tweak our Javascript a bit and layer in some additional information:

  1. After you’ve uploaded the markers_map.html file to your TCNJ web account, fire up a web browser and point it to the file: http://www.tcnj.edu/~username/directory/markers_map.html
  2. What happened?
<!-- markers_map.html -->
 <script>
 // initialize our map
 var map = L.map('map').setView([16, -24], 3);
 
 // add a MapQuest tile layer
 L.tileLayer('http://otile4.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png', {
 attribution: '&copy; <a href="www.openstreetmap.org/copyright">OpenStreetMap</a>'
 }).addTo(map);
 
 // Add markers
 
 // TCNJ
 L.marker([40.268835, -74.78091]).addTo(map)
 .bindPopup('<a href="http://www.tcnj.edu" title="TCNJ Website" target="_blank">Go Lions!</a>"');
 // TICAH 
 L.marker([-1.3154995, 36.695187]).addTo(map)
 .bindPopup('<a href="http://ticahealth.org/index.htm" title="TICAH Website" target="_blank">TICAH!</a>');
 // 1000 Hills Community Helpers 
 L.marker([-29.7562074, 30.7433415]).addTo(map)
 .bindPopup('<a href="http://www.1000hch.co.uk/Default.aspx" title="1000 Hills Community Helpers Website" target="_blank">1000 Hills Community Helpers</a>');
 // CEWOD 
 L.marker([-5.0904712, 39.093979]).addTo(map)
 .bindPopup('<a href="http://cewod.org/" title="CEWOD Website" target="_blank">Women Center for Communication and Development</a>');
 </script>

Getting Marker Data from Files

Now let’s tweak our Javascript some more, pulling in our marker data from a file:

  1. After you’ve uploaded the data_map.html and map_data.txt files to your TCNJ web account, fire up a web browser and point it to the file: http://www.tcnj.edu/~username/directory/data_map.html
  2. What happened?
<!-- data_map.html -->
 <script>
 
 // initialize our map, centered somewhere around the Cape Verde Islands
 var map = L.map('map').setView([16, -24], 3);
 
 // add a MapQuest tile layer
 L.tileLayer('http://otile4.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png', {
 attribution: '&copy; <a href="www.openstreetmap.org/copyright">OpenStreetMap</a>'
 }).addTo(map);
 
 // get our data from file using Ajax
 var xmlhttp =new XMLHttpRequest();
 xmlhttp.onreadystatechange = function() {
 if (xmlhttp.readyState == 4 && xmlhttp.status == 200) {
 
 // split up the text file by line
 var lines = xmlhttp.responseText.split('\n');
 for(var line = 0; line < lines.length; line++){
 
 // and split each line by coma
 var vals = lines[line].split(",");
 for(var val=0; val<vals.length; val++){
 console.log(vals[val]);
 }
 
 // place the markers
 L.marker([parseFloat(vals[1]), parseFloat(vals[2])]).addTo(map)
 .bindPopup(vals[0]);
 }
 }
 }
 xmlhttp.open("GET","map_data.txt",true);
 xmlhttp.send(); 
 
 </script>
# map_data.txt
TCNJ,40.268835,-74.78091
TICAH,-1.3154995,36.695187
1000 Hills Community Helpers,-29.7562074,30.7433415
Women Center for Communication and Development,-5.0904712,39.093979

Twilio Location Data

It turns out Twilio supplies additional data about callers in the TwiML request variables. Let’s take a minute to look at the Twilio Documentation.

Understanding these options, let’s see what we can get:

Twilio SMS Location Variables Example

  1. After you’ve uploaded the sms_location_vars.php and data.txt files to your TCNJ web account, log into Twilio, click into your number detail page, and edit the Message request url for your number to point to ‘sms_location_vars.php’.
  2. SMS your Twilio number with any message. Make sure you’ve set the file permissions on data.txt to 666.
  3. What happened?
  4. Now point your web browser to http://www.tcnj.edu/~your-user-name/your-folder/data.txt
  5. What do you see?
// sms_location_vars.php
<?php
 // we can get the number of the sender using the 'Fromn' request value
 $from = $_REQUEST['From'];
 $city = $_REQUEST['FromCity'];
 $state = $_REQUEST['FromState'];
 $zip = $_REQUEST['FromZip'];
 $country = $_REQUEST['FromCountry'];
 $msg = $_REQUEST['Body'];
 
 header("content-type: text/xml");
 echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
 
 // get the exact time of the response
 $t = time();
 
 // set the timezone
 date_default_timezone_set('America/New_York');
 
 // open a file ponter to write our data
 $fp = fopen("data.txt", "a");
 fwrite($fp, $from . "," . $city . "," . $state . "," . $zip . "," . $country . "," . date("c", $t) . "\n");
 
 // close out file pointer
 fclose($fp);
?>
<Response>
 <Message>Thanks! Here's your phone's area code location: <?php echo $city . ", " . $state . ", " . $zip . ", " . $country; ?></Message>
</Response>

Mapping Locations From SMS

Unfortunately, the location variables Twilio provides aren’t really all that useful. The location data returned turns out to be the location data for the area code, or, more specifically, the phone number’s Numbering Plan Area (NPA). This location data doesn’t change depending on where the caller is calling from.

As a result, we need another solution to capture location data for the actual location of the caller.

  1. After you’ve uploaded the sms_map_data.php, twilio_map.html and twilio_data.txt files to your TCNJ web account, log into Twilio, click into your number detail page, and edit the Voice request url for your number to point to sms_map_data.php. Make sure the twilio_data.txt file permissions are set to 666.
  2. SMS your Twilio number with a coma separated line including a location name, a latitude, and a longitude. Something like “TCNJ,40.268835, -74.78091”.
  3. What happened?
  4. Now point your web browser to http://www.tcnj.edu/~your-user-name/your-folder/twilio_map.html.
  5. What do you see?
// sms_map_data.php
<?php
 // we can get the number of the sender using the 'Fromn' request value
 $from = $_REQUEST['From'];
 $msg = $_REQUEST['Body'];

 header("content-type: text/xml");
 echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";

 // break up the message into an array for cleaning
 $msg_arr = explode(",",$msg);

 // remove any extra spaces
 for($i=0; $i<count($msg_arr); $i++){
   $msg_arr[$i] = trim($msg_arr[$i]);
 }
 
 // put it back together as coma separated
 $msg = implode(",",$msg_arr);
 
 // open a file ponter to write our data
 $fp = fopen("twilio_data.txt", "a");
 fwrite($fp, $msg . "\n");
 
 // close out file pointer
 fclose($fp);
?>
<Response>
 <Message>Thanks for the incident report!</Message>
</Response>

Challenge

  1. Break up into your groups and create a Leaflet map based on the the markers_map.html example.
  2. Each member of the group should find the latitude & longitude of a location and place a marker on the map using the appropriate Javascript.
  3. Now, create a new Leaflet map based on the twilio_map.html example, you’ll need to use the sms_map_data.php & twilio_data.txt files as well.
  4. Once you’ve created the system, have each member of you group text in a location in a location name, latitude, longitude format.

Assignment

Reading

Partner Organization Interviews and Follow-up Survey

  1. Meet with your team and review your notes from your initial partner interview
  2. Using the secondary & followup questions list from last week, and adding any new questions that have come up as a result of your initial partner interview, refine your TCNJ Qualtrics survey in preparation for submission to your partner organization.

Design Notebook

  1. Create a new page in your Design Notebook and label it “Initial Partner Interview” and today’s date.
  2. Comment on your experience with your initial partner interview. Include your overall impressions, including your partner organization’s top needs you feel your team should address. Based upon this initial interview, what additional details do you feel you need in order to more clearly define your project?
  3. Be prepared to discuss in class next week.

*Assignments are due before class begins on Mondays. Be prepared to present your work in class for discussion.