Gluco Technical Documentation 0.2
June 9th, 2023
Shonumi aka D.S. Baxter


***************************************************
1. Introduction
***************************************************

The Glucoboy is a cartridge for the Game Boy Advance that featured the unique ability to process diabetic testing strips. Released on November 14, 2007 exclusively in Australia, it was designed by inventor Paul Wessel and produced by Guidance Interactive. The goal was to encourage children with juvenile diabetes to regularly check their blood sugar and to keep their levels in check. The Glucoboy would record the player's glucose and award points based on how well it fit within a healthy range. These Glucose Reward Points (GRPs) were used to unlock new minigames and in-game items. It was the first time such a medical was officially licensed for sale on any of Nintendo's platforms.


***************************************************
2. General Hardware Information
***************************************************

- Comes in an oversized white cartridge with an ovular top-end.
- Comes with a segmented LCD screen capable of displaying a few digits for glucose levels.
- Has "M" and "C" buttons on the sides of the LCD screen, which should work similarly to other glucose meters (e.g. FreeStyle Freedom Lite).  
- Has a slot for accepting blood testing strips at the very top.
- Uses a coin cell battery, presumably to power the unit's glucose checking functions as well as an internal real-time clock.
- Has a USB slot on the lower side of the unit.
- The PCB is split into two main sections: top for glucose checking hardware, bottom for GBA ROM and EEPROM.
- Top PCB contains a Texas Instruments M430FG437, presumably used to handle glucose checking and managing the RTC.


***************************************************
3. Accessing Glucoboy Data
***************************************************

For the most part, the GBA does not directly deal with any of the glucose checking or blood testing. Instead, other components within the Glucoboy handle that and merely present the results, which the GBA can read back like any other value in memory. To that end, the Glucoboy offers a single, multipurpose 1-byte register mapped to the address 0xE000000. Internally, the Glucoboy's ROM refers to this as the "MAGIC PORT". In this document, it is more aptly renamed as GLUCO_CNT. By reading and writing to GLUCO_CNT, data can be extracted regarding the current GRPs earned from testing. Other miscellaneous hardware info about the Glucoboy can also be retrieved.

To access data on the Glucoboy, an index must first be written to GLUCO_CNT. Different data — such as normal GRPs earned today or bonus GRPs earned that day — are stored at different indices. Once an index is set, the Glucoboy triggers a Game Pak IRQ. Following this, 1-byte, 4-bytes, or 6-bytes must be read from/written to GLUCO_CNT, depending on the index. For example, in the case that an index returns 4-bytes of data, GLUCO_CNT must be read a total of 4 times, once per byte. All data is read/written MSB-first, therefore, software must also manually adjust LSB-first values on the GBA. Additional Game Pak IRQs indicate when the next byte is ready to read/write. Evidently, Game Pak IRQs are generated after a brief delay when accessing GLUCO_CNT.

Below is the typical proceedure used by the Glucoboy's software:

-----------------------------------------------------------
6-byte Index Access
-----------------------------------------------------------
WRITE INDEX TO GLUCO_CNT
	WAIT FOR GAMEPAK IRQ

READ OR WRITE BYTE 5 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 4 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 3 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 2 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 1 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 0 AT GLUCO_CNT
-----------------------------------------------------------


-----------------------------------------------------------
4-byte Index Access
-----------------------------------------------------------
WRITE INDEX TO GLUCO_CNT
	WAIT FOR GAMEPAK IRQ

READ OR WRITE BYTE 3 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 2 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 1 AT GLUCO_CNT
	WAIT FOR GAMEPAK IRQ
READ OR WRITE BYTE 0 AT GLUCO_CNT
-----------------------------------------------------------


-----------------------------------------------------------
1-byte Index
-----------------------------------------------------------
WRITE INDEX TO GLUCO_CNT
	WAIT FOR GAMEPAK IRQ

READ OR WRITE BYTE 0 AT GLUCO_CNT
-----------------------------------------------------------


***************************************************
4. Index Overview
***************************************************

Below is a brief list of all known indices and their currently understood functions:

