LcdBoost library for Netduino

Introduction.

This article show a concrete application of the circuit presented in my previous post.
Although the hacking is something versatile, it has been focused on driving LCD modules in general.
Here is a presentation of a small yet powerful library to simplify the graphic management, even having few memory resources.

Hardware.

There’s almost no changes from the circuit shown in my past article: just some improvement, which has been tested over two-three different kinds of LCD modules. Every time, with no problems.

For my convenience, I created the circuit on a piece of proto-board. I know, it’s not the best solution I could do, but it seems working okay. It’s easy to connect, and it leaves the Netduino pins free for further extensions.

I just added a transistor more, to drive the LCD backlight, where available. Nothing special, but it came almost for free, because luckily on the same Netduino connector there’s a PWM output also.
By the way, there’s no power supply, and most of the LCDs are using the old, faithful, +5VDC. Thus, I used a dedicated connector, using the same pinout as the *duino like connector. It means almost nothing, but it’s worthwhile keeping almost the same pinout pattern, as for convention.
Moreover, this separate power connector yields to a dedicate power supply, instead of overloading the Netduino’s embedded regulator.

Software.

Having a very fast data transfer offers the possibility to structure the library better. Abstraction is asking often a little more of memory resources, but also yields to a better integration of modules. The result is somewhat amazing, at least for a managed device as Netduino is.

First off, I wanted to separate the two layers involved in the UI: the physical and the logical. The physical layer is meant as the “driver”, which actually knows how is the LCD module, its features, and much more. The logical layer should not know anything about the hardware, instead has to organize the user’s API at best, so the user will find comfortable interacting with any display.
Of course this is just the goal: we must bear in mind that never ever will achieve a WPF-like APIs.

Secondly, I wished to offer the APIs in two flavors. Okay, the library is actually the same, but the user can choose to access the display in a imperative-way, or in a declarative-way. However, you can mix all that: no exclusivity at all.

The imperative way is the most intuitive (really?), which came from our childhood. Most of the personal computer had no enough resources, and the “do this”/”do that” programming manner became the most famous. Both the code samples contained in my old post about LCD driving with SPI, are shaped in the imperative fashion.
The declarative way is much more powerful, elegant, and -I’d add- intuitive. Instead of polluting our code with specific actions, let’s declare a bunch of “object”, which we’ll interact with. Each object has its own properties, along with methods. Isn’t sounding familiar?
Further I’ll show a small example of using the LcdBoost library, taking advantage of its declarative APIs.

How is this library made?

As stated, the library is designed to be a “satellite” project to be linked to your own application. You shouldn’t copy-and-paste modules, which leads to errors, and misalignment.
The user interact normally with the logical layer, although it can access the specific physical layer wherever some custom chip-tailored function should be performed. For instance, often the LCD modules are based on the Hitachi HD44780 chip, which offers a character pattern customization. This feature is specific for that chip, thus should be accessed directly to the driver instance.
Also, the library is meant to be improved, and extended. Both the logical and the physical layers are structured to be easily extended. Physical drivers are pluggable, and the logical graphic entities are also pluggables.
At the moment of writing this post, there’s only support for character matrix LCD modules. I’d like to drive some dot-matrix module, but I’m not sure to be able to do it.

The imperative access consists in just three methods:

        /// <summary>
        /// Clear the entire screen
        /// </summary>
        public void Clear()
        {
            // ...
        }


        /// <summary>
        /// Set the starting (reference) position
        /// to be used by any further text operation
        /// </summary>
        /// <param name="x"></param>
        /// <param name="y"></param>
        public void SetCursorPosition(
            int x,
            int y
            )
        {
            // ...
        }


        /// <summary>
        /// Write a text string (as plain ASCII) on the video cache
        /// </summary>
        /// <param name="text">The string to be written</param>
        /// <remarks>
        /// The text starting reference has to be set by using the <see cref="SetCursorPosition"/>.
        /// After this call, the logical position is moved accordingly
        /// </remarks>
        public void Write(string text)
        {
            // ...
        }

It’s really the minimum, and -honestly- I would not care so much, in favor of the declarative APIs (which I’m proud of!)

Okay, I’m a big fan of WPF, thus I *tried* to mimic that approach. The problem is that WPF would require *TONS* of memory, plus several parts of the regular framework, not implemented in the .Net Micro Framework.
So, the declarative API allow to operate with objects, which must implement a common interface:

namespace Toolbox.NETMF.Hardware
{
    /// <summary>
    /// Fundamental interface for implementing any graphic element
    /// to be managed in the declarative-way by the LcdBoos library
    /// </summary>
    public interface ILcdBoostElement
    {
        /// <summary>
        /// Indicates whether the graphic element is hidden or not
        /// </summary>
        bool IsHidden { get; }

        /// <summary>
        /// Renders the element's cache onto the video viewport
        /// </summary>
        /// <param name="cache">The target video cache to be filled</param>
        /// <param name="container">The parent container bounding rectangle</param>
        void Render(
            LcdBoostVideoCache cache,
            LcdBoostRect container
            );
    }
}

The library comes with just two “renderable” objects (so far):

It’s clearly limited to the character-matrix modules, but surely enough at first attempt.
Again, the LcdBoostElementCharPoint is a particular case of the more generic LcdBoostElementTextArea. It has been tailored for a single character entity, but is performing much better due the fewer calculations.

Performance.

Well, I had hard time to believe my eyes: the rendering is blazing fast. The physical driver has been improved several times, always within a compromise of performance and readability.
I must admit that the only result I have are for character matrix display, all based on the Hitachi HD44780 chip. The “practical” result is that the slowest part is surely the LCD itself, but…I mean the *real* LCD: the crystals! It looks that the crystal inertia is so huge, that you can reach 2-3 fps. At this point, the Netduino speed is a minor problem.

Anyway, here is a couple of snapshots taken with the scope.
The first one shows the overall rendering process (logic arrangement, plus physical transfer), along the timer cycle (100ms). The high-level interval is the actual busy period.

The second picture (below) is showing the physical transfer time via SPI. Since my display is a 20×4 character matrix, the transfer is accomplished on two sequential steps. The overall transfer takes less than 20 ms.

NOTE: the timing of the pictures is based on the demo game presented below.

A simple demo game.

To be attractive, a sample should be something funny.
Here is a simple pong-like game. The game itself has no meaning: using a 20×4 display is still playable with difficulty.
The interesting thing is how readable is the code, and how simple is creating even complex tasks. I’d also add that a similar approach will probably improve both efficiency, and compactness of the resulting code.
Do you have ever programmed any XNA game?
Well, the concept is quite simple: declare your resources (e.g. bitmaps, sounds, etc), then add the game logic. All the life is hanging to a “loop” which renders the game scenery. Here is the same.
Just add your ILcdBoostElement-derived elements to an array, that will be you resource-bag to be rendered. Afterward, the actual rendering will be performed automatically within a timed loop.

namespace Toolbox.NETMF.Hardware
{
    /// <summary>
    /// A demo of a simple pong-like game
    /// </summary>
    /// <remarks>
    /// The aim of the demo is demonstrating how simpler is
    /// creating even pretty complex games, by taking advantage
    /// of the declarative approach, instead of the imperative one.
    /// 
    /// The paddle is controlled by any numeric port
    /// 
    /// NOTE: although this demo can work on any lcd size,
    /// has been tailored for a 20x4 char matrix LCD module
    /// </remarks>
    class DemoPong
    {
        private const int BrickRows = 2;
        private const int BrickColumns = 16;
        private const int TotalBricks = BrickRows * BrickColumns;

        private const int AvailablePaddles = 5;

        private static LcdBoostElementCharPoint[][] _elem_bricks;
        private static LcdBoostElementTextArea _elem_paddle;
        private static LcdBoostElementTextArea _elem_score;
        private static LcdBoostElementTextArea _elem_paddles_left;
        private static LcdBoostElementCharPoint _elem_ball;
        private static LcdBoostElementTextArea _elem_gameover;

        private static Random _rnd;


