ODK forms are created in the normal way. Not all features are supported by succinct data at this time.
STATUS: This functionality is operational.
Forms are prepared by running xml2recipe over them, which will produce the recipe file and template file.
The recipe file describes the type of each field in the form to be included in the succinct data.
BUG: The recipe file may need hand modification for a variety of reasons. The recipe file can be hand modified before first distribution to phones, for example to exclude certain fields or place limits on the lengths of fields. However, if you modify the recipe file then any succinct data messages created to the previous version of the recipe will be impossible to read, and succinct data will grossly misinterpret any such messages. Eventually we intend to support the use of succinct data attributes in the ODK XML form so that hand modification is never required.
The recipe and template files should be copied to the succinct directory of your succinct data bundle marshalling area. You will also need to include a smac.dat file for SMAC to reference when compressing succinct data messages.
If you wish for succinct data messages to be automatically sent by SMS, also add a .sms file containing the number to send to, e.g, +61427679796.
NOTE: The same version of smac.dat must be used for all forms, or else messages will be grossly misinterpretted by succinct data resulting in gobbledygook. Just use the version we have supplied to avoid problems.
STATUS: This functionality is operational.
-
Create a directory to hold the set of forms you want to push out, e.g., operation-potato.
-
Create forms/, icons/ and succinct/ subdirectories under that directory.
-
Copy the ODK forms you wish to push out into the forms/ directory.
-
For any forms you wish to have SMSed automatically, create a file of the form succinct/formname.sms containing the number to send the SMS to as a single line of plain ASCII text.
-
Copy _index.txt from another form bundle directory and edit it to suite. BUG: We should create this for you.
-
Run assemble_bundle giving it the path to the directory structure, e.g., assemble_bundle operation-potato
-
You should now have a valid bundle, e.g., operation-potato.succinct.config that can be copied to phones, as described below.
Use the assemble_bundle script in the examples directory of this repository to create a .succinct.config directory that can be installed on phones.
The .succinct.config file should be copied into /servalproject/sam/configs on the SD card of the phone.
You then need to start "Serval SAM" on the phone and go into preferences and eventually select the file (or it will be selected automatically) and reload configuration.
For some partly out of date instructions from the previous life of Serval SAM that may nonetheless be useful:
http://developer.servalproject.org/dokuwiki/doku.php?id=content:servalsam:main_page
STATUS: This functionality is operational.
BUG: Reloading configuration deletes all previous form instances, when it probably shouldn't.
The succinctdata branch of http://github.com/servalproject/survey-acquisition-management ("Serval SAM") is used to select the form to complete. It automatically launches ODK Collect, and then captures the form when complete, and extracts it's succinct data for transmission.
There is (currently) about a 20 second delay from form completion before the succinct data is extracted. We will look into reducing or removing this delay.
The succinct data is written to the sdcard in the servalproject/sam/succinct_spool directory.
The succinct data messages include an identity token that allows the receive side to determine which form was used to create it. This is based on a hash of the recipe file name, not contents, so recipe files should not be modified when auto-generated by xml2recipe, and whenever changing an ODK form specification one should be sure to increment the version field.
BUG: Auto-detection of form type relies on the filename not content of form recipes. This should change in a future version to be based on the content of the recipe so that mis-matches cannot occur. This is important since mis-matches render the data unreadable.
A separate program is expected to collect the succinct data, and transmit it via appropriate means. See below.
STATUS: This functionality is operational.
We intend to write program that sends succinct data messages by either SMS or inReach depending on which is available.
Transmission will be able to be automatic or manually controlled.
BUG: For SMS the only safe path is to base64 the data, because Android does not provide a real binary API for SMS. This means <=120 characters per succinct data message for now.
STATUS: This program has yet to be written.
On the receive side, the succinct data messages must be written to a file, and then fed through the SMAC program which takes the following arguments:
smac recipe decompress
This expects there to be both a .recipe and .template file that correspond to the form represented in the succinct data message.
Succinct data messages encode the identity of the recipe within them, allowing the recipe decompression process to automatically determine the correct recipe, and hence ODK form specification to use when reconstituting a succinct data message.
Both a .stripped and a .xml file will be created for the reconstituted form. These will be in a subdirectory corresponding to the cannonical form name (form name + "." + version).
STATUS: This functionality is operational.