Load and Display Text on the LCD of a LinkIt™ Assist 2502 development board

Introduction

This project uses the MediaTek LinkIt™ Assist 2502 development board’s communication features to load and display text on an LCD display.

This tutorial guides you through:

  • Building the prototype, with details of the hardware requirements and how to put them together to run the project.
  • Creating the software to provide the interfaces to load and display data on the LCD screen.

At the end of the tutorial there are details on where to go for additional information on the LinkIt Assist 2502 development board and how to create software for it.

Before You Start

If you haven't built a LinkIt Assist 2502 project before, you'll need to setup your development environment. Full details can be found in the LinkIt Assist 2502 Developer’s Guide. Complete this before you continue.

Create The Software

This section describes how to create the software required as follows:

  • Create a LinkIt Assist 2502 project in the Eclipse IDE.
  • Add text resource to the Eclipse IDE.
  • Add a font file to the LinkIt Assist 2502 development board.
  • Find the size of the .ttf file.
  • Modify your application so it displays text.

Creating an Assist 2502 project in the Eclipse IDE

The LinkIt Assist 2502 SDK 2.0 provides example application projects that could serve as a reference implementation for your application development. The example projects are grouped by folder under {SDK_installation_path}\examples\API. In this tutorial you’ll create a project to load and display text on LinkIt Assist 2502 development board. To create the project Graphic_LoadFont, follow these steps:

  1. Launch the Eclipse IDE.
  2. In the Eclipse IDE File menu point to New and click Other to display the project wizard.
  3. Expand the LinkIt Assist 2502 SDK 2.0 Example folder, select Example Application (*.vxp) and click Next, as shown below.
  4. Provide the Project Name and select the Hardware Platform, as shown below. You can modify the default settings or keep as they are. ClickNext to continue the setup.
  5. A list of example applications (on the left) and their descriptions (on the right) appear in the  LinkIt Assist 2502 SDK 2.0 Example Wizard , as shown below. Select the  Graphic_LoadFont  project and click  Finish  to open the application.

     

    You’ve now successfully loaded the example application in your Eclipse IDE. Next you’ll add a source file to display on your LinkIt Assist 2502 board.  

Defining the Strings

To display content on your development board, you need to embed string APIs in your Eclipse IDE. Once the resource is available, you can apply it using a reference to the resource ID. The string resource is created in the Resource Editor and included in the application  .vxp  file as part of the build process. During the runtime, functions of the Resource module search for the address of the given resource ID, load the content of the resource into the target device’s RAM and report the RAM address to the application. Then the string is displayed on the LCD screen. To embed the string resource, you can either use a pre-built string resource or define your own. 

Embedding a pre-built string resource

  1. Click the  Resource Editor , as shown below. 
  2. Click  Strings  on the left side of the  Resource Editor . There is already one string resource in the  Graphic_loadFont  example project with its ID  Resource Type  Description  and language options such as  English  Si_Chinese  and  Tr_Chinese , as shown below. 
     
    You’ll use the resource ID  STR_ID_HELLO  in your source code to display the text in the languages defined for this resource ID — such as English, Simplified Chinese and Traditional Chinese — on your LinkIt Assist 2502 development board’s LCD screen.

Adding a new language to an existing resource 

In this example, you’ll add a new language to an existing resource in the Resource Editor, and modify the related API parameter to get this string by its resource ID.

  1. Click the Resource Editor.
  2. Click Strings on the left side of the Resource Editor. The existing resource strings will be displayed. Point to the STR_ID_HELLO string resource.
  3. Right click on STR_ID_HELLO and then select Language.
  4. The Language  and its corresponding  ID  will be displayed, as shown below. 
     

Select the language items to use in your application development. The parameter ID is used in the source code of your application to initialize the resource. Open the  LoadFont.c  source file and replace the input parameter to the function  vm_res_init(86)  according to your needs at:

/* The callback to be invoked by the system engine. */
void handle_sysevt(VMINT message, VMINT param) {
    switch (message) {
    case VM_EVENT_CREATE:
        vm_res_init(86);    /* Initiate resource as Simple Chinese */
        break;
    case VM_EVENT_PAINT:
        draw_hello();
        break;
    case VM_EVENT_QUIT:
        vm_res_release();
 
        break;
    }
}

