Ooka Heating Devices LLC AIR-A001B Revolutionary Pod-Based Device User Guide
- June 1, 2024
- Ooka Heating Devices LLC
Table of Contents
User Guide
CONFIDENTIAL:
All information contained in this document may not in whole or in part be
communicated to third parties without the prior written permission
Uncontrolled copy unless stamped ‘Controlled’ or viewed as pdf. If this is an
uncontrolled copy, verify the revision is current before use.
Document Type| Technical Note| Related proceoure| QMS QP 0006 QMS QP 0314|
CAMBRIDGE DESIGNPARTNERSHIP
---|---|---|---|---
Document Title| 0010\ GUI User Guide| Template| QMS-QT 3012-C
Document Number| EHR-0053-GD| Active Date| 06/04/2023
Revision| A| Project Name| Bandit| Status| Active
INTRODUCTION
This document provides an overview of the OOKA GUI created to support the OOKA
product development, servicing, and maintenance. It also guides the user
through installing the OOKA GUI.
This revision of the OOKA GUI User Guide has been written for OOKA GUI version
6.0.0.
VERSION COMPATIBILITY
The table below details which versions of the GUI are compatible with which versions of the OOKA device firmware.
| OOKA GUI Version | OOKA Device Firmware Version(s) |
|---|---|
| 6.0.0 | Phase 1 (“Ajman”) Firmware v3.13 Phase 2 (“Bandit”) Firmware v1.0 |
INSTALLATION
- Double click the OOKA GUI Setup v6.0.0.msi installer package.
- The Setup Wizard should appear.
- Click Next, then select the location at which to install the OOKA GUI.
- Click Next again, then click Install to begin installing the OOKA GUI
- If the GUI is installed successfully, the Setup Wizard will state that it has completed. Tick the Launch OOKA GUI box if it is not already selected. Click Finish to close the Setup Wizard.
- The Setup Wizard should close, and the OOKA GUI should open. Note that the selected Serial Port may differ to that shown below.
CONNECTING TO AN OOKA DEVICE
- Open the OOKA GUI application.
- Click the drop-down menu below the ‘Serial Port’ text to select a connected OOKA device (note that the available COM Ports may differ to that shown below).
- Press the Connect button to connect to the OOKA device. When the device is connected, the Connect button will change to say ‘Disconnect’, and the fields on the Details tab of the GUI will be filled in.
- The GUI will auto-detect whether the connected device is running a Phase 1 or Phase 2 application, or one of the two bootloader modes, and will use the appropriate serial speed and enable the appropriate functionality.
OOKA GUI TABS AND USAGE
The table below shows which tabs are available for the different Build types of the OOKA device firmware.
| Debug| Release| Test| Secondary Bootloader| MCU Board Bring Up
---|---|---|---|---|---
Details| 
| 
| 
| |
Update| | | | |
Test| | | | |
Levels| | | | |
Accelerometer| 
| | | |
Temperature| | | | |
Power| | | | |
Time| | | | |
Battery| | | | |
Diagnostics| | | | |
Reset| | | | |
Serial Monitor| | | | |
---|---|---|---|---|---
Safe Mode Recovery| | | | |
RF Test| | || |
EMC Test| | || |
6.1 DETAILS
The Details tab provides information about the firmware that is currently
running on the OOKA device, along with the device hardware version. 
- Version: The version of firmware running on the connected OOKA device.
- Type: The firmware build type running on the connected OOKA device.
- Hash: The Git commit hash of the firmware running on the connected OOKA device.
- Branch: The Git branch name of the firmware running on the connected OOKA device.
- Hardware: The hardware version of the assembled device (Phase 2 devices = “OOKA 4.0”, Phase 1 production devices = “OOKA 3.0”)
- Control, NFC, Button, Ring: The hardware revisions of these PCBs
6.2 UPDATE
This tab is only available for Phase 2 (“Bandit”) devices. This tab provides a
means of updating the firmware that is running on a Phase 2 OOKA device.
To update a unit a four-pin cable needs to be attached, and the DC charging
cable needs to be inserted. Drag-and-drop the new firmware package onto the
application or use the file browser, then press the “Start Update” button. The
package must be one which includes the secondary bootloader (the binary file
will have the name “bandit_code_production_boardBL<build
type>_v
At the start and end of update, the top ring will be lit up pink to indicate
that the unit is currently running the Ooka loader.
For the rest of the update cycle, the unit appears off, and progress will be
displayed on the “Update” tab in the Service Application (see images below).
The other tabs in the Service Application disappear during the update, as the
normal command set is temporarily unavailable. The unit may reset during the
process.
An error may occur during the firmware update process. Please refer to
Appendix A for a full list of the error codes that may be presented during an
update.
6.3 TEST
The Test tab allows testing of some device functionality and may be used to
carry out parts of the Final Assembly Test of a device during manufacture.
-
LEDs: Tick the boxes to turn on the LEDs. Untick the boxes to turn off the LEDs.
o Red, Green, and Blue: ticking will light up the Top LED Ring the respective colours.
o Battery LED: ticking will turn on the Battery Bar LEDs, with the bottom LED lit blue.
o Button LED: ticking will turn on the Button Ring LEDs. -
Sound: Ticking the Buzzer box will turn on the buzzer to make a continuous single-pitch sound. Untick the box to turn off the Buzzer.
-
Switches: The box to the right of the Button Status text indicates whether the button is pressed (green box) or not pressed (red box). The box to the right of the Capsule Door text indicates whether the Capsule Door is open (green box) or closed (red box).
-
Tag Key: Select whether the Production or Test NFC key should be used.
6.4 LEVELS
The Levels tab auto-updates with temperatures as measured/set on the
device.
- Thermocouple 1, 2: The temperature of the heater as measured by the heater thermocouples.
- Battery Temperature: Temperature of the battery, measured by the sensor inside the battery pack.
- System Temperature: The temperature of the main control PCB, as measured by the accelerometer (on the main board).
- Heater Target Temperature: The temperature from the session Profile Stage that the heater is aiming to reach/maintain. This should be 0 if a session is not in progress.
6.5 ACCELEROMETER
The Accelerometer tab auto-updates with reading from the accelerometer. 
- Tilt: The magnitude of the device tilt, classified as None, Small, or Large, by the device firmware.
- X, Y, Z Axis: The tilt values measured by the accelerometer.
A vertical device should have a tilt of ‘None’, with components X ≈ -1, Y ≈ 0,
Z ≈ 0.
The axes correspond to the below directions:
6.6 TEMPERATURE
The Temperature tab allows the user to read and set the temperature values in
the device Profile to use in a Session. All values are displayed in degrees
Celsius.
When the GUI first opens, this tab will display some default values. Click the
Read button to read the actual profile values as they are set on the device.
To change the profile temperatures used by the device, change the appropriate
temperature value, then click the ‘Set’ button next to the number that was
changed. Note that clicking Set will only update the value that the Set button
is next to. To change multiple temperature values, the user must click the Set
button next to each of the values.
6.7 POWER
The Power tab allows the user to read and set the power percentage values in
the device Profile to use in a Session. All values are displayed as
Percentages.
When the GUI first
opens, this tab will display some default values. Click the Read button to
read the actual profile values as they are set on the device.
To change the profile powers used by the device, change the appropriate power
value, then click the ‘Set’ button next to the number that was changed. Note
that clicking Set will only update the value that the Set button is next to.
To change multiple power values, the user must click the Set button next to
each of the values.
6.8 TIME
The Time tab allows the user to read and set the duration values in the device
Profile to use in a Session. All values are displayed in Seconds.
When the GUI first opens, this tab will display some default values. Click the
Read button to read the actual profile values as they are set on the device.
To change the profile times used by the device, change the appropriate time
value, then click the ‘Set’ button next to the number that was changed. Note
that clicking Set will only update the value that the Set button is next to.
To change multiple time values, the user must click the Set button next to
each of the values.
6.9 BATTERY
The Battery tab auto-updates with battery-related measurements from the
firmware.
- Battery Voltage: The average battery voltage per cell, as measured by the device firmware, in Volts. Since there are 4 cells, the total battery voltage may be approximated by multiplying this number by 4.
- Battery State of Charge: The battery voltage as a percentage of its total voltage. This is the value that is indicated by the Battery Bar LEDs on the front of the OOKA device.
- Battery Charge Current: The current that the battery is charging at, in milli-amps. This value should be 0 if the device is not charging.
6.10 DIAGNOSTICS
The Diagnostics tab auto-updates with the last error/exception codes raised by
the OOKA device.
- Last Displayed User Error Code: The error code of the last User Error that was displayed on the device.
- Last Exception Code: The error code of the last Exception that was raised by the OOKA device firmware.
Refer to document EHR-0051-GD-1 Message API for Bandit Firmware v1.0.0 for information on what the error and exception codes mean.
6.11 RESET
The Reset tab enables the user to reset various parts of the device firmware
back to their default states.
- Reset Profile to Default: This button will reset the loaded session profile back to the default values that are set by the firmware.
- Reset Profile to Safe: This button will reset the loaded session profile back to the ‘safe’ values that are set by the firmware. This corresponds to setting all the values to ‘0’.
- Reset Device State: This button will reset the OOKA device’s UI back to its ‘normal’ operational state. This may be useful after using the Test tab to change parts of the UI.
6.12 SERIALMONITOR
The SerialMonitor tab displays a log of the most recent serial commands that
have been sent by the computer and the OOKA device.
Each
line in the ‘Serial Events’ box shows the time at which the command was
sent/received, the direction of travel of the data (>>> = PC to OOKA, <<< =
OOKA to PC), and the data bytes sent/received (in hexadecimal format).
The user may log the serial commands sent/received to a file on the PC. To do
so, select the folder path to save the log file to (next to the Browse
button), then click Record Log. Only command data sent/received while the
Record Log button is ticked will be saved to the file. The data will be
visible in the created file after the Record Log button has been unticked.
6.13 SAFE MODE RECOVERY
See Section 7 Safe Mode Recovery.
6.14 EMC TEST
The EMC Test tab is only available when connected to an OOKA device running
the Test firmware build. This tab enables the user to switch between EMC tests
(Radiating/ Immunity) and control the buzzer, while monitoring the device
status. It also provides an interface for viewing and logging data transmitted
over the serial interface.
Radiating mode will set the device to continuously scan for RF tags, turn on
the heater and button LEDs and pulse the top lid LEDs. The buzzer checkbox can
be used to optionally sound the buzzer in the device. Bringing a tag within
range of the NFC field when in radiating mode should result in the success
counter incrementing.
Immunity mode is much the same as Radiating mode but sets the heater at a
lower temperature to reduce the chance of physically destroying an NFC tag
within the OOKA device’s oven.
6.15 RF TEST
The RF Test tab is only available when connected to an OOKA device running the
Test firmware build. It enables the user to switch between Radio tests
(Unmodulated/Continuous Scan) while monitoring the device status. It also
provides an interface for viewing and logging data transmitted over the serial
interface.
In Continuous Scan mode, the device will repeatedly scan for tags, and
increment the attempt, timeout and success counters accordingly. Bringing a
tag within range of the NFC field when in Continuous Scan mode should result
in the success counter incrementing.
In Unmodulated mode, the NFC field is turned on but the device does not check
for tags.
SAFE MODE RECOVERY
The Safe Mode Recovery tab is available in the GUI before connecting to an OOKA device. It can be used to update/reflash the firmware onto the device to attempt to ‘recover’ it if the OOKA device persistently enters Safe Mode without obvious cause.
When the devices has encountered an error condition too many times, it enters
Safe Mode, as indicated by one orange and three white LEDs. Pressing the power
button will attempt to reset the error and restart the device, however if the
error condition is still present, the device may reenter Safe Mode shortly
thereafter. It may be that a new firmware version supports working around this
error. If this is the case, you can use Safe Mode Recovery to flash this newer
version.
When you select “Start Recovery” above, you will be prompted to press the
power button to reset the OOKA. The GUI will set the service pin, meaning that
the OOKA should enter the bootloader, making a firmware upgrade possibly.
ROUBLESHOOTING
8.1 ERROR CONNECTING TO DEVICE
You may observe the below error when attempting to connect to an OOKA device:
Check that:
- The OOKA device is connected to the computer via the USB-Serial Cable
- The Serial Cable has the correct orientation at the OOKA device-end
- The OOKA device is awake (At least one of the battery bar LEDs on the front of the device will be lit if the device is awake). If the device is asleep, press the button on the front of the OOKA device, or connect the AC Adapter, to wake the device.
- The intended firmware build has been flashed to the device (e.g. This error will occur if the device is running the MCUBoardBringUp firmware build as this build is not supported by the GUI. Debug, Test, Release, and Secondary Bootloader builds are all supported by the GUI and will not be the cause of this error).
8.2 DEVICE DISCONNECTED
You may observe the following “Device disconnected” error when using the GUI
after the device has been connected (the specific command that timed out will
vary):
Check that:
- The OOKA device is awake (At least one of the battery bar LEDs on the front of the device will be lit if the device is awake). If the device is asleep, press the button on the front of the OOKA device, or connect the AC Adapter, to wake the device. To keep the device awake throughout GUI usage, the capsule door may be kept open so that the Top LED Ring flashes white.
REVISION HISTORY
9.1 REVISION DETAILS
9.2 CHANGES SINCE LAST REVISION
N/A
APPENDIX A FIRMWARE UPDATE ERROR CODES
These error codes are shown when a firmware update fails, in the form “Error:
EXXX”, where XXX is the error number.
| Code | Condition |
|---|---|
| 1 | Serial connection is not open when firmware upgrade operation starts. |
Reconnect and try again.
2| Device hardware version is not supported by the firmware update mechanism
3| At the start of every phase, the code double-checks that the devices is in
the right mode.
This error is raised if one of these checks failed, meaning that the device
mode changed since the end of the previous phase
4| We tried to determine whether the device was in the application or
secondary bootloader, but got a serial error which wasn’t a timeout
5| We asked the device to enter a particular mode, but after a timeout it was
not in that mode
6| We wanted to transition the device from one mode to another, but the device
wasn’t in the initial mode. This probably means that the device changed mode
unexpectedly
7| We tried to send the USER_RESET command to send the device into the
secondary bootloader, but got an error.
8| We tried to read the device UUID from the secondary bootloader in order to
start transitioning to the primary bootloader, but the command timed out
9| We tried to read the device UUID from the secondary bootloader in order to
start transitioning to the primary bootloader, but got an error sending the
command
10| We tried to tell the secondary bootloader to enter the primary bootloader,
but the command timed out
11| We tried to tell the secondary bootloader to enter the primary bootloader,
but got an error sending the command
12| We tried to tell the secondary bootloader to enter the primary bootloader,
but it responded saying the CRC we sent was incorrect
13| We tried to tell the secondary bootloader to enter the primary bootloader,
but it responded saying it was busy decoding the application
14| We tried to tell the secondary bootloader to enter the primary bootloader,
but it responded with an unknown error
15| We tried to tell the primary bootloader to reset back into the secondary
bootloader, but got an error
16| We tried to connect to the secondary bootloader after transitioning to it
from the primary bootloader, but the connection failed
17| We tried to tell the secondary bootloader to launch the main application,
but the command timed out
18| We tried to tell the secondary bootloader to launch the main application,
but got an error sending the command
19| We tried to tell the secondary bootloader to launch the main application,
but it responded with “Denied”, which was unexpected
20| We tried to tell the secondary bootloader to launch the main application,
but it responded saying it was busy decoding the application
21| We tried to tell the secondary bootloader to launch the main application,
but it responded with an unknown error
22| We tried to tell the primary bootloader to erase flash, but blhost
responded with an error
23| We tried to tell the primary bootloader to program flash memory, but
blhost responded with an error
24| We tried to read the firmware image back from the primary bootloader, but
blhost responded with an error
25| We tried to verify the firmware image we’d read back, but the size of the
image we read back did not match the size of the image which we wrote
26| We tried to verify the firmware image we’d read back, but it differed from
what we wrote
27| We tried to tell the secondary bootloader to decode the application, but
the command timed out
28| We tried to tell the secondary bootloader to decode the application, but
got an error sending the command
29| We tried to tell the secondary bootloader to decode the application, but
responded with “Denied”, which was unexpected
30| We tried to tell the secondary bootloader to decode the application, but
responded saying that it was busy decoding the application
31| We tried to tell the secondary bootloader to decode the application, but
responded with an unknown error
32| We tried to read the decode progress from the secondary bootloader, but
the command timed out
33| We tried to read the decode progress from the secondary bootloader, but
got an error sending the command
34| We waited for the secondary bootloader to decode the application, but it
timed out
35| We tried to start the firmware update operation, but the firmware type was
Unknown
36| We tried to determine whether the device was in the application or
secondary bootloader, but got a firmware type of Unknown
37| We tried to send a serial command to the device at the very start of the
upgrade to determine its mode, but the command timed out
38| We tried to send a serial command to the device at the very start of the
upgrade to determine its mode, but got an error sending the command
39| At the very start of programming we check to see whether the device is in
the same mode as when we initially connected. If not, we raise an error
telling the user to try again (and force a disconnect/reconnect to re-fetch
the mode)
40| We tried to start the firmware update without the charger plugged in
41| We got another, unknown and unexpected error