Setting up the SDK

This page will show you how to set up the FunKey SDK (Software Development Kit) and start developing your own programs for FunKey.

What is the FunKey-SDK?

FunKey is an embedded Linux device with an ARM processor at its core. Programs made for other computers will not work on FunKey, and developing programs on the FunKey itself is rather impractical. Instead, development for embedded devices like FunKey almost always uses a method known as cross compilation: building software on one platform (such as a desktop computer) to be used on another (like FunKey).

The FunKey-SDK contains a cross-compilation environment based on GCC, including the compiler toolchain and the libraries available on the FunKey.

Where can I get the FunKey-SDK?

The FunKey-SDK is included in releases of the FunKey-OS, starting from version 2.0.0, and can be found on GitHub: https://github.com/FunKey-Project/FunKey-OS/releases/.

Build host requirements

The authors of the FunKey-OS and FunKey-SDK have included a detailed Readme file that describes how to set up a machine to build the OS and SDK themselves. We don't need to re-build the OS or SDK as we can just download the latest binaries from the release, but we do need a similarly configured host machine to use the SDK.

The FunKey-SDK is designed to run on a Ubuntu or Debian Linux host, and is tested to work on Ubuntu 20.04 LTS specifically. Other versions or Linux distros may work with some modifications.

If you're working with a different OS you can always run Ubuntu in a Virtual Machine. For those of you familiar with Docker, a specially prepared Dockerfile is made available for you. If you normally work on Windows 10 you can use the Windows Subsystem for Linux 2 to run Ubuntu.

Setting up WSL2

(Based on this guide by Microsoft.)

First, make sure your version of Windows 10 is new enough. Press Win + R to open the Run window and type in winver to check your Windows version and build number. The version should be 1903 or higher, the build number 18362 or higher.

Enable Virtual Machine Platform and Windows Subsystem for Linux.

Enabling Windows Features

Open the Windows Features windows either by searching for "Windows Features" in the Start Menu, or by opening Settings -> Apps & features -> Optional features -> More Windows features. There ensure that both Virtual Machine Platform and Windows Subsystem for Linux are enabled. After pressing OK to confirm, Windows will ask you to reboot your computer to complete installation.

Download the Linux kernel update package

An additional update is required to run WSL2. Download and install the following package from Microsoft:

• WSL2 Linux kernel update package for x64 machines

Set WSL2 as your default version (optional)

You can run the following command in PowerShell to make WSL2 the default version. New installations of Linux distributions on Windows will then automatically use WSL2. Otherwise they will use WSL version 1 by default.

wsl --set-default-version 2

Install Ubuntu using the Microsoft Store

Now that WSL2 is ready to be used you can download a Linux distribution from the Microsoft Store. For this guide, it is recommended to install Ubuntu 20.04 LTS. After installing, Ubuntu can be started by either selecting it from the Start Menu or typing ubuntu2004 on the command prompt. The first time you run Ubuntu you will be asked to create a new user account with a username and password. These do not have to be the same as your Windows account.

If you've enabled WSL2 as the default version in the previous step, Ubuntu will be automatically configured to use that version. If you haven't set WSL2 as default, or if you've installed Ubuntu before setting WSL2 as default, it's possible to manually change the version for this distro. First, open a PowerShell window and type the following command to list all installed Linux distributions:

wsl --list --verbose

Check the name of the distribution you want to upgrade and run:

wsl --set-version <distribution name> <versionNumber>

With <versionNumber> set to 2 to use WSL2. You can use the same command with version number 1 to return to WSL 1.

All done!

Your Ubuntu installation is now ready to be used. Starting Ubuntu from the Start Menu will open a terminal with a Bash prompt. Everything you type here will be executed in Ubuntu. You can run and install applications within Ubuntu as you would on a complete installation or virtual machine. You can access the Windows filesystem via /mnt; the C: drive is mounted as /mnt/c. Windows cannot access the Linux filesystem, including the /home directories, so be sure to copy any files you wish to share from Linux to the Windows filesystem.