-----------------------------------------------------------
Index	| Size 	| Description
-----------------------------------------------------------
0x20	| 4	| Read System Date
0x21	| 4	| Read Daily GRPs Earned
0x22	| 4	| Read Bonus GRPs Earned
0x23	| 4	| Read Current Number of Good Days
0x24	| 4	| Read Number of Good Days Until Bonus Rewarded
0x25	| 4	| Read Hardware Flags
0x26	| 4	| Read LD Threshold
0x27	| 4	| Read Serial Number
0x31	| 1	| Read Unknown Flag
0x32	| 1	| Read Unknown Flag
0x60	| 4	| Write System Date
0x61	| 4	| Write Daily GRPs Earned
0x62	| 4	| Write Bonus GRPs Earned
0x63	| 4	| Write Current Number of Good Days
0x64	| 4	| Write Number of Good Days Until Bonus Rewarded
0x65	| 4	| Write Hardware Flags
0x66	| 4	| Write LD Threshold
0x67	| 4	| Write Serial Number
0xE0	| 1	| Read Unknown Flag
0xE1	| 1/6*	| Write Game Stats (*Write 6 bytes, Read 1 byte)
0xE2	| 1	| Read Unknown Flag
-----------------------------------------------------------

A number of these indices do not appear to be used except for debugging. During normal operation, data for the System Date, Hardware Flags, LD Threshold, and Device Serial Number are read but ultimately unused. A hidden test menu inside the Glucoboy ROM can read and write to all of them, however. While these indices provide useful information about the Glucoboy, they are technically not required for the games, which focus on GRPs.

The size of each index indicates how many bytes are read or written when accessing them. A more detailed explanation of known indices follows:

-----------------------------------------------------------------------
Index 0x20 - Read System Date
-----------------------------------------------------------------------

This index returns the current system date according to the Glucoboy's RTC. The clock is used internally to decide if glucose testing has been performed on a consistent schedule in order to give out GRPs. The Glucoboy software does not take advantage of this outside of debugging. 4 bytes are returned representing a date. The complete 32-bit value uses these fields for time:

-----------------------------------------------------------
Bits	| Description
-----------------------------------------------------------
0  - 5	| Minutes (0 - 59)	
6  - 11	| Hours (0 - 23)
12 - 16	| Days (1 - 31)
20 - 23	| Months (1 - 12)
24 - 30	| Years (2001 - 2100)
-----------------------------------------------------------

Days and Months always start counting at 1. That is to say, a binary value of 0 will translate to 1, so the maximum value for each category should be 11 and 30 respectively.

Years starts counting at 2100. That is to say, a binary value of 0 will translate to the year 2100. A binary value of 1 will translate to the year 2001, and so on. Essentially, this value can be added to 2000 to get the current date, with 0 being a special case.





-----------------------------------------------------------------------
Index 0x21 - Read Daily GRPs Earned
-----------------------------------------------------------------------

This represents the amount of GRPs earned on any specific day. It is added to the Total GRPs earned. This value is checked each and every time the Glucoboy boots up, so a constant value of 10, for example, would continually add 10 GRPs every time the game is loaded. In practice, this value was updated after a blood test was performed. The exact amount would be determined by factors such as whether the levels were healthy and whether the test was done in accordance to a regular schedule. The GBA does not seem to have access to the components that calculated GRPs, so it only reads whatever the hardware reports.

The 4 bytes returned by this index form an signed 32-bit integer. Only positive numbers are valid, so the maximum allowed value is therefore 2147483647.





-----------------------------------------------------------------------
Index 0x22 - Read Bonus GRPs Earned
-----------------------------------------------------------------------

This represents the amount of bonus GRPs earned by maintaining healthy glucose levels over a specific number of days. The Glucoboy would likely update this when the "Current Number of Good Days" value was greater than or equal to the "Number of Good Days Until Bonus Rewarded" value. These bonus GRPs are added to the Total GRPs once read. The exact amount of bonus GRPs granted as part of the Glucoboy's internal algorithms is not known.

The 4 bytes returned by this index form an signed 32-bit integer. Only positive numbers are valid, so the maximum allowed value is therefore 2147483647.





-----------------------------------------------------------------------
Index 0x23 - Read Current Number of Good Days
-----------------------------------------------------------------------

This index represents the number of continuous "good days", i.e. days were the player consistently checked their glucose levels and those same levels were within an acceptable range. Failing to meet those requirements would presumably reset the this value.

The 4 bytes returned by this index form an signed 32-bit integer. Only positive numbers are valid, so the maximum allowed value is therefore 2147483647.





-----------------------------------------------------------------------
Index 0x24 - Read Number of Good Days Until Bonus Rewarded
-----------------------------------------------------------------------

