Portable Game Console Project "ilo musi" - Third Prototype, PCB, Menu, Clock Calibration, Software Release and Suspension of Development

May 1, 2019, 3:17 p.m. Behind the Scenes Electronics Portable Game Console Programming ilo musi

Hey guys. Sorry for not updating you guys about this portable game console project for an extended period of time. I have been rather busy lately. https://ilonanpa.sadale.net/ The previous blogpost of this game console was about the Stay In game developed for the 4th Alakajam. This blogpost aims to document the update of the portable game console project since the last blogpost! :)

Name of the Portable Game Console - ilo musi!

This project had come a long way without having an official name. From now on, "ilo musi" will be the name of this portable game console! It means "amusing device" or "playful device" or "toy" in Toki Pona language. This name is chosen mainly because it is unique, and it is meaningful. As this game console is a minimalist one, this name also map well to the ideology of minimalism of Toki Pona.

Hardware Update - Third Prototype of Hardware, with PCB!

I've drawn a PCB for this project! And this is the first PCB I've ever designed in my life! I've done this PCB almost five months ago. But I didn't have the time to blog about this. :)

A photo of a hand holding a piece of PCB of ilo musi

This PCB was designed using KiCAD. The main reason of using this PCB software is that it's FOSS. To learn drawing a PCB, I went thru the official getting started documentation of KiCAD. After going thru the tutorial, I managed to draw the PCB for the game console. It's easier than I thought it'd be. :)

Hardware: [Resolved] Terrible Mistake of MicroSD Pinout of PCB Design

I've made a mistake on designing the PCB. I messed up the pinout of the microSD card as I thought that it would be identical to full-side SD card. Then I designed the circuit based on the pin-mapping of the full-size SD card. It turns out that they're different.

Notice how there's an extra VSS1 in the full-size SD card. I didn't notice that and I messed up. Too bad! I realized this mistake after sending my design to the PCB fab. :'(

I asked about how much would it cost to modify the design. The PCB fab told me that it's already in production. So it wasn't possible to change the design anymore. I ordered another batch of PCB with the new design. And now I've got 10 wrong ilo musi PCBs laying around:

A photo of 10 wrong PCB of ilo musi packed in bubble wrap

Oh well. Lesson learned: Review the design carefully before sending it for PCB fabrication.

Hardware: Other issues in the current prototype

With the microSD issue fixed, the current PCB is working properly. Anyway, there're still some minor issues with the PCB:

Hardware: Specs Changes since Second Revision of Hardware

The microcontroller had been upgraded from STM32F030K6T6 to STM32F030C6T6. STM32F030C6T6 has more GPIO pins compared with STM32F030K6T6. And it is easier to upgrade to another pin-compatible microcontroller with STM32F030C6T6, which is the main reason of this change. With STM32F030C6T6, it'd be possible to upgrade the RAM and flash space of the microcontroller without modifying the PCB.

As a result of the microcontroller upgrade, the amount of spare GPIO had been increased from 12 pins to 22 pins. Now there're 22 user-accessible GPIO pins that can be accessed by the games developed for this game console! :)

In the final product, the following specs is to be expected:

Software News

Software News: Game Selection Menu

The game-selection menu of ilo musi is implemented! Its purpose? You guessed it. It's used for selecting a game on the microSD card. With game selection menu, it's possible to store multiple games on the same microSD card. Then the player can choose a ROM from the microSD card and play it! The menu also load system configurations and has feature designed for the ease of game development.

A photo of ilo musi's game selection menu

Software News: Menu: Game Selection

As shown on the picture above, the player can choose the game using the menu. The menu can be navigated using key UP and key DOWN. Key 1 is used for starting the game, and key 2 is used for refreshing the microSD card (useful for changing the microSD card).

This portable game console supports microSD card formatted as FAT32 filesystem. The file names are shown as 8.3 filename. Directory navigation is possible.

Upon the game is selected, self-flashing would be performed. After that, the program counter would be jumped from the bootloader to the game. Then it'd be up to the game to handle what to do.

Software News: Menu: Debugging Games

As for the procedure of new game development, first, prepare the game resources, including graphical assets and whatever needed and pack the game ROM as "DEBUGRES.IMG". After that, put the file "DEBUGRES.IMG" file somewhere on the microSD card (can be put onto the root directory). Then program the game code to the microcontroller using ISP. Then the game console would be reset. Then the developer would navigate to the directory containing the "DEBUGRES.IMG". If the file is available in the directory, the game console would not perform self-flashing and jump to the game right away. Since the self-flashing part is skipped, this allows the developer to run debugger for the source code of the game with the updated game code that the developer had just flashed using ISP without repacking the game ROM. This "DEBUGRES.IMG" feature makes the life of the game developers easier.

Software News: Menu: Contrast Adjustment and Internal Clock Calibration Values

It is possible to perform contrast adjustment using the menu by pressing key LEFT and key RIGHT. This would adjust the brightness of the pixels on the LCD. The contrast adjustment value is stored on the option bytes of the microcontroller so that it'd persist after reboot.

