Black Lives Matter - Action and Equality. ... Adafruit is open and shipping.

Introducing Emuchron - A Monochron emulator for Debian Linux
Moderators: adafruit_support_bill, adafruit

Please be positive and constructive with your questions and comments.

Introducing Emuchron - A Monochron emulator for Debian Linux

by toinec on Fri Feb 28, 2014 6:53 pm

Introducing Emuchron - A Monochron emulator for Debian Linux

Hi there,

Today I've pushed my software project Emuchron to github.

For detailed information refer to the 80+ pages long installation, configuration and end-user manual "Emuchron_Manual.pdf" in the [support] folder in the github repository.

What is Emuchron?

First some background.
Coding clocks for the Monochron open source clock is (debatable) fun, but has its drawbacks. The main drawback is not being able to properly test clock and graphics code on a functional level. Clocks sometimes seem to hang, the graphics turn out not to be fluid or are simply incorrect.
Up to now the only way to debug a functional clock and graphics functionality is to generate debug output strings from the Monochron clock via the FTDI bus to a terminal application on the connected computer. Although this debug method is useful, it is considered cumbersome and inflexible.

Enter Emuchron, a lightweight Monochron emulator for Debian Linux 6 and 7.

The main feature of Emuchron is to emulate the Monochron hardware and keep the emulator stubs as far away as possible from functional clock code and high-level graphics functions. This allows a programmer to code, debug and test clocks and graphics functions in a controlled Debian Linux environment ahead of uploading firmware to Monochron. Emuchron is controlled via a command line tool dedicated to supporting these development and test features.
Next, effort is put into creating a Monochron clock plugin environment with the aim to reduce efforts for developing new clocks and building Monochron firmware. This is demonstrated by the list of 12(!) clocks built from scratch and a migrated pong clock, all included in the firmware node.
And to enhance the graphic capabilities of Monochron clocks, the high-level glcd graphics library now includes a 5x5 proportional font and new text, area fill and support routines.
Oh, and let me not forget to mention that the firmware also supports a Mario alarm!

Emuchron has been in development since mid-2012 up to early 2014. Lots of time was spent on making Emuchron as robust and stable as possible. If you’re a Monochron clock programmer have a look at it. I hope you like it as much as I do. Feel free to comment and report bugs but be aware that the time I can spend on Emuchron is limited.

I added some screenshots of Emuchron-in-action below.

Use gdb with Nemiver or DDD to debug your clock and glcd graphics code
Emuchron-gdb.png (138.5 KiB) Viewed 1099 times

This is what Emuchron is mostly about. Using gdb and Nemiver as its front-end you're able to debug functional clock code and high-level glcd code.
Once your code has proven to work correctly in Emuchron, use it, unmodified, to build Monochron firmware and upload it to your Monochron clock.
The Monochron LCD stub device shown here is based on the ncurses library.

The firmware also includes a migrated Pong clock
Emuchron-Pong.png (52.99 KiB) Viewed 1099 times

Emuchron introduces a software clock plugin framework to make it easy to add new clocks. The original Pong clock code has been modified to fit this framework. It took about 1 day of efforts to get the basic Pong clock functionality running in Emuchron.
The Monochron LCD stub device shown here is based on the OpenGL2/GLUT library that allows you make the output window as large as wanted while retaining its correct aspect ratio. Your clock will look nice on a 60” screen!
As shown in the command shell, Emuchron can provide statistics on the built-in emulator stub and LCD stub devices.
The command shell of Emuchron is named mchron.
In mchron the user can select clocks, set the clock date and time, emulate the Monochron buttons and alarm switch, and feed a selected clock with a continuous stream of time and keyboard events. A user can prepare mchron commands in a script file that is saved as plain text, after which it can be executed via the mchron command line. This comes in very handy for creating and running test and demo scripts. As the mchron interpreter supports basic repeat capabilities one can easily create scripts to generate all minutes in a day and see how a clock reacts. Many test and demo scripts can be found in the [script] folder of the github repository.

Test your Monochron application prior to uploading it to the actual Monochron clock
Emuchron-Monochron.png (73.45 KiB) Viewed 1099 times

Emuchron also supports a stubbed Monochron application. Test your Monochron application in Emuchron prior to uploading the final firmware to your Monochron clock. The Monochron buttons are stubbed using keyboard keys. As can be seen, the Monochron configuration page can be tested and, if needed, debugged using gdb in combination with Nemiver or DDD.

Posts: 12
Joined: Tue Aug 20, 2013 8:42 am

Re: Introducing Emuchron - A Monochron emulator for Debian L

by af3556 on Sun Aug 03, 2014 7:43 am

This is really awesome work!

I've been using it to play with some changes for my son's clock, while sitting on a train home from work. Firing up the emulator is much quicker than 'make program', and it's easier to balance on the lap too :-)

I've made a small correction for a gcc warning:
emulator/stub.c:631:13: warning: cast from pointer to integer of different size [-Wpointer-to-int-cast]
int > size_t


