Mastering Xedge Application Deployment: From Installation to Creation

A ready-to-run Xedge application comes as a ZIP file. The foundation of Xedge, the Barracuda App Server, can mount and run applications directly from the ZIP file without the need to unzip the data. This approach streamlines application deployment and minimizes the storage footprint.

Whether you need to simply upload a collection of scripts or create fully automated, self-starting applications, the app uploader simplifies the process. It supports various deployment scenarios, ensuring your applications are up and running with minimal effort.

The following 30-second video demonstrates the drag-and-drop feature integrated into Xedge for effortless ZIP application deployment.

In the video above, the application automatically starts after uploading. You can upload any ZIP file, but it will not automatically launch unless it includes specific attributes tailored for Xedge compatibility. We'll delve deeper into this below when we explain how to Create a Ready-to-Run Xedge Application.

Manual Installation

An application packaged as a ZIP file can also be manually installed. To do so, navigate to http://server-name/rtl/apps/disk/ to access the web file manager. Here, you can drag and drop the ZIP file into the web file manager. Afterward, return to http://server-name/rtl/, expand the 'disk' section, right-click on the ZIP file, and select 'New App' to open the 'Application Configuration.' For more information on creating applications manually, see the tutorial Your First Xedge32 Project, section How to create and Xedge app.

How to Create a Ready-to-Run Xedge Application

Once you've completed the development of your application and it's ready to be deployed, you'll need to package it. Assuming your application is stored in a directory named "MyApp," you can zip all the files together using the following command:

cd MyApp
zip -D -q -u -r -9 ../MyApp.zip .

These commands are compatible with Linux and Windows operating systems. The parameters used with the zip command ensure that hidden files and directories are included, ensuring that your application is packaged comprehensively.

Note that excluding the application's root directory name in the ZIP file is required.

The MyApp.zip file we used in the above video is available for download from GitHub. We encourage you to download and unzip it, as we will discuss its contents below.

Inside the ZIP file, you'll find several files, including:

  • .preload - Application's preload script
  • MyTest.xlua - Example program
  • index.lsp - LSP page
  • .config - Xedge Lua application configuration script

The .preload script and MyTest.xlua are standard Xedge Lua files programmed to execute automatically when the application launches. These files contain basic code that outputs messages to the Xedge console, demonstrating the application's functionality. Moreover, the application supports Lua Server Pages (LSP), allowing the included index.lsp page to be accessed via a browser, as shown in the above video.

Understanding the .config File in Xedge Application Deployment

The .config file plays a key role in the automatic management of the Xedge application. After you upload your application, Xedge loads this configuration file and executes it as a Lua script. This process is essential for tailoring the application's setup within the Xedge environment. The .config script below is from MyApp.zip.

local function install(io)
   trace("Installing MyApp", io:resourcetype())
   return "The .config script: The app is installed"
end

local function upgrade(io)
   trace("Upgrading MyApp", io:resourcetype())
   return "The .config script: The app has been upgraded"
end

return {
   install=install,
   upgrade=upgrade,
   autostart=true,
   startprio=0,
   name="MyApp",
   dirname="myapp", -- LSP app @ http://domain/myapp/
}

The script must return a table, although all parameters within are optional. Here's a breakdown of what each parameter signifies:

  • install: Xedge executes this function for new installations. It's an opportunity to perform initial setup tasks, like creating any necessary external configuration scripts that users need to adjust.
  • upgrade: A function triggered if the application is upgraded, allowing for necessary adjustments post-upgrade.
  • autostart: When set to true, this parameter ensures the application automatically starts after being uploaded, simplifying the deployment process.
  • startprio: This controls the startup priority when autostart=true. The maximum priority is 0. The default priority is 100.
  • name: This is the name of the application as displayed in Xedge's navigation pane. If not specified, Xedge uses the ZIP file's name by default.
  • dirname: Required for applications that include Lua Server Pages (LSP), dirname specifies the base URL for accessing the application. If set to an empty string, the application is treated as a root application.

