BWS and BAS Amalgamated

Embedded Web Server and IoT Toolkit C Code Libraries

• BAS and BWS License
• BWS: Barracuda Embedded Web Server C library
• BAS: Barracuda Embedded App Server C library

The BWS and BAS C code libraries are C89 compatible and support the following platforms: Embedded Linux, Zephyr, FreeRTOS+TCP or lwIP, VxWorks, QNX, INTEGRITY, Windows & Win CE, Azure RTOS, Nucleus RTOS, embOS, RTXC, SMX, MQX, RTOS-32, Mac, and UNIX/POSIX.

Real Time Logic has crafted the two amalgamated libraries from the full BAS SDK; Amalgamated indicates that we have combined all separate C files into one file, simplifying the compilation and integration process into your build. The products run on anything from tiny FPGA's to online cloud servers.

Both BWS and BAS are application servers that share the same porting layer modules, making their integration process almost identical. BAS includes all the C APIs available in BWS, but it goes a step further by focusing on the Lua language. This makes BAS handy for rapid development and offers an easier entry point for secure web and IoT app development. Check out the tutorial Embedded Web Server vs. Embedded Application Server if you are new to application server technology.

Web Server vs. App Server

The following video demonstrates two key points: how to test compile the Xedge RTOS example for Linux or Windows Subsystem for Linux and an explanation of the difference between an Embeddable Application Server library and an Embeddable Web Server library. For additional details, see the tutorial Embedded Web Server vs. Embedded Application Server.

BWS

The Barracuda Embedded Web Server is a small embedded HTTP(S) and WebSocket C source code library pre-integrated with the SharkSSL TLS stack. The source code is optimized for compact, deeply embedded devices.

• Barracuda Embedded Web Server Product Page

BAS

The Barracuda App Server, powered by BWS, is a powerful IoT toolkit that equips engineers with the necessary tools to create secure and efficient web and IoT products. While you can develop applications using C/C++ on BAS, it also features the powerful Lua engine. This engine is designed for ease of use, enabling developers to construct up to 80% of their embedded applications in Lua without compromising on efficiency.

• Barracuda App Server Product Page

When learning a new framework, it's not mastering the language that's time-consuming - it's understanding the API. The Lua IoT and Web APIs are considerably simpler and more intuitive than their lower-level C counterparts. For this reason, opting for Lua can significantly reduce your development time. Using Lua instead of C for network-enabled applications offers several compelling advantages:

• Ease of Use: Lua is renowned for its simplicity and elegance, significantly reducing the learning curve for new developers and speeding up the development process.
• Flexibility: Lua's lightweight and flexible nature makes it ideal for scripting customizable behaviors in network applications without the complexity often associated with C.
• Rapid Prototyping: Lua enables faster prototyping and iteration, which is crucial in IoT development.
• Enhanced Security: Lua provides a higher-level approach that abstracts many low-level operations, reducing the risk of security flaws that are more prevalent in direct system-level coding with C.
• Efficiency: Although Lua is an interpreted language, it runs efficiently on embedded systems, thanks to its well-optimized engine and the ability to offload performance-critical tasks back to C modules if necessary.
• Lua Server Pages (LSP for short) is a Lua API that includes a compact and efficient Lua web framework, non-blocking asynchronous sockets, and many (I)IoT protocols.

Are you already using Lua? Not a problem!

The Lua source code is included in BAS.c, but you can exclude this code by compiling with -DUSE_BA_LUA=0. You can compile and link BAS.c with your Lua version by excluding our version.

C Code Components

Include the following in your build:

• Amalgamated C code library (amalgamation of many files); one of:
  • BWS.c: The Barracuda Web Server
  • BAS.c: The Barracuda App Server
• ThreadLib.c: Kernel porting layer
• SoDisp.c: TCP/IP porting layer (the socket dispatcher)
• BaFile.c: File system porting layer (optional)

Who Can Use BAS Amalgamated

