This document shows how to build an mPower custom application consisting of a cross compiled C++ application named CPPExampleApp which reads a message file that was installed with the application as a dependency then updates the status file with the current time and the message.
Note: This document assumes that the mpower_custom_app_template repo has been cloned into ~/
Note: All text files must use the Unix (LF) line ending convention.
Note: This example uses kate as the text editor. Most text editors will suffice.
Note: This document assumes that the cross compiler has been installed to ~/local.
MultiTech provides cross compiler toolchains for use on a PC host running a modern distribution of linux. The cross compiler toolchains target specific MultiTech products and mPower versions. Download the correct toolchain for your MultiTech product and install on a modern Linux PC host system.
Note: This example requires knowledge of cross-compiling, cross compilers, and general software engineering best practices. These subjects are outside of the scope of the document and are not addressed.
Note: The toolchain installation includes a shell script, usually beginning with environment-setup, that sets toolchain-specific environment variables in the current shell. Source this script before compilation so the CMake build environment will use the correct compiler.
Make a directory for the source code of the application and change into it.
$ mkdir -p CPPExampleApp/src
$ cd CPPExampleApp/src
In this mPower custom application example there will be one folder and five required files. They are named provisioning, p_manifest.json, example.ipk, manifest.json, Install, Start, and CPPExampleApp respectively.
The p_manifest.json file is a JSON formatted file that is used by the app-manager software running on the MultiTech mPower enabled device during the installation process to install included ipk formatted packages as dependencies of the application.
Package files (ipk) and p_manifest.json must be in a directory named provisioning. Create provisioning directory and change to it.
$ mkdir -p provisioning
$ cd provisioning/
Copy the p_manifest.json provided by the mPower Custom App Template repository to the application source provisioning directory.
$ cp ~/mpower_custom_app_template/src/p_manifest.json .
Open p_manifest.json in a text editor.
$ kate p_manifest.json &
The p_manifest.json file is a JSON formatted file contains the following members:
| Key | Type | Description |
|---|---|---|
| pkgs | Array | Contains an array of packages that will be installed. |
| FileName | String | Name of included ipk file to install. |
| type | String | Always "ipk" |
| pkg_name | String | Name of package as declared in the ipk file |
Edit p_manifest.json to read:
{
"pkgs": [
{ "FileName": "example.ipk", "type": "ipk", "pkg_name": "CPPExampleAppIPK" }
]
}
Save and close p_manifest.json.
Download and copy example.ipk package into the provisioning directory.
Exit provisioning directory:
$ cd ..
The manifest.json file is a JSON formatted file that is used by the app-manager software running on the MultiTech mPower enabled device during the installation process to identify the application and specify where it will be installed.
Copy and rename manifest.json.basic.example provided by the mPower Custom App Template repository to the application source directory.
$ cp ~/mpower_custom_app_template/src/manifest.json.basic.example ./manifest.json
Open manifest.json in a text editor.
$ kate manifest.json &
The manifest.json file is a JSON formatted file contains the following members:
| Key | Type | Description |
|---|---|---|
| AppName | String | Name of the application. This is used for the installed app directory name and displaying in the UI and on DeviceHQ |
| AppVersion | String | Version of the application. DeviceHQ uses this to distinguish between versions |
| AppDescription | String | Description for your purposes |
| AppVersionNotes | String | Any applicable notes for the particular version of the application displayed on DeviceHQ |
| SDCard | Boolean | Optional variable. Can not be used with PersistentStorage. Determines where app is installed and saved. A value of true uses external SD card. A value of false uses non-persistent internal NVRAM which may be overwritten during factory reset and firmware upgrades. |
| PersistentStorage | Boolean | Optional variable. Can not be used with SDCard. Determines where app is installed and saved. A value of true uses persistent NVRAM that won't be overwritten by a factory default or firmware upgrade. A value of false uses non-persistent internal NVRAM which may be overwritten during factory reset and firmware upgrades. |
Edit manifest.json to read:
{
"AppName": "CPPExampleApp",
"AppVersion": "0.0.1",
"AppDescription": "Example mPower application runs a C application that reads a configuration file and writes it to the system log.",
"AppVersionNotes": "First Version",
"PersistentStorage": true
}
Save and close manifest.json
The Install file is a shell script which is executed by the app-manager software running on the MultiTech mPower enabled device during the installation process. The Install script is responsible for installing additional packages, performing configuration, and/or other tasks that should be done during the application installation.
Copy the base Install script provided by the mPower Custom App Template repository to the application source directory.
$ cp ~/mpower_custom_app_template/src/Install .
The base Install script will not need to be edited in this example.
The Start file is a shell script which is executed by the MultiTech mPower enabled device when the application is started. The Start script is responsible for starting and stopping the application.
Copy the base Start script provided by the mPower Custom App Template repository to the application source directory.
$ cp ~/mpower_custom_app_template/src/Start .
Open Start in a text editor.
$ kate Start &
Edit the following variables to use the provided values in the Start script.
Note The configuration file location is provided by the CONFIG_DIR environment variable set by app-manager before the Start script is run during normal use.
NAME="CPPExampleApp"
DAEMON="${APP_DIR}/CPPExampleApp"
DAEMON_DEBUG_ARGS=""
DAEMON_ARGS="${DAEMON_DEBUG_ARGS}"
Save and close Start.
Compile and link the included main.cpp file using CMake and the previously installed cross-compiler.
Download and copy main.cpp and CMakeLists.txt source files into the src directory.
Exit the src directiory, remove existing build dir if exists and create a clean build directory.
$ cd ..
$ rm -rf build/
$ mkdir -p build/
Enter build directory.
$ cd build/
Source script to set cross compiler environment.
$ . ~/local/environment-setup-armv7vet2hf-neon-mlinux-linux-gnueabi
Build executable file.
$ cmake ../src/
$ make
Copy executable to the application source directory.
$ cp ./CPPExampleApp ../src/
Leave build directory.
$ cd ..
mPower requires the custom application to be packaged as a gzipped tarball.
In this mPower custom application example there will be one folder and five required files. They are named provisioning, example.ipk, manifest.json, Install, Start, and CPPExampleApp respectively.
Enter the application source directory and build the gzipped tarball.
$ cd src/
$ tar --hard-dereference -hczf CPPExampleApp_0_0_1.tgz provisioning manifest.json Install Start CPPExampleApp
CPPExampleApp_0_0_1.tgz file. Application will install and run.