jcrona / tamalib

A hardware agnostic Tamagotchi P1 emulation library

TamaLIB - A hardware agnostic Tamagotchi P1 emulation library

Synopsis

TamaLib is a hardware agnostic Tamagotchi P1 emulation library built from scratch. It is self-contained and aims at running on any platform powerful enough, from microcontrollers (MCUs) to desktop computers, thus spreading virtual life across the digital world.

So far, it has been successfully implemented on different platforms:

• Desktop computers (check out TamaTool for more information)
• STM32F072 MCU based board (check out MCUGotchi for more information).
• OpenTama which is an STM32L072 MCU based board (check out OpenTama and MCUGotchi for more information).
• Arduino UNO (check out ArduinoGotchi for more information).
• The R software environment (check out tamaR for more information).

Importing TamaLIB

TamaLIB cannot be used as is. In order to create life on a specific target, you need to import all TamaLIB related .c and .h files in your project (for instance in a lib subfolder), to create a hal_types.h file using the template provided and to implement the hal_t structure, that will act as an abstraction layer between TamaLIB and your OS or SDK (detailed information can be found in hal.h). This abstraction layer basically connects TamaLIB to your target's buttons, clock, audio and screen, while also defining the C types that TamaLIB should use to represent 4-bit, 5-bit, 8-bit, 12-bit, 13-bit and 32-bit variables. Once done, you will be able to call the TamaLIB API from your project.

Using the TamaLIB API

Basically:

/* ... */

/* Register the HAL */
tamalib_register_hal(&my_hal);

/* ... */

/* Initialize TamaLIB */
tamalib_init(my_program, my_breakpoints, 1000000); // my_breakpoints can be NULL, 1000000 means that timestamps will be expressed in us

/* ... */

/* Enter TamaLIB's loop */
tamalib_mainloop();

/* ... */

/* Release TamaLIB */
tamalib_release();

/* ... */

Your main project should then forward any button input to TamaLIB using the tamalib_set_button() function.

As an alternative to tamalib_mainloop(), you can call tamalib_step() directly if your execution flow requires something more complex than a simple mainloop. In that case, TamaLIB will neither call the HAL handler() function, nor the HAL update_screen() function by itslef.

License

TamaLIB is distributed under the GPLv2 license. See the LICENSE file for more information.

Hardware information

The Tamagotchi P1 is based on an E0C6S46 Epson MCU, and runs at 32,768 kHz. Its LCD is 32x16 B/W pixels, with 8 icons. To my knowledge, the ROM available online has been extracted from a high-res picture of a die. The ROM mask was clear enough to be optically read. The pictures can be seen there (thx asterick for the link !).
I would love to see the same work done on a P2 and add support for it in TamaLIB/TamaTool !

__
Copyright (C) 2021 Jean-Christophe Rona

tamalib's Issues

Feature request: State serialisation/deserialisation

For most concrete implementations (e.g. in tamatool https://github.com/jcrona/tamatool/blob/master/src/state.c ), there exists a need to serialise the state to an array of bytes, so that it may be saved in non-volatile storage etc.

IMHO this logic should be contained within tamalib itself, along with functions vaguely like

#define SERIALISED_STATE_SIZE [something]

void get_serialised_state(uint8_t *buf);
void set_serialised_state(uint8_t *buf);

Frequency tones and time drift

Hello Jean-Christophe,

I found your library and I'm very happy with it.
I'm doing some experiments with it and an ESP32 board (actually an M5Stack Core).
During my experiments, I noticed that the frequency reported in the callback static void hal_set_frequency(u32_t freq) is ten times the real value.
For example, the initial beep (when the emulator boots) is reported as 23406 Hz, far beyond the real tone frequency. Dividing it by 10, it have the correct tone/frequency.
Is that correct?
Using the static void hal_sleep_until(timestamp_t ts) callback I can manage correctly the synchronization between the emulated MCU and the ESP32, but I noticed a little time drifting (around a second over ten minutes, the emulated machine go faster).
I checked the tamatool WIN32 application and there is a similar time drift.
There is a way for setting the time in the emulated machine, without doing it manually?
Thank you for your excellent work, it bring me back to the '90 heheh

Cheers,

Stefano

Tamalib on its way to run in Retro-go on the Game & Watch Mario & Zelda Edition

Hi I just wanted to let you know that I have successfully 'ported' your fantastic lib to a new emulator for the Nintendo Game & Watch system. It was great fun, and thank you for making tamalib. I have incorporated some changes, mostly to suit the needs of Retro-Go. I have also added a 'fast-forward' function to emulate the 'always on' functionality so the emulator can catch up upon repower on. I added an instruction decoding cache to aid this and make the tamagotchi as fast as possible. It can now run about 300% faster (above 8000fps on my device) when needed.

Thank you again for making this emulator.
My fork can be found here:
https://github.com/BenjaminSoelberg/tamalib
And the retro go code here:
https://github.com/BenjaminSoelberg/game-and-watch-retro-go/tree/tamagotchi/Core/Src/porting/tama
A PR to incorporate it into the main branch of retro-go is on its way.

Decompilation?

Is very hard to do a decompilation to port the program to c or c++? are there some tools for the architecture? I'm wondering if is possible to traduce the rom to C or C++

tamalib MCU frequency

Not an issue, just a question.

It was pretty easy to run tamalib and Tamagothi P1 on Raspberry Pi Pico Clone RP2040 with a SSD1306 display, but i got some problem to understand how to set the correctly run frequency to get the time and speed run correctly.

bool_t tamalib_init(const u12_t *program, breakpoint_t *breakpoints, u32_t freq);

In tamalib_init does the freq value mean the MCU frequency?

If yes, does the sleep_until function used to add a delay and simulate the 32768Hz?

Always 5 points displayed for the player

Looks like every game result shows 5 points for the player.

See jcrona/tamatool#1 for more information.

TamaLib in Arduino UNO

Thanks so much for the great work! After huge modification of your source code, I managed to run the entire TamaLib plus ROM in Arduino UNO, a ATmega328P with 32K Flash 2K SRAM device.

The 4K memory[] allocation is not really necessary. It only requires 320 bytes for main memory.

I will share my project in Gitlib later.

https://youtu.be/MJvAr_od06M
https://youtu.be/ab3_0PLWAnc

Extracting the rom from a connection V5

Hi. I was interested into contributing to tamagotchi emulation by working on the V5 (familitchi) as it's the one I own
I took it apart and took pictures of both sides of the board

however I'm not too sure about how to go about ripping the rom from the device as it would be necessary to reverse engineer it
Do you have information about it ?
I do have a soldering iron and a hot air rework station as well as a few wires i could use