Preliminary Technical
Manual
Crank App System
This document details the preliminary design
aspects of the Crank app and associated system.
This encompasses Android, iOS and server design,
component overviews of the architecture and use
case descriptions and diagrams.
CSCI321 Group KW1A: Riley Adam, Callum
Thomson, Garrett Frost & James Simpson
6/6/2013
Preliminary Technical Manual
Crank App
Contents
Architecture Design ........................................................................................................................ 2
Overview......................................................................................................................................... 2
Front-end........................................................................................................................................ 2
Handset ...................................................................................................................................... 2
Webpage .................................................................................................................................... 3
Back-end ......................................................................................................................................... 3
Database ......................................................................................................................................... 4
Use Cases ............................................................................................................................................. 5
Use Case Diagrams ...................................................................................................................... 5
Use Case Descriptions ............................................................................................................... 8
Preliminary Android Design ..................................................................................................... 27
Preliminary iOS Design ............................................................................................................... 29
Preliminary Server Design ........................................................................................................ 30
Server classes ............................................................................................................................ 30
Potential Data Classes ............................................................................................................ 32
The Communication ..................................................................................................................... 33
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
Architecture Design
Overview
The overall architecture of the Crank system is of the Model-View-Controller
design. The front end is the view and is dedicated to displaying the data, the
back-end server is the controller and is responsible for all computations and the
database is the Model where all the persistent data is stored.
The back-end was chosen to do the computation to prevent duplication of code
for handset implementation as well as naturally having more processing power
than a handset and battery life is not an issue.
Front-end
Handset
The handset app will be developed for Android and iOS devices. The overall
design and look and feel of the app on the different platforms will differ
according to development and UI standards. However both platforms will offer
the same functionality. The app allows a user to track their rides, view ride
details and allow basic account management.
The handset design also follows Model-View-Controller architecture.
The Android app will be developed using the Android SDK 4.2 with Google APIs.
The language primarily used will be Java and Google’s Android variation of Java.
The minimum version of Android that the app will run on is 3.2 (Honeycomb)
and employs the Google Services and Google Maps SDKs and APIs to display map
information.
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
The iOS app will be developed using the iOS SDK 6.0 with Cocoa Touch. The
language primarily used will be Objective C. The minimum version of iOS that the
app will operate on is 6.0 and will employ the Google Maps SDK for iOS to display
map information.
Both handsets will use the built in GPS receiver and location services to record
GPX files while a user is riding. Upon ride completion the app will make a TCP
socket connection to the back-end server to upload this file for analysis and
storage. The app will also make socket connections to the back-end to access
information from the database to display. The handset will use whatever
network connection it can find be it mobile network, Wi-Fi or tethered.
The app will also utilize the handset’s local storage to store the user’s profile
information and temporarily store GPX files that are yet to be uploaded.
Webpage
The webpage gives the full analysis of the user’s ride statistics, segments, rides
and achievements. It acts as the hub to the Crank system experience and offers
all the same functionality that the handset app does (excluding the GPS tracking).
On top of this the website allows a user to upload GPX files of existing rides so
they can be added to their profile and analysed. These GPX files can come from
any GPS tracking device such as another app or a Garmin device.
There is also an administration aspect to the webpage where an admin can login
to the system and perform tasks such as user account maintenance, restoration
of system and segment editing.
It interacts with the back-end to store and retrieve data from the database as
needed. In the event of a user uploading a GPX file, the back-end receives this file
and parses the contents to analyse ride statistics. The back-end will then save
this information to the database.
When a page on the website first loads, it is loaded with some initial data using
php. When more data is requested to be viewed (e.g.: when viewing a different
ride) JavaScript sockets are employed to access the requested information. This
means there is no page refresh needed effectively making each page a mini web
app.
The website also uses the Google maps API to display interactive map fragments
of rides and segments. The statistical graphs will be drawn client-side with
JavaScript onto HTML5 Canvases. This allows graphs to be superimposed over
one another.
Back-end
The back end is a threaded Java application running on a Virtual Private Server.
It uses socket connections to connect to the front-end creating a new thread for
every new connection. The back end performs as a middleman between the front
end and the database. It also takes in GPX files and parses them to calculate ride
statistics.
The back-end connects to the front-end (both website and handset) using TCP
socket connections. A communication protocol will be defined for common
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
requests such as storing, retrieving and parsing information. Once a socket
connection is created a new thread is spawned to handle the connection and
communication with the front-end. The back-end server will then perform an
action based on the communication from the front-end.
The back-end server will be split into several dedicated classes to handle the
various requests.
Database
The database is hand written SQL and runs on our VPS as a MySQL Server. The
relational tables store data on every facet of our system. The only thing not
stored directly in the database is pictures. Pictures are stored as jpg mages in our
file system; the database does however store a string containing the directory
path and filename of the image. The database design avoids data redundancy
where possible while maintaining an easy to query architecture. Data integrity is
at the forefront of the design utilizing numerous constraints and correct data
types to ensure the validity of data.
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Use Cases
Use Case Diagrams
User
User Options(FUF8)
Login (FUF1)
Edit Prof ile(FUF7)
Register (FUF2)
Add Friends(FUF9)
<<include>>
<<include>>
<<include>>
<<include>>
<<include>>
<<include>>
<<include>>
<<include>>
<<include>>
View previous rides (FUF5)
View profile (FUF4)
View local rides and segments
(FUF6)
View Friend Prof iles(FUF10)
Logout (FUF3)
Social Media Integration(FUF11)
User login (BUF1)
User Prof ile Updating(BUF3)
<<include>>
Store data (C2)
Multiple client communication (C3)
<<extend>>
Front-end communication (C1)
<<extend>>
<<extend>>
Retrieve data (C2)
User logout(BUF2)
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
User
Track Ride(AF1)
Upload Ride(AF2)
Store gpx File on Handset (AF3)
Maintain Login (AF4)
Store User Inf ormation (AF5)
<<include>>
<<include>>
Display Ongoing Ride Inf ormation
(AF6)
View Map while Riding (AF8) Continuation of App in Background
(AF7)
Voice Notif ications (AF9)
Listen to Music on Ride (AF11)
Take Photos While on Ride (AF10)
Store Data (C2)
Retriev e Data (C2)
<<extend>>
<<extend>>
Multiple Client Communication(C3)
<<extend>>
Front End Communication(C1)
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
User
Edit Profile (WPF1)
<<extend>>
Edit Profile (FUF7)
Create Segment (WPF3)
Upload Existing GPX File (WPF2)
Interact With Graphs (WPF4)
Receive friend request (BUF5)
Send emails (BUF4)
<<include>>
<<include>>
<<include>>
<<include>>
Store Data (C2)
<<extend>>
Multiple Client Communication(C3)
<<extend>>
Front End Communication(C1)
<<extend>>
Retreive Data (C2)
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
Restore System From Backup
(AD1)
Edit Users (AD2)
User
Admin
Delete Users (AD3)
Edit Segment (AD4)
Edit Achievement (AD6)
Create Achievement (AD5)
Delete Achievement (AD7)
Use Case Descriptions
USE CASE: Login
REQUIREMENT ID: FUF1
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank
SUCCESS END CONDITIONS: A User successfully logs into the system
FAILED END CONDITIONS: A User is denied access to the system
TRIGGER: None
BASIC FLOW:
1. A User is greeted with the login screen
2. The User inputs their email and password
3. The system verifies their credentials with those on the database
4. The system logs the User in
ALTERNATE FLOW:
4.1
The system alerts the User that the email – password combination is
incorrect.
4.1.1 The system presents the User the login screen again
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Register
REQUIREMENT ID: FUF2
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User must not have a pre-existing account with Crank
SUCCESS END CONDITIONS: A User successfully registers with the system
FAILED END CONDITIONS: A User is cannot register with the system
TRIGGER: None
BASIC FLOW:
1. A User is greeted with the login screen
2. The User selects the option to register
3. The User enters their personal details along with email and password
4. The system checks their credentials with those on the database for any duplicates
5. The system alerts the User of a successful registration and logs the User in
ALTERNATE FLOW:
4.1
The system alerts the User that the email is already registered
4.1.1 The system presents the User the register screen again
USE CASE: Logout
REQUIREMENT ID: FUF3
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User must be logged in
SUCCESS END CONDITIONS: A User successfully logs off the system
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. A User selects the logoff option from within the application
2. The system logs the user off and returns them to the login screen/page
ALTERNATE FLOW:
None
USE CASE: View Profile
REQUIREMENT ID: FUF4
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User is logged in
SUCCESS END CONDITIONS: A User successfully views their profile and account details
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. A User selects the view profile option from within the application
2. The system presents the User with a screen/page detailing the user’s profile, stats
and account information
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: View Previous Rides
REQUIREMENT ID: FUF5
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User is logged in and has completed at least one ride with the app.
SUCCESS END CONDITIONS: A User successfully views their previous rides
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. A User selects the view rides option from within the application
2. The system presents the User with a screen/page detailing the user’s rides with their
basic statistics
3. A User selects a ride to view in more detail
4. The system presents another screen/page with the increased detail on the ride
including map, average speed and other ride statistics
ALTERNATE FLOW:
None
USE CASE: View Local Rides and Segments
REQUIREMENT ID: FUF6
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User is logged in and there have been local segments posted
SUCCESS END CONDITIONS: A User successfully views the local segments and rides
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. A User selects the segment explorer option from within the application
2. The system presents the User with a screen/page detailing the local rides and
segments of the area with their basic statistics.
3. A User selects a segment to view in more detail
4. The system presents another screen/page with the increased detail on the segment
including map, leaderboard, User’s position and other segment statistics
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Edit Profile
REQUIREMENT ID: FUF7
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank and is logged in
SUCCESS END CONDITIONS: The user has successfully edited their profile
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. A user selects the edit profile option from within the application
2. The application presents the user with an editable version of their profile
3. The user edits their desired fields
4. User hits done
ALTERNATE FLOW:
None
USE CASE: User Options
REQUIREMENT ID: FUF8
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank and is logged in
SUCCESS END CONDITIONS: A user successfully edits their options
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The user selects the options menu item from with the application
2. The application presents the user with the options screen
3. The user changes the desired options
4. The user hits done
ALTERNATE FLOW:
None
USE CASE: Add friends
REQUIREMENT ID: FUF9
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank and is logged in
SUCCESS END CONDITIONS: A user adds a friend to their friends list
FAILED END CONDITIONS: The friend request is denied by the other person
TRIGGER: None
BASIC FLOW:
1. The user selects the add friend option from within the application
2. The user searches for their friend by their first and last name
3. The user finds the friend and sends a friend request
4. The friend accepts the friend request
5. The friend is added to the users friend list
ALTERNATE FLOW:
4.1 The friend denies the friend request
4.1.1 The friend is not added to the user’s friend list
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: View friend profiles
REQUIREMENT ID: FUF10
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank and has at least one friend
SUCCESS END CONDITIONS: The user views a friend’s profile
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The user selects the view friends list option
2. The user is presented with a list of their friends
3. The user selects a friend they wish to view the profile of
4. The user is presented with the profile of the desired friend
ALTERNATE FLOW:
None
USE CASE: Social media integration
REQUIREMENT ID: FUF11
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User is logged in, has a Facebook and/or Twitter account, has the social
media option turned on and has completed at least one ride
SUCCESS END CONDITIONS: A rides details are posted to Facebook or Twitter
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The user completes a ride
2. The application automatically posts certain details to that users Facebook and/or
Twitter account
ALTERNATE FLOW:
None
USE CASE: Track ride
REQUIREMENT ID: AF1
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank and is logged in
SUCCESS END CONDITIONS: A ride is tracked and a GPX file is created
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. A user selects RIDE from within the application
2. The user takes a ride while the GPS on their phone tracks and records all the
relevant information and stores it as a GPX file
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Upload ride
REQUIREMENT ID: AF2
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A User has a pre-existing account with Crank and is logged in
SUCCESS END CONDITIONS: A user successfully uploads a ride to the server
FAILED END CONDITIONS: A ride is not uploaded to the server
TRIGGER: None
BASIC FLOW:
1. A user completes a ride
2. The GPX file is created
3. The GPX file is automatically uploaded to the server
4. The user is alerted to the success of the upload
ALTERNATE FLOW:
3.1 The GPX file cannot be uploaded to the server due to limited internet access
3.1.1 The GPX file is stored on the users phone to be automatically uploaded at a
later date
3.1.2 The user is alerted to the inability to upload the GPX file and that it will be
uploaded when internet access is restored
3.1.3 The GPX file is uploaded when internet access is returned
USE CASE: Store gpx File on Handset
REQUIREMENT ID: AF3
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: A user is logged in and is currently riding or has finished a ride
SUCCESS END CONDITIONS: A gpx file with ride information is stored on the
handset
FAILED END CONDITIONS: The gpx file cannot be stored and ride information is lost
TRIGGER: The user has started a new ride
BASIC FLOW:
1.
2.
3.
4.
User starts a new ride
The app gets information as user is riding
Ride information is logged in a new gpx file
At the end of the ride the gpx file is saved and completed
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Maintain Login
REQUIREMENT ID: AF4
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User has logged in
SUCCESS END CONDITIONS: User is logged in to the app on every start-up
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The app stores the users encrypted information on the handset
ALTERNATE FLOW:
None
USE CASE: Store User Information
REQUIREMENT ID: AF5
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User has a valid account and is logged in
SUCCESS END CONDITIONS: User information is stored on the handset
FAILED END CONDITIONS: User information cannot be stored on the handset
TRIGGER: A user opens the app
BASIC FLOW:
1. The user opens the app and is logged in
2. The app checks the current stored information with the database
3. Any new information is downloaded
ALTERNATE FLOW:
None
USE CASE: Display ongoing ride information
REQUIREMENT ID: AF6
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: The user is currently riding
SUCCESS END CONDITIONS: Ride information is being displayed to user in real time
FAILED END CONDITIONS: None
TRIGGER: User has started a ride
BASIC FLOW:
1. User starts a new ride
2. App obtains information from GPS network
3. App uses statistics to calculate ride details such as speed and distance travelled
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Continuation of App in Background
REQUIREMENT ID: AF7
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: App is recording a ride
SUCCESS END CONDITIONS: App continues running as a background process in the
phone
FAILED END CONDITIONS: None
TRIGGER: The app is sent to the background
BASIC FLOW:
1. User exits the app while recording a ride
2. App window disappears but app continues running as a background process
ALTERNATE FLOW:
None
USE CASE: View Map while Riding
REQUIREMENT ID: AF8
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User is currently recording a ride
SUCCESS END CONDITIONS: User can see a map on screen and see their progress in
real time
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1.
2.
3.
4.
User presses the map view button while undertaking a ride
The app displays a Google maps segment
The app gets the user’s coordinates from the GPS network
The app displays the user’s current position on the map and updates at equal
intervals
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Voice Notifications
REQUIREMENT ID: AF9
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: The User is about to start or finish a ride and has the voice notifications
setting turned on.
SUCCESS END CONDITIONS: The user hears the notification
FAILED END CONDITIONS: The user doesn’t hear the notification
TRIGGER: Starting ride, ending ride, receiving achievement
BASIC FLOW:
1. The system plays voice notification
2. The user hears notification
3. The user dismissed notification
ALTERNATE FLOW:
2.2 The User doesn’t hear the notification
USE CASE: Take Photos While on Ride
REQUIREMENT ID: AF10
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: Mobile has a camera built in and the app is recording a ride
SUCCESS END CONDITIONS: The User successfully takes a photo
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The User presses camera button on app’s ride screen
2. User then points camera and takes photo as per usual
3. Photo is saved as part of the ride
ALTERNATE FLOW:
None
USE CASE: Listen to Music on Ride
REQUIREMENT ID: AF11
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User has music on mobile device
SUCCESS END CONDITIONS: User listens to music.
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The User presses music icon on app’s ride screen
2. User chooses what song to play
3. App plays song and returns user to ride screen
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
USE CASE: Edit Profile
REQUIREMENT ID: WPF1
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User already has an account
SUCCESS END CONDITIONS: The User changes their desired profile information
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. User Logs in
2. User goes to edit profile
3. User edits what information they want to change
4. User submits changes
5. User Logs out
ALTERNATE FLOW:
None
USE CASE: Upload Existing GPS File
REQUIREMENT ID: WPF2
PRIMARY ACTOR: A User
SECONDARY ACTORS: None
PRECONDITIONS: User has an account and a GPX file ready to upload
SUCCESS END CONDITIONS: The User successfully logs a ride.
FAILED END CONDITIONS: The User doesn’t log a ride
TRIGGER: None
BASIC FLOW:
1. User logs in
2. User clicks upload GPX file
3. User browses for GPX file
4. User uploads GPX file
5. Server authenticates it’s a real GPX file
6. The ride is recorded along with Stats, Map, Achievements etc.
7. User views ride log
8. User logs out.
ALTERNATE FLOW:
5.1 It’s not a real GPX file
5.1.1 User is notified the ride was not logged
5.1.2 User logs out or attempts again
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Crank App
USE CASE: Create Segment
REQUIREMENT ID: WPF3
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User has been on a ride
SUCCESS END CONDITIONS: User creates a Segment for others to see and challenge them
with based on their completed rides
FAILED END CONDITIONS: User doesn’t create a segment
TRIGGER: None
BASIC FLOW:
1. User logs in
2. User selects ride
3. User selects create segment
4. User selects the part of the ride that should be a segment
5. User creates a segment
6. User logs out
ALTERNATE FLOW:
None
USE CASE: Interact With Graphs
REQUIREMENT ID: WPF4
PRIMARY ACTOR: User
SECONDARY ACTORS: None
PRECONDITIONS: User has a ride to view
SUCCESS END CONDITIONS: The user gets more accurate/ helpful information out of the
data
FAILED END CONDITIONS: None
TRIGGER: User wants more detailed feed back
BASIC FLOW:
1. User logs on
2. User selects a ride
3. User tries different combinations of options to view data in different ways on
different graphs
4. User logs off
ALTERNATE FLOW:
None
USE CASE: Front End Communication
REQUIREMENT ID: C1
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: There is a connection between the front-end and back-end
SUCCESS END CONDITIONS: The system successfully transfers data between the front-end
and back-end
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. Data gets sent between the front-end and back-end
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Store Data
REQUIREMENT ID: C2
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: None
SUCCESS END CONDITIONS: The system successfully stores data in the database
FAILED END CONDITIONS: None
TRIGGER: The front-end has sent a request to store data
BASIC FLOW:
1. The back-end receives the data from the front-end to store in the database
2. The back-end writes the data to the database
3. The back-end notifies the front-end of the successful storage
ALTERNATE FLOW:
None
USE CASE: Retrieve Data
REQUIREMENT ID: C2
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: None
SUCCESS END CONDITIONS: The system successfully retrieves data from the database
FAILED END CONDITIONS: None
TRIGGER: The front-end has sent a request to receive data
BASIC FLOW:
1. The back-end reads the requested data from the database
2. The back-end sends the data to the front-end
ALTERNATE FLOW:
None
USE CASE: Multiple Client Communication
REQUIREMENT ID: C3
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: There is a connection between the front-end and back-end
SUCCESS END CONDITIONS: The system successfully handles the data transfers between the
front-end and back-end for multiple simultaneous clients
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. Data gets sent between the front-end and back-end to different clients at the same
time
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: User Login
REQUIREMENT ID: BUF1
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: A User has a pre-existing account with Crank
SUCCESS END CONDITIONS: The system successfully logs the User in
FAILED END CONDITIONS: The system denies access to the User
TRIGGER: A User has attempted to login
BASIC FLOW:
1. The back-end receives the User’s credentials from the front-end
2. The back-end verifies the User’s credentials with those on the database
3. The back-end sends to the front-end a notification that the credentials are correct
ALTERNATE FLOW:
2.1
The back-end sends to the front-end a notification that the credentials are
incorrect
USE CASE: User Logout
REQUIREMENT ID: BUF2
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: A User must be logged in
SUCCESS END CONDITIONS: The system logs the User off
FAILED END CONDITIONS: None
TRIGGER: A User has selected the log out option
BASIC FLOW:
1. The back-end is notified by the front-end that the User wishes to log off
2. The back-end severs the connection with the front-end
3. The back-end removes log in data
ALTERNATE FLOW:
None
USE CASE: Send Emails
REQUIREMENT ID: BUF4
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: A User has a pre-existing account with Crank and has opted to receive
emails
SUCCESS END CONDITIONS: The system successfully sends the User an email
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The system compiles and sends an email to the User
ALTERNATE FLOW:
None
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Receive Friend Request
REQUIREMENT ID: BUF5
PRIMARY ACTOR: None
SECONDARY ACTORS: User
PRECONDITIONS: A User has sent another User a friend request
SUCCESS END CONDITIONS: The system successfully sends the user a notification of the
friend request
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. The system alerts the User of the friend request when the User next logs on.
ALTERNATE FLOW:
None
USE CASE: Restore System From Backup
REQUIREMENT ID: AD1
PRIMARY ACTOR: Administrator
SECONDARY ACTORS: None
PRECONDITIONS: The system has previously been backed up
SUCCESS END CONDITIONS: The system is restored to a previous working copy
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
5. The Admin logs on
6. The admin selects restore system
7. Admin selects the date and time of the backup to restore from
8. The system gets restored
9. The admin logs off
ALTERNATE FLOW:
None
USE CASE: Edit Users
REQUIREMENT ID: AD2
PRIMARY ACTOR: Administrator
SECONDARY ACTORS: User
PRECONDITIONS: A User has a pre-existing account with Crank
SUCCESS END CONDITIONS: A User‘s account is successfully edited
FAILED END CONDITIONS: No User’s account is edited
TRIGGER: None
BASIC FLOW:
1. An admin logs in
2. Admin chooses to edit a user
3. Admin enters users ID
4. Admin edits user account
5. Admin saves changes
6. Admin logs out
ALTERNATE FLOW:
4.1 User ID doesn’t exit
4.1.1 Admin logs out
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Delete Users
REQUIREMENT ID: AD2
PRIMARY ACTOR: Administrator
SECONDARY ACTORS: User
PRECONDITIONS: A User has a pre-existing account with Crank
SUCCESS END CONDITIONS: A User‘s account is successfully deleted
FAILED END CONDITIONS: No User’s account is deleted
TRIGGER: None
BASIC FLOW:
1. An admin logs in
2. Admin chooses to edit a user
3. Admin enters users ID
4. Admin chooses to delete the user
5. Admin confirms deletion
6. Admin logs out
ALTERNATE FLOW:
4.1 User ID doesn’t exit
4.1.1 Admin logs out
USE CASE: Delete segment
REQUIREMENT ID: AD3
PRIMARY ACTOR: Admin
SECONDARY ACTORS: None
PRECONDITIONS: Segment exists to delete
SUCCESS END CONDITIONS: Segment is deleted from the system
FAILED END CONDITIONS: Segment is not deleted from the system
TRIGGER: None
BASIC FLOW:
1. Admin logs in to the system
2. Admin searches for segment to be deleted
3. Admin selects segment and hits delete
4. System reports back on deleting of the segment
ALTERNATE FLOW:
3.1 Segment is not found
3.1.1 System reports back on segment not being found and no changes are made
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
USE CASE: Restore System From Backup
REQUIREMENT ID: AD1
PRIMARY ACTOR: Administrator
SECONDARY ACTORS: None
PRECONDITIONS: The system has previously been backed up
SUCCESS END CONDITIONS: The system is restored to a previous working copy
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
10. The Admin logs on
11. The admin selects restore system
12. Admin selects the date and time of the backup to restore from
13. The system gets restored
14. The admin logs off
ALTERNATE FLOW:
None
USE CASE: Edit Users
REQUIREMENT ID: AD2
PRIMARY ACTOR: Administrator
SECONDARY ACTORS: User
PRECONDITIONS: A User has a pre-existing account with Crank
SUCCESS END CONDITIONS: A User‘s account is successfully edited
FAILED END CONDITIONS: No User’s account is edited
TRIGGER: None
BASIC FLOW:
7. An admin logs in
8. Admin chooses to edit a user
9. Admin enters users ID
10. Admin edits user account
11. Admin saves changes
12. Admin logs out
ALTERNATE FLOW:
4.1 User ID doesn’t exit
4.1.1 Admin logs out
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Crank App
USE CASE: Delete Users
REQUIREMENT ID: AD2
PRIMARY ACTOR: Administrator
SECONDARY ACTORS: User
PRECONDITIONS: A User has a pre-existing account with Crank
SUCCESS END CONDITIONS: A User‘s account is successfully deleted
FAILED END CONDITIONS: No User’s account is deleted
TRIGGER: None
BASIC FLOW:
7. An admin logs in
8. Admin chooses to edit a user
9. Admin enters users ID
10. Admin chooses to delete the user
11. Admin confirms deletion
12. Admin logs out
ALTERNATE FLOW:
4.1 User ID doesn’t exit
4.1.1 Admin logs out
USE CASE: Edit Segment
REQUIREMENT ID: AD3
PRIMARY ACTOR: Admin
SECONDARY ACTORS: None
PRECONDITIONS: Segment exists to edit
SUCCESS END CONDITIONS: A segment is successfully edited
FAILED END CONDITIONS: Segment is not edited
TRIGGER: None
BASIC FLOW:
1. Admin logs in to the system
2. Admin searches for the segment to edited
3. Admin selects the segment and edits it appropriately
4. System reports back on editing of the segment
ALTERNATE FLOW:
3.1 Segment is not found
3.1.1 System reports back on segment not being found and no changes are made
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Create Achievement
REQUIREMENT ID: AD4
PRIMARY ACTOR: Admin
SECONDARY ACTORS: None
PRECONDITIONS: None
SUCCESS END CONDITIONS: An achievement is successfully added to the system
FAILED END CONDITIONS: None
TRIGGER: None
BASIC FLOW:
1. Admin logs in to the system
2. Admin selects the add achievement option from the menu
3. Admin adds in the conditions for the achievement
4. Admin uploads an image file to accompany the achievement
5. Admin hits add achievement to add it to the system
6. System reports back on adding of achievement
ALTERNATE FLOW:
None
USE CASE: Edit Achievement
REQUIREMENT ID: AD4
PRIMARY ACTOR: Admin
SECONDARY ACTORS: None
PRECONDITIONS: Achievement exists to edit
SUCCESS END CONDITIONS: An achievement is successfully edited
FAILED END CONDITIONS: Achievement is not edited
TRIGGER: None
BASIC FLOW:
1. Admin logs in to the system
2. Admin searches for achievement
3. Admin edits achievement appropriately and hits save
4. System reports back on editing the achievement
ALTERNATE FLOW:
3.1 Achievement is not found
3.1.1 System reports back on achievement not being found and no changes are
made
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
USE CASE: Delete Achievement
REQUIREMENT ID: AD4
PRIMARY ACTOR: Admin
SECONDARY ACTORS: None
PRECONDITIONS: There is an achievement to delete
SUCCESS END CONDITIONS: Achievement is deleted
FAILED END CONDITIONS: Achievement is not deleted
TRIGGER: None
BASIC FLOW:
1. Admin logs in to the system
2. Admin searches for achievement to delete
3. Admin selects achievement and hits delete
4. System reports back on deleting of achievement
ALTERNATE FLOW:
3.1 Achievement is not found
3.1.1 System reports back on achievement not being found and no changes are
made
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Preliminary Android Design
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Crank App
The design of the Android app is centered on the many views of the app. In
general there is a class responsible for every view with a few single classes
dedicated to multiple views (in the case of SegmentDetailsView,
AchievementView and RideDetailsView).
The Communications class exists to interact with the back-end server. All
communications go through this class which will compile the requests into the
desired xml protocol and read the responses. There is the possibility of including
a pre-existing xml reader-writer library or to implement our own to deal with
the protocol.
The GPSTracker class interacts with the built in GPS receiver in the device and
records the GPX file. It is this file that will be uploaded to the back-end for
analysis.
It is expected that this design will grow and change as we discover the need for
new helper classes and potentially more view classes. However the overall
structure has been defined.
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
GPS Tracking
RidePhotoView
Preliminary iOS Design
Crank App
NewRideView
RideMapView
Communication
GoalsView
RideView
AchievementsView
BaselineAchievementsView
PersonalAchievementsView
Preliminary Technical Manual
LeaderBoardView
RideResultsView
MainSegmentView
RiddenSegmentsView
SegmentOverviewView
RideOverviewView
The iOS architecture and app flow is a little different to that of the Android app
as they both have their own standards in place in terms of what the software is
capable of and what users have come to expect when using apps of that platform.
This mostly included changing of the main title bar from having a menu that can
be accessed from all areas to only being accessible from a few select screens
where it is deemed necessary.
SegmentClimbView
MainRideView
RideClimbView
Several different view types will be used to create the app including tab bar
controllers, list views, detail controllers and main controllers to link them
together. There will also be a navigation controller to allow navigation between
different screens.
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
LocalSegmentsView
HomeScreenView
SettingsView
Shown above is the general idea for the iOS architecture. It shows all views that
will be used to create and show the app to the user. As we are using tabs to move
between some screens and not an entirely new screen, some of these screens
have been made children of other views.
Preliminary Technical Manual
Crank App
Preliminary Server Design
Server classes
Upon running the server app:
1. CrankAppServer makes an instance of TCPSocket
2. TCPSocket binds to port and waits for a connection
Upon a client connecting to the app:
1. TCPSocket makes an instance of Thread
2. Thread waits on a read call
Upon a client sending a request
1.
2.
3.
4.
Thread reads in request
Thread makes an instance of Parser
Parser parsers request and returns values to Thread
Thread creates a dbController and calls the required function calls (store or
retrieve functions or both)
5. dbController returns either confirmation of successful store OR requested data if
retrieve call to the Thread
6. Thread makes an instance of Packager and gives it the response from
dbController
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
7. Packager turns response into XML and splits it up into packets and returns to
Thread
8. Thread sends XML to client
9. Thread waits on a read call
Upon a client uploading a GPX file
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Thread reads in request
Thread makes an instance of Parser
Parser parsers request and returns values to Thread
Thread realises it’s a GPX file request and reads in GPX file packets
Thread makes new instance of GPXFile and passes it GPX string still in XML
format
GPXFile parses it using its own parser, calculates ride stats, achievements,
segments ridden etc. (will need an instance of dbController to compare the given
ride with other rides/ segments etc)
GPXFile returns all this data to Thread
Thread creates a dbController and calls the required function calls (store or
retrieve functions or both)
dbController returns either confirmation of successful store OR requested data if
retrieve call to the Thread
Thread makes an instance of Packager and gives it the response from
dbController
Packager turns response into XML and splits it up into packets and returns to
Thread
Thread sends XML to client
Thread waits on a read call
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Potential Data Classes
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Crank App
The Communication
The main method of communication between the back–end server and the frontend (Both the website and the handset applications) will be by sending xml style
strings between the two via TCP sockets. This xml will conform to a pre-defined
standard that follows the structure of:
<packets>[number of packets]</packets> - number of packets to read from stream
<request>[type of request]</request> - for the server or
<response>[type of response]</response> - for the front-end
Followed by the necessary data in named tags.
An exception to this would be the uploading of GPX files when a user submits a
ride. An xml request will first be sent alerting of the incoming file and the server
will then be prepared to receive the file in a different method.
The differing request types will define what the back end expects to receive after
the <request> tag. This is the same with the front end and the <response> tag.
This can be data ranging from user details to ride statistics. An example for the
front end receiving ride statistics is shown below:
<packets>1<packets>
<response>RideInformation</response>
<ride id=”KieraClimb12/12/12”>
<rideName>Kiera Climb</rideName>
<distance>20.5</distance>
<time>01:21:03</time>
<mTime>01:05:09</mTime>
<avgSpeed>19.6</avgSpeed>
<avgMSpeed>25.5</avgMSpeed>
<maxSpeed>65.2</maxSpeed>
<date>12/12/12<date>
<startTime>13:45:22</startTime>
</ride>
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
Research and Feasibility study
<Overview of what was researched and why, etc>
iOS
Android
Competing products
Survey data
Heart Rate Monitors
<Intro on HRMs etc>
ANT+
Bluetooth v4.0
GPX data
Technically speaking, GPS and the resulting GPX files are still evolving. The data
gathered from the GPS receiver in the handset can vary in resolution in both
elevation and Lat, Long coordinates. These inaccuracies require certain
algorithms (discussed in a later section) to maintain as much accuracy as
possible.
A solution for the issue of inaccurate elevation data gleaned from the GPS
satellites is to look up online elevation databases supplied by NASA. However
these databases have a resolution of approximately 30 metres outside of the USA
and are also a paying service and so have been deemed infeasible.
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Crank App
Development Environments
Server
The IDE used in the production of Crank’s server was IntelliJ IDEA Ultimate
Edition. It has many unique and powerful features allowing us to focus on
producing the best and most reliable product we can in the shortest amount of
time. An example of such features is its database integration. It allows us to
query the database and use SQL code completion as we write the java code
meaning less time testing and more time coding. It also has many advanced code
refactoring and analysis tools to help make our program as efficient as possible
both in terms of execution time and memory consumption. This is a key issue as
our server is hardware limited so to maximize the amount of clients we can
serve at a time it is critical to emphases good coding practises.
Website
The IDE used in the production of Crank’s websites (both marketing and
interactive client) was Netbeans IDE. This IDE has long been known for its ease
of use and powerful code completion. Add to this the ability to view HTML files
and their accompanying style sheets on the one page and you have yourself the
perfect dev. environment for website construction. Coming with full support for
such libraries as smarty and languages such as PHP, JavaScript, CSS3, HTML5,
SQL and more, this truly is a web guru’s dream IDE.
Android
For Android development we first tried using Eclipse with the Android
development plugin. Then, with the release of Android Studio earlier this year as
an early access preview, we decided to shift to it as a development environment.
However since this IDE was so new, it was missing many features that we would
need for the development of our app. Since we only had a limited time period to
develop our app we decided to go with IntelliJ, a well-established IDE for Java
development with built in Android development tools. This meant we could
spend more time building the app rather than wasting time trying to get the IDE
to work as required. One useful feature of IntelliJ is the built in UI editor for
Android applications. This allowed us to layout the basic structure of our screens
before making the finishing touches in the xml layout files.
Development Environment Installation
Versioning
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
Web Page Technology
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Crank App
Algorithms
GPX File Analysis
While researching and implementing the algorithms to parse the GPX data and
derive the ride statistics I encountered several inconsistencies and technical
limitations that needed to be addressed and potentially rectified.
GPS coordinate inaccuracies
This issue is primarily concerned with the inacuracy of the handset being used to
detect the GPS satellites though the phenomenon known as gps reflecting, where
the gps single bounces of surrounding tall structures, must also be accounted for.
To accommodate for these inaccuracies the raw GPX route data is “smoothed” by
running it though an algorithm that analyses the current coordinates in relation
to the current speed (calculated from the timestamps of each point) and the
previous few coordinates. If the point is found to be outside of the threshold then
it is discounted.
When detecting if a rider was stationary or moving the innacuracies of the GPS
was again apparent. While testing it was revealed that no two coordinates
recorded were exactly equal even when the rider was stationary. To address this
issue a threshold was again used to determine if a rider was stationary. This time
the current speed was analysed and if it was under 1km/h the rider is deemed to
be stationary. So for the purposes of calculating average moving speed and
moving time, these points were discarded.
GPS elevation inaccuracies
The satellite data for elevation that is received from the GPS satellites is very
unreliable and inaccurate and like the coordinates, are prone to jumping
erratically.
Two potential solutions are to either implement another smoothing algorithm or
get the elevation data from a web service.
The problem with smoothing however is determining a suitable threshold for
discarding. Take for example a mountain bike ride; it is entirely possible for a
rider to drop 1 or 2 metres a second and then come back up again (in and out of
a gully).
A better solution is the online coordinate elevation databases that apps such as
Garmin Connect and Strava use. However these in brief are expensive to use. See
Resources for links to more information.
In the end the smoothing algorithm was implemented.
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Preliminary Technical Manual
API Documentation
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Design Patterns used
Riley Adam, Callum Thomson, Garrett Frost & James Simpson
Crank App
Preliminary Technical Manual
Crank App
Resources
https://strava.zendesk.com/entries/20965883-Elevation-for-Your-Activity
http://asterweb.jpl.nasa.gov/obtaining_data.asp
Riley Adam, Callum Thomson, Garrett Frost & James Simpson