This index represents the number of remaining "good days" needed until the bonus GRPs would be granted. Logically, this value would decrease by one every 24-hours, so long as the players glucose levels were kept in check regularly. The exact amount of days until players can get bonus GRPs was part of the Glucoboy's internal algorithms and as such is not currently known.

The 4 bytes returned by this index form an signed 32-bit integer. Only positive numbers are valid, so the maximum allowed value is therefore 2147483647.





-----------------------------------------------------------------------
Index 0x25 - Read Hardware Flags
-----------------------------------------------------------------------

This index represents a set of hardware status flags for the Glucoboy. Only 7-bits of the 32-bit index value is used as such:

-----------------------------------------------------------
Bit	| Description
-----------------------------------------------------------
0	| GMEM FAULT
1	| PMEM FAULT
2 	| INCENTIVE
3	| PNEW STATS
4	| MEASUREMENT
5	| GMETER FAULT
6	| PMETER FAULT
-----------------------------------------------------------

The following descriptions are estimates of each bit's likely meaning. Keep in mind these are guesses for the time being.

"GMEM FAULT" and "PMEM FAULT" refer to errors in the memory allocated for blood testing result. The Glucoboy may separate memories for general glucose test result and postprandial glucose test results. If those areas of memory have issues, they would probably be reported here.

"INCENTIVE" refers to the Glucoboy's proprietary method of determining how it gave out GRPs. This was dicated by factors such as timeliness in testing, frequency in testing, and whether or not glucose levels were healthy. This flag probably indicates that the player had met these conditions.

"PNEW STATS" possibly refers to new data tracking postprandial glucose levels, conceivably an update to some kind of statistic used to measure the player's performance in relation to INCENTIVE.

"MEASUREMENT" possibly indicates a new glucose reading has been done.

"GMETER FAULT" and "PMETER FAULT" refer to failures with the actual glucose and postprandial meters.

Despite "GMEM/GMETER FAULT" and "PMEM/PMETER FAULT" being potentially serious hardware issues, the Glucoboy software does not take any specific actions on them outside of debugging. For example, the player is not warned if any of these components stops working, although, it may affect retrieving GRPs, which does display an error message.





-----------------------------------------------------------------------
Index 0x26 - Read LD Threshold
-----------------------------------------------------------------------

This index holds the value of the "LD Threshold", which possibly refers to a "Low-Data Threshold". This would represent the minimum number of samples from glucose testing needed to get an accurate test.

The 4 bytes returned by this index form an unsigned 27-bit integer. It is used to represent values ranging from 00000000 - 99999999. 





-----------------------------------------------------------------------
Index 0x27 - Read Serial Number
-----------------------------------------------------------------------

This index holds the value of some kind of serial number for the Glucoboy. It is currently unknown if this would have been a per-device serial number or something broader to distinguish versions and revisions.


The 4 bytes returned by this index form an unsigned 27-bit integer. It is used to represent values ranging from 00000000 - 99999999. 





-----------------------------------------------------------------------
Index 0x31 - Read Unknown Flag
-----------------------------------------------------------------------

The exact purpose of this index is unknown, however, it seems to act as a flag. Reading any non-zero value causes the Glucoboy to register an error when retrieving GRPs.





-----------------------------------------------------------------------
Index 0x32 - Read Unknown Flag
-----------------------------------------------------------------------

The exact purpose of this index is unknown, however, it seems to act as a flag. Reading any non-zero value causes the Glucoboy to register an error when retrieving GRPs.





-----------------------------------------------------------------------
Index 0x60 - Write System Date
-----------------------------------------------------------------------

This index is used to set the current system date for the Glucoboy's built-in RTC. This index only appears in the debugging menu. It receives 4 bytes representing a date. See Index 0x20 above for the format.





-----------------------------------------------------------------------
Index 0x61 - Write Daily GRPs Earned
-----------------------------------------------------------------------

This index sets the amount of GRPs earned on any specific day. It receives 4 bytes representing a signed 32-bit integer. This index is not used by the Glucoboy ROM except for debugging, as setting Daily GRPs is a task left for other components of the Glucoboy's hardware during blood testing.





-----------------------------------------------------------------------
Index 0x62 - Write Bonus GRPs Earned
-----------------------------------------------------------------------

