Version 49 (modified by 10 years ago) ( diff ) | ,
---|
Android Developer Guidelines
Table of Contents
We have 3 different Android clients written in Java:
- OpenDataKit Collect
- OpenGeoSMS
- Japan client
It is also possible now to write applications in Python, which would provide the benefit of being easier for the core developers to maintain & could potentially reuse libraries, like the DAL, lxml & ultimately Sync:
It would also be possible to develop a client using HTML5
ODK Collect
An Android XForms client
- http://opendatakit.org/use/collect/
- http://www.kobotoolbox.org - extended version
- http://geoodk.com/ - Geo version
- OpenRosa - joint project between ODK & JavaRosa
Download Code
Install yet another SCM tool, HG Mercurial
- defaults will suffice during setup
Get a local copy of ODK collect by checking out from Google Code.
Currently the best version to get is the NCSU branch:
hg clone https://vinbitr-odk-collect.googlecode.com/hg/ vinbitr-odk-collect
This includes:
- ODK Collect trunk (as of Dec 16th)
- jaxdroid changes essential for Sahana
- Support for selecting Images from Media Library
- Support for Wireless Location fix
There is another version which includes support for SMS Form Submission
- link pending
Build
- Install Java JDK
- Install Android SDK
- Download some platforms using the SDK Manager
- Install ANT, a cross platform Java build automation tool.
- Download and extract Ant (1.8.1 at time of writing): http://ant.apache.org/bindownload.cgi
- Create 'ANT_HOME' environment variable.
- Add '%ANT_HOME%\bin' directory to 'PATH' environment variable (Windows syntax).
- Install Eclipse (tested with 3.6.1)
- Install Android plugin
- Import project into Eclipse (project name should avoid spaces)
- Right-click on folder & 'Build Project'
To deploy you'll need to create a self signed keystore and use the .apk packaging wizard (Right-click on project, menu Android tools, Export Signed Application Package), or use the configured Sahana Eden application downloadable from Android Market, enable accept self signed certificates to work with Sahana Eden demo site.
Editing Code
Follow the Build instructions above.
Can Run or Debug in the Emulator
Right-click on the project & select properties | Android to check the API revision used.
- Base ODK Trunk can run on basic Android 1.5: API 3
- SMS functionality requires Android 1.6: API 4
- Does it fail gracefully on older API? (does compile at least still)
Branding
See jaxdroid's branch:
- Edit
/res/values/strings.xml
<string name="app_name">Sahana Eden</string> <string name="default_server">https://demo.eden.sahanafoundation.org/eden/xforms</string> <string name="main_menu_details">Magnifying human resources with technology</string> <string name="main_menu_message">Sahana Eden</string>
Testing
Can use Curl to submit the XForms to the server to easily be able to step though in Eclipse without needing to have a Public IP reach your PC or use the emulator.
curl --basic -u username@domain.com:password -F xml_submission_file=@xform.txt http://127.0.0.1:8000/eden/xforms/submission
SMS Structure
XForms sent via SMS are split into Multi-Part messages with a sequence header. This header is currently a custom 5-digit unique identifier for that particular form submission. That sequence information and unique identifier are prepended to the each part of the multi-part SMS transmission by the modified ODK Collect branch's SMS form submission code. It will look something like this:
- (1/3)(12345)<?xml version='1.0' ?><pr_person>...
- (2/3)(12345)last_name>...
- (3/3)(12345)-08</date_of_birth></pr_person>
The unique identifier -- here, 12345 -- is actually significantly more random than that.
These messages are then reassembled by the tropo()
function in controllers/msg.py
which calls concatSMS(lastMessage, fromaddress)
. The reason the tropo() controller method calls concatSMS() with each new part of a multi-part message is that the messages may arrive out of order. However, when the concatSMS() method detects that all message parts of that XForms submission have been received, it will stitch those messages together (while removing the prepend), and submit them to parserdooth() as for normal messages.
ToDo
- Get the newly-developed features merged into ODK Trunk:
- jaxdroid work on Sahana compatibility
- access to Image Library
- Wireless location fix
- SMS form submission
- Dropdown support within the forms (which will be difficult to FKs)
- Client-side validation where possible (which probably needs to be added/maintained manually...but we need somewhere to put these)
- Can the client currently understand validation errors & present these back to the user?
- We currently send back JSON
- Send Images
- Generate appropriate XForms from image_id fields (ideally using XSLT)
- GeoTagger is a sample Form for ODK which can be used as a template for what needs to be produced by
controllers/xforms.py
- GeoTagger is a sample Form for ODK which can be used as a template for what needs to be produced by
- Provide an interface in Sahana through which users can submit these images via ODK Collect & have them stored (in the doc_image table, referenced by the image_id foreign key)
controllers/xforms.py
- ideally use an XSLT to convert the XForm to S3XML
- See Sahana Eden Mobile Photo Upload Blueprint for additional information.
- Generate appropriate XForms from image_id fields (ideally using XSLT)
- Send Location Coordinates
- Generate appropriate XForms from location_id fields (ideally using XSLT)
- GeoTagger is a sample Form for ODK which can be used as a template for what needs to be produced by
controllers/xforms.py
- Provide an interface in Sahana through which users can submit these coordinates via ODK Collect & have them stored (in the gis_location table, referenced by the location_id foreign key)
controllers/xforms.py
- ideally use an XSLT to convert the XForm to S3XML
- Sahana's Location should have the lower accuracy marked when fix was obtained wirelessly: either source or ce fields (ideally the latter if we have a numeric value available).
- Improve existing support for XForms
- Authentication Issues and Solutions
- Integrate changes made earlier for submitting images via ODK Collect to use the new APIs. Ensure that this functionality works correctly.
- See Sahana Eden Improve existing support for XForms for additional information.
- See Detailed report for Project -Improve existing support for XForms for authentication related changes.
- See this for a short video on the project.
- Support Component Tabs for a multi-table form
- SMS (building on the current NCSU code)
- Need to give user feedback that SMS is sent when HTTP fails (currently they just get a 'Submission failed' message!)
- Should really give them an optional Prompt
- Need to compress the form submissions
- Use the OpenRosa SMS API
- Strip out empty/default fields
- encode the characters more efficiently
- Need to authenticate the form submissions
- Needs to work on the Sahana server side with more than just the controllers.msg.tropo() method (like sms_handler_modem)
- Should have optional response notifications per complete form to say one of:
- Submission Successful: URL of record: http://..../
- Validator Error: xxx
- Need to delete the submitted form from the mobile device when it the submission was confirmed successful.
- The current multi-part transmission uses a very custom sequence number, which should be made more standard (& take up less room)
- Want to be able to download Forms via SMS
- Push updates from server
- Pull requests from client
- Need to give user feedback that SMS is sent when HTTP fails (currently they just get a 'Submission failed' message!)
- QR Code to download the Trunk version (which should update from this version & not default ODK location)
- UserGuidelines on creating/embedding a custom QR code for a deployment-specific version
- Have the list of downloadable XForms more easily configurable (currently hardcoded in controllers/xforms.py formList())
- e.g. Use the same approach as Importer does by marking resources in the modules list in 000_config.py
References
- ANT samples
OpenGeoSMS
See BluePrint/Messaging/OpenGeoSMS
Japan Client
Uses REST services to talk to Sahana back-end.
Available in Japanese only.
Only works with the code used for the Japan Deployment.
- Download: https://play.google.com/store/apps/details?id=org.sahanafoundation.sahana
- Code: http://bazaar.launchpad.net/~sahana-eden-jp/sahana-eden/sahanaAndroid/files
- Function Names & Comments are in English.
- Dev docs in Japanese: http://www.sahana.jp/development/sahana-android
- but could be translated if there is interest.
- Japan-customised Sahana: http://bazaar.launchpad.net/~sahana-eden-jp/sahana-eden/iwate/files
- Demo: http://japan.sahanafoundation.org/android_backend/