Badger2040_XForm

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.

Requirements

Minimal

• Badger2040 or Badger2040w
  • https://shop.pimoroni.com/products/badger-2040?variant=39752959852627
  • https://shop.pimoroni.com/products/badger-2040-w?variant=40514062188627
• Thonny (or another compatible IDE)
  • https://thonny.org/

Full

• ODK Central

XLSForm compatibility

Supported question types

*Both select_one and select_many type questions allow the use of image files instead of text

Question types on the wishlist

Question types unlikely to be implemented

Writing a form for Badger2040_XForm

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

Design your form, using only the types of questions that have been implemented.

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.

Copying forms and software to Badger2040

This assumes that you'll be adding the Badger2040_Xform software to BadgerOS

• Open Thonny and copy the contents of your local examples folder to the examples folder 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 icons folder on the badger

• Run form.py, either directly, or through the badgerOS interface.

• Modify form.py line 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"

Using form.py

The user interface is pretty self-explanatory

Text

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

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

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

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.

Submitting data to ODK central

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.

Description of form.py

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:

Imports and Initial Setup

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, and machine for hardware interaction.
• Custom libraries: pcf85063a for the RTC module.

Constants and Global Variables

Several constants define the display dimensions, font settings, menu button positions, colors, character sets, and other UI elements.

Loading Form Definition

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.

State Management

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.

Button Actions

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).

Drawing Functions

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.

QR Code Generation

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.

Disk Usage and Progress Bar

Utility functions like map_value and draw_progress_bar are used to display disk usage, giving users an indication of available storage.

Main Function

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.

Usage

To use this script on a Badger 2040 device:

1. Prepare the Form: Create an ODK Build JSON form and place it in the /forms directory on the device.
2. Upload the Script: Copy this script to the Badger 2040.
3. 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.
4. Save and Submit: The filled form can be saved, generating CSV and XML files that can be uploaded to an ODK Central server.

Conclusion

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.