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

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

  • 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 with submodules (git clone --recursive)

  • 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 GUI development/modification:

Building and Running HelloWorld๏ƒ

  1. 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

  2. Navigate to the HelloWorld directory:

    cd $UNA_SDK/Docs/Tutorials/HelloWorld

  3. Build the application:

    mkdir build && cd build
cmake -G "Unix Makefiles" ../Software/Apps/HelloWorld-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.

Running on Simulator๏ƒ

To test the app on the simulator (Windows only):

  1. Open HelloWorld.touchgfx in TouchGFX Designer and click Generate Code (F4) (do this once).

  2. Navigate to HelloWorld\Software\Apps\TouchGFX-GUI\simulator\msvs

  3. Open Application.vcxproj in Visual Studio

  4. Press F5 to start debugging and run the simulator

The simulator will display the HelloWorld GUI. 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 TouchGFX GUI (Optional)๏ƒ

If you want to explore or modify the GUI design:

  1. Install TouchGFX Designer (see toolchain setup for installation)

  2. Open the TouchGFX project:

    HelloWorld.touchgfx

  3. Make design changes in TouchGFX Designer (add/modify screens, widgets, interactions)

  4. Generate code after making changes:

    • Click โ€œGenerate Codeโ€ button in TouchGFX Designer, OR

  5. Rebuild the app to include your GUI changes:

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

Note: HelloWorld has a minimal GUI. For learning GUI development, study the more complex examples like Cycling or HRMonitor apps, or see the toolchain setup.

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 GUI Layer (Frontend)๏ƒ

  • Built with TouchGFX framework. For detailed information about the TouchGFX port implementation, see TouchGFX Port Architecture

  • 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

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. 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๏ƒ

  1. Get HelloWorld running - Follow the build steps above and confirm the app launches

  2. Explore the code structure - Look at Service.cpp and Model.cpp to understand the messaging flow

  3. Check the commented examples - Review the commented HR and FIT code to see whatโ€™s available

  4. Continue to the next tutorial - Learn how to enable heart rate monitoring and data logging

  5. Study other example apps - Look at Alarm or Cycling apps for different patterns

Troubleshooting๏ƒ

Build Issues๏ƒ

  • Ensure all SDK paths are correctly configured

  • Check that TouchGFX is properly installed

  • 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!