This index sets the amount of bonus GRPs earned by maintaining healthy glucose levels over a specific number of days. It receives 4 bytes representing a signed 32-bit integer. This index is not used by the Glucoboy ROM except for debugging, as setting Bonus GRPs is a task left for other components of the Glucoboy's hardware during blood testing.





-----------------------------------------------------------------------
Index 0x63 - Write Current Number of Good Days
-----------------------------------------------------------------------

This index sets the number of continuous "good days", i.e. days were the player consistently checked their glucose levels and those same levels were within an acceptable range. It receives 4 bytes representing a signed 32-bit integer. This index is not used by the Glucoboy ROM except for debugging, as setting number of "good days" is a task left for other components of the Glucoboy's hardware during blood testing.





-----------------------------------------------------------------------
Index 0x64 - Write Number of Good Days Until Bonus Rewarded
-----------------------------------------------------------------------

This index sets the number of remaining "good days" needed until the bonus GRPs would be granted. It receives 4 bytes representing a signed 32-bit integer. This index is not used by the Glucoboy ROM except for debugging, as setting number of "good days" needed to unlock a bonus is a task left for other components of the Glucoboy's hardware during blood testing.





-----------------------------------------------------------------------
Index 0x65 - Write Hardware Flags
-----------------------------------------------------------------------

This index sets the hardware status flags for the Glucoboy. It receives a 32-bit integer, but only the first 7-bits actually represent the flags. This index is only See Index 0x25 above for the format.





-----------------------------------------------------------------------
Index 0x66 - Write LD Threshold
-----------------------------------------------------------------------

This index sets the value of the "LD Threshold". It only appears in the debugging menu. The index receives 4 bytes that form an unsigned 27-bit integer, which must have valid values of 00000000 - 99999999.





-----------------------------------------------------------------------
Index 0x67 - Write Serial Number
-----------------------------------------------------------------------

This index sets the value of some kind of serial number for the Glucoboy. It only appears in the debugging menu. The index receives 4 bytes that form an unsigned 27-bit integer, which must have valid values of 00000000 - 99999999. 





-----------------------------------------------------------------------
Index 0xE0 - Read Unknown Flag
-----------------------------------------------------------------------

The exact purpose of this index is unknown, however, it seems to act as a flag. Reading any non-zero value causes the Glucoboy to register an error when retrieving GRPs.





-----------------------------------------------------------------------
Index 0xE1 - Write Game Stats
-----------------------------------------------------------------------

This index is used to write various information about the games (Lost Star Saga, Knock'em Downs, Solar Wing, Plexus, and Raccoon Rancher) to the Glucoboy. This appears to be data such as high scores and possibly time played. Although this information is stored in EEPROM as part of a normal game save, an additional copy is made for the Glucoboy internally. This index receives 6 additional bytes as parameters. Game Stats uses 60 bytes in total, so this index must be written to multiple times to complete the data.

The Glucoboy writes to Game Stats sequentially when using the 0xE1 index. That is to say, each time it writes data to the index, it moves onto the next category automatically until all 10 have been edited. The table below shows the order of each category and what each value represents:

-----------------------------------------------------------
Category 	| Description
-----------------------------------------------------------
VCSECS		| Number of seconds played for Lost Star Saga
VCHIGH		| High Score for Lost Star Saga
KDSECS		| Number of seconds played for Knock'em Downs
KDHIGH		| High Score for Knock'em Downs
SWSECS		| Number of seconds played for Solar Wing
SWHIGH		| High Score for Solar Wing
PLSECS		| Number of seconds played for Plexus
PLHIGH		| High Score for Plexus
RRSECS		| Number of seconds played for Raccoon Rancher
RRHIGH		| High Score for Raccoon Rancher
-----------------------------------------------------------

The index accepts two inputs spread across 6 bytes. The first is a 16-bit value followed by a 32-bit value. The 16-bit value appears to be constant, as the Glucoboy ROM always sets it to 0x3000. The 32-bit value represents the actual integer to write to a given category. Both of these inputs are written LSB-first, which stands in contrast to every other index.

When reading this index, it seems to act as a flag, and any non-zero value causes the Glucoboy to register and error when retrieving GRPs.





-----------------------------------------------------------------------
Index 0xE2 - Read Unknown Flag
-----------------------------------------------------------------------

The exact purpose of this index is unknown, however, it seems to act as a flag. Reading any non-zero value causes the Glucoboy to register an error when retrieving GRPs.