Note

Make sure to have the corresponding font file loaded on the target device, otherwise the string won’t display correctly after uploading your code.

Adding a new string resource

To add a user defined string resource in the Resource Editor:

  1. Click New and name the string STR_ID_TEST. Define the Resource Type and Description.
  2. Add language to your resource file, see Adding a new language to an existing resource. Define the fields under EnglishSi_Chinese and Tr_Chinese, as shown below.
  3. Define 联发科创意实验室 under the Si_Chinese and Tr_Chinese fields.
  4. Open LoadFont.c and update the input parameter of the vm_res_get_string() function, as shown below:

    string = vm_res_get_string(STR_ID_TEST, &size);

    This API gets the string item defined in the  Resource Editor  by its resource ID. If there are multiple languages defined in the string table, the language passed to the  vm_res_init()  will be used, as described in adding a new language .

Adding a font file to the LinkIt Assist 2502 development board

The LinkIt Assist 2502 SDK provides supported fonts (.ttf) files in the LINKIT_ASSIST_SDK\custom\VectorFont\Etrump folder, as shown below:

The folder contains seven font families; MTKYH2312F.ttf and MTKYHBIG5F.ttf correspond to Chinese fonts. You’ll useMTKYH2312F.ttf in this project to display the Chinese content.

To copy the MTKYH2312F.ttf font file to your board as follows:

  1. Connect the board to your PC using a USB cable.
  2. Navigate to Computer on your PC. The LinkIt Assist 2502 will appear as a Removable Disk drive under Devices with Removable Storage, as shown below.
  3. Copy MTKYH2312F.ttf to the root directory of the removable storage.

Finding the size of the .ttf file

Before commencing the application implementation, determine the size in bytes of the font file used in the project.

  1. Navigate to the LINKIT_ASSIST_SDK\tools\VectorFont\CheckEtrumpMemSize folder.
  2. Copy the MTKYH2312F.ttf font file.
  3. Open the command window on your PC and run the following command.

    C:\lxsSW\0-ONE2.0\MediaTek_LinkIt_Assist_2502_SDK_2_0_46\LINKIT_ASSIST_SDK\tools
    \VectorFont\CheckEtrumpMemSize>CheckEtrumpMemSize.exe MTKYH2312F.ttf 
    MTKYH2312F.ttf : 39987 bytes

    The result is 39987 bytes for the  MTKYH2312F.ttf  file.

 Modifying your application  

Launch the application project in the Eclipse IDE, open the LoadFont.c source file then modify the macro value EXTERNAL_FONT_SIZE and EXTERNAL_FONT_PATH, as shown below (lines 40 and 42):

#define SCREEN_WIDTH 240 
#define SCREEN_HEIGHT 240 
#define EXTERNAL_FONT_SIZE 39987 /* external font size calculated by CheckMemSize.exe tool, 32 * 1024 */
#define FONT_CACHE_SIZE 131072 /* 128 * 1024 */ 
#define EXTERNAL_FONT_PATH "C:\\MTKYH2312F.ttf" 
#define FONT_PATH_MAX_LENGTH 40
The  EXTERNAL_FONT_SIZE  is the font file size calculated in  Finding the size of the .ttf file . And the  EXTERNAL_FONT_PATH  is the path to the root directory of the board; it’s  C:\\MTKYH2312F.ttf in this example. Once the parameters are configured, click  Build  to build the application in the Eclipse IDE, as shown below.

You can now connect your board and view the result. 

Running Your Application

To run the application on your LinkIt Assist 2502 development board, do the following: 

  1. Connect the battery to the board.
  2. Connect the board to your PC with a USB cable.
  3. Press the PWR key, located on the side of the board, for 3 seconds to boot-up the device.
    1. The output from the application using the Simplified Chinese fonts with vm_res_init(86) will be displayed on the LCD screen, like this:
    2. The output from the application using the English fonts with  vm_res_init(44)  will be displayed on the LCD screen, like this:
       

    3. The output from the application using the Traditional Chinese fonts with  vm_res_init(886)  will be displayed on the LCD screen, like this: 

    4. The first character isn’t displayed correctly as the loaded font on the target device doesn’t include the traditional Chinese fonts. Current file on the board is MTKYH2312F.ttf.

    5. The output from the application using the Si_Chinese with vm_res_init(86) and a newly defined string will be displayed on the LCD screen, like this:

Displaying content from a real-time resource

Content can be displayed only if there is a supporting font file loaded on the target Assist 2502 device. You can also display any text on the device, if it’s defined in the vm_graphic_draw_text() function. If the text is not in UCS-2 format, it needs to be properly formatted before sending it to the display. For example, to display “联发科技” on Assist 2502, apply the UCS-2 code chart to the string to obtain the HEX format 5480 D153 D179 8062, then assign the parameters of the vm_graphic_draw_text() function as follows:

vm_graphic_draw_text(&frame, 1, 1, "\x54\x80\xD1\x53\xD1\x79\x80\x62");

The parameters and their description are shown below.

ParameterValueDescription
vm_graphic_frame_t* frame&frame[IN] Frame pointer
VMINT x1[IN] X offset of start position
VMINT y1[IN] Y offset of start position
VMWSTR text"\x54\x80\xD1\x53\xD1\x79\x80\x62"[IN] Text encoded using UCS-2 format

The result looks like this:

Full Source Code

The full source code of the implementation is as follows:

#include "vmtype.h" 
#include "vmstdlib.h"
#include "vmlog.h"
#include "vmwdt.h"
#include "vmgraphic.h"
#include "vmsystem.h"
 
#include "ResID.h"
#include "vmchset.h"
#include "vmgraphic_font.h"
#include "lcd_sitronix_st7789s.h"
#include "vmdcl.h"
#include "vmdcl_gpio.h"
#include "vmdcl_pwm.h"
 
#define SCREEN_WIDTH 240
#define SCREEN_HEIGHT   240
#define EXTERNAL_FONT_SIZE  39987
#define FONT_CACHE_SIZE     131072
#define EXTERNAL_FONT_PATH  "C:\\MTKYH2312F.ttf"
#define FONT_PATH_MAX_LENGTH    40
 
#if defined(__HDK_LINKIT_ONE_V1__)
#define BACKLIGHT_PIN  VM_PIN_D1
#elif defined(__HDK_LINKIT_ASSIST_2502__)
#define BACKLIGHT_PIN VM_PIN_P1
#else
#error " Board not support"
#endif
 
VMUINT8 *font_pool;
 
/* Set font and draw hello world text */
static void draw_hello(void) {
    vm_graphic_color_argb_t color;
    vm_graphic_frame_t frame;
    vm_graphic_frame_t* frame_group[1];
    VMWCHAR font_path[FONT_PATH_MAX_LENGTH + 1];
    VMWSTR font_paths_group[1];
    VM_RESULT result;
    VMUINT32 pool_size;
    VMUINT32 size;
 
    vm_graphic_point_t positions[1] = {0, 0};
 
    frame.buffer_length = SCREEN_WIDTH * SCREEN_HEIGHT * 2;
    frame.buffer = vm_malloc_dma(frame.buffer_length);
    if(frame.buffer == NULL)
    {
        return;
    }
 
    frame.color_format = VM_GRAPHIC_COLOR_FORMAT_16_BIT;
    frame.height = SCREEN_HEIGHT;
    frame.width = SCREEN_WIDTH;
    frame_group[0] = &frame;
     
    color.a = 255;
    color.r = 243;
    color.g = 154;
    color.b = 30;
    vm_graphic_set_color(color);
    vm_graphic_draw_solid_rectangle(&frame, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT);
 
    result = vm_graphic_get_font_pool_size(EXTERNAL_FONT_SIZE, 1, FONT_CACHE_SIZE, &pool_size);
    if(VM_IS_SUCCEEDED(result))
    {
        font_pool = vm_malloc(pool_size);
        if(NULL != font_pool)
        {
            result = vm_graphic_init_font_pool(font_pool, pool_size);
        }
        else
        {
            vm_log_info("allocate font pool memory failed");
            return;
        }
    }
    if(!(VM_IS_SUCCEEDED(result)))
    {
        vm_log_info("init font pool failed");
        return;
    }
    vm_chset_ascii_to_ucs2(font_path, (FONT_PATH_MAX_LENGTH + 1) * 2, EXTERNAL_FONT_PATH);
    font_paths_group[0] = font_path;
    vm_graphic_reset_font();
    result = vm_graphic_set_font(font_paths_group, 1);
    if(!(VM_IS_SUCCEEDED(result)))
    {
        vm_log_info("set font failed");
    }
 
    color.r = 255;
    color.g = 255;
    color.b = 255;
    vm_graphic_set_color(color);
    vm_graphic_set_font_size(VM_GRAPHIC_LARGE_FONT);
    vm_graphic_draw_text(&frame, 1, 1, "\x54\x80\xD1\x53\xD1\x79\x80\x62");
#if defined(__HDK_LINKIT_ASSIST_2502__)
    vm_graphic_blt_frame(frame_group, positions, 1);
#endif
    vm_free(frame.buffer);
    vm_free(font_pool);
    font_pool = NULL;
}
 
/* The callback to be invoked by the system engine. */
void handle_sysevt(VMINT message, VMINT param) {
    switch (message) {
    case VM_EVENT_CREATE:
        vm_res_init(86);    /* Initiate resource as Simple Chinese */
        break;
    case VM_EVENT_PAINT:
        draw_hello();
        break;
    case VM_EVENT_QUIT:
        vm_res_release();
 
        break;
    }
}
 
void lcd_backlight_level(VMUINT32 ulValue) {
 
      VM_DCL_HANDLE pwm_handle;
      vm_dcl_pwm_set_clock_t pwm_clock;
      vm_dcl_pwm_set_counter_threshold_t pwm_config_adv;
 
      vm_dcl_config_pin_mode(BACKLIGHT_PIN, VM_DCL_PIN_MODE_PWM);
 
      pwm_handle = vm_dcl_open(PIN2PWM(BACKLIGHT_PIN),vm_dcl_get_owner_id());
      vm_dcl_control(pwm_handle,VM_PWM_CMD_START,0);
      pwm_config_adv.counter = 100;
      pwm_config_adv.threshold = ulValue;
      pwm_clock.source_clock = 0;
      pwm_clock.source_clock_division =3;
      vm_dcl_control(pwm_handle,VM_PWM_CMD_SET_CLOCK,(void *)(&pwm_clock));
      vm_dcl_control(pwm_handle,VM_PWM_CMD_SET_COUNTER_AND_THRESHOLD,(void *)(&pwm_config_adv));
      vm_dcl_close(pwm_handle);
}
 
/* Entry point */
void vm_main(void) {
#if defined(__HDK_LINKIT_ASSIST_2502__)
    lcd_st7789s_init();
    lcd_backlight_level(60);
#endif
    vm_pmng_register_system_event_callback(handle_sysevt);
}

Conclusion

You’ve now successfully displayed Chinese text on your LinkIt Assist 2502’s LCD. For more information on the MediaTek LinkIt Assist 2502 development and prototyping board refer to LinkIt Assist 2502 developer’s guide. 

FAQ 

How do I change the font size?

The font file uploaded to the Assist 2502 development board determines the font style. Call the vm_graphic_set_font_size()function to assign a new font size. This function is used in the LoadFont.c example code. There are three text sizes to choose from: VM_GRAPHIC_SMALL_FONT, VM_GRAPHIC_MEDIUM_FONT and VM_GRAPHIC_LARGE_FONT. To change the font size simply set the input parameter to the vm_graphic_set_font_size() function with one of these options.

How do I change the position of the text?

As this example shows, all the text began displaying from the left top of the screen. You can set the position that the text is displayed in by setting the 2nd and 3rd parameters of the vm_graphic_draw_text() function. These two parameters represent the horizontal and vertical start position of the text. Please note the screen size is 240 * 240 pixels. In order to display the text on the screen, the value of these two parameters should be smaller than 240.