An XForm interface for Badger2040
The Badger 2040 is a wearable device with an e-ink display which comes in two flavours, either with or without WiFi.
The device has potential as a data collection system, especially in the context of data journaling of events or observations taking place across long periods of time. The device benefits from extremely low power draw, meaning that it can potentially be used in low resource settings where there is a lack of access to options for charging smart devices, and/or low device literacy.
This project aims to develop a framework for data collection using the Badger2040, using ODK's XLSForm architecture as the archetype.
Various aspects of the XLSForm are outside the scope of the device's limited computational capabilities, so we focus here on core survey functions.
- Badger2040 or Badger2040w
- Thonny (or another compatible IDE)
- ODK Central
| Question type | Supported | Detail |
|---|---|---|
| text | Yes | Free text response. |
| integer | Yes | Integer (i.e., whole number) input |
| select_one* [options] | Yes | Multiple choice question; only one answer can be selected. |
| select_multiple* [options] | Yes | Multiple choice question; multiple answers can be selected. |
*Both select_one and select_many type questions allow the use of image files instead of text
| Question type | Supported | Detail | Use Case | Barriers |
|---|---|---|---|---|
| decimal | No | Decimal input | ||
| range | No | Range input (including rating) | ||
| date | No | Date input | ||
| time | No | Time input | ||
| note | No | Display a note on the screen, takes no input. Shorthand for type=text with readonly=true | ||
| rank [options] | No | Rank question; order a list | ||
| geopoint | No | Collect a single GPS coordinate | ||
| geotrace | No | Record a line of two or more GPS coordinates | ||
| dateTime | No | Accepts a date and a time input | ||
| calculate | No | Perform a calculation; see the Calculation section below | ||
| file | No | Generic file input (txt, pdf, xls, xlsx, doc, docx, rtf, zip) | ||
| acknowledge | No | Acknowledge prompt that sets value to "OK" if selected |
| Question type | Supported | Detail | Reasoning |
|---|---|---|---|
| select_one_from_file [file] | No | Multiple choice from file; only one answer can be selected. | |
| select_multiple_from_file [file] | No | Multiple choice from file; multiple answers can be selected. | |
| image | No | Take a picture or upload an image file. | |
| audio | No | Take an audio recording or upload an audio file. | |
| geoshape | No | Record a polygon of multiple GPS coordinates; the last point is the same as the first point. | |
| background-audio | No | Audio is recorded in the background while filling the form. | |
| video | No | Take a video recording or upload a video file. | |
| barcode | No | Scan a barcode, requires the barcode scanner app to be installed. | |
| hidden | No | A field with no associated UI element which can be used to store a constant | |
| xml-external | No | Adds a reference to an external XML data file |
This software takes as input an XLS form in JSON format. At present the only way to get the correct format is in ODK Build (https://build.getodk.org/) or KoBo Build.
In Kobo Toolbox you can see it in the API response for any form, but a shortcut is in the UI also if you open a project and replace the last part of the URL with ‘json’
e.g. https://kf.kobotoolbox.org/#/forms/[assetuid]/json
Badger2040_XForm respects the following flags
- Required [All question types]
- Range (Min/Max) [Integer only]
Save the ODK Build design to a file, this will save as a json file
At this stage, if you want to use images instead of text for your select one type questions, you need to replace the label with the name of the image file as shown below
All images should be 1-Bit jpeg files, like these.
Jpg files with higher bit depth should work, but won't look as nice.
This assumes that you'll be adding the Badger2040_Xform software to BadgerOS
-
Open Thonny and copy the contents of your local
examplesfolder to theexamplesfolder on the badger device- form.py
- icon-form.jpg
- sendODK.py
- icon-sendODK.jpg
-
Upload any icons and jpegs you'll need for your form to the
iconsfolder on the badger -
Run form.py, either directly, or through the badgerOS interface.
-
Modify
form.pyline 25 to add the name of the current ODK Build JSON file.- For instance, if your new form is called "beagles.odkbuild", you would set line 25 to
form = "/forms/beagles.odkbuild"
- For instance, if your new form is called "beagles.odkbuild", you would set line 25 to
The user interface is pretty self-explanatory
Text type questions allow the user to use buttons A and C to scroll through a set of characters [A-Z + SPACE] and to select (Button C) or delete (select character DEL). At present the system does not wrap around from Z to A. Data entry takes a while and we expect that this type of question will be less often used that select types.
Integer type questions allow the user to use buttons A <-> and C <+> to increment either down or up through a numeric series. Pressing Button C changes the ordinal, meaning that increments can be in 1s, 10s, or 100s. The system has capability to set a range of values from a minimum to a maximum value.
Select One type questions populate the screen with a list of possible answers from which the user can select exactly one option. If answer is required, exactly one option must be selected in order to progress. If answer is not required then either zero OR one option can be selected. Buttons A and C move the cursor through the list of options. Button B {SELECT} selects the current option, moving the radio box checker to the current answer. Selecting the currently highlighted box removes the checker and returns and empty submission.
Select Multiple type questions populate the screen with a list of possible answers from which the user can select zero or more options. If answer is required, then one or more option must be selected in order to progress. If answer is not required, then zero OR more options can be selected. Buttons A and C move the cursor through the list of options. Button B {SELECT} selects the current option, moving the radio box checker to the current answer. Selecting the currently highlighted box removes the checker and returns and empty submission. Buttons A and C move the cursor through the list of options. Button B {SELECT} selects the current option, moving the radio box checker to the current answer. Selecting the currently highlighted box removes the checker and returns and empty submission.
The sendODK.py app will connect to an instance of ODK central and allows submission of forms.
You'll need to modify your copy of sendODK.py to include your network SSID, password and so on. It also needs an ODK Central URL, username and password.
Note that you should probably use the credentials of a user who has no higher access level than data collector on ODK Collect. We don't recommend having devices lying around in the field which could reveal the username and password of a user with data viewer, project manager or system admin. The sendODK.py app has been tested and works with data collector user credentials.
This Python script is designed to run on a Pimoroni Badger 2040/2040W device, providing a form engine compatible with ODK (Open Data Kit). The script loads an ODK Build form definition in JSON format, manages user input through various form controls, and saves form submissions in CSV and XML formats. Here's a detailed breakdown of its components:
The script begins with necessary imports and initial settings:
- Standard libraries:
time,utime,json,os,io,random,sys. - Libraries specific to the Badger 2040 hardware:
badger2040,badger_os. - External libraries:
qrcode,ubinascii,jpegdec, andmachinefor hardware interaction. - Custom libraries:
pcf85063afor the RTC module.
Several constants define the display dimensions, font settings, menu button positions, colors, character sets, and other UI elements.
The form definition is loaded from a JSON file specified by the form variable. The JSON structure contains controls and metadata which define the form's behavior and appearance.
A state dictionary holds the current state of the form, including the position in the form, current control values, and other necessary flags. This state is loaded from and saved to non-volatile memory using badger_os.state_load and badger_os.state_save.
Functions define the behavior for various button actions, such as navigating through the form (start, show_previous, show_next), adjusting integer values (increment, decrement, change_magnitude), selecting options (next_option, previous_option, select_option), and managing text input (next_char, previous_char, select_char).
These functions handle rendering the UI elements on the Badger 2040's display, including text, buttons, scrollbars, options, checkboxes, and radio buttons. They ensure the UI is updated correctly based on user interactions and form state.
The form's data can be converted into a QR code for easy transfer. The csv function compiles the form data into a CSV format, and draw_qr_code renders the QR code on the display.
Utility functions like map_value and draw_progress_bar are used to display disk usage, giving users an indication of available storage.
The main loop manages the form's display and user interactions. It checks for button presses, updates the display as needed, and handles form submission.
To use this script on a Badger 2040 device:
- Prepare the Form: Create an ODK Build JSON form and place it in the
/formsdirectory on the device. - Upload the Script: Copy this script to the Badger 2040.
- Run the Script: Execute the script on the device. The form will be loaded, and the user can navigate and fill it out using the buttons on the device.
- Save and Submit: The filled form can be saved, generating CSV and XML files that can be uploaded to an ODK Central server.
This script provides a complete solution for filling out ODK forms on a Badger 2040 device, including user interaction, form management, and data submission. It demonstrates how to leverage the hardware capabilities of the Badger 2040 to create a functional and user-friendly form engine.