There's also a similar flex warning, but my flex expertise is zero and don't know how to fix that:
$ make -f MakefileEMU rebuild
bison -o emulator/ -d emulator/expr.y
flex -o emulator/expr.yy.c emulator/expr.l
gcc -g -o mchron -lm -lncurses -lreadline -lglut -lGLU -lpthread emulator/stub.o emulator/lcd.o emulator/lcdglut.o emulator/lcdncurses.o emulator/scanutil.o emulator/mchronutil.o emulator/mchron.o ratt.o ks0108.o glcd.o config.o anim.o clock/analog.o clock/digital.o clock/mosquito.o clock/nerd.o clock/pong.o clock/puzzle.o clock/slider.o clock/spotfire.o clock/cascade.o clock/speeddial.o clock/spiderplot.o clock/trafficlight.o emulator/ emulator/expr.yy.c -lfl
emulator/expr.y: In function ‘exprEvaluate’:
emulator/expr.y:83:9: warning: cast to pointer from integer of different size [-Wint-to-pointer-cast]

And finally, the (amazing!) documentation notes, on p61, that the FTDI/USART interface is set for 38400, but it's actually 19200 (ratt.c:121: uart_init(BRRL_192);).

Posts: 17
Joined: Sat Jul 11, 2009 3:46 am

Re: Introducing Emuchron - A Monochron emulator for Debian L

by toinec on Sat Aug 09, 2014 7:09 pm

Hi Ben,

Thx for your kind words.
I also read your post on requesting to have Emuchron mentioned on the Monochron dev pages (thx!), and the one on your light sensor mod that is based on Emuchron. Very nice!

Regarding the build warnings you're seeing:
Emuchron is built and supported on 32-bit versions of Debian only and the warning you're seeing seem to be caused by building Emuchron on a 64-bit version of Debian.
Yesterday I created a 64-bit Debian 7 VM inVMWare fusion on my Mac in an attempt to replicate the build warnings.
To be honest, I'm quite surprised Emuchron builds on 64-bit Debian, not even mentioning it appears to be working properly! This was certainly not intended, but is a nice surprise.

And yes, I get the same warnings in stubEeprom_read_byte(), stubEeprom_write_byte() and exprEvaluate().
Your int -> size_t change in stub.c provides proper portability between 32-bit or 64-bit, and I'll integrate it in the Emuchron node in time. Thx for that!

The warning in exprEvaluate() however turns out to be more tricky. Flex and Bison generate code and I don't seem to be able to get red of it for now, except by disabling the build warning at mchron link time in MakefileEmu (see below for proof-of-concept). I know, this is only ignoring the symptoms but it's only being used in building the final Bison/Flex object.

# Build project (= emuchron with mchron)
all: $(COBJ) $(BOBJ) $(FOBJ)
$(CC) -g -Wno-int-to-pointer-cast -o $(TARGET) $(CLIB) $(COBJ) $(BOBJ) $(FOBJ) $(FLIB)

Your remark regarding the FTDI/USART interface of 38400 vs 19200 puzzles me a bit.
I'm only able to establish a properly working debug data connection at baudrate 38400 in minicom.
In my case minicom is run in a Debian 6 32-bit VM in both VirtualBox and VMWare Fusion.
The settings were found using trial and error and were documented as such.
Are you able to establish a minicom conn at 19200? If so, can you provide me the settings?

Haven't done much in Emuchron lately, apart from creating an 'encryption clock' for my little nephew (change digit '0' to 'A', '1' to 'B' etc), but started recently on an optimized Mario implementation. Got that to work this morning, saves me ~240 bytes, and should wrap that up in a few weeks. I will then integrate the time_t change as well. By then hope to have a better/proper solution for the Bison warning as well.

Kind regards,

Posts: 12
Joined: Tue Aug 20, 2013 8:42 am

Re: Introducing Emuchron - A Monochron emulator for Debian L

by toinec on Thu Aug 14, 2014 9:14 pm

Hi Ben,

I cherry-picked your int->size_t delta into Emuchron master.

And, I just pushed a proper fix for the bison warning on Debian 64-bit.


Posts: 12
Joined: Tue Aug 20, 2013 8:42 am

Re: Introducing Emuchron - A Monochron emulator for Debian L

by af3556 on Fri Aug 15, 2014 12:00 am

Great, thanks!

Re. the serial (UART) connection: I'm using gnu screen (, as follows:
Code: Select all | TOGGLE FULL SIZE
~% screen /dev/tty.usbserial-AH01CEB9 19200

Screen has worked fine both on a Mac and a i686 Linux box (physical machine, not a VM), with both ftdi and prolific USB-serial devices - with only TX, RX and GND.
Posts: 17
Joined: Sat Jul 11, 2009 3:46 am

Re: Introducing Emuchron - A Monochron emulator for Debian L

by toinec on Tue Aug 19, 2014 7:47 pm

Hi Ben,

Installed and tried screen: on my machine it takes 38400, similar to minicom.
Yes, it's a bit weird.

I'm using an unmodified FTDI Friend v1.1 to hook up my machine to Monochron.
In an upcoming version of the documentation I'll add a note stating that baudrate mileage may vary.

@Adafruit: any thoughts on this?


Posts: 12
Joined: Tue Aug 20, 2013 8:42 am

Please be positive and constructive with your questions and comments.