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.
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 (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.
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.
The sub directory Lua-Examples includes ready to use examples.
You may use any of the examples as follows:
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.
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:
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:
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:
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.
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:
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.
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:
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 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.
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.
See the Lua debug instructions for the RT 1020 development board for information on how to debug Lua code on an embedded device.
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.
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:
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.
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.
Example:
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.
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:Using the Mako Server as the NetIo file server:
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()
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.
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:
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.