Along with contrast adjustment value, the clock calibration trimming value is also stored in the option bytes. The option bytes are loaded by the menu on boot. We'll get to the clock calibration trimming value in the next section of this blogpost.

There're only two option bytes in the microcontroller. The two 5-bit calibration trimming values takes 10 bits. That leaves 6 bits for contrast adjustment, which is good enough as the range of adjustment is from -10 to +2. Needless to say, some bitwise manipulation is required to put three different values into two option bytes. And this has been taken care of. :)

Software News: Clock Calibration "Game"

In most of the cases, the internal clock just works fine. According to the datasheet of STM32F030C6T6, the main clock (HSI) of the microcontroller typically has an error of ±5% at full temperature range (and ±1% at 25°C). This 5% of error often wouldn't be a major issue. If the game is running 5% slower or faster, it'd barely be noticeable. However, for things like asynchronous communication, particularly UART, 5% of error would be an major problem. We'd want to control the error to within 2% or so for reliable UART communication. For this reason, some clock calibration mechanism is required.

I've thought about including clock calibration mechanism in the game selection menu. However, it takes quite a bit of code size for clock calibration. For this reason, I made a "game" dedicated for performing clock calibration.

A 32.768kHz crystal soldered onto the device serves as a reference clock source for performing the calibration. This crystal is assumed to have almost no error, which actually is the case because the error we're looking at would be 0.01%-ish. With this clock source, the clock calibration "game" would be able to calibrate the clock by setting the trimming values (i.e. calibration value) of the main clock (HSI) and the ADC clock (HSI14) appropriately. After that, the game would measure the frequency of the low frequency internal clock (LSI) and show it on the screen, which isn't possible to get calibrated. Finally, the calibrated values are saved to the option bytes so that it'd be loaded by the game selection menu upon the game console is booted, which makes the calibration persists across power cycles.

Software Released!

The software of this game console had been released!

Software Release: Template Game

To facilitate development of new game for this game console, I've prepared a new game template! It's a skeleton code with simple structure that would be useful for most of the games. It includes code for graphical assets loading, input handling, clean screen, frame limiting and a simple game object management library.

The Github repository containing the template game for ilo musi can be found here

Software Release: Python Scripts

A few Python scripts were developed to facilitate working with custom music, graphic and ROM format of ilo musi.

The Github repository containing the Python scripts can be found here

Software Release: Bootloader and Game ROMs

The bootloader is the core of the game console. It contains the game menu and the system library of the game, which all game ROMs would depend on.

The Github repository containing the bootloader and game ROMs can be found here. Currently only the binary is released because there are probably still some bugs in the bootloader. The source code of the bootloader will be eventually made available.

Bad News - Project Development Suspended!

Since I'm done with freelancing, I've got two day job offers. To my surprise, the employment agreements of both companies have a clause saying that the copyright of all work I do while I'm employed would go to the company. The local law here say that the copyright of the stuffs that employees do during "course of employment" would go to the employer, and it'd go to the author otherwise. It means that I'd hold the copyright of hobbyist projects that I work outside work hours. But I'm not sure if the agreement would override the law.

For the existing work that I've done on this project, the copyright is definitely mine. To avoid legal dispute, the development of this game console had been suspended since I've got the day job. I'm trying to come up with an agreement on copyright arrangement of this project with my employer. My employer had verbally agreed that I'd hold the copyright of this project. But still, the paperwork isn't done yet. Hopefully everything would go thru.

In case of non-agreement on paperwork, I could just distribute this game console anyway. Despite that limitations stated above, this game console is currently perfectly playable. So it's possible to distribute it without any further copyrightable development work. Another way to do that is to hand over this project to someone else. Someone had expressed interest in hacking on this project. So I'd imagine it wouldn't be difficult to look for contributors. I could also look for a new job. But the friendly coworkers, awesome culture and decent compensation of the company are just too much for me to give up. And this kind of clause is probably more than common in employment agreements. So switching to another job may not help at all.

Meanwhile, I think I may look for legal consultation from professional lawyer on the actual copyright ownership of hobbyist projects. I know that I've signed the employment agreement. However, it wouldn't make sense if all the stuffs I make outside work hours would be copyrighted by the employer. That way I technically wouldn't even be able to post any text or photo or video to any blog or chatroom or social media without infringing the copyright of my employer. And that's just bullshit. What I really need to know is if the employment agreement would override the local copyright law. If it doesn't, I'd be all good to work on this project without any new agreement with my current employer.

Anyway, the non-copyrightable work of this project can go on without any problem, including some testing that doesn't generate copyrightable material, production efficiency research and distribution of this game console.

What's next?

I'll be continue working on this game console.

No copyrightable would be generated for these tasks. I can work on these straight away:

New copyrightable material would be generated for these tasks. I have to check for the copyright ownership of the stuffs that I work on before working on these, or I could ask someone else to do these for me:

I aim to get this project done by the end of this year (not including the emulator). Let's pray and hope the copyright crap would get resolved so that the development can resume. Stay tuned! :)