The LSP Application Manager

The LSP App Manager turns the Barracuda App Server into an awesome development tool and is our recommended starting point for anyone that plans on using the Barracuda App Server and the Lua plugin in an RTOS environment. Once the development is complete, some minor changes to the build swaps out the LSP App Manager's Lua code with your own dedicated LSP/Lua bootloader.

There are two LSP Application Manager versions:

Get a quick introduction to the LSP Application Manager by navigating to our online tutorial server or by viewing the LSP Application Manager's ESP32 Video Tutorial. The LSP Application Manager can be used as an easy to use "Read-Eval-Print Loop" (REPL) as explained in the Rapid Firmware Development Using Lua tutorial.

Note that you can use any text editor with the LSP Application Manager, including the integrated Lua Server Pages IDE.

Compiling the LSP App Manager

The following section includes generic build instructions. We provide two ready to use RTOS build projects you may download and use:

Include the following files in your build:

The file LspZip.c must be created by running barracuda/examples/lspappmgr/make/BuildLspZip.cmd.

If you are using Linux, run the included makefile for "host build" to produce LspZip.c or create a shell script that replicates the DOS batch file BuildLspZip.cmd.

The file LspZip.c is a C array containing the zipped LSP App Manager's resource files ( and is mounted by the C startup code as a ZipIo and used by the Lua VM's required 'vmio'. We recommend studying the content of the produced ZIP file to get an understanding of the various resource files.

Note: The included Web-IDE is large and requires many static resource files and is, for this reason, not included in the default resource file The default build is setup to use an online CDN repository for the Web-IDE; however, this requires that you have an Internet connection and that your browser can download files from the Internet. You may optionally include all resources in by running the included makefile as follows:

make plat=posix large=true ziplsp

The above command creates a full and LspZip.c. The full is seven times the size of the one using CDN.

In addition to including the above files in your IDE/Makefile, add the required include path and #define directives as required by your platform. See the readme file barracuda/builds/[platform]/readme.txt for details.

The file system plugin barracuda/xrc/DiskIo/[platform]/BaFile.c is optional and may be included if you have a file system in the device and if a suitable plugin is found in barracuda/xrc/DiskIo/ directory. You must add #define NO_BAIO_DISK in your IDE/Makefile if you do not plan on using a file system. See the DiskIo documentation for details.

Enabling Additional Features

BAS Amalgamated (BAS.c) includes features that are by default not compiled. These features can be enabled by the following macros. The macros can be enabled on any platform, including RTOS, unless stated otherwise.

The following macros are required if you plan on using the Let's Encrypt plugin. The macros are pre-set for the following ports: POSIX (Linux/QNX), Windows, VxWorks, and INtime.

All porting layers, except POSIX and Windows, have the following pre-set:

The above construction makes Lua use integer only and excludes floating point numbers. To re-enable floating point, compile the code with:

See inc/arch/XXX/luaconf.h for details.

Lua and LSP Examples

The sub directory Lua-Examples includes ready to use examples.

You may use any of the examples as follows:

  1. Create a new application using the LSP App Manager (see below)
  2. Using the Web-IDE, create a new file and paste the content of the example into this file
  3. Run the example using the Web-IDE

You may optionally copy the file directly to the application's directory. Each application created by the LSP App Manager has its own directory. This directory is on your own host computer if using the NetIo (see below) and on the embedded device if using the DiskIo. You may mount the embedded device as a WebDAV instance and work on files directly using the WebDAV mount (explained below).

When not using the Web-IDE, each LSP file can be accessed as follows http://device-ip-address/app-name/file-name, where app-name is the name created using the LSP App Manager and file-name is the name of the file.

Developing your Lua App using the LSP App Manager IDE

After following the above steps and after starting your embedded device, use a browser and navigate to the device's IP address. After clicking the New Application button, you should see the following UI:

LSP App Manager figure 1

Figure 1: WFS running on PC with IP and LSP App Mgr with IP

We have combined two browser windows in Figure 1. The top window shows the Web File Server (WFS) running on the host PC and the bottom window shows the LSP App Manager running in the embedded device. Note: See instructions below for information on using the Mako Server as an alternative to wfs if you do not have a ready to use wfs server.

You may either select the "net" ( NetIo ) or the "disk" ( DiskIo ) as the file system if you have included barracuda/xrc/DiskIo/[platform]/BaFile.c in your build. Only the "net" file system is available if you compiled with #define NO_BAIO_DISK.

The NetIo is the preferred file system for development even if your build includes a native file system. The NetIo lets you keep all Lua/LSP files on your host computer during development. The benefit with this construction is to prevent loss of data due to embedded file system corruption during development.

The top browser window in Figure 1 shows the WFS running on the host computer. The WFS acts as a remote file system for a device using the NetIo. The NetIo greatly simplifies development since the files may be physically stored on your host computer during development.

Notice how we browsed to the file location c:\development ( ) using the WFS in the first browser window in Figure 1. This address was copied to the "Directory/ZIP File" field in the LSP App Manager (bottom browser window in Fig. 1). You may click the browse button to further descend into the directory:

LSP App Manager figure 2

Figure 2: Browsing using NetIo at location:

You may right click in the tree to create new directories and to rename directories. Double click the directory to select it as the directory for your LSP/Lua application.

You may intend to only develop one LSP Application and if so, select "Root Application" as shown below:

LSP App Manager figure 3

Figure 3: Configuring the LSP directory as a "root application" in the virtual file system.

After clicking the submit button as shown in Figure 3, the LSP App Manager redirects you to the "Application List" as shown below.

LSP App Manager figure 4

Figure 4: The Application List shows all configured applications

You may edit the LSP application as soon as it is started. Click the Running button's state "No" to flip the switch and to start the new LSP application. The following figure shows the LSP IDE after flipping the switch and after clicking the Edit button:

LSP App Manager figure 5

Figure 5: The LSP App Manager's IDE

You may right click in the left pane to create new files and directories. Double clicking on a file opens the file in the integrated LSP IDE. The IDE lets you edit and run the Lua code from within the IDE. If you are using the NetIo, you may also use any other editor of your choice since the files are stored locally on your host computer.

The following video shows how to use the LSP App Manager using the older version which has a slightly different UI.

WebDAV and Web File Server Instance

A WebDAV and Web File Server instance is installed in the device at the URI '/fs/' if you included a native file system (BaFile.c) in your build. You may mount/map the embedded system's file system as a drive on your host computer and directly edit resource files on the device. See the following video if you are new to using WebDAV:

Application's and the .preload script

Unlike a standard web server, the Barracuda App Server supports what is known as the virtual file system and you may install not just one, but multiple web applications in the virtual file system. The LSP App Manager lets you create any number of applications.

The startup script:

For each application, you may optionally create a .preload script. An introduction to the .preload script concept can be found in the Mako Server's .preload documentation.

You may dynamically restart the .preload script by clicking the Running button's switch (Figure 4) twice.

The LSP App Manager's Configuration File

The LSP App Manager keeps the configured application(s) and their state in a JSON file. This file is stored on the embedded file system if the LSP App Manager is compiled with file system support or in the browser using Web Storage if the LSP App Manager is compiled with #define NO_BAIO_DISK.

The LSP application(s) startup state differs between a device with and without file system support:

Note: When using the NetIo, make sure to start the Web File Server on your host computer prior to booting the embedded device.

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

See the Lua debug instructions for the RT 1020 development board for information on how to debug Lua code on an embedded device.

Adding Lua Bindings

To access the device hardware via the embedded system's C code, custom Lua bindings must be added. See the getting started guide and advanced Lua bindings for how to create Lua bindings automatically or manually.

Let's Encrypt

The LSP App Manager enables automatic installation of trusted certificates for servers running on private networks. The LSP App Manager includes the two Mako Server modules acmebot and acmedns. Note that the LSP App Manager does not support configuration files, and the two modules must, therefore, be controlled programmatically.


  1. Read the Mako Server tutorial Let's Encrypt for an introduction to using the Let's Encrypt plugin.
  2. Make sure your build meets the compile time requirements as explained in the acme module.
  3. Use the provided Lua (LSP) example acme.lsp as a base for your user interface interaction. Note that a zone key is normally embedded in the firmware.
  4. When releasing the product and replacing the LSP App Manager with your own startup code, copy the Let's Encrypt initialization code in the LSP App Manager's .config script to your own .config script. See the acme module for details.

Creating the Release Build

You may create the final release when the development is complete.

The recommended release method is to ZIP all LSP files together and then convert the ZIP file to a C array using the bin2c tool. Your web application stored in the ZIP file may then be compiled and linked with your firmware. If you have a file system, you may optionally store the ZIP file on the file system. In any event, our recommendation is to always use the ZipIo for deployed applications and not to store web pages directly on the embedded file system. The ZipIo is in most cases faster than fetching resources directly from an embedded file system.

The LSP Application Manager's startup code LspAppMgr.c is designed for mounting an embedded ZIP file and to initially run the .config Lua startup script. You may use the file LspAppMgr.c "as is" for your release if you add the .config script we have prepared to the root of your application. The .config script opens the server's listening ports and loads the optional .preload script.

  1. Copy the .config script as explained above.
  2. Modify the .config script as needed.
  3. ZIP all files together and include any additional resources from the Barracuda App Server's resource directory or copy the resources from the original file. Note, the ZIP file must not include the name of the top directory.
  4. Convert the ZIP file to a C array as follows: bin2c -z getLspZipReader LspZip.c.
  5. Replace the original LspZip.c (The LSP App Manager's Lua code) with the file produced in step 3.
  6. Compile and link.

You may want to study the content of the original prior to creating your own ZIP file.

Note that you may create any number of ZIP files and associate each ZIP file with a Barracuda Resource Reader, thus effectively creating an app for each ZIP file. You may also have part of your application read resources via a DiskIo if you, for example, want your customers to be able to modify or add LSP code. The Barracuda App Server is extremely configurable and you may assemble a server anyway you want.


The following video shows how to use the LSP Application Manager for developing an IoT network client. The LSP Application Manager and the Web Server component are used for the initial development, then later disabled in the final product since only the client libraries are required.

NetIo Details

The NetIo is a Web File Server client specifically designed to operate a remote Web File Server Object. We provide a pre-compiled binary Web File Server. You may also use the Mako Server as the file server, but you must then create and install a Web File Server instance in the virtual file system. See the details below on how to use the Mako Server as the NetIo file server.

Note that you may get severe performance degradation when using the NetIo since the NetIo generates multiple requests for each resource fetched. The NetIo speed is directly proportional to the speed of the TCP/IP stack being used in the embedded system. The faster the TCP/IP stack, the faster the NetIo will respond. The following diagram illustrates a page request using the NetIo:

Browser        Embedded System         Web File Server
  |                   |                       |
  |    get page       |                       |
  | --------------->  |                       |
  |                   |  stat (file exists?)  |
  |                   | --------------------> |
  |                   |         yes           |
  |                   | <-------------------  |
  |                   |                       |
  |                   |   get fragment 1      |
  |                   | --------------------> |
  |                   |    fragment 1         |
  |     response      | <-------------------  |
  | <---------------  |                       |
  |                   |                       |
  |                   |   get fragment 2      |
  |                   | --------------------> |
  |                   |    fragment 2         |
  |     response      | <-------------------  |
  | <---------------  |                       |
  |                   |                       |
  |                   |                       |

Figure 6: Browser to Device to WFS Sequence Diagram

Configure the net file system as follows:
  1. The bin directory contains a pre-compiled Web File Server. Start bin/wfs.
  2. Make note of the port number used by the server.
  3. In the LSP Application Manager, select the net file system and click browse.
  4. Enter the path http://hostip:port/fs/, where hostip is your host computer's IP address and port is the port number the wfs executable is listening on.
  5. Press the "Submit" button.

Using the Mako Server as the NetIo file server:

  1. Download the Mako Server for your platform.
  2. Unpack the Mako Server and optionally install the server as explained on the Mako Server site.
  3. Navigate to a directory you want to act as the base for storing resources used by the NetIo client.
  4. Create directory 'www'.
  5. Create the file 'www/.preload'.
  6. Open the .preload file in an editor and paste the following content into the editor:
    local io = ba.openio"home"
    local ldir = ".LOCK"
    print("Creating WebDAV and WFS at http://address/fs/ using base path",
    if not io:stat(ldir) and not io:mkdir(ldir) then
       error"Cannot create the WebDAV lock dir"
    fsdir=ba.create.wfs("fs", io, ldir)
  7. Save the file and start the Mako Server as follows: [path/2/server/]mako -l::www.
  8. Make sure the file server is working by navigating to http://localhost/fs/.

You may now use the LSP Application Manager in the embedded device and enter the following URL for the NetIo: http://ip-address/fs/, where 'ip-address' is the IP address of the host computer running the Mako Server.

Block Diagram

The block diagram below includes the LSP Application Manager (in red), the Barracuda Application Server C library (yellow), and C startup code (orange). The LSP Application Manager's Lua application, which is embedded into the executable, is best visualized as Lua firmware. The Lua firmware is a compressed ZIP file stored inside the executable and made available to the Lua Virtual Machine via the ZipIo.

The LSP Application Manager's Component Diagram:

LSP Application Manager

Figure 7: LSP App Manager Block Diagram

The LSP Application Manager (red) is loaded by the C Startup Code (orange) at startup. The C Startup Code instructs the Lua Virtual Machine (VM) to load the Lua code from the embedded ZIP file.

The C Startup Code, which can be found in src/LspAppMgr.c, is also responsible for assembling a web server. The C code is similar to the code described in the getting started guide.