Installing the FunKey-SDK

Unpack the .tar.gz file. Before you can use the SDK you must first run the relocate-sdk.sh script. This will update all references paths in the SDK to its current location. If you decide to move the SDK to another directory at a later point, don't forget to re-run the script.

The SDK is now ready to use. For additional convenience it is highly recommended to source the environment-setup of the SDK. This will add the SDK utilities to the $PATH, setup standard variables such as $CC and $LD to refer to the SDK versions of the toolchain, setup standard options for $CFLAGS, and create aliases for configure and cmake to work with the SDK.

Your first application

Building

Let's build a simple application to test that everything is working. Below is a small C program that will use SDL to display a green square for 5 seconds, and then exits.

#include <SDL/SDL.h>

int main(int argc, char *argv[])
{   
    // Init SDL Video
    SDL_Init(SDL_INIT_VIDEO);

    // Open HW screen and set video mode 240x240, with double buffering 
    SDL_Surface* hw_surface =
        SDL_SetVideoMode(240, 240, 32,
                         SDL_HWSURFACE | SDL_DOUBLEBUF | SDL_FULLSCREEN);
    
    // Hide the cursor, FunKey doesn't come with a mouse
    SDL_ShowCursor(0);

    // Draw a green square in the middle of the screen
    SDL_Rect draw_rect = {.x=70, .y=70, .w=100, .h=100};
    Uint32 color = SDL_MapRGB(hw_surface->format, 0, 255, 0);
    SDL_FillRect(hw_surface, &draw_rect, color);
    
    // Switch buffers to show the square we just drew
    SDL_Flip(hw_surface);

    // Sleep for 5 seconds
    SDL_Delay(5000);

    /// Deinit SDL
    SDL_Quit();

    return 0;
}

Save this file as hello.c somewhere outside of the SDK directory. If you've sourced the environment-setup you can use the variable $CC to refer to the C compiler in the SDK. Let's build our program as hello:

$CC hello.c -o hello -lSDL

Packing

The hello program you've just created is a valid executable for FunKey, but in order for the launcher to find it we must first bundle the program in an OPK package. Create a new folder for the contents of the package and put into it:

• The hello program.
• An icon for your program in PNG format, 32 x 32 pixels in size, called hello.png.
• A desktop file called hello.funkey-s.desktop, containing the following text:

[Desktop Entry]
Type=Application
Name=Hello
Comment=A simple test app
Exec=hello
Icon=hello
Terminal=false
Categories=applications;

This file describes your program to the launcher:

• Type: Always set to "Application"
• Name: This is the name of the application shown in the launcher
• Comment: A description of the application
• Exec: This the command to execute your program
• Icon: The name of the icon file, without the .png extension
• Terminal: Always set to false, FunKey doesn't support terminal applications
• Categories: The categories under which the launcher will show the application, in a semicolon-separated list

Once you've got everything ready you can turn the folder into a package using the OpenPackage Creator. Select your folder with the Open button, or drag it over the window. The OpenPackage Creator will note that you've already created .desktop file. Choose the "Use existing as is" option. Finally, click the Pack button to create hello.opk, ready to be transferred to the FunKey.

Installing

Connect the FunKey to your computer via USB. Open the menu on the FunKey, select Mount USB and press A twice to confirm. Your FunKey will now be visible as a USB drive on your computer. You can place your application in any 1st-level folder, and you can create as many as you want to organise your applications. Let's create a new folder called Applications and place hello.opk in there. Safely remove the USB drive from your computer, and in the FunKey menu select Eject USB and press A twice to confirm.

Your application is now installed on FunKey. Note that only the GMENU2X launcher can open custom applications. So switch to that launcher via the FunKey menu if you haven't already. You should find an application called Hello under the applications category in the launcher.