Ready To Run Barracuda App Server Project For NXP's RT 1020

iMX RT1020 144LQFP CHIP

NXP's crossover processors are applications processors built with an MCU core, architected to deliver high performance and functional capabilities of applications processors, but with the ease-of-use and real-time low-power operation of traditional MCUs.

The Barracuda App Server, with its wealth of IoT and industry protocols available via the easy-to-use Lua programming language, greatly simplifies any type of OT-IT bridging & development, and makes edge programming fun. Lua enables non hard core C/C++ developers to safely work with embedded system programming. See the Edge Computing Software page for information on how the Barracuda App Server powered RT1020 MCU can be used as an advanced edge platform.

The RT 1020 project includes additional GPIO and UART Lua drivers (Lua bindings) in addition to the many Barracuda App Server APIs. Schematics for a ready to use RT1020 module can be download from Github.

Barracuda App Server + NXP Crossover MCU = Powerful IoT Edge Foundation.


Lua Embedded Web Server for NXP

How To Compile The Source Code And Run The LSP Application Manager

The RT 1020 project is designed for the i.MX RT1020 Evaluation Board and is configured to use our LSP Application Manager, an example that turns the Barracuda App Server into an interactive Lua development tool, aka Lua REPL.

MCUXpresso Open Projects

Download and install the free MCUXpresso IDE.

Download and unpack the Barracuda App Server RT 1020 ZIP File in a suitable development directory.

Start the MCUXpresso IDE and select File -> Open Projects from File System...

Click the Directory button and brows to the location where you unpacked the ZIP file. Select the directory and click the Finish button at the end of the dialog box.

MCUXpresso Import Project

When the indexer has completed (bottom right corner), right click the project and select Build Project as shown below:

MCUXpresso Build Projects

You should see 'Build Finished. 0 errors..' in the build console when the build is complete.

Required: RT 1020 development board, SD-card, USB-cable, and Ethernet-cable.

As explained in the MIMXRT1020-EVK Development Platform Getting Started Guide, plug a USB cable to the development board. In addition, insert an SD card into the development board. The Barracuda App Server does not require a file system, but this project is configured to use a file system. You must also insert an Ethernet cable and wire the board to your local network.

Right click on the project and select Debug As -> MCUXpresso IDE LinkServer.

MCUXpresso: Debug As

Press F8 (Run-> Resume) after the firmware has been uploaded and after the debugger halts at the main() function. You should now see printouts similar to the following in the MCUXpresso console:

Mounting SD card...
Volume mounted !
Initializing PHY...
Getting IP address from DHCP ...
IPv4 Address: 192.168.10.187
DHCP OK
Server listening on IPv4 port 80
SharkSSL server listening on IPv4 port 443
Initializing the Let's Encrypt plugin.
SNTP time: 2022-10-06T08:53:01Z
WebDAV/WFS URL: http://192.168.10.187/fs/

You should now be able to navigate to the IP address printed in the console. You should then see the LSP Application Manager user interface.

How to navigate to the device:

The project is set up to obtain an IP address via DHCP as shown in the console example above. You can navigate to the IP address using a browser. You can also navigate to http://LWIPBAS, the mDNS name set in the project, but note that mDNS takes time to resolve and makes the browsing experience slower. You can also access the device via our SharkTrustX demo portal https://lspappmgr.realtimelogic.com/ after running the ACME example as explained in the example section below.

How To Run Your First Lua Examples

Web File manager: Drag and Drop

Navigate to the directory where you unpacked the Barracuda App Server ZIP file, then to LspAppMgr-RT1020/BAS/examples/lspappmgr. This directory contains the sub-directory Lua-Examples.

Upload this directory to the RT1020 by using WebDAV or by using the built in Web File Manager. The combined WebDAV and Web File Manager URL is http://ip-address/fs/. See the WebDAV how to video for information on how to mount a WebDAV drive.

If using the Web File Manager as shown to the right, use a browser and navigate to http://ip-address/fs/, click the + button to create directory "Lua-Examples", click the "Lua-Examples" link to navigate to http://ip-address/fs/Lua-Examples/, select the files, and drag & drop the files into the browser window at http://ip-address/fs/Lua-Examples/.

Web File Manager: Upload

The Web File Manager starts uploading the files as soon as you drop them into the browser window.

When the upload has completed, navigate to http://ip-address, click the New Application button, click browse (1), and select the Lua-Examples. Click the Submit button (2) and complete the New Application Wizard using default settings.

LSP Application Manager: New-Application LSP Application Manager: Start Example

Start the application by toggling the Running button (1). Click the Edit button (2) to bring up the integrated Lua IDE.

In the Lua IDE, expand the examples in the left pane, and double click any of the examples to open the source code in the editor. You may then click the run button to execute the example.

LSP Application Manager IDE

Note that the blinkled.lsp example is not working as the 'generic Lua LED example bindings' have not been installed.