BAS Amalgamated runs efficiently on a Cortex M4 running @100Mhz and up; however, most microcontrollers will need external memory. See the Memory section in the Porting Barracuda to an Embedded System for details.

Before Downloading the Source Code

The Barracuda App Server is a feature-rich product. To ease into its diverse options, you might find it helpful to start by downloading one of the pre-compiled binaries with included Lua tutorials, which are complemented with handy Lua tutorials, prior to accessing the source code.

How To Compile

To compile BAS, include BAS.c, src/arch/XXX/ThreadLib.c, src/arch/NET/XXX/SoDisp.c, and optionally src/DiskIo/XXX/BaFile.c, where XXX is the required porting layer. In addition, the compiler's include path must include inc/arch/XXX, inc/arch/NET/XXX, and optionally inc/DiskIo/XXX

BAS is extremely flexible and can, for example, be used as follows:

• Compiled and integrated with RTOS powered monolithic firmware
• Compiled and run as a process on a High Level Operating System (HLOS) such as embedded Linux
• Compiled and integrated with a standard (desktop) application

BAS Amalgamated is very easy to compile and several command line compilation examples are shown below. You can add the code to any IDE and Makefile system.

Examples

BAS and BWS are versatile C libraries designed for seamless integration into a wide range of devices and programs, from small ASIC-powered gadgets to Windows applications. To help you get started with the libraries, we provide three ready-to-use reference builds:

• The Mako Server (BAS)

• The Xedge (BAS)

• The C++ WebSocket Server Example (BWS)

• BAS Examples: The Mako Server is designed for HLOS, and Xedge is designed for RTOS. Both examples provide a Lua foundation enabling rapid interactive development of web, IoT, and business logic (high level logic).

• BWS Example: The C++ WebSocket Server Example shows how to implement everything using C code.

Mako Server (HLOS)

The Mako Server Example can be compiled for High Level Operating Systems (HLOS) such as Windows, (embedded) Linux, QNX, and VxWorks.

Windows:

Use the Visual Studio project file found in: BAS/examples/MakoServer/VcMake; however, make sure to download SQLite or disable the SQLite build in the project file.

Linux:

See the tutorial Embedded Linux Web Interface Design for details; however, the server can be downloaded and compiled for Linux as follows:

