wiki:DeveloperGuidelines/Mobile/Android

Version 38 (modified by Fran Boon, 12 years ago) ( diff )

Move ODK ToDo here

Android Developer Guidelines

Table of Contents

  1. Japan Client
  2. OpenGeoSMS
  3. ODK Collect
    1. Download Code
    2. Build
    3. Editing Code
      1. Branding
      2. Testing
      3. SMS Structure
    4. ToDo
    5. References

We have 3 different Android clients written in Java:

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:

It would also be possible to develop a client using HTML5

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.

OpenGeoSMS

See BluePrint/Messaging/OpenGeoSMS

ODK Collect

An Android XForms client

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:

There is another version which includes support for SMS Form Submission

  • link pending

Build

  1. Install ​Java JDK
  2. Install ​Android SDK
    • Download some platforms using the SDK Manager
  3. 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).
  4. Install ​Eclipse (tested with 3.6.1)
  5. Install ​Android plugin
  6. Import project into Eclipse (project name should avoid spaces)
  7. 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
    • 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.
  • 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).
  • 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
  • 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

BluePrint/Mobile UserGuidelines/Mobile

Note: See TracWiki for help on using the wiki.