Using emWin's QR-Code functions – KBA231613

Version 3

    Author: LePo_1062026        Version: **

     

    Translation - Japanese: emWinのQRコード機能の使用 – KBA231613 - Community Translated (JA)

     

    The SEGGER emWin library can be used with PSoC® devices to create GUI elements in displays. Version 5.34 added the ability for the user to easily construct QR codes on GUI displays.

     

    They simplified the API calls to four functions:

    • GUI_QR_Create() – Create the RAM-based structure of the QR Code. Note: To provide the best contrast for reading QR Codes, use a light (white) background color.
    • GUI_QR_Delete() - Delete the RAM-based structure of the QR code.
    • GUI_QR_Draw() – Draw the RAM-based structure of the QR code on the display.
    • GUI_QR_GetInfo() – Get physical information about the QR code.

     

      See the emWin User Guide & Reference Manual for details.

    RAM Allocation for the GUI’s Pool Memory:

                                   

    QR-Code generation may require significant RAM resources.  Here are the factors that require more RAM:

     

    • Larger content to encode requires more RAM i.e., short text strings utilize less RAM; longer text strings need more RAM.
    • Number of pixels used in a QR ‘module’.  The ‘Module’ is square logic encoding element.
    • ECC level.  Higher error correction levels will require a larger QR bitmap.
    • A higher ‘Version’ can indirectly require more RAM.  It is usually common to use Version=0 to auto-detect the Version needed based on content.

     

    To make sure that you have enough GUI RAM memory available, set the #define GUI_NUMBYTES in GUIConf.h. Segger recommends setting this value to 0x10000 at a minimum.  This will allocate the GUI pool RAM memory for the entire library and be used for the QR-codes as well as other GUI functions as needed.

     

    If this amount of RAM is more than your application requires, allocate the maximum you can provide. As the next step, during the development phase, run your application with as many display varying use cases as you can. Include the GUI_ALLOC_GetMaxUsedBytes() function to get the run-time peak count of the GUI RAM used in your application. The GUI_NUMBYTES value can be modified with this maximum value (plus 10% as a precaution).

     

    Note:  Typically, if enough RAM is not allocated for the emWin library, it may crash with a SysLib fault.

     

    Example Code:

     

    #include "GUI.h"

     

    /* This example is a simple QR-Code generation that places it in the bottom-right corner of the display.

    A ‘Module’ is the QR definition of the smallest logic element.  The size of the ‘Module’ is how many pixels (in one dimension) used.  This size is used for both ‘X’ and ‘Y’ dimensions.

    */

        GUI_HMEM qrCode = GUI_QR_Create(

    “This is a text string.  It could be a URL address”,

    //UTF-8 text to be used for the QR-code

          2, // Define the one-dimensional pixel size for the 'Module' size.

          GUI_QR_ECLEVEL_H// ECC level.  A higher level will allow for better error correction.

          0 );  // The QR 'Version' encoding style.  A value of 0 will autodetect what is needed.

     

    /*  Now that the QRCode is virtually created, get its' dimensional info.  Use GUI_QR_GetInfo(). */

    GUI_QR_INFO pInfo;

        GUI_QR_GetInfo(

        qrCode,     //Handle of the QR-code to be drawn.

        &pInfo);    // pointer to the memory of the QR info structure.

     

    /* Use the QR info to determine the size of the QRCode in one dimension (pInfo.Size).  To place it in the bottom-right corner, substract it from the display's X and Y size */

        GUI_QR_Draw(

        qrCode,                     //Handle of the QR-code to be drawn.

        LCD_GetXSize()-pInfo.Size,  //Subtract the one-dimensional size of the bitmap from the display's X size.

        LCD_GetYSize()-pInfo.Size); //Subtract the one-dimensional size of the bitmap from the display's Y size.

     

        GUI_QR_Delete(qrCode);  //Handle of the QR-code to be drawn.  This is no longer needed.  Free the GUI RAM allocated.

      

    /* Depending on the display you are using (such as the EINK), it may require an update function.  Others may be automatically updated. */

        /* Send the display buffer data to display*/

        UpdateDisplay(CY_EINK_FULL_4STAGE, true);   // Update the display.

     

    See the example on Segger’s Wiki page: https://wiki.segger.com/QR_Code_(Sample)

     

    The attached PSoC Creator™ and ModusToolbox® projects show the display effects of the setting of the different GUI_QR_Create() parameters.