Expand description
Build, encode and decode the configuration QR codes used by ODK Collect and its rebrand KoboCollect.
A configuration QR code carries a JSON document with three sections:
General— unprotected settings: server, account, form management, user interface;Admin— protected settings: the admin password and every access-control switch (true= the interviewer may use it);Project— the name, icon and colour shown in the project switcher.
The JSON is compressed with zlib, encoded as base64 and rendered as a QR code. Any setting the code omits is reset to its default when scanned, so the model keeps every field optional and serialises only what you set.
use collect_settings::{Settings, General, Admin, Project, Autosend, FormUpdateMode};
let settings = Settings {
general: General {
server_url: Some("https://kc.kobotoolbox.org".into()),
username: Some("interviewer01".into()),
password: Some("secret".into()),
autosend: Some(Autosend::WifiAndCellular),
form_update_mode: Some(FormUpdateMode::MatchExactly),
automatic_update: Some(true),
..General::default()
},
admin: Admin::locked_interviewer("admin-pw"),
project: Some(Project::new("Household survey").icon('H').color("#6b63e6")),
};
let payload = settings.encode().unwrap(); // base64(zlib(json))
let back = Settings::decode(&payload).unwrap();
assert_eq!(back.general.username.as_deref(), Some("interviewer01"));
let svg = settings.qr_svg(4).unwrap(); // ready to embed or print
assert!(svg.starts_with("<svg"));The key names follow the current ProjectKeys / ProtectedProjectKeys of
ODK Collect. Keys that were renamed between releases (save_as →
save_as_draft, mark_as_finalized → finalize_in_form_entry) are
emitted under both names so one code works on old and new app versions;
Collect silently drops the keys it does not know.
Structs§
- Admin
- Protected settings: the admin password and the access-control
switches. Every switch means “the interviewer may use this”:
Some(false)hides it behind the admin password. An omitted key resets totrue(allowed) when the code is scanned. - General
- Unprotected settings. Every field is optional: an omitted key resets to the app default when the code is scanned, so set only what you mean.
- Project
- Name, icon and colour of the project as shown in the app’s project switcher.
- QrCode
- The encoded QR code symbol.
- QrOptions
- Rendering options for
Settings::qr_svg_with. - Settings
- The complete document carried by a configuration QR code.
Enums§
- Autosend
- When finalized forms are sent without the interviewer pressing Send.
- Basemap
Source - Basemap provider for geo questions.
- Constraint
Behavior - When constraints are validated.
- EcLevel
- The error correction level. It allows the original information be recovered even if parts of the code is damaged.
- Error
- Errors from encoding, decoding or rendering.
- Font
Size - Font size of the form entry screen, in sp. Collect accepts 13, 17, 21, 25 and 29.
- Form
Update Mode - How blank forms are kept in sync with the server.
- Guidance
Hint - Whether guidance hints are shown.
- Image
Size - Downscaling applied to photos taken in the form.
- Navigation
- How the interviewer moves between questions.
- Periodic
Check - Interval of the background check for form updates.
- Theme
- App theme.
Functions§
- decode
- Decode a scanned payload back into
Settings. - encode
- Serialise, compress and encode: the exact string a QR code must carry.
- encode_
json - Compress and encode an already serialised JSON document.
- render_
svg - Render any
QrCodewith the given options.