Soc ninja title



The messy code is currently just a mesh between EmbeddedArtists' command2 sketch and SdFat-beta's library and code. Also I use Adafruit's RTClib to communicate with the DS1307 RTC chip.

You'll need to install those libraries in order to compile the Arduino sketch available from the gitweb repository or directly here.

E-Ink display

The library for the e-ink display uses the simple XBM format [ wikipedia ]. The display board itself has flash memory to permanently store up to 255 sectors; for the 2,7" display, each image uses 2 sectors, effectively giving us space for up to 127 images.

For our project, each caracter uses 2 images: one for the big hanzi / kanji character and another one with the pinyin / romaji and its explanation. This, again, reduces by 2 the number of stored symbols, giving us space for about 63 pairs of character-information.

Again, if we use about 26 images for internal purposes ( welcome screen, information screens to display miscellaneous information ) this leaves us space for 50 characters, which is quite enough for daily usage :-).

At the moment, the program always uses the first two sectors (0, 1) to store the selected card and then display it, so we are not affected by the limits of flash capacity.

Micro-SD card and image files

I used a cheap microSD card with 4GB of capacity. formatted under Windows 10 with FAT filesystem, and with the following file structure:

  • 1-500/
    • CARD1.XBM
    • [ ... ]
    • CARD500.XBM
  • 501-1000/
    • CARD501.XBM
    • [ ... ]
    • CARD1000.XBM
  • 1001-1500/
    • CARD1001.XBM
    • [ ... ]
    • CARD1500.XBM
  • 1501-2000/
    • CARD1501.XBM
    • [ ... ]
    • CARD2000.XBM
  • 2001-2500/
    • CARD2001.XBM
    • [ ... ]
    • CARD2499.XBM
  • EXP1-500/
    • EXP1.XBM
    • [ ... ]
    • EXP500.XBM
  • EXP501-1000/
    • EXP501.XBM
    • [ ... ]
    • EXP1000.XBM
  • EXP1001-1500/
    • EXP1001.XBM
    • [ ... ]
    • EXP1500.XBM
  • EXP1501-2000/
    • EXP1501.XBM
    • [ ... ]
    • EXP2000.XBM
  • EXP2001-2500/
    • EXP2001.XBM
    • [ ... ]
    • EXP2499.XBM

Pretty self-explanatory. The X-Y/CARDZ.XBM files contain the XBM image of each card. Its analogous EXPX-Y/EXPZ.XBM file contains the character definition card.

The file LVL.TXT contains an integer from 1 to 2499 that defines the user "level", that is, the number of cards the user should already know or is studying, and limits the higher reachable card using the device. I still have to think and implement a way to upgrade it: either automatically or by using the buttons/BlueTooth with Android program.

The file HIST.TXT stores a line with the timestamp, an space and the card ID for each card it is displayed. Example:

1458297715 12
1458297730 13
1458296330 22

I don't know what will happen as the file grows up. I will probably make it clean up after each synchronization with the Android program...

Creating the cards

You can skip this if you just use the pre-created images i published.

To create the image of each card I just downloaded and parsed the html table of a website (,,

Then, I created an SQLite database and inserted the parsed data:

CREATE TABLE chinese ( id int, hanzi text, pinyin text, translation text );

Using this databse, I wrote a python program that creates the card images
You can find all of this in the card_generator directory of the gitweb repository.
I published as a matter of curiosity, also you can use it to generate more cards, change its info, font, another language, etc. Maybe i make an online version of the script if i get any requests to do so, which i highly doubt :-).


The initial prototype has a total of 4 buttons:

  • RND: random character. Will display a random character from 1 to the level of the user. I will avoid displaying the current character again.
  • EXP: explain. Will show the card with information for the current character. If pressed again, it will go back to the character card.
  • NEXT: will increase by 1 the current card. If at the end of the list, it will go to 1.
  • PREV: will decrease by 1 the current card. If at the starting of the list, it will go to the last card of the level.

If you found anything useful enough and you want to thank us for that, please consider donating to people who need it, like the NGO OXFAM. Thank you !


Comments are manually approved. Just be a bit patient :-)

There are currently no comments

New Comment


required (not published)


Recent Tweets