QCA4020 Getting Started with the Moddable SDK

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.

• QCA4020 Development Kit

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

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:

FreeRTOS

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.

Device configuration

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.

Link map

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:

1. Build your Moddable app
2. Build the QCA4020 launcher application
3. Flash the application to the device
4. 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.

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

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

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

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

1. Launch the xsbug debugger in the background. Then launch the serial2xsbug tool.

   xsbug &
   serial2xsbug /dev/ttyUSB1 115200 8N1
   

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

3. At the (gdb) prompt type c to continue three times to launch the helloworld app. The application will then stop at the debugger statement in xsbug.

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

5. You can then press the (run) button to continue debugging. The trace functions are displayed on the xsbug 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.