The example acme.lsp, as shown in the IDE screenshot above, shows how to automatically install a trusted X.509 certificate using our Let's Encrypt plugin. The FreeRTOS/lwIP video starting at 4:30 shows how the Let's Encrypt example works. ACME is short for Automatic Certificate Management Environment (RFC 8555).

How To Use an External IDE

The internal web-based Lua IDE is easy to use since the IDE is an integral part of the LSP Application Manager. However, a more advanced IDE may be preferred and is required if you plan on debugging Lua code.

You may use any external IDE/editor and edit files directly on the RT 1020’s SD-card by first mounting the device as a WebDAV drive. The FuguHub site includes (older but still relevant) instructions for How to Mount a WebDAV Drive using various client operating systems.

To mount the RT 1020’s WebDAV server, use the URL https://ip-address/fs/. The WebDAV server does not use authentication and does not request user credentials.

How To Debug Lua Code

The Barracuda App Server includes a Lua debug module that is compatible with Visual Studio Code and the Lua plugin. The following screenshot shows the debugger in action.

Lua Debugger Screenshot

The debugger requires access to the Lua files, but we cannot access Lua files via WebDAV from the device when debugging. The reason for this is that the debug module halts all activity in the server, including the WebDAV server when a breakpoint is hit. Instead, the Lua files must be kept on your host computer and accessed from the device by using the NetIo. See the LSP Application Manager documentation for additional NetIo details.

Configure a debug session as follows:

Follow our How to Debug Lua Code Using Visual Studio Code instructions found on GitHub; However, do not follow the instructions verbatim, but install all tools listed in the Prerequisites section and configure Visual Studio Code as explained in the section Configuring VS.

Navigate to your local directory LspAppMgr-RT1020/BAS/examples/lspappmgr

Copy the File Server Directory from GitHub and place a copy of this directory in LspAppMgr-RT1020/BAS/examples/lspappmgr such that you have the directory LspAppMgr-RT1020/BAS/examples/lspappmgr/FileServer.

Start the Mako Server as follows in the LspAppMgr-RT1020/BAS/examples/lspappmgr:

mako -l::FileServer

Alternatively, if the Mako Server is not in the path:

/path/2/mako -l::FileServer

The File Server App sets up a file server that will be accessed by the NetIo client running in the device. The File Server App should automatically open a browser window with the Web File Manager. Click the Lua-Examples link (1) and copy the full URL (2).

Web File Server

Using the browser, navigate to the device IP address, click New Application (1), select net (2), paste in the URL (3), and click the Submit button.

Network File System

Complete the New Application wizard and name the application LuaExamplesR (R for remote). The following screenshot shows the Application List after adding the new application. Notice that we have disabled the first application. The two applications contain duplicate copies of the same files and the debug monitor gets confused by this setup. In general, when using the debugger, make sure you only have one application running.

LSP Application Manager with two applications

You should see the following printout in the File Server console as soon as the NetIo client connects to the File Server App running on your host:

Creating 'Visual Studio Code' config file:   Lua-Examples/.vscode/launch.json

As detailed in the GitHub documentation, a launch.json file is required with a sourceMaps attribute. This file with the sourceMaps attribute is automatically created by the File Server App.

Start Visual Studio Code and open the local directory: LspAppMgr-RT1020/BAS/examples/lspappmgr/Lua-Examples

Click on the httpclient.lsp file and add the two following lines at the top of the file just below the comment:

require"ldbgmon".connect{client=false}
trace"Running LSP page"

The following screenshot shows the code modification:

Visual Studio Code with Lua

Using your browser, navigate to http://ip-address/LuaExamplesR/httpclient.lsp, where ip-address is your RT 1020’s IP address. The browser will now be waiting (spinning) since the web server is now frozen and waiting for the debugger client (Visual Studio Code) to connect. The web server can at this point only be resumed by the debugger.

In Visual Studio Code, press the F5 button to start a debug session. Visual Studio Code should now connect to the debug monitor and automatically halt the code as shown in the screenshot below.

Visual Studio Code with Lua Http Client

You can now step through the code or simply resume by pressing F5. When the server resumes, the browser window stops spinning. Refreshing the browser window will not stop the LSP page again now that you have an established debugger connection. To stop the code at the same location, set a breakpoint at the trace() call in the editor.

Visual Studio Code Set Breakpoint

You can now refresh the browser and the new breakpoint will be hit. Try stepping into the code (F11). Notice that you can step into the HTTP client library httpm, which is partly implemented in Lua. The code is not part of your application, but is embedded inside the firmware. The debug monitor sends the Lua source code to Visual Studio Code from the LSP Application Manager’s ZIP file embedded in the firmware.

The following short video shows how to remotely debug Lua code on a Raspberry Pi. The instructions are similar; however, the server running on the Raspberry Pi (the one being debugged) is the Mako Server and not the LSP Application Manager.

Further Reading

Prior to reading any of the following tutorials, check out the online Lua Tutorials and read the LSP Application Manager Documentation.

Lua examples and tutorials compatible with RT 1020: