Veethree D7 SDK
Loading...
Searching...
No Matches
SWU generation example

Please refer to Creating software updates to understand Software Update images.

SWU Template App

SWU Template App example shows an easy to configure template for creating a Software Update (SWU) image. The app demonstrates how to include application binaries and custom data files into a target install directory and package them to an SWU image.

The template application is a QML application that displays IP addresses of all network interfaces on the D7 and build timestamp of the application. The target install folder also includes a .txt file that contains the build timestamp that is shown on the UI. This timestamp file is generated as a part of the CMake build step for convenience. The target-install folder included in this example can be used as a template folder structure to generate a packaged image. The template folder contains a systemd .service file and .conf file to mark the service as non critical. Application binary is installed in the bin folder after building the app. This folder will be packaged as is when generating the SWU image. The same folder structure will be replicated on the /app partition of the D7 when applying the software update.

The target-install folder generated by this application after build steps, has the following structure:

~/d7-sdk/examples/gui/qml-swu-template/build/target-install$ tree
.
├── bin
│ ├── qml-swu-template-app
│ └── timestamp.txt
├── qml-swu-template.service
└── sys
└── etc
└── systemd
└── non-critical.d
└── app.conf

Usage

To generate an SWU image from this app, simply build and install application binary targets using CMake. The build command requires the cache variable: CMAKE_BUILD_TYPE- to generate either a 'Debug' or 'Release' image.

To get started, open a new terminal (on linux) or CMD window (on windows) and navigate to the base directory of this example ~/d7-sdk/examples/gui/qml-swu-template/.

Source the target toolchain as:

# Linux
source $HOME/d7-sdk/toolchain/environment-setup-armv8a-veethree-linux

on windows:

:: Windows
%USERPROFILE%\d7-sdk\toolchain\environment-setup-armv8a-veethree-linux.bat

Generate build files in the build directory using the CMake command:

# cmake -G Ninja -DCMAKE_BUILD_TYPE=<Debug/Release> -B build .
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -B build .

Build and install the target using:

cmake --build build/ --target install

The install step copies the template files from the target-install folder to the install directory, installs the app binary in the bin folder and creates the SWU image using the swugen utility. If the build is successful, the SWU image file swu-template-{sdk-version}+{sdk-build-number}.swu would be generated in the build directory created. Use this file to apply a software update to the D7 using either a USB-C drive or the SWUpdate web interface.

Including libraries or data files

Library files or data files (like text, JSON, XML, etc) can also be packaged in the SWU image file to be deployed to the D7. This example generates a .txt file containing the application build timestamp in the bin directory during the CMake install step and it is automatically included in the SWU image. To include files apart from the app binary files, simply add them to the target-install directory. No additional steps or flags are required to include these extra files in the final image while using the swugen utility.

Replicating image generation to other applications

To include CMake SWU image generation to your target application, copy the target-install template folder from this example to your application's directory.

After copying the folder, rename the systemd .service file in target-install to your application service name and edit the file to run your application binary instead of qml-swu-template-app. Also edit the description.

The application included in this example is marked as non-critical by the file target-install/sys/etc/systemd/non-critical.d/app.conf. If you would like to retain this, edit the app.conf file to use your app name. Otherwise delete the file.

To automatically install the application binaries to the target-install folder, create a target in the CMakeLists.txt file of your application by including the lines:

install(TARGETS ${APPNAME}
RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}
)

Add these lines for all the targets your app generates. Set CMAKE_INSTALL_PREFIX to the path of target-install folder.

To automatically install library files in target-install folder, use:

install(TARGETS ${LIBRARY}
ARCHIVE DESTINATION ${CMAKE_INSTALL_PREFIX}
LIBRARY DESTINATION ${CMAKE_INSTALL_PREFIX}
)

This application runs the swugen utility as a custom installation logic from the CMake install step. To the run the utility on the shell combine install(CODE ...) with execute_process as:

install(CODE "execute_process(COMMAND $HOME/d7-sdk/tools/swugen <OPTIONS>)")

The same build commands as above can be used to build and install the app. Make sure all the paths are modified to match your application.

The example code below highlights the CMakeLists.txt used to generate SWU image. Please refer to the full example in /examples/gui/qml-swu-template in the SDK installation folder.

CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(qml-swu-template-example VERSION 0.1 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_STANDARD 17)
# SDK path is the absolute path of SDK install directory. This is usually $HOME/d7-sdk (linux) or %USERPROFILE%\d7-sdk (windows)
set(SDK_PATH $ENV{OECORE_TARGET_SYSROOT}/../../../ CACHE PATH "" FORCE)
# Set the CMAKE_INSTALL_PREFIX path to be build/target-install. Also can be passed from the command line using -DCMAKE_INSTALL_PREFIX.
set(CMAKE_INSTALL_PREFIX "${CMAKE_CURRENT_BINARY_DIR}/target-install" CACHE PATH "Default install prefix" FORCE)
# Build the app and install
add_subdirectory(app)
# Include GNUInstallDirs to use installation directory variables
include(GNUInstallDirs)
# After installing target, generate .swu file if SDK_PATH is set
if(NOT SDK_PATH STREQUAL "")
# Determine whether --develop or --release flag has to be used to generate .swu
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
set(IMAGE_TYPE "--development")
else()
set(IMAGE_TYPE "--release")
endif()
# Generate update layout after install step is complete
# Use .bat extension when building on windows
if(CMAKE_HOST_WIN32)
set(SWU_UTIL "${SDK_PATH}/tools/swugen.bat")
else()
set(SWU_UTIL "${SDK_PATH}/tools/swugen")
endif()
# Post target install, run a series of commands to create an optional data file and then generate the .swu file
# This is an optional step to include a timestamp file
# Create a custom file in the bin directory ${CMAKE_INSTALL_PREFIX}/bin i.e {CMAKE_INSTALL_FULL_BINDIR} and write the current timestamp as the build timestamp.
# Ignore this step if not necessary.
# This file can be added anywhere in {CMAKE_INSTALL_PREFIX} and it will be automatically included in the swu image
install(CODE
"string(TIMESTAMP CURRENT_TIME \"%Y-%m-%d %H:%M:%S\")
file(WRITE \"${CMAKE_INSTALL_FULL_BINDIR}/timestamp.txt\" \"\${CURRENT_TIME}\")"
)
# Copy the target-install template folder to build directory
install(
DIRECTORY ${CMAKE_SOURCE_DIR}/target-install/
DESTINATION ${CMAKE_INSTALL_PREFIX}
)
# Call the swugen utility to create the swu image
install(CODE
"execute_process(
COMMAND ${SWU_UTIL} -i \"${CMAKE_INSTALL_PREFIX}\" -k \"${SDK_PATH}/keys/default-key\" -o \"${CMAKE_CURRENT_BINARY_DIR}/swu-template.swu\" ${IMAGE_TYPE} --update
)"
)
endif()