bash <(wget -O - https://raw.githubusercontent.com/RealTimeLogic/BAS/main/LinuxBuild.sh)

Download and cross-compile the code for (embedded) Linux as follows:

export CC=/opt/gcc-linaro-7.1.1-2017.08-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-gcc
bash <(wget -O - https://raw.githubusercontent.com/RealTimeLogic/BAS/main/LinuxBuild.sh)
Change the above CC environment variable to your cross-compiler.

Download and cross-compile the code, including Lua GPIO bindings, for embedded Linux as follows:

export CROSS_COMPILE=/opt/gcc-linaro-7.1.1-2017.08-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-
bash <(wget -O - https://raw.githubusercontent.com/RealTimeLogic/BAS/main/RaspberryPiBuild.sh)

Details:

The following example builds the Mako Server without SQLite for HLOS. You can copy and paste the command into a Linux shell. Note that you can also download pre-compiled Mako Server versions for many operating systems on the Mako Server Web Site.

gcc -o examples/MakoServer/mako -fmerge-all-constants -O3 -Os\
    -DUSE_EMBEDDED_ZIP=0 -DBA_FILESIZE64 -DLUA_USE_LINUX -DMAKO -DUSE_SQL=0\
    -Iinc -Iinc/arch/Posix -Iinc/arch/NET/Posix\
    src/BAS.c\
    src/arch/Posix/ThreadLib.c src/arch/NET/generic/SoDisp.c src/DiskIo/posix/BaFile.c\
    examples/MakoServer/src/MakoMain.c\
    -lpthread -lm -ldl

The above command works for any HLOS with a GCC compiler (and derivatives), including cross compiling for embedded Linux, compiling for QNX, and compiling for VxWorks 7. Simply replace 'gcc' with the applicable compiler. Note that VxWorks is a cross between HLOS and RTOS; thus, you may consider using Xedge instead (details below). BAS supports VxWorks 5 and up.

See the Mako Server's Build Documentation for details on macros and other important information, but note that the amalgamated version in the standard SDK works differently.

After running the above compilation command and after building mako.zip using the mako script, start the server as follows:

$examples/MakoServer/mako

Mako Server. Version 3.7
BAS lib 4920. Build date: Dec  2 2021
Copyright (c) Real Time Logic.

Mounting /tmp/BAS/examples/MakoServer/mako.zip
Server listening on IPv6 port 9357
Server listening on IPv4 port 9357
Loading certificate MakoServer
SharkSSL server listening on IPv6 port 9443
SharkSSL server listening on IPv4 port 9443

Compiling for Windows

The following example compiles and links the server as a 64 bit Windows application using the Visual Studio command line compiler (cl). Note that we include two additional C files. These two C files make it possible to run the server as a Windows service. Note that the pre-compiled Mako Server for Windows is compiled as a 32 bit application.

cl /O2^
 /DUSE_EMBEDDED_ZIP=0 /DBA_FILESIZE64 /DMAKO /DUSE_SQL=0^
 /Iinc /Iinc/arch/Windows /Iinc/arch/NET/Windows^
 src/BAS.c^
 src/arch/Windows/ThreadLib.c src/arch/NET/generic/SoDisp.c src/DiskIo/windows/BaFile.c^
 examples/MakoServer/src/MakoMain.c^
 examples/MakoServer/src/Windows/MakoWinMain.c examples/MakoServer/src/Windows/servutil.c^
 ws2_32.lib kernel32.lib User32.lib Gdi32.lib advapi32.lib ole32.lib oleaut32.lib shell32.lib^
 /link /machine:X64 /OUT:examples/MakoServer/mako.exe

The above command requires setting up the command line for 64 bit compilation. The above can be copied and pasted "as is" into a command window.

Including SQLite in the Build

The Mako Server can optionally be linked with the SQLite database engine. The following command shows how to include SQLite and activate the Lua SQLite bindings. However, before running the compilation command, download SQLite and copy sqlite3.c and sqlite3.h to the BAS/src directory.

gcc -o examples/MakoServer/mako -fmerge-all-constants -O3 -Os\
    -DUSE_EMBEDDED_ZIP=0 -DBA_FILESIZE64 -DLUA_USE_LINUX -DMAKO\
    -Iinc -Iinc/arch/Posix -Iinc/arch/NET/Posix\
    src/BAS.c\
    src/arch/Posix/ThreadLib.c src/arch/NET/generic/SoDisp.c src/DiskIo/posix/BaFile.c\
    examples/MakoServer/src/MakoMain.c\
    src/ls_sqlite3.c src/luasql.c src/sqlite3.c\
    -lpthread -lm -ldl

Xedge (RTOS)

The Xedge is designed as a Lua foundation and an interactive development environment that enables the development of Lua code directly on an embedded device. When you are done with the development, the code enables several options for producing a release (final product). In the following instructions, we cover how to build the tool. See the online Xedge documentation for details on how to use this tool.

Compiling and Integrating Xedge

The Xedge IDE tool comprises a Single-Page Web Application (SPA) and supporting server-side code. These resources are crucial and must be included in the build.

Please note that the above compilation process is just an example - the Barracuda App Server platform is flexible and can support any deployment strategy you require. For a quick overview of compiling Xedge, check out the tutorial Rapid Firmware Development with the Barracuda App Server. This tutorial also shows how to replace the integrated IDE with a custom IoT application. While it uses an ESP32, the same method applies to any CPU.

Fetch the repos and build the resource ZIP file:

# Fetch the Barracuda App Server
git clone https://github.com/RealTimeLogic/BAS.git
# Fetch the Barracuda App Server's resources
git clone https://github.com/RealTimeLogic/BAS-Resources.git
# Go to the build directory
cd BAS-Resources/build/
# Run the build script. If on Windows, use Xedge.cmd
# When prompted, initially select n for OPC-UA, s for small cacert.shark,
# and n for compressing the files
. Xedge.sh
# The ZIP file is converted to a C array by the build script;
# copy this to the Xedge directory
cp XedgeZip.c ../../BAS/examples/xedge/
cd ../../BAS

The file XedgeZip.c embodies Xedge's resources, transformed into a C file. You can uncover this file's resources and detailed build instructions in the BAS-Resources Repository.

To compile Xedge, include BAS.c as previously explained. In the following example, we use Linux as an example and compile the server into a standalone product. For an embedded device, include the files in your build.

gcc -o examples/xedge/xedge -Iinc -Iinc/arch/Posix -Iinc/arch/NET/Posix\
    src/BAS.c\
    examples/HostInit/Main.c examples/HostInit/HostInit.c\
    src/arch/Posix/ThreadLib.c src/arch/NET/generic/SoDisp.c src/DiskIo/posix/BaFile.c\
    examples/xedge/src/xedge.c examples/xedge/src/led.c\
    examples/xedge/XedgeZip.c -lpthread -lm

• The above produces a warning when compiled on Linux. You can remove the warning by specifying a POSIX environment by adding -DLUA_USE_POSIX.

• The files Main.c and HostInit.c are designed for a non-embedded host build. You need to study those two files and set up similar code for your RTOS environment. At a minimum, you need a dedicated thread to run the function barracuda(void), which does not return, with stack size BA_STACKSZ.

• The file xedge.c is the Xedge's C startup code.

• The file led.c includes example Lua bindings. You can remove this from your build by defining -DNO_XEDGE_AUX or simply removing the function call in xedge.c

• For embedded, a recommendation is to initially tests the server without file system support. Remove the file BaFile.c from your build and compile with -DNO_BAIO_DISK, a macro used by xedge.c

• If you get a link error that includes dlmalloc, include src/dlmalloc.c in your build and initialize the allocator as shown in the file examples/HostInit/Main.c.

• Note: The Xedge build instructions provided above are an excerpt from the Xedge full SDK build guide, which includes additional details such as creating a release build. Please note that there are minor differences in file locations between the two.

Cross Compiling Xedge for Embedded Systems

Include the files as instructed above in your IDE or Makefile. Most embedded systems require an efficient allocator, which is included. See, for example, the FreeRTOS Readme File for how to set up all required components. Most embedded RTOSs require the same setup.

Pre-compiled binaries: Try running the server on an ESP32 using FreeRTOS and lwIP, even if you plan to use a different RTOS or device. The ESP32 is user-friendly and great for learning about RTOS. Use the pre-compiled ESP32 Xedge binaries for this purpose.

Enabling and Disabling 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.

• USE_DBGMON=1: Include Lua Debugger Support.
• USE_REVCON=1: Enable the reverse connection if you plan on using the connection bridge feature in SharkTrustX. Note that both Xedge and the Mako Server include the Let's Encrypt plugins acmebot and acmedns.
• USE_OPCUA=1: The OPC-UA stack is implemented in Lua and can be found in mako.zip/.lua/opcua. The OPC-UA stack requires a C module. Enable this flag when compiling BAS if you plan on using OPC-UA.
• USE_FORKPTY=1: Enable the advanced process management API, which is available for Linux and QNX. This API is required if you plan on using the CGI plugin or the web shell.
• USE_REDIRECTOR=1: Enable the Reverse Proxy
• USE_UBJSON=1: Enable Universal Binary JSON

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.

• SHARKSSL_ENABLE_ASN1_KEY_CREATION=1
• SHARKSSL_ENABLE_RSAKEY_CREATE=1
• SHARKSSL_ENABLE_ECCKEY_CREATE=1
• SHARKSSL_ENABLE_CSR_CREATION=1
• SHARKSSL_ENABLE_CSR_SIGNING=1

The following Mako Server specific macro enables loading external Lua modules. When not using a pre-built Mako Server and when using the source code you can instead choose to integrate additional Lua bindings directly with your build.

• USE_LUAINTF

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

• LUA_NUMBER_INTEGER=1

  • Makes Lua use integer only and excludes floating point numbers. To re-enable floating point, compile the code with:

• LUA_NUMBER_INTEGER=0

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

• NO_LDEBUG

  • Exclude the Lua "debug" module

• Mako Server Specifics:

  • NO_SHARKTRUST
  • Do no include tokengen.c; disable built-in SharkTrustX key

• Xedge Specifics:

  • NO_SHARKTRUST
  • NO_ENCRYPTIONKEY
  • Do not include NewEncryptionKey.h; disable soft TPM
  • NO_XEDGE_AUX
  • Do not call xedgeOpenAUX() (your own Lua bindings)

Porting Layers

Contact Real Time Logic should you have a problem with the porting layer when used with your version of the target APIs.

The generic directory 'inc' must also be in the include path.

Additional Build Examples

VxWorks

The following example shows how to compile Mako Server for VxWorks 7. Use Xedge if you are using an older VxWorks version.

wr-cc -o examples/MakoServer/mako -static -fmerge-all-constants -O3 -Os\
    -DUSE_EMBEDDED_ZIP=0 -DBA_FILESIZE64 -DBA_HAS_ANSI_IO -DMAKO -DUSE_SQL=0\
    -DLUA_NUMBER_INTEGER=0\
    -Iinc -Iinc/arch/VxWorks -Iinc/arch/NET/Posix\
    src/BAS.c\
    src/arch/VxWorks/ThreadLib.c src/arch/NET/generic/SoDisp.c src/DiskIo/posix/BaFile.c\
    examples/MakoServer/src/MakoMain.c\
    -lnet

Note that we are not including SQLite support. You can include SQLite by using the SQLite version provided by Wind River.

Azure RTOS using IAR

The following example shows how to compile the generic BAS library for Azure RTOS using IAR for ARM. We have the following directories tx (ThreadX), nx (NetX), and BAS.

iccarm -e -c^
  -Itx -Inx^
  -IBAS/inc -IBAS/inc/arch/ThreadX^
  BAS/src/BAS.c

Using the above compilation settings, you would also need to include src/arch/ThreadX/ThreadLib.c, src/arch/ThreadX/SoDisp.c, and optionally src/DiskIo/FileX/BaFile.c.

FreeRTOS

i.MX RT1020

Download a ready to compile and run project for i.MX RT1020.

ESP32

Xedge32 is an Xedge version for the ESP32 and ESP32-S3 microcontrollers.

Barracuda App Server Tutorials

• What is an Embedded Application Server?
• Using Lua for IoT and Web Application Development
• Online Interactive Lua and LSP Tutorials
• Modern Approach to Embedding a Web Server in a Device
• The Ultimate Guide to Embedded Web Server Technology
• A Large List of Mako/BAS Tutorials
• Ready To Run Examples (GitHub)

Online Documentation

• Introduction
• Lua APIs
• BAS/BWS C/C++ API
• SharkSSL TLS Stack C/C++ API

License

BAS and BWS Amalgamated are licensed for use under the GPLv2 or a standard commercial license. For our users who cannot use BAS and BWS Amalgamated under GPLv2, a commercial license is available. A free commercial license for small companies is available. See the startup license page for details: https://realtimelogic.com/startuplic/

GPLv2 details:

The following clarification is for users who choose to use GPLv2 and to distribute derivative work. The GPLv2 license applies to all BAS and BWS APIs including, but not limited to the BAS and BWS C APIs, BAS Lua APIs, and web content hosted by a BAS and BWS derivative product. Web content hosted by the server is considered part of the application as a whole.

GPLv2: https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html