Tips for Compiling the Laser Keyboard Software Source Code

I. Introduction

Currently, the full source code of RoboPeak open source laser projection keyboard design has been published on Github. The released source code applies the LGPL license. You can freely use the code and modify it as long as you follow the terms described in LGPL. This article describes how to compile the source code of the  signal processing software for RoboPeak Laser Projection Keyboard on Windows and MacOS systems. Besides, some in-depths implementation details are provided to help you understand the source code and make cool modifications.

Quick Ref:

• Compile the source on Windows
• Compile the source on MacOS
• More details

II.  Reasons to compile the source code

Firstly, compiling the source code allows you to experience the latest features which hasn’t been included in the stable release version yet. You can be the very first personal to trail these cool features.

Secondly, if you want to make some modifications/improvements to the current design, compiling the source code is the first step.

Thirdly, if you find our released signal processing software cannot work on your system, compiling the source code by yourself may be a quick solution before RoboPeak team release bug fix to your issues.

III. Prerequisite

• Windows

Windows XP or higher version

Visual Studio 2010 (with VC++ package installed) or Visual C++ 2010 express (higher version may work as well, but they haven’t been tested yet)

Git Tool support (e.g. msysgit)

• MacOS

OS10.7 or higher (we use OS10.8)

XCode 4.5 or higher with GCC support (we don’t use llvm-gcc)

GIT tool (you can install it using macport or homebrew)

Besides the above requirements, we also assume you have some basic ideas related to software developement: e.g. how to compile a C++ program on Windows/MacOS, what OpenCV is , what GIT is , etc Also, you need to clone the latest source on github.

IV. Compile the source code on Windows

STEP1: clone the source code from github

We recommend you to use tortoise-git to clone the source code to your local folder. The following is an example: or using the following command:

git clone https://github.com/robopeak/laserkbd.git

You should get the following file structure after the clone operation has been finished:

STEP2: Compile the source using VS2010

Enter the laser_kbd_neo folder and open the VS solution file laser_kbd.sln:

To build the source code, simply using the Release configuration and start build. You will find the compiled binary file laser_kbd.exe under the folder: laser_kbd_neoRelease:

STEP3: Copy the essential files to build the working package

The generated executable requires its dependencies to be present in the same folder. You need to copy these dependencies to make the compiled software work. It is recommended to create a clean folder like output under the root of the source code: i.e.   laserkbd_source_rootoutput Copy the above laser_kbd.exe into this folder, and the following files as well:

• laser_kbd_neores folder
• sdkpackrefdll*.dll files

The final package should look like the following:

Done!

The signal processing software build by your own is ready to go now!

V. Compile the source code on MacOS

STEP#1 Clone the source code

Clone the laser keyboard source code to your local folder using the following command:

$ git clone https://github.com/robopeak/laserkbd.git

You should find the following files/folders in the cloned source folder:

Shikais-MacBook-Pro:laserkbd csk$ ls
README.md laser_kbd_neo sdkpack

STEP#2 Compile the source using XCode

Enter the folder laser_kbd_neo/xcode, open the project file: LaserKeyborad.xcodeproj.

You can execute the final workable software package simply click the Run button (for debug version)

VI. Implementation tips

1. file organization

The source code tree is organized based on the following structure:

<source root>
      +---- laser_kbd_neo/            <--- All the source code/IDE project files/3rd party libs src
      |          +---- ref/           <--- source code of the 3rd party libs
      |          +---- res/           <--- image/data required by the software
      |          +---- src/           <--- source code of the signal processing software
      |          |      +---- port/      <--- target platform dependent code
      |          +---- xcode/         <--- MacOS/xcode related code and the project file
      |          |---- laser_kbd.sln  <--- Visual Studio 2010 solution file
      +---- sdkpack
                 +---- license_and_copyrights/   <--- license/readme files of the 3rd party libs
                 +---- ref/
                        +---- dll/               <--- prebuilt dll binaries of the 3rd party libs (win32)
                        +---- lib/               <--- prebuilt static lib binaries of the 3rd party libs (win32)
                        +---- inc/               <--- header source of the 3rd party libs
                        +---- dylib/             <--- prebuilt dll binaries of the 3rd party libs (MacOS)

 

2. How to port the code to other platforms?

The signal processing software is inherently designed with highly portability:

1) all the core logic is implemented as platform independent

2) all the target specific code. is located under the src/port folder

3) there is a clean interface between the platform independent code and the target specific code.

4) all the 3rd libs required by the software are highly portable as well, e.g. OpenCV

If you want to port the code to a new platform, you should implement a new port layer for that platform. The port layer should provide at least the  following functions:

• Key event injection

Inject key events to the target OS when virtual keys is pressed

• Camera video capture and exposure control

As openCV doesn’t provide interface to allow user code to control a camera’s exposure value. The port layer should implement it.

The interfaces to  the target specific code are defined in the header files under the src/port/common folder. If you really want to do the port work, you should start from that place.

Also, the existing Windows and MacOS port layers are good reference for you.

3. how to change the keyboard layout?

The code inside the file src/keyboard_emu/layout_provider.cpp controls the keyboard layout used by the software (the actual keyboard layout projector should be changed as well).

You can modify the _key_mapper[] array to change the layout.

4. how to add sound feedback when a “key” has been pressed?

This feature has been implemented on Windows target.

As the way to playing a sound is target specific, it is recommended to implement the code inside the port layer. Here is the example to show you how to do this on Windows platform.

We use the following Win32 API to play a sound from a given wav file:

BOOL sndPlaySound(
 LPCTSTR lpszSound,
 UINT fuSound
 );

In the example, we choose a wav file called type.wav. When user press “keys”, Windows will play the sound.

The interface OSKeyInjector::injectKeyEvents defined in the port  layer will be invoked when user pressed “keys”. It should be a good place for us to added the sound feedback.

Here is a snapshot of the injectKeyEvents implementation on Windows platform (keyinjector_win32.cpp)

    virtual bool injectKeyEvents( const std::vector<KeyEventDesc> & intputlist)
    {
        if (!intputlist.size()) return false;

        INPUT * inputs = new INPUT[intputlist.size()];

        do
        {
            for (int pos=0; pos<intputlist.size(); ++pos)
            {
                inputs[pos].type = INPUT_KEYBOARD;
                inputs[pos].ki.wVk = intputlist[pos].keyval;

                if (intputlist[pos].type == KEY_EVENT_PRESSED) {
                    hasinputs = true;
                    inputs[pos].ki.dwFlags =  0;
                } else {
                    inputs[pos].ki.dwFlags =  KEYEVENTF_KEYUP;
                }

                inputs[pos].ki.time = 0;
            }

            SendInput(intputlist.size(), inputs, sizeof(INPUT));

        }while(0);

        delete [] inputs;

        return true;
    }

We changed the above code to the following:

    virtual bool injectKeyEvents( const std::vector<KeyEventDesc> & intputlist)
    {
        if (!intputlist.size()) return false;

+        bool hasinputs = false;

        INPUT * inputs = new INPUT[intputlist.size()];

        do
        {
            for (int pos=0; pos<intputlist.size(); ++pos)
            {
                inputs[pos].type = INPUT_KEYBOARD;
                inputs[pos].ki.wVk = intputlist[pos].keyval;

                if (intputlist[pos].type == KEY_EVENT_PRESSED) {
+                    hasinputs = true;
                    inputs[pos].ki.dwFlags =  0;
                } else {
                    inputs[pos].ki.dwFlags =  KEYEVENTF_KEYUP;
                }

                inputs[pos].ki.time = 0;
            }

            SendInput(intputlist.size(), inputs, sizeof(INPUT));

        }while(0);

        delete [] inputs;

+        if (hasinputs && g_config_bundle.playsound) {
+            // play sound feedback
+            std::string soundfile = FILEPATH_RESOURCE_SOUND_FOLDER;
+            soundfile += "type.wav";
+            ::sndPlaySoundA( soundfile.c_str(), SND_ASYNC);
+        }

        return true;
    }

Now the sound feedback feature has been implemented. You may checkout the latest source to have a try:)