Firmware Design Specification

This page is to record design decisions and objectives. Just a start for now...

Note:
TBD = To Be Determined;
TBC = To Be Confirmed (based on source code of previous Safecast devices, existing documentation or consulting with subject matter experts).

UX Design

Button placement

The buttons are along the top edge of the screen. This requires a rotation of the TFT screen.

• Right: Main action on the right side.
• Centre:
• Left: Menu

Button behaviour

The button behaviour is context dependent.

Colour scheme

The colour scheme remains consistent throughout the design.

• NORMAL Gray_80% = Normal graphics, boxes and text (menus), also if stale data (CPM etc.), status line
• HIGHLIGHT Yellow = Active or fresh data
• INACTIVE Grayed out = inactive, not present
• ERROR Red = Error, including text on status line

Screen designs

Common elements on screens

• Device ID number
• SAFECAST and year identifier (maybe graphics logo too)
• Bottom left status line (e.g. logging, no SD card, etc.)
• Do not show the firmware version on screens; it should only be on something like the boot screen.

Menu display

In the menu display, menu items are shown in a column flush left. The active choice is highlighted in ACTIVE colour, and the others are in NORMAL. There is a line of dashes from the active choice to a text box on the right side. The text is a short description of the item. Generally, the menu is operated with single taps of the three buttons.

Buttons

• Right: Enter = accept the choice and proceed of the screen.
• Centre: Next = highlight the next choice down, wrap to top if at bottom
• Left: Back = Return to previous screen or operating mode

Drive mode

In Drive mode, the bGeigie records CPM, time, position and logs to a file in a format suitable for submission to the map database.

In Drive mode, the screen must blank after a timeout interval to prevent burn-in. The timeout is configurable.

Buttons

• Right: When stopped logging, start logging; when logging, stop logging.
  When the SD card is absent and the user chose at startup to proceed without logging, the Start Log button is grayed out and the note No SD card available is displayed in the bottom left of the screen.
• Centre:
• Left: Menu
  • Menu items: Drive, Survey, Fixed, Logs, Settings (the left button changes to "Close")

Layout TBD

• NN CPM (compensated)
• µSv/h
• Bq/m2

GPS

• Longitude
• Latitude
• Altitude (m MSL) meters above mean sea level
• H. DOP Horizontal dilution of precision
• Date as YYYY/MM/DD
• Time as HH:MM:SS
• Satellites (number of satellites used in most recent fix computation)

Status line

• Show "Logging" or blank if not logging.

Survey mode

In Survey mode, the screen should stay live, on the assumption that the user is actively investigating hotspots.

Buttons

• Right: When stopped logging, start logging; when logging, stop logging.
  When the SD card is absent and the user chose at startup to proceed without logging, the Start Log button is grayed out and the note No SD card available is displayed in the bottom left of the screen.
• Centre:
• Left: Menu
  • Menu items: Drive, Survey, Fixed, Logs, Settings (the left button changes to "Close")

Layout

• µSv/h
• CPM
• Bq/m^2
• Max µSv (TBD: starting from when?)
• Cumulative dose µSv (TBC: cumulative? Like a nuclear worker's dosimeter)

Status line

• Show "Logging" or blank if not logging.

Fixed mode

TBD

Configuration mode

Buttons

• Right: TBD
• Centre: TBD
• Left: Menu
  • Menu items TBD

TBD

Log viewer mode

Buttons

• Right: TBD
• Centre: TBD
• Left: TBD

TBD

Start-up and self-check

After the initial "splash" screen, the firmware checks files on the SD card and non-volatile storage (NVS) for configuration integrity. If everything checks out, the drive mode screen is the first displayed.

Initial "Splash" screen

Displayed briefly (1 second) only once (the time could be configurable, or zero).

• Safecast (C), year and logo
• Device name (bGeigie Zen)
• Device ID number
• Firmware revision

First time startup but no SD card

There is no SD card and the non-volatile storage is not initialized. Display instructions to the user, then stall.

Welcome to your bGeigieZen!
Please insert your bGeigieZen SD-card into the SD-card slot and restart the device.

Show QR code to help URL

No SAFEZEN.TXT on SD card

Display instructions to the user then stall.

Welcome to your bGeigieZen!
Could not find SAFEZEN.txt on the SD-card.
For help visit...

Display QR code URL to help page.

Device ID mismatch

The device ID in the SD card is different than the one stored in non-volatile storage.

Offer the user choices:

1. Do nothing (stall and wait for user to swap SD cards)
2. Proceed with the ID number in NVS, but with other parameters on the SD card
3. Re-number the device in NVS to match ID on SD card

No SD card, NVS settings available

No SD card, settings available in non-volatile storage (including device ID). This should not be a reason to stall since survey mode is still available even though logging is not available.

Display a choice to the user:

1. Proceed without logging
2. Install SD card (stall)

When proceeding without logging, the Start Log button on the Drive and Survey screens must be grayed out.

Empty SD card

Local settings available in non-volatile storage but there is no SAFEZEN.TXT on SD card (new or previously used elsewhere).

Display a choice to the user:
Prepare the SD card for operation? Y/N (default N)

Realtime clock module (M5Stack Core2 or retrofit to original Core)

The M5Stack Core2 has an onboard battery backed-up realtime clock module. This module does not give as accurate time as the GNSS time, but it usable for giving new files names based on the current date. The RTC module includes a "Voltage Low" bit:

• VoltLow=1 means that there has been a low voltage event and the date-time data is unreliable
• VoltLow=0 means that the date-time is valid. The bit doesn't tell anything about the validity of the initial setting. In other words, the time counted since last update matches the actual elapsed time.

The RTC date and time are updated once from GNSS time after startup when the GNSS time first becomes valid.

Errors

Specific conditions:

• No G-M tube: receiving no pulses from the G-M tube, clue that it is missing or high voltage module not working.
• Invalid GPS data: the module is communicating, but the data received is unreadable or unusable. This may be due to a misconfiguration of the GNSS module.
• Others?

Error log file

A separate error file logs error reports to study later. The user could send this for tech support.

Format?

Configuration files

Configurations (SD)

• device id (required)

• us/h divisor = 334

• cpmn = Cs137

• bqm2 factor = 37

• bqmn = Cs137

• country code

• gt (0)

• gm (0)

• sensor type (0)

• sensor shield (0)

• sensor mode (0)

##Configurations (SD + Config server)

• API key
• access point password
• wifi ssid
• wifi password
• username
• click sound level (0-10)
• alarm threshold
• home latitude
• home longitude
• home range

Local storage

• last latitude
• last longitude

Hard-coded

• screen lower brightness timeout (for each operational mode)
• screen off timeout (for each operational mode)
• screen colours : (white / yellow / red)

Ideas for later (noted here until implemented or rejected)

• timezone offset
• accumulated dose
• In Survey mode, if an accelerometer is available, the screen blanking can be cancelled on motion detected. The M5Stack Core2 includes an accelerometer, but unfortunately it is in the cover over the GPIO connector and must be removed to mount the module to the bGeigieZen system board. An accelerometer can be installed in the Grove connector.