High-Level Design Document
Design Document – Smart-phones for Community project
Name of the project: EarCast
#1: Hila Peleg, 200167591: peleg.hila@gmail.com
#2: Amit Perelstein, 021952650: amitpp@gmail.com
Table of Contents
Design Document – Smart-phones for Community project .......................................................................... 1
Table of Contents .................................................................................................................................. 1
Introduction .......................................................................................................................................... 2
2
3
4
5
6
1.1
Overview ....................................................................................................................................................2
1.2
Design Goals and Non-Goals .........................................................................................................................2
1.2.1
Goals ..................................................................................................................................................2
1.2.2
Non-Goals ............................................................................................................................................3
1.3
Dependencies ..............................................................................................................................................3
1.3.1
Feature Dependencies ...........................................................................................................................3
1.4
Audience ....................................................................................................................................................3
1.5
Assumptions and Design Constraints List ........................................................................................................4
1.6
Issues List ..................................................................................................................................................4
1.7
To-do List + Expected time-tables .................................................................................................................4
Logical Architecture ......................................................................................................................... 5
2.1
Application Context ......................................................................................................................................5
2.1.1
The Application .....................................................................................................................................5
2.1.2
App Server ...........................................................................................................................................6
2.1.3
Publisher UI .........................................................................................................................................6
Design ........................................................................................................................................... 7
3.1
Classes .......................................................................................................................................................7
3.1.1
Class Diagram ......................................................................................................................................7
3.1.2
Class Details ...................................................................................................................................... 10
3.2
Flows ....................................................................................................................................................... 11
3.2.1
On Init .............................................................................................................................................. 11
3.2.2
On Shutdown ..................................................................................................................................... 11
3.2.3
Publishing location sends message ........................................................................................................ 11
3.2.4
Subscribe Using QR ............................................................................................................................. 11
3.2.5
Location Selection From List ................................................................................................................. 11
3.2.6
Manual Detach from Location ............................................................................................................... 12
3.2.7
Querying a location’s recent messages .................................................................................................. 12
3.3
User Interface ........................................................................................................................................... 12
3.3.1
Main Window ...................................................................................................................................... 12
3.3.2
Manual Location Selection .................................................................................................................... 13
3.3.3
Location messages and configuration .................................................................................................... 14
3.3.4
Application Configurations .................................................................................................................... 15
3.4
Synchronization and Protection Mechanisms.................................................................................................. 16
3.5
Setup ....................................................................................................................................................... 17
Physical Architecture ...................................................................................................................... 17
References – to external papers/packages ........................................................................................ 17
Revision History ............................................................................................................................ 17
High-Level Design Document
Introduction
1.1 Overview
This document introduces the design specifications for both the client (phone app) and server side of
EarCast, a mobile application aiming to bring the text of PA messages to the hearing impaired.
First, some terminology: a “publishing location” is a logical entity comprised of two parts. The first is
its physical location, an area probably best defined by center coordinate and radius. The second is its
PA messages.
Due to technical issues (see Constraints section) the entering of a publishing location will not be
absolutely transparent to the user. But once a publishing location is entered and until it is left (be it
manually or by location services) a textual version of messages heard over the PA will be sent to the
user’s phone as pop-ups in the app itself or as Toast messages.
Of course, as a slight edge over the regular, hearing crowd present, the app can use what is already
in place to allow added features over this intuitive and passive interface: filters, the ability to query
past messages, and accessing messages of remote locations.
1.2 Design Goals and Non-Goals
1.2.1 Goals
Providing location-based textual version of PA announcements in public spaces for the hearingimpaired.
1. The identification of a publishing location will be available to the user in one of four ways:
1. When the app is in the foreground it will test the user’s current location against nearby
publishing locations, and if it has entered one, it will attach itself to it. When it exists the
radius of the location it will detach itself from it.
2. The user can select a location from an available list (filtered down by general area). Users
can also manually detach themselves from a location that was subscribed by manual
selection.
3. A list of permanent locations will attach immediately when the app is turned on.
4. The subscription can be performed by photo recognition of a matrix barcode (we will use
QR Code) which the locations can display in a visible place. This will both serve to raise
awareness of the service, and can be useful for locations who do not wish to publish by
location-recognition (for example, a small public place located inside a larger mall or
public place).
2. Receiving PA messages will by default be by push notifications, which will send a Toast
message. This means messages from the attached locations can be received even when the
app is in the background.
3. The user will be able to query previous messages in any of the connected locations.
4. In locations that provide this information, the user will be able to filter messages by their
type, thus ignoring the frequent regular messages (such as “Mind the gap”) and be informed
High-Level Design Document
only when something is out of the ordinary. The filter will happen in the server, and the
desired filter level will be given to the attach. Four such levels exist:
1. FirstTime (e.g. “Mind your bags” or “Stay behind the yellow line”)
2. General (e.g. “The train entering track 2 will stop in Tel-Aviv University, Herzelia, …”)
3. ChangeNotice
4. Urgent
5. The user will be able to block messages from any connected location. This block will be
enforced by the app itself, which will not consider the location in testing for entering location,
and not allow to connect to it manually.
The application will include a “publisher” side as well, meant for allowing locations to send their
announcements.
1. The server-side will provide a well-known interface (preferably WebService) to facilitate the
sending of messages.
2. We will also provide a small generic client application that includes templates, to encourage
publishers to interface with us.
1.2.2 Non-Goals
The app will not update the user’s location when it is running in the background (see Assumptions
and Constraints section) which means the location identification will only be functional when EarCast
is the foreground application.
1.3 Dependencies
1.3.1 Feature Dependencies
1.4 Audience
The main audience of the app is the hearing-impaired population that is making use of public
transportation and other public services.
That said, it is fair to assume the app would be of use to other populations outside its main target
audience, such as the attendees of places loud enough that PA announcements are not audible, and
people who wish to query the PA history (described in 1.2.1.3) before arriving at a location, for
example, while making a train exchange that is a close call, checking before the train has reached
the platform that the departing train has not changed tracks.
High-Level Design Document
1.5 Assumptions and Design Constraints List
The main assumption that we must take on is that the user will have the app running constantly in
the foreground if he is moving from place to place in a way that might result subscribe/unsubscribe
to a publishing location. This is due to the existing constraint which prohibits 3rd party code from
running in the background. We hope to introduce this feature as soon as the phone permits it.
Another assumption has to do with integration with publishing locations. For the sake of the demo
we shall provide mock publishing locations, in hopes that actual ones will chose to offer this
important service.
1.6 Issues List
The lifetime of the application is problematic, as tapping a toast message currently re-launches the application.
1.7 To-do List + Expected time-tables
High-Level Design Document
2 Logical Architecture
2.1 Application Context
GeoCoor
dinateW
atcher
Phone’s
Camera
App Server
The Application
Location
Decider
Configs
Editors
pull services:
select
location,
message
query
internet
Location
subscriber/
unsubscriber
Arriving
message
pusher
Location
manager
Recent
history DB
internet
Publisher
UI
The Phone
2.1.1 The Application
2.1.1.1 GeoDecider
Based on the GeoCoordinateWatcher’s change event. Whenever the user moves, the Location
Decider needs to determine whether a location has been entered or exited, and call attach or detach
accordingly against the server. It will also determine when it nearing the edge of the radius of
locations it has in its database, and call again for more locations.
2.1.1.2 Configs Editor
Two sets of configurations are available and need managing (saving, loading and applying):
application wide settings which include the minimal message level for any location, locations to be
made permanent and blocked locations, and the user that is logged in; and specific location settings
which include a specific message level, the ability to save a location as permanent or remove its
permanent status or block it.
2.1.1.3 Pull Services
Pull services gives the user an active interface to query old messages from the server and actively
select a location. Selecting a location may be done from a list of nearby locations (about 100 nearest
locations) or on a map, by searching for a location by name, or by activating the camera to capture
a matrix barcode.
High-Level Design Document
2.1.2 App Server
2.1.2.1 Location Subscriber/Unsubscriber
Offers the application the ability to attach and detatch itself from publishing locations. It is also
responsible for checking whether a location is blocked for a certain user, including temporary blocks
(the user will try to attach itself, it is the subscriber’s responsibility to only allow this when the block
is removed – possibly never.)
2.1.2.2 Location Manager
Handles the publishing locations, and allows both other components in the server as well as the user
application (via Webservice) to query for locations by different means – ID, location, radius from a
location. This is very tightly coupled with the recent history DB, and provides the outward interface
for querying it.
2.1.2.3 Arriving Message Pusher
Responsible for receiving the messages arriving from the publishing locations by webservice and
pushing them to the subscribed clients.
2.1.2.4 Recent History Database
Holds the recent messages for all. The user application will query it through the Location Manager.
2.1.3 Publisher UI
Demo user interface for publishing against the server – SOAP client and basic user interface.
High-Level Design Document
3 Design
3.1 Classes
3.1.1 Class Diagram
High-Level Design Document
High-Level Design Document
High-Level Design Document
3.1.2 Class Details
3.1.2.1 PublisherWebService
The web service to which the publishing locations send the notifications. The webservice interface
includes the following arguments: Location ID (a string identifier), the message (a string) and
message type (see list 1.2.1.4). For each call to the webservice, the subscriptions table in the
database will be queried to get the users to which the message needs to be sent – and send the
toast notification. The message will then be stored in the messages table so it can be queried in
message history.
3.1.2.2 UsersLocationSubscriber
An interface to serve the phone’s requests to connect to locations. It contains five main public
methods that handle its exposed functionality:
1. Announce User: Sends to the server the current PN Channel URL for the user.
2. Attach: Subscribes a user to a location at the requested alert level.
3. Update: Changes the alert level for a user’s subscription.
4. Detach: Unsubscribes a user to a location’s messages. This will remove the user-location pair
from the UsersDB table.
5. Detach All: Unsubscribes the user from all the locations to which it is subscribed by removing
all the user’s user-location pairs.
3.1.2.3 LocationsManager
Allows the phone access to the locations table for the locations database and to the recent messages
table to access each location’s saved messages. It has three main interface methods:
1. Get (around a coordinate): This method is meant to service the phone’s location decider,
which means it needs to return a geographic radius of locations around the user’s current
location. In order to make the phone’s work in deciding easier, this method will aim to return
approx. 100 locations, and the radius around the user which was used to make the cut. It will
attempt to select a radius such that it will provide the amount of locations closest to 100.
2. Search Locations: This method will search all locations in the DB for locations whose name
matches the given query string, and return any matches to the user.
3. Get Message History: This method will service the user’s pull services. Given a location ID it
will return the last 10min’s messages.
3.1.2.4 LocationData list
A list of LocationData instances, which are populated by calling LocationsManager::get(). It is used
by the GeoDecider to be crossed with the current location. Each element has the following data:
1. CenterPoint (a coordinate)
2. Radius (in meters)
3. Is Geo-Based, which distinguishes permanent locations and locations selected manually from
locations that were entered and should be exited according to the user’s location.
High-Level Design Document
3.1.2.5 GeoDecider
The class which contains the callback registered to the location change event. On each change of
location it can cross the new location with the list of LocationData objects to determine whether it
needs to attach to any of them, detach from any of them, or call the server for more locations using
LocationsManager::get(). It will skip locations that are not geo-based.
3.1.2.6 QRCodeAnalyzer
Spawned when the menu option to select a location by its QRCode is selected. It will launch a photo
chooser and wait for it to return with a picture, which it will analyze. It will then try to attach using
the analysis result as a location ID, and notify of an error if it is an invalid location ID (or if the
picture doesn’t contain a valid QR code).
3.2 Flows
3.2.1 On Init
The user turns on the application. The main window is opened and sends a request to the Locations
Manager with the current location, which will be answered with the approximately 100 nearest
locations (a radius which includes ~100 locations) which are then processed into the LocationData
list, along with the permanent locations which are saved in the App Config. Permanet locations will
immediately be attached against the UsersLocationSubscriber.
The GeoDecider is initialized and subscribes to the location change event of GeoCoordinateWatcher.
It will also take the current location and check it against the LocationData list as it will do
whenever the event calls the callback. If it recognizes a location as being entered or left, it will call
attach or detach against the server’s UsersLocationSubscriber. If responding to an event, it will
also check whether the user is nearing the bounds of the radius of locations provided, at which case
it will again ask the LocationsManager for locations around the current location.
3.2.2 On Shutdown
All locations are detached from the UsersLocationSubscriber – unlike going to background we do
not want toasts to continue arriving.
3.2.3 Publishing location sends message
The publishing locations Publisher UI or any other SOAP client sends an XML with the message to
the PublisherWebService. The publisher will spawn a PNSender for the message, which will query
the UsersDB for the users attached to this location. The UsersDB will use the PreferencesFilter to
determine which users should not get the message – and those that should will get a toast PN sent.
3.2.4 Subscribe Using QR
Selecting the option in the main menu will create a QRCodeAnalyzer object which will create a
photo chooser and wait for the picture to return. Once a picture is received, it will be parsed and if
containing a valid location ID attach will be called from the UsersLocationSubscriber.
3.2.5 Location Selection From List
Selecting the option from the main menu will call the server’s LocationsManager get_all(). The
returning list of locations will be displayed in one of several ways (filterable list or map) to the user,
and once the user has selected a location, attach will be called from the UsersLocationSubscriber.
High-Level Design Document
3.2.6 Manual Detach from Location
If a user has selected the option from the main window, detach() will be called directly from
UsersLocationSubscriber.
3.2.7 Querying a location’s recent messages
The user selects the location’s details (configuration window) from the main window, and there
selects “Message History”. This will call LocationManager’s get_msg_history for the location, and
the list of messages (approx. last 10 minutes) will be returned to the phone and displayed to the
user.
3.3 User Interface
3.3.1 Main Window
High-Level Design Document
3.3.2 Manual Location Selection
High-Level Design Document
3.3.3 Location messages and configuration
High-Level Design Document
3.3.4 Application Configurations
High-Level Design Document
3.3.5 Publisher Client
3.4 Synchronization and Protection Mechanisms
Most synchronization issues are handled by the transactionality of the database (Azure SQL).
High-Level Design Document
3.5 Setup
Deploying a XAP to the phone.
4 Physical Architecture
All aforementioned Web Services are hosted on Azure cloud at http://earcast.cloudapp.net/
The publisher application can be run from any computer that has .NET4 installed.
5 References – to external papers/packages
QR Code library that was used: ThoughtWorks.QRCode.Codec (can be found on CodeProject). It was
ported to the compact framework by us.
6 Revision History
Date
Author
Description (include reviews with reviewer lists)
14.12
Hila Peleg &
First draft
Amit Perelstein
3.3
Hila Peleg
15.3
Hila Peleg &
Screenshots and class diagrams
Amit Perelstein
Trimming out features which were not implemented.