|Skill Level||Area of Focus||Operating System||Software Tools|
|Beginner||Embedded, IoT||RTOS||QCA 402x Wi-Fi/BLE/ZigBee|
Hello, world - sample to the debugger console.
Setting up a new development environment can be challenging. Usually, the first development goal is to compile and debug a simple helloworld application.
The Moddable SDK "helloworld" application stops in the debugger at launch and then outputs a Hello World message to the debugger. In this project you will learn how to set up your development board and environment to run "helloworld". You will also learn the development workflow for using the Moddable SDK with the QCA4020.
Build / Assembly Instructions
Follow the one-time setup instructions in the Moddable SDK Getting started with QCA4020 development document to complete the following steps:
- Linux Host Environment Setup. Moddable supports FreeRTOS on the QCA4020 Customer Development Board (CDB) using a Linux host build platform.
- QCA4020 SDK Setup, including FreeRTOS, QuRT, and OpenOCD
- ARM Toolchain Setup
- Moddable Host Tools Build
We will discuss specfic details on some of the steps above, then build the
helloworld example app. Follow the Moddable setup instructions along with the explanation below.
Linux Host Environment Setup
First we set up a
qualcomm/ directory in your HOME directory. This directory will contain the Qualcomm SDK, FreeRTOS and QuRT.
Then we set some environment variables, download and build support libraries, and install the OpenOCD tool for debugging.
There are a number of downloads and steps involved. Follow the instructions in the Getting started with QCA4020 development document closely.
Some specific details follow:
The Moddable runtime uses FreeRTOS with a microsecond clock. The clock is configured with
FreeRTOSConfig.h. In the same file, we also configure the size of the heap with
Two other defines:
configUSE_MALLOC_FAILED_HOOK are setup to assist in debugging.
During development we want to use the debugger. We disable sleep on the QCA4020 CDB to allow JTAG to connect at boot time. The watchdog timer is also disabled to allow xsbug to connect and step through code without triggering a watchdog reboot. At later stages of development, you'll likely want to enable sleep and the watchdog timer for power efficiency and stability.
The modifications are in the file
In the same file, DEP (data execution prevention) is disabled to allow more RAM to be allocated to applications.
The QCA4020 link map is modified to specify where the different components of your application will be located in RAM and flash. Moddable apps have their resources, application native code, bytecode and static variables stored in flash. Application code can also run out of execute-in-place (XIP) memory.
The link map is located in the file
In this file, we set
RTOS_HEAP_SIZE to match the FreeRTOS value
configTOTAL_HEAP_SIZE, move static data to Flash, and adjust the read-only vs. RAM data space.
Building and Debugging an Application
In this section we learn how to build, install and debug the Moddable
helloworld example app on the QCA4020 CDB. This will pave the path to further development and demonstrate the development workflow.
After the one-time environment setup and Moddable tools are built, the workflow proceeds as follows:
- Build your Moddable app
- Build the QCA4020 launcher application
- Flash the application to the device
- Use gdb and xsbug to debug your application
Use at least three console windows. One for building project source, one for building the launcher application and debugging with gdb, and one to start xsbug.
Building the Moddable app
Start by opening a terminal window on the Linux build host and navigate to the your application's directory. You will run the
mcconfigcommand line tool from the application directory and perhaps edit some source and/or configuration files.
Build the app using the command:
mcconfig -d -m -p qca4020/cdb
$MODDABLEenvironment variable was initialized and mcconfig tool built as part of the Moddable SDK setup described above. There are a number of command line options we specify when building the app:
-doption builds the debug version of the application that connects to xsbug over the serial port.
-moption launches make to build the app.
-p qca4020/cdboption defines the target platform.
The mcconfig tool builds the Moddable XS runtime, application, modules, and compiles assets into an archive that will be included in the final build. It uses the
manifest.json file to define which components and resources to include in your app and how to build it. See the Manifest document for details about the
The results of the build will be located at
$MODDABLE/build/bin/qca4020/cdb/debug/helloworld/xs_qca4020.a and temporary files located in
xs_qca4020.a will be linked to the QCA4020 launcher app in the next step.
Build the QCA4020 launcher application
Open another terminal window. In this window, we will navigate to the launcher application's build directory and build the QCA4020 application. We will continue to use this directory to flash and debug the application.
Navigate to the project build directory and build the QCA4020 launcher application, which includes the Moddable runtime archive built above and QCA4020 libraries. The
makecommand is prefixed by the environment variables required to build a debug version of the
cd $MODDABLE/build/devices/qca4020/xsProj/build/gcc APP_NAME=helloworld DEBUG=1 make
APP_NAME environment variable specifies which
xs_qca4020.a archive to link to:
$MODDABLE/build/devices/qca4020/xsProj directory is derivative of the QCA4020 sample applications and has a similar structure to the examples in the QCA4020 SDK.
Flash the application to the device
In the same terminal window, we'll load the application to the QCA4020.
Navigate to the project build directory and flash the built application to the device:
cd $MODDABLE/build/devices/qca4020/xsProj/build/gcc sh flash_openocd.sh
This will launch OpenOCD to connect to the device and flash the application. It will take some time to complete and there is a lot of output on the screen.
When flashing has completed there will be a message similar to the following:
[2019-07-18 12:17:16,728] INFO: Script finished processing generated_fwd_table.xml File:flash_through_gdb.py:718 Function:main Finished Flashing
Use gdb and xsbug to debug your application
xsbugdebugger in the background. Then launch the
xsbug & serial2xsbug /dev/ttyUSB1 115200 8N1
In the terminal window where you completed flashing to the device, run
gdb(arm-none-eabi-gdb) to launch the app:
cd $MODDABLE/build/devices/qca4020/xsProj/build/gcc arm-none-eabi-gdb -x v2/quartzcdb.gdbinit
You will use gdb to debug the native part of your code and xsbug to debug the script portion.
cto continue three times to launch the
helloworldapp. The application will then stop at the
debuggerstatement in xsbug.
In xsbug, press the (step) button twice.
Note the items below in the
mainis connected to the debugger.
The File pane (b) shows source code. The orange dot and highlighted line indicate that we are stopped at line 18.
The left pane (c) has expandable panels for displaying real-time instrumentation output, inspection of the call stack and variables. At the top of the left pane are buttons to kill, pause, run, step, step-in and step-out.
The Locals panel shows the variable message has been assigned the string
Hello, world - sample.
The Console pane (d) displays
traceoutput, information and error messages.
The xsbug screenshot shows that the application stopped at the
debuggerstatement at line 15, and then we stepped twice.
You can then press the (run) button to continue debugging. The
tracefunctions are displayed on the
xsbugconsole. The INSTRUMENTS pane displays real-time application runtime status and feedback.
Complete xsbug documentation can be found here.
Note that all Moddable applications are built and run following the same basic steps outlined above.
The Moddable SDK contains many examples demonstrating the numerous modules available including display and sensor drivers, networking, BLE and Piu. Piu is the Moddable SDK user interface framework, allowing developers to design and implement user interfaces with smooth, flicker-free animations and beautiful font rendering on resource-constrained SoC and microcontroller platforms.
- Moddable Blog Post: Qualcomm QCA4020 Now Supported by Moddable SDK
- Moddable SDK: Networking Reference.
- Moddable SDK: Tools Reference.
- Moddable SDK: Manifest Reference documentation
The Moddable SDK with Qualcomm QCA4020 support is available immediately as part of the Moddable SDK repository on GitHub. The Moddable SDK is available for use with either a FOSS (Free and Open Source Software) license or a commercial software license. Additional information on both licenses is provided on the Moddable website.