Both install and upgrade functions receive an IO instance as their argument, allowing them to perform file operations specific to the application. They can also return a text message, displayed in Xedge following the upload, providing immediate feedback on the installation or upgrade process, as demonstrated in the video above.

See the Xedge documentation for additional information.

Creating a Collection of Lua Modules and Using the Lua require Function

The Lua require Function:

Lua modules are small, reusable pieces of code that help organize and modularize your programs. The require function is essential for loading these modules, keeping your code clean and manageable. By using require("module_name"), you can easily import the needed module and access its functions and variables, which promotes code reuse and better organization.

Creating a Collection of Modules:

Many Lua modules available online are compatible with Xedge and can be imported and stored on the Xedge internal flash file system. An Xedge application is ideal for creating a collection of Lua modules since the collection is stored compressed on the device, optimizing storage space.

Step-by-Step Guide:

  1. Set Up Directory Structure:

    On your host computer (e.g., Windows), create the following directory structure:

    .config - The config script
    .preload – The Lua startup script
    .lua - A directory where you insert all the Lua modules
        
  2. Create the .config Script: The .config script should include something like this:

    return {
       autostart=true, -- Must auto start
       startprio=0, -- Must start early
       name="ModuleCollection", -- Any name
    }

    This configuration ensures that the Lua application starts when the device boots and that it starts before other applications that depend on the modules in this application.

  3. Write the .preload File: The .preload file should include one line of code:

    xedge.createloader(io)

    The xedge.createloader() function ensures the .lua directory is added to the Lua module search path.

  4. Zip the Files and Upload to Xedge:

    Zip together all of these files and upload them to the Xedge as previously explained. Any other Xedge application depending on the module(s) in this application should now function correctly.


Need a helping hand?

Unlock the potential of embedded web servers and IoT with our curated tutorials. They're your DIY toolkit for success. But if you're racing against the clock or need a deeper perspective, our expert consulting services are your ace in the hole. With Real Time Logic, you're never alone on your DIY journey. Let's collaborate and make magic happen!



OPC-UA

OPC-UA Client & Server

An easy to use OPC UA stack that enables bridging of OPC-UA enabled industrial products with cloud services, IT, and HTML5 user interfaces.

Edge Controller

Edge Controller

Use our user programmable Edge-Controller as a tool to accelerate development of the next generation industrial edge products and to facilitate rapid IoT and IIoT development.

On-Premises IoT

On-Premises IoT Platform

Learn how to use the Barracuda App Server as your On-Premises IoT Foundation.

Embedded Web Server

Barracuda Embedded Web Server

The compact Web Server C library is included in the Barracuda App Server protocol suite but can also be used standalone.

WebSocket Server

Microcontroller Friendly

The tiny Minnow Server enables modern web server user interfaces to be used as the graphical front end for tiny microcontrollers. Make sure to check out the reference design and the Minnow Server design guide.

WebDAV Server

Network File System

Why use FTP when you can use your device as a secure network drive.

HTTP Client

Secure HTTP Client Library

PikeHTTP is a compact and secure HTTP client C library that greatly simplifies the design of HTTP/REST style apps in C or C++.

WebSocket Client

Microcontroller Friendly

The embedded WebSocket C library lets developers design tiny and secure IoT applications based on the WebSocket protocol.

SMTP Client

Secure Embedded SMTP Library

Send alarms and other notifications from any microcontroller powered product.

Crypto Library

RayCrypto C Library

The RayCrypto engine is an extremely small and fast embedded crypto library designed specifically for embedded resource-constrained devices.

Embedded PKI Service

Automatic SSL Certificate Management for Devices

Real Time Logic's SharkTrust™ service is an automatic Public Key Infrastructure (PKI) solution for products containing an Embedded Web Server.

Modbus

Modbus TCP client

The Modbus client enables bridging of Modbus enabled industrial products with modern IoT devices and HTML5 powered HMIs.

Posted in Whitepapers