        public static void Run(
            LcdBoostProxy lcd,
            NumericInput paddle)
        {
            //init the random number generator using a pseudo random seed
            _rnd = new Random(DateTime.Now.Millisecond);

            //define an array for containing all the UI-elements
            var elements = new ILcdBoostElement[TotalBricks + 6];
            var elem_count = 0;

            /**
             * Allocates the resources to be used in the program
             * this is very similar to the "sprite" approach
             **/

            //right-side wall
            var wall = new LcdBoostElementTextArea();
            wall.Text = "||||";
            wall.Bounds.Left = 16;
            wall.Bounds.Top = 0;
            wall.Bounds.Width = 1;
            wall.Bounds.Height = 4;
            elements[elem_count++] = wall;


            // ...


            /**
             * Create a new session of game.
             * The session contains only the dynamic data used
             * by the game. The logic is meant to be outside.
             * That's much like a functional approach
             **/
            var session = new GameSession();
            session.NewBall();


            /**
             * Master clock for the game refresh
             * 
             * Notice that the clock is handling the display refresh
             * at 10 fps, but the game logic has to be slowed down
             * because would be too fast to play
             **/
            int clock_counter = 0;
            var clock = new Timer(
                _ =>
                {
                    //invoke the game logic
                    Worker(
                        session,
                        clock_counter++
                        );

                    //refresh display
                    lcd.Dump(elements);
                },
                null,
                100,
                100);


            Thread.Sleep(Timeout.Infinite);
        }


        /// <summary>
        /// The game logic
        /// </summary>
        /// <param name="session"></param>
        /// <param name="clock_counter"></param>
        private static void Worker(
            GameSession session,
            int clock_counter)
        {
            //stop logic when there'are no more paddles left
            if (session.PaddlesLeft <= 0)
                return;

            //timer scaling to slow down the game logic
            if ((clock_counter & 0x07) != 0)
                return;

            //retrieve the current ball coords
            int x = _elem_ball.X;
            int y = _elem_ball.Y;

            // ...

        }


        /// <summary>
        /// 
        /// </summary>
        private class GameSession
        {
            /// <summary>
            /// Overall score
            /// </summary>
            public int Score;

            /// <summary>
            /// Paddles left
            /// </summary>
            public int PaddlesLeft = AvailablePaddles;

            /// <summary>
            /// 2D vector defining the ball speed
            /// </summary>
            public readonly Vector BallSpeed = new Vector();


            /// <summary>
            /// Init for a new incoming ball
            /// </summary>
            public void NewBall()
            {
                int n = _rnd.Next(10000);

                //gets the new ball position
                _elem_ball.X = 2 + n % 12;
                _elem_ball.Y = 0;

                //gets the new ball speed
                this.BallSpeed.DX = n < 5000 ? -1 : 1;
                this.BallSpeed.DY = 1;

                //update the paddles left box
                _elem_paddles_left.Text = "_" + this.PaddlesLeft.ToString() + "_";
            }
        }


        /// <summary>
        /// Simple class for defining a 2D vector
        /// </summary>
        private class Vector
        {
            public int DX;
            public int DY;

            public void InvertX()
            {
                this.DX = -this.DX;
            }

            public void InvertY()
            {
                this.DY = -this.DY;
            }
        }

    }
}

As seen previously, in the performance section, the rendering loop is timed to refresh the display on every 100 ms, that is 10 fps. It’s fairly poor as it were a normal video game, but it’s indeed too fast to be playable. Thus, the logic update has been scaled down of a factor of 8.

The paddle controller deserves a word of mention.

The poor-man game controller

In any decent arcade game, the controller is an important component. However, I’m not going to produce video-consoles, nor focusing on the comparison on game controllers. I just needed a quick-and-dirty way to move the paddle for my pong-like game, but…I also realized that I hadn’t anything fitting the goal.
So, I took my bag of trashy stuffs, carefully collected by my (poor) dad, and I began digging. The most obvious thing is the last to be considered: why not a normal brushed motor? My dad had dozen of small motors, so I got one of them, probably originally built on a old tape-deck.
The circuit is somewhat ridiculous: just a 1/2 voltage divider, and the motor. Okay, I’ve seen that a capacitor is a good way to get the reading more stable.

The voltage divider just creates an halfway voltage, so that the working point for the ADC is about in the middle of the range. As stated, the capacitor yields more stability to this voltage point. Finally, the motor is connected from this voltage divider, and any Netduino analog input.
When you take the motor spinning by using fingers, it works actually as a dynamo, and produces a little voltage. This voltage can be either positive or negative respect to the voltage divider point. The software samples the analog input periodically, and converts the samples accordingly.

As long you don’t get the motor spinning fast, there’s no danger at all.

Conclusions.

Once again, Netduino does it better.
It’s just another little piece of knowledge to get you working better with Netduino, and the .Net Micro Framework. Sometime the solution isn’t coming quickly as expected, but collecting experience helps a lot.

Future goals is hacking the new gaming console Netduino-based: the PIX-6T4, by Nwazet.

The library is part of the Cet Open Toolbox, and can be downloaded together with schematics and Fritzing diagrams.