Skill Level | Area of Focus | Operating System | Software Tools |
---|---|---|---|
Beginner | Embedded, IoT | RTOS | QCA 402x Wi-Fi/BLE/ZigBee |
This project introduces you to Moddable SDK development in JavaScript on the QCA4020 System-On-Chip (SoC) Product Development Kit. The Moddable SDK is a combination of development tools and runtime software to create applications for embedded devices. The QCA4020 IoT solution offers Wi-Fi, Bluetooth low energy (BLE), and 802.15.4 capable radios in a single-chip package. In this project, we cover Linux host environment setup and verify the setup by building, flashing and running the Moddable SDK helloworld JavaScript example app on the QCA4020/CDB. The helloworld
example app connects to the Moddable xsbug JavaScript source-level debugger and traces the string Hello, world - sample
to the debugger console.
Objective
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.
Materials Required / Parts List / Tools
In the Box
The contents of the QCA4020 Development kit, as seen above, include:
- QCA4020 development board
- USB to Micro USB cables
- Power supply
- Jumpers
- Setup Guide
Additional Resources
- QCA4020 Development Kit Users Guide
- Moddable SDK
- Getting started with QCA4020 development using the Moddable SDK
- Moddable SDK helloworld JavaScript example app
- Moddable SDK tools documentation
- Moddable SDK manifest documentation
- Moddable SDK xsbug JavaScript source-level debugger
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 configTICK_RATE_HZ
in FreeRTOSConfig.h
. In the same file, we also configure the size of the heap with configTOTAL_HEAP_SIZE
.
Two other defines: configCHECK_FOR_STACK_OVERFLOW
and 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 $MODDABLE/build/devices/qca4020/xsProj/src/export/DevCfg_master_devcfg_out_cdb.xml
.
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 ~/qualcomm/qca4020/target/bin/cortex-m4/freertos/DefaultTemplateLinkerScript.ld
.
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
A Moddable app contains the JavaScript bytecode of your application, the XS JavaScript runtime, and compiled resources for your app.
Start by opening a terminal window on the Linux build host and navigate to the your application's directory. You will run the
mcconfig
command line tool from the application directory and perhaps edit some source and/or configuration files.cd $MODDABLE/examples/helloworld
Build the app using the command:
mcconfig -d -m -p qca4020/cdb
The
$MODDABLE
environment 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:The
-d
option builds the debug version of the application that connects to xsbug over the serial port.The
-m
option launches make to build the app.The
-p qca4020/cdb
option 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 manifest.json
file.
The results of the build will be located at $MODDABLE/build/bin/qca4020/cdb/debug/helloworld/xs_qca4020.a
and temporary files located in $MODDABLE/build/tmp/qca4020/cdb/debug/helloworld
.
The archive 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
make
command is prefixed by the environment variables required to build a debug version of thehelloworld
app:cd $MODDABLE/build/devices/qca4020/xsProj/build/gcc APP_NAME=helloworld DEBUG=1 make
The APP_NAME
environment variable specifies which xs_qca4020.a
archive to link to: $MODDABLE/build/bin/qca4020/cdb/debug/APP_NAME/xs_qca4020.a
The $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
Open another terminal window. In this window, we will launch xsbug, the Moddable SDK JavaScript source-level debugger that was built as part of the Moddable SDK setup described above. We will also start the serial2xsbug tool that bridges communication between the QCA4020's serial port and the host TCP/IP port that xsbug uses.
Launch the
xsbug
debugger in the background. Then launch theserial2xsbug
tool.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.
At the
(gdb)
prompt typec
to continue three times to launch thehelloworld
app. The application will then stop at thedebugger
statement in xsbug.In xsbug, press the
(step) button twice.
Note the items below in the
xsbug
window.The machine tab at (a) shows that the JavaScript virtual machine
main
is 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
trace
output, information and error messages.The xsbug screenshot shows that the application stopped at the
debugger
statement at line 15, and then we stepped twice.
You can then press the
(run) button to continue debugging. The
trace
functions are displayed on thexsbug
console. 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.
What's Next?
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.
See QCA4020 Modern UI Application Development with the Moddable SDK for an in-depth explanation of the weather example app, a JavaScript app from the Moddable SDK that issues HTTP requests to the OpenWeatherMap REST API and displays the weather forecast for various U.S. cities on a color 240 x 320 LCD.
Conclusion
Congratulations! By following the steps outlined in this project, you've successfully built, deployed and run a basic JavaScript app on the QCA4020/CDB that connects to the Moddable SDK xsbug source-level JavaScript debugger. We look forward to hearing about applications you built with the Moddable SDK. We're available to help with design, implementation, training, and support.
Further Reading
- Moddable Blog Post: Qualcomm QCA4020 Now Supported by Moddable SDK
- Moddable SDK: Piu JavaScript Reference.
- Moddable SDK: Networking Reference.
- Moddable SDK: Tools Reference.
- Moddable SDK: Manifest Reference documentation
- Moddable SDK: xsbug Reference JavaScript source-level debugger
Availability
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.
Contributors
Name | Title/Company | |
---|---|---|
Michael Kellner | [email protected] | Moddable Tech, Inc. |