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 view the LSP Application Manager's ESP32 Video 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

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 (lsp.zip) 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 lsp.zip. 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 lsp.zip by running the included makefile as follows:

make plat=posix large=true ziplsp

The above command creates a full lsp.zip and LspZip.c. The full lsp.zip 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.

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 192.168.1.100 and LSP App Mgr with IP 192.168.116.1

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 (http://192.168.1.100/fs/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: http://192.168.1.100/fs/C/development/

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.

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.

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.

Prerequisites:

  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 lsp.zip 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 lsp.zip 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 lsp.zip 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.

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 for 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",
       io:realpath"")
if not io:stat(ldir) and not io:mkdir(ldir) then
   error"Cannot create the WebDAV lock dir"
end
require"wfs"
fsdir=ba.create.wfs("fs", io, ldir)
fsdir:insert()
  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.