HelloWorld - Introduction to UNA App Architecture

Welcome to the UNA SDK tutorial series! HelloWorld is your first step in learning to build applications for the UNA Watch platform. This tutorial focuses on the fundamental app architecture - how service and GUI components communicate - without the complexity of sensors or data logging.

Project Folder

HelloWorld comes with two GUIs that show the same screen: one built with TouchGFX, one with LVGL. The service, the message contract and the build system are the same for both; only the GUI process differs. Pick the toolkit you prefer and follow that column through the series. The two are shown side by side so you can also compare them.

What You’ll Learn

How to set up your development environment for UNA apps
The basic structure of a UNA Watch application
How service and GUI layers communicate
How to build and run apps on simulator and hardware
How the same GUI is expressed in TouchGFX and in LVGL
Understanding the UNA app framework fundamentals

Getting Started

Prerequisites

Before building HelloWorld, you need to set up the UNA SDK environment. Follow the toolchain setup for complete installation instructions, including:

UNA SDK cloned (git clone https://github.com/UNAWatch/una-sdk.git)
ST ARM GCC Toolchain (from STM32CubeIDE/CubeCLT, not system GCC)
CMake 3.21+ and make
Python 3 with pip packages installed

Minimum requirements for HelloWorld:

UNA_SDK environment variable pointing to SDK root
ARM GCC toolchain in PATH
CMake and build tools

For the TouchGFX GUI:

TouchGFX Designer installed (see toolchain setup) if you want to modify the design or run the TouchGFX simulator

For the LVGL GUI:

The LVGL submodule checked out once: git submodule update --init ThirdParty/lvgl (from the SDK root)
Node.js and Python, only if you regenerate the converted fonts (see Assets)

Building and Running HelloWorld

Verify your environment setup (see toolchain setup for details):

echo $UNA_SDK                   # Should point to SDK root. 
                                # Note for backward compatibility with linux path notation it uses '/'

which arm-none-eabi-gcc         # Should find ST toolchain
which cmake                     # Should find CMake

Navigate to the HelloWorld directory:
```
cd $UNA_SDK/Docs/Tutorials/HelloWorld
```

Build the application with the GUI of your choice. Each is its own CMake project and produces its own .uapp:

# TouchGFX GUI
mkdir build && cd build
cmake -G "Unix Makefiles" ../Software/Apps/HelloWorld-CMake
make

# LVGL GUI (from the tutorial directory again)
cd .. && mkdir build-lvgl && cd build-lvgl
cmake -G "Unix Makefiles" ../Software/Apps/HelloWorldLVGL-CMake
make

The app will start and show a basic GUI demonstrating the UNA app framework. This HelloWorld focuses on the core architecture - the service-GUI communication pattern that all UNA apps use. The two builds install side by side on the watch (D:\Apps\HelloWorld\ and D:\Apps\HelloWorldLVGL\) and appear in the launcher as HelloWorld and HelloWorldLVGL.

Running on Simulator

TouchGFX (Windows only):

Open HelloWorld.touchgfx in TouchGFX Designer and click Generate Code (F4) (do this once).
Navigate to HelloWorld\Software\Apps\TouchGFX-GUI\simulator\msvs
Open Application.vcxproj in Visual Studio
Press F5 to start debugging and run the simulator

LVGL (Windows and Linux): the simulator is a plain CMake project in Software/Apps/LVGL-GUI/simulator. It runs the real service and GUI processes against the SDK’s mock kernel, with the display in an SDL2 window. It needs a host C++ compiler, CMake, a generator (Ninja, or Visual Studio on Windows) and SDL2, and no IDE: on Linux or WSL, GCC, Ninja and the SDL2 development package; on Windows, MSVC, which the free Build Tools for Visual Studio provide as well as the Visual Studio IDE (the “Desktop development with C++” workload’s “C++ CMake tools for Windows” component brings CMake and Ninja). The build’s architecture must match the SDL2 it links; it is chosen by the developer prompt with the Ninja generator (x86 or x64) and by -A with a Visual Studio generator (-A Win32 or -A x64; Ninja does not take -A). Without an installed SDL2 the Windows build reuses the 32-bit copy TouchGFX Designer ships and must therefore be 32-bit, as in the commands below; with an installed 64-bit SDL2 pick the 64-bit option instead.

:: Windows, in an "x86 Native Tools Command Prompt for VS" (a cmd window with
:: the 32-bit MSVC environment loaded; any shell after vcvarsall.bat x86 is the same)
cd /d %UNA_SDK%\Docs\Tutorials\HelloWorld\Software\Apps\LVGL-GUI\simulator
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build
build\bin\HelloWorldLVGLSimulator.exe

# Windows, any shell: the Visual Studio generator finds MSVC itself and also
# writes a solution ("Visual Studio 18 2026" needs CMake 4.2 or newer,
# "Visual Studio 17 2022" works with the 3.21 minimum)
cd $env:UNA_SDK\Docs\Tutorials\HelloWorld\Software\Apps\LVGL-GUI\simulator
cmake -S . -B build -G "Visual Studio 18 2026" -A Win32
cmake --build build --config Debug
.\build\bin\HelloWorldLVGLSimulator.exe

# Linux, or WSL (Debian/Ubuntu: sudo apt-get install build-essential cmake ninja-build libsdl2-dev)
cd $UNA_SDK/Docs/Tutorials/HelloWorld/Software/Apps/LVGL-GUI/simulator
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build
(cd build/bin && ./HelloWorldLVGLSimulator)

In either simulator the keyboard keys 1, 2, 3 and 4 are the watch buttons L1, L2, R1 and R2. HelloWorld only reacts to R2, which exits the app. Since HelloWorld has minimal interactive elements, it primarily demonstrates the app startup and basic framework.

For detailed simulator setup and features, see Simulator.

Working with the TouchGFX GUI (Optional)

If you want to explore or modify the GUI design:

Install TouchGFX Designer (see toolchain setup for installation)
Open the TouchGFX project:
```
HelloWorld.touchgfx
```
Make design changes in TouchGFX Designer (add/modify screens, widgets, interactions)
Generate code after making changes:
- Click “Generate Code” button in TouchGFX Designer, OR

Rebuild the app to include your GUI changes:

cmake -G "Unix Makefiles" /path/to/HelloWorld-CMake # If artifacts has been changed
make

Working with the LVGL GUI (Optional)

There is no designer: the screen is code. gui/src/screens/MainScreen.cpp creates the label and the button hint with the SDK’s drawing helpers (SDK/GUI/LVGL/Draw.hpp), which take the same coordinates a TouchGFX Designer shows, so a layout can be copied across. Edit it, rebuild, run. Adding a font or an icon means adding it to assets/assets.json and regenerating (see Assets).

HelloWorld App Overview

HelloWorld demonstrates the essential UNA app architecture:

The Service Layer (Backend)

Runs as the main application thread
Handles sensor connections and data processing
Manages app lifecycle (start/stop)
Communicates with the GUI through messages

The service is one copy of the code, Software/Libs, shared by both GUI builds: HelloWorld-CMake and HelloWorldLVGL-CMake each link it with their GUI. Compare the two CMakeLists.txt: the service half is identical, and the GUI half differs in three lines (TOUCHGFX_PATH becomes GUI_PATH, and the UNA_SDK_*_GUI variables become UNA_SDK_*_GUI_LVGL).

The GUI Layer (Frontend)

Built with TouchGFX or LVGL. For the TouchGFX port, see TouchGFX Port Architecture; for the LVGL port, see the RunLVGL tutorial
Displays information to the user
Receives updates from the service
Handles user interactions

Communication Between Layers

Uses the UNA kernel messaging system
Service sends data to GUI via custom messages
GUI can send commands back to service

The kernel does not know which toolkit a GUI process uses. It hands the process a 240 x 240 frame buffer, button codes and a 10 Hz tick, and each toolkit’s port in the SDK turns those into its own rendering and events.

Project Layout

HelloWorld/
  ARCHITECTURE.md                       this page
  Resources/                            launcher icons (shared)
  Output/, OutputLVGL/                  where each build puts its .uapp (and, for apps that
                                        have one, its app-manifest.json)
  Software/
    Libs/                               the service (shared)
      Header/Service.hpp
      Sources/Service.cpp
      libs.cmake
    Apps/
      HelloWorld-CMake/CMakeLists.txt       .uapp with the TouchGFX GUI
      HelloWorldLVGL-CMake/CMakeLists.txt   .uapp with the LVGL GUI
      TouchGFX-GUI/                         TouchGFX GUI process
        HelloWorld.touchgfx                 the Designer project
        gui/include/gui/, gui/src/          model, view, presenter, containers
        generated/                          Designer output (do not edit)
        simulator/msvs, simulator/gcc       Visual Studio and gcc simulator projects
      LVGL-GUI/                             LVGL GUI process
        lvgl-gui.cmake                      sources and include dirs
        assets/assets.json                  fonts and images to convert
        assets/fonts/*.c                    converted font (committed)
        gui/include/gui/, gui/src/          model, screen, entry point
        simulator/CMakeLists.txt, main.cpp  CMake simulator project

The Same Screen in Two Toolkits

The screen is a “Hello World” label with a hint arc beside the R2 button, and R2 exits. Here is how each toolkit expresses the pieces.

Piece	TouchGFX (`TouchGFX-GUI/gui`)	LVGL (`LVGL-GUI/gui`)
Owner of the model and screen	`FrontendHeap` (generated singleton)	`GuiApp.cpp`: `una_lvgl_app_init()` constructs `Model` and `MainScreen`, then `lv_screen_load()`
Model	`Model` registers with `TouchGFXCommandProcessor` and implements `IGuiLifeCycleCallback`; also a `UIEventListener`	`Model` registers with `SDK::LVGL::Port` and implements `IGuiLifeCycleCallback`
Screen	`MainView` (widgets, key handling) + `MainPresenter` (talks to the model)	`MainScreen`: one class owning an LVGL screen object
The label	`TextArea` placed in Designer, text from `texts.xml`, font from the typography table	`Draw::label(root, &poppins_regular_18, "Hello World", 19, 98, 203)`
The button hint	`ButtonsSet` custom container with twelve bitmaps, `setR2(WHITE)`	`SDK::LVGL::Buttons`, `set(NONE, NONE, NONE, WHITE)`: arcs drawn by LVGL, no bitmaps
Button input	`MainView::handleKeyEvent(uint8_t key)`	`LV_EVENT_KEY` on the screen object; `MainScreen::onKey(uint8_t code)`
Exit	`presenter->exit()` -> `model->exitApp()` -> `mKernel.sys.exit()`	`mModel.exitApp()` -> `mKernel.sys.exit()`
Fonts	Designer converts the TTF at generate time	`assets/assets.json` + `lvgl_assets.py` convert it to a C file, committed

What is the same: the Model class and its lifecycle callbacks, the button codes (SDK::GUI::Button), the colours (SDK::GUI::Color), the service, and the kernel messages.

Entry point

TouchGFX: FrontendHeap::getInstance() is created by the SDK’s TouchGFX entry point; its constructor builds the model and shows the start screen chosen in Designer.

LVGL: the SDK’s entry point (Libs/Source/AppSystem/EntryPoint/LVGL/main.cpp) initialises the port and calls the app’s una_lvgl_app_init(). HelloWorld’s version, in GuiApp.cpp, builds the shared styles, the model and the screen, and loads the screen. It also defines una_lvgl_default_font(), which names the font LVGL falls back to, so LVGL’s built-in font stays out of the binary.

Buttons

The kernel delivers each button as a click code ('1'..'4') plus a press code when it goes down and a release code when it comes up (SDK/GUI/Button.hpp). TouchGFX passes them to the view’s handleKeyEvent(). The LVGL port posts them as LV_EVENT_KEY events to the active screen; MainScreen registers one event callback on its screen object and switches on the code. HelloWorld acts on the R2 click only.

The LVGL screen in full

MainScreen::MainScreen(Model& model) : mModel(model)
{
    mRoot = lv_obj_create(nullptr);                 // a screen object
    Draw::applyScreen(mRoot);                       // black, unscrollable
    lv_obj_add_event_cb(mRoot, &MainScreen::keyEventCb, LV_EVENT_KEY, this);

    Draw::label(mRoot, &poppins_regular_18, "Hello World", 19, 98, 203,
                LV_TEXT_ALIGN_CENTER, SDK::GUI::Color::WHITE);

    mButtons = std::make_unique<SDK::LVGL::Buttons>(mRoot);
    mButtons->set(SDK::LVGL::Buttons::NONE, SDK::LVGL::Buttons::NONE,
                  SDK::LVGL::Buttons::NONE, SDK::LVGL::Buttons::WHITE);
}

Every object is created on mRoot, and LVGL deletes them with it. The Draw helpers and Buttons are part of the SDK (Libs/Header/SDK/GUI/LVGL/) and are what the activity apps use, so a tutorial screen looks like a shipped one.

LVGL assets

LVGL needs fonts as C arrays. LVGL-GUI/assets/assets.json lists them, here one entry: Poppins Regular at 18 px, printable ASCII, 2 bits per pixel, taken from the TTF the TouchGFX GUI already ships in TouchGFX-GUI/assets/fonts. The converted file is committed, so building needs no converter. To add a font or an icon, add an entry and run:

python $UNA_SDK/Utilities/Scripts/lvgl_assets/lvgl_assets.py Software/Apps/LVGL-GUI/assets/assets.json

Fonts go through lv_font_conv (run with npx, so Node.js is needed); images through LVGL’s own LVGLImage.py (needs the pypng and lz4 Python packages). Declare each generated symbol in gui/include/gui/Assets.hpp.

Size on the watch

Build	`.uapp`	GUI code (text)	GUI RAM (bss)
HelloWorld (TouchGFX)	228 KB	214 KB	71 KB
HelloWorldLVGL	167 KB	158 KB	139 KB

LVGL is linked from source, so the GUI carries only the parts it uses; its RAM is dominated by the frame buffer and the 40 KB object pool set in the SDK’s lv_conf.h. The TouchGFX library is prebuilt, and its RAM is the frame buffer plus the Designer-generated heap.

Understanding the Commented Code

HelloWorld includes commented-out implementations of common UNA app features. These serve as reference examples for future tutorials:

Heart Rate Sensor Integration: Complete sensor connection, data parsing, and real-time GUI updates
FIT File Logging: Activity data recording with session summaries
Custom Messaging: Service-to-GUI communication patterns

Note: The next tutorial will walk through enabling heart rate monitoring step-by-step. For now, focus on understanding the basic app structure and messaging framework.

Understanding UNA App Communication

HelloWorld demonstrates the two main ways UNA apps communicate between service and GUI:

SDK Custom Messages (Service → GUI)

Used for real-time data updates. The service creates messages using SDK::make_msg<>() and sends them via the kernel. The GUI receives them in Model::customMessageHandler().

AppTypes Events (GUI → Service)

Used for commands and configuration. The GUI sends events through the IGuiBackend interface, which the service implements to receive commands.

These patterns form the foundation of all UNA app communication, and they are the same whichever toolkit draws the screen. Future tutorials will show how to implement specific features using these systems.

Common Patterns and Best Practices

Sensor Integration

Always check matchesDriver(handle) before processing sensor data
Validate data with isDataValid() before using
Handle sensor timeouts and disconnections gracefully

Message Design

Use unique message type IDs (increment from 0x00000001)
Keep messages small and focused on single purposes
Use descriptive names for message types and fields

GUI Updates

Only update GUI when necessary to avoid performance issues
Use appropriate data types (float for measurements, int for counts)
Handle invalid/missing data gracefully

File Operations

Use the kernel’s filesystem interface (mKernel.fs)
Handle file I/O errors appropriately
FIT files are Garmin’s standard format for activity data

Next Steps

Get HelloWorld running - Follow the build steps above and confirm the app launches
Explore the code structure - Look at Service.cpp and Model.cpp to understand the messaging flow
Check the commented examples - Review the commented HR and FIT code to see what’s available
Continue to the next tutorial - Learn how to enable heart rate monitoring and data logging
Study other example apps - Look at Alarm or Cycling apps for different patterns, or RunLVGL for a complete activity app with an LVGL GUI

Troubleshooting

Build Issues

Ensure all SDK paths are correctly configured
Check that TouchGFX is properly installed
For the LVGL build, check that ThirdParty/lvgl is populated (git submodule update --init ThirdParty/lvgl)
Verify CMake finds all required dependencies

Runtime Issues

Check log output for error messages
Verify sensor connections on real hardware
Use the simulator for initial testing

Common Mistakes

Forgetting to uncomment all related code sections
Using duplicate message type IDs
Not handling message memory management properly

Remember: Every complex app started as a simple HelloWorld. Take it step by step, and you’ll be building amazing UNA Watch applications in no time!