Using Xedge

Xedge is a Lua-based application environment built on the Barracuda App Server. It lets you create, run, update, and deploy Lua and LSP applications on an embedded device without rebuilding the full firmware for every application change.

This page explains how to use Xedge. For the product overview, benefits, and design philosophy, see the online Xedge product page. For standalone firmware build and porting instructions, see Building Xedge Standalone with BAS.

Quick Map

Video: How to use the Xedge IDE

The video shows the basic IDE workflow: create a web application, open files, keep files pinned in the editor, and start or stop applications. It uses the Xedge IDE integrated into the online Lua tutorial. You can try the same environment by opening the Online Lua tutorial: Xedge.

With Xedge, you can manage multiple Lua applications and LSP web applications on the same device. Running applications are shown in green in the left pane. The net file system is a network file system and must be initialized before use. See Using the NetIO for setup details.

The Two Xedge Versions

1) Xedge for Mako Server

When using the Mako Server, Xedge is typically loaded as follows:

mako -l::xedge.zip

Download a pre-assembled Xedge.zip for the Mako Server.

See Mako Server: Xedge IDE for setup instructions and integration details when running the IDE with Mako Server. If you want immediate hands-on experience, try the online Lua tutorial, which includes a Mako Server-powered, fully functional Xedge IDE ready to use directly in your browser.

2) Xedge standalone (RTOS)

When running standalone on an embedded device, the Xedge Lua application and web UI are integrated into the firmware along with the Xedge C startup code. Use this page after Xedge is running. For firmware build and porting instructions, see Building Xedge Standalone with BAS.

We also offer an advanced ready-to-run Xedge reference version known as Xedge32:

• Download Xedge32
• Xedge32 Documentation

Security Model

Xedge stores configuration data, including passwords and other sensitive settings, in an encrypted JSON-encoded database file named xcfg.bin. The protection model differs slightly between the standalone firmware version and the Mako Server version.

Standalone Version

In standalone Xedge, the server-side application can be embedded as a ZIP file in the firmware. The effectiveness of encrypted application storage and the software-based Trusted Platform Module (softTPM) depends on the product secret, device-specific input, firmware protections, and attacker capabilities. Configure the required C startup settings as described in Standalone Xedge Version and Security Settings, and review the softTPM security model and limitations.

Xedge Mako Server Version

The Xedge Mako Server version uses a per-device secret, allowing the database to be decrypted only on the same machine where it was created. Copying the xcfg.bin file to another machine will not compromise the data since decryption is not possible elsewhere. To enhance the security of the Xedge Mako Server version and strengthen database protection, follow the guidelines on the Xedge GitHub page.

Visual Studio Code-like Editor

Xedge uses the Monaco Editor when the browser can reach the unpkg.com Content Delivery Network (CDN). Monaco provides the editing engine used by Visual Studio Code (VS Code). Because of its size, Xedge does not embed Monaco in its package and falls back to a basic editor when the CDN is unavailable. The message "cannot load the Monaco Editor" indicates that the browser could not reach the CDN.

Create and Manage Xedge Applications

When Xedge starts, the left pane shows the file systems registered by the platform-specific C code. The available file systems vary by target. A disk-enabled target may show a persistent disk file system, while a development setup may also show a network file system such as net.

The usual workflow is:

1. Expand one of the file systems in the left pane.
2. Create or select a directory that will become the application root.
3. Open the context menu by right-clicking or long-pressing the directory.
4. Select New App and configure the application.
5. Add .preload, .xlua, LSP, or other application files as needed.
6. Start, stop, or restart the application from the IDE.

You can also register a deployed Lua application packaged as a ZIP file. ZIP-based applications are read-only in the IDE and are typically used for deployment or OTA-style updates. For more information, see Xedge Application Deployment: From Installation to Creation.

The tutorial Your First Xedge32 Project is useful even if you are not using ESP32 because it shows the Xedge IDE workflow in a concrete device-oriented project.

AI-Assisted Development with LSP-Claw

If you use AI agents for Xedge development, consider using LSP-Claw. LSP-Claw is an MCP server that runs inside Mako Server or Xedge and gives the AI agent a controlled lab application where it can inspect files, create Lua and LSP applications, start or restart the lab, and read trace output instead of editing arbitrary local files.

For Xedge standalone and RTOS targets, install LSP-Claw as an Xedge application. The MCP endpoint is then typically available at http://device-address/lsp-claw/mcp.lsp. See the LSP-Claw GitHub repository for setup instructions, AI agent configuration examples, and starter prompts.

Creating Xedge Applications

Begin by expanding a file system. Navigate to the destination directory or create a new one using the Context Menu. You can open the Context Menu by right-clicking on a resource or long-pressing using a tablet or phone. Select "New App" in the Context Menu to open the Application Configuration dialog. After creating an application, the left pane tree view refreshes, and your new app appears in the tree view.

Xedge Application Details and Lua Environments (_ENV)

An Xedge application is either a directory or a ZIP file managed by Xedge. The application can contain startup code, long-running Lua programs, and optional web pages. Xedge starts the application by loading its special files in a defined way:

If you're new to Lua, start with our online Lua Scope Tutorial, which offers a clear and practical introduction to how Lua environments work. The Mako Server uses the same .preload script concept; the tutorial Lua Environments and the .preload Script is a good follow-up resource.

An application can include web pages when it is LSP enabled. Enable LSP in the Application Configuration dialog when the application must serve a browser-based UI or other dynamic web content.

Every .preload file and .xlua file in an Xedge application runs in its own Lua environment, so they operate separately from each other. However, .xlua files inherit elements from the .preload file, which means functions, variables, and libraries defined in the .preload file can be used by the .xlua files. Each .preload file also inherits from the global environment. Think of these environments as a stack of individual sheets, where each sheet represents an environment. The global environment is at the top, the .preload file environment is in the middle, and the .xlua file environments are at the bottom. This relationship is illustrated in figure 1.

Figure 1: Applications and individual files managed by Xedge

The .xlua files are the cornerstones of the Lua REPL. Each running .xlua file should be considered as an independent program. Saving this file terminates any previous version, and the new version is loaded and executed. By separating Lua into individual programs, developers can work on one program while having separate programs run independently, enabling development in a running system.

An .xlua file is typically used for non-visual programs that interact with hardware resources, run protocol clients such as MQTT, or maintain background logic. Use LSP for browser-facing web applications.

Web Applications:

If you want to design web applications in Xedge, use the 'LSP' (Lua Server Pages) feature. This requires enabling 'LSP' for your application, which you can do through the application configuration dialog.

An 'LSP-enabled' application contains files with the .lsp extension. Usually, there will be a file called 'index.lsp' in the root directory of the application, which serves as the entry point for your web application.

While .lsp pages can access the environment established by the .preload file, they do not inherit any elements from it, unlike .xlua files. To better understand how .lsp pages operate and interact with the rest of the application, see the Command Environment section.

Lua REPL and Hardware Resources

Xedge is designed to quickly tear down and recreate Lua programs, enabling fast testing and development. The Lua language includes a garbage collector that eventually collects (destroys) non-referenced Lua code. When a program restarts, the old version is dereferenced and replaced with a new one. However, when working with hardware resources, relying on the garbage collector may not be practical since there may be only one resource or a very limited set of resources. Hardware resources should generally be released immediately in a REPL. For this reason, Xedge includes logic that can automatically shut down resources when a program is renewed.

For optimal results, hardware resources should not be declared using the Lua keyword "local" when using the REPL. If you do, ensure that you use the unload handler to release the resource. The unload handler is executed when the program is shut down (or replaced with a new version).

ESP32 example 1, not using the local keyword:

pin18 = esp32.gpio(18,"OUT")

ESP32 example 2, using the "local" keyword:

local pin18 = esp32.gpio(18,"OUT")

function onunload()
   pin18:close()
end

These considerations apply to any resource, not just hardware resources, when using the REPL.

The Xedge Virtual File System

The Xedge UI is a Single Page Application (SPA) that works through a virtualized file system exposed by the server-side Xedge application. You can access the same file system outside the IDE by opening http://device-address/rtl/apps/.

Figure 2 shows the Web File Manager and Windows File Explorer mapped as a WebDAV drive. When you use the Web File Manager or WebDAV, you work directly with the files behind the Xedge applications. Saving an .xlua file through an external editor, for example, triggers the same server-side reload logic as saving the file in the IDE.

Figure 2: Accessing the Xedge virtual file system.

Check the WebDAV product page if you are new to WebDAV.

Configuration

You can access the configuration menu by clicking the three dots located in the top-right corner of the interface.

SMTP Settings

By enabling the SMTP settings, Xedge can send important information by email. One notable feature is reporting Lua exceptions. If one of your Lua programs crashes, a detailed message is sent to your email address. SMTP settings also enable the xedge.elog() function, allowing you to send messages by email. Unless it is an emergency message with the flush attribute set, messages are accumulated and sent in bulk when either the maximum size or time limit is reached. Note that email messaging is automatically disabled when the Xedge browser UI is connected to an Xedge device.

See the tutorial How to Send Emails with the Xedge IDE for a step-by-step guide to configuring the SMTP settings.

Automatic Certificate Management Environment (ACME)

Xedge can obtain and renew a browser-trusted TLS certificate for a device on a private network. The certificate page uses a SharkTrust portal to register the device name and publish the temporary DNS record required by Let's Encrypt. Open the configuration menu from the three dots in the top-right corner, then select Auto Certificate Management.

For a first test, enter an email address, choose an unused device name, enable Let's Encrypt Staging, and click Save. Xedge checks the name, saves the settings, waits for a valid system clock when necessary, enrolls the device, and requests a certificate. A staging certificate is not trusted by browsers. Disable staging after the complete process works.

After a device is registered, the page keeps its assigned name and ACME email address read-only. Changing the custom portal, zone key, or zone secret selects another SharkTrust identity and requires new device enrollment. Switching only between the Let's Encrypt staging and production services preserves the SharkTrust registration, but creates or selects a separate ACME account and certificate profile.

Xedge automatically uses its integrated Trusted Platform Module (TPM) interface for ECC certificate keys when the interface is available. Otherwise it creates a software ECC key. The saved ACME state contains a TPM key descriptor rather than a plaintext ECC private key when the TPM is used.

🚫 Test Identity Only

A zone identity included with a precompiled Xedge package is intended for testing and home use with the associated Real Time Logic domain. A product deployment should use its own SharkTrust portal and protected zone identity.

The Xedge page exposes the normal user settings only. Applications that need direct Lua control should use the shared ACME module guide, starting with acme/runtime. The generic reference also explains HTTP-01, automatic DNS-01, manual DNS-01, storage, lifecycle callbacks, and lower-level APIs.

Authentication

Xedge supports both local user accounts and Single Sign-On (SSO). To open the Authentication Settings, click the three dots, followed by clicking Authentication.

Installing an authenticator changes how you access the Web File Manager and the WebDAV server. First log in to Xedge at https://device-name/rtl/, or at http://localhost/rtl/ during local testing. You can then open /rtl/apps/. To use WebDAV, open the Web File Manager, right-click the file or directory you want to access, and select Copy Session URL. Use this URL when mapping the WebDAV drive. A Session URL contains a login token and must be protected like a password.

Local Users

You can create multiple local users. To add a new user, input the desired username and password. To remove an existing user, enter the username and leave the password field empty.

Keep a recovery account while configuring SSO.

Create and test a local user before enabling Single Sign-On. This account lets you return to the Authentication Settings if the external identity configuration fails. After SSO has been tested from a separate browser session and you have a recovery plan, you can remove the local user.

Single Sign-On (SSO)

SSO is a user authentication process that enables users to access multiple applications with just one set of login credentials.

If you are new to SSO, be sure to check out the Single Sign-On tutorial. It provides an introduction to using SSO with Xedge.

Xedge supports Microsoft Entra ID Single-Sign-On (SSO), a feature that simplifies user access to multiple applications using a single set of credentials. To set up users, they must be part of the organization's Entra ID tenant, with appropriate roles and permissions assigned to access the desired applications. Configuring SSO involves registering the applications, defining user access, and managing authentication settings in the Entra ID portal.

Entra ID offers a free tier with basic features that can support smaller-scale use, such as for personal or family purposes. To get started, you need to sign up for a free Microsoft Azure account and create an Entra ID tenant. Then, you can invite your friends as users in your tenant and configure access to applications using Entra ID and SSO.

Choose the device URL before configuring SSO. Use localhost for local testing. For a physical device, do not use its IP address as the normal SSO address. Configure automatic certificate management, assign the device a domain name, and access Xedge through that trusted HTTPS URL.

Xedge derives and stores the Entra redirect URI from the URL used when you save the SSO settings. The scheme, host name, port, and path must match the redirect URI registered in Entra. For example, if you save the settings while using https://device.example.com/rtl/, register https://device.example.com/rtl/login/. If you later change from localhost to a device domain name, register the new redirect URI and save the Xedge SSO settings again while connected through the new URL.

After signing up for Entra ID, create the required SSO settings as follows:

1. Open the Azure portal and click on the Microsoft Entra ID icon.
2. In the left pane, click on App registrations.
3. At the top of the page, click on + New registration.
4. Enter a suitable name for your application.
5. In most cases, the account type should be set to Single tenant.
6. Click on Select a platform and choose Web. Do not register the Xedge callback under Single-page application.
7. Enter the exact Xedge redirect URI. The path must end with /rtl/login/. Use http://localhost/rtl/login/ for a local test or a trusted HTTPS URL such as https://device.example.com/rtl/login/ for a device.
8. Click on Register at the bottom of the page.
9. On the following page, make sure to copy and save both the Application (client) ID and Directory (tenant) ID.
10. Navigate to Client credentials and click on Add a certificate or secret.
11. Click on + New client secret.
12. Provide a name for your client secret.
13. Choose a suitable expiration date for the secret.
14. Click on Add at the bottom of the page.
15. Finally, copy the client secret Value immediately, as you will not be able to see this value again.
16. Open Xedge through the same URL used in the registered redirect URI. Enter the Directory (tenant) ID, Application (client) ID, client secret Value, and secret expiration date in the Authentication Settings, then click Save.
17. Test SSO in a separate browser session before removing the local recovery user.

Replacing an invalid or expired client secret

A client secret can be set to a maximum of two years. If Microsoft Entra reports that the configured secret is invalid or expired, Xedge presents a recovery form during login. An administrator who can manage the Entra app registration must create a new secret and enter its Value, not its Secret ID, together with its expiration date. Xedge tests the replacement by completing a Microsoft sign-in and saves it only after that sign-in succeeds.

Disabling SSO

Open the Authentication Settings, clear the Tenant ID, Client ID, and Client Secret fields together, then click Save. Clearing only some of these fields is treated as incomplete configuration.

SSO troubleshooting

See the Microsoft Entra authentication error reference for other error codes.

After completing these instructions, you can grant individual users within the organization access to the application by following these steps:

1. In the Azure portal, click on the Microsoft Entra ID icon.
2. In the left pane, click on Enterprise applications.
3. Search for and select the application you just registered in the application list.
4. Click on the Users and groups tab in the application's Overview page.
5. Click on the + Add user button, located above the users list.
6. In the Add Assignment panel, click on the Users and groups field.
7. Search for and select the individual users you want to grant access to the application. You can select multiple users by clicking on the checkboxes next to their names.
8. After selecting all users you want to grant access to, click on the Select button at the bottom of the panel.
9. Optionally, you can assign a specific role to the users by selecting it from the Role dropdown menu. If no roles are defined for the application, users will be assigned the default access.
10. Click on the Assign button at the bottom of the panel to grant the selected users access to the application.

Xedge API

Xedge extends the API provided by the Barracuda App Server with a few additional APIs. The Xedge ESP32 reference example Xedge32 also extends Xedge with a wealth of ready-to-use hardware (GPIO) APIs.

The global xedge object includes many functions and objects. All of them should be considered private, except for the ones listed below.

xedge.createloader(io)

New applications should use appreq for private modules. It keeps the module state local to the Xedge application.

xedge.createloader(io) is retained for applications that intentionally load application modules with the standard require() function. It extends require()'s search path so it can find Lua files in the current application's .lua directory. If an existing application needs this compatibility behavior, add the following line to the beginning of the application's .preload script.

xedge.createloader(io) -- io is the application's pre-defined IO interface

xedge.createloader() works with applications loaded from either a directory or a ZIP file. Keep it for compatibility with applications that intentionally place modules in the global require() search and cache.

Xedge and BAS do not include a package manager. When several applications need the same Lua modules, manually assemble those modules into a separate application and load that application before the applications that depend on it. The shared module application can call xedge.createloader(io) from its .preload script so dependent applications can use standard require() for the shared modules.

The example application require-test (GitHub) shows the require()-based pattern.

appreq(module)

Loads and caches a private module from the current application's .lua directory. The function is installed when the application has a .preload script. Mako Server and Xedge share the same appreq behavior; see the Mako Server's appreq(module) documentation and examples.

Use standard require() for built-in Xedge/BAS modules and deliberately shared modules. appreq is not available when Xedge runs a standalone script using xedge script.lua.

xedge.elog(op, formatstring, ...)

xedge.eflush([op])

The functions elog and eflush are enabled if the SMTP settings have been configured. Function elog either appends to the internal message queue or flushes the queue after 30 seconds if the option table includes the attribute flush set to true. Function eflush sets flush to true and immediately flushes the message queue by sending an email.

The option table op may include:

• Boolean ts: prepend a timestamp to the message.
• Boolean flush: send the email. This flag is automatically set when calling eflush. When flush is set to true, the following attributes accepted by mail:send() may be set: subject, from, to, cc, bcc, and attach.

Note: When a browser is connected to the Xedge IDE, calling xedge.elog() has the same effect as calling xedge.log(). In other words, no email is sent or buffered, so calling xedge.eflush() has no effect.

xedge.event(event, cb [, remove])

• String event - The event name to subscribe to.
• Function cb - The event callback handler.
• Boolean remove - The event handler is installed if this argument is not set or if it is false. The event handler is removed if this argument is true.

Xedge.event() serves as a messaging distribution handler. To subscribe to events, install a callback function. To remove the callback, call the function with the same parameters and set the third argument to true.

To trigger an event, invoke the global function _XedgeEvent(event, ...). The first parameter must specify the event name. The _XedgeEvent() function is primarily designed to be called from C code and provides an efficient way to transmit events to Lua code. For more details, consult the standalone Xedge build guide. See also Xedge32 for information on how the C code generates events for the ESP32.

Note: The Xedge event mechanism uses an instance of the EventEmitter, and function _XedgeEvent() sets the retain flag on all events received.

Internally, Xedge creates an event when Lua code crashes, allowing you to implement logic that reboots the system if any script fails during runtime. The following example shows how to design an event function that restarts the system after a runtime failure.

local function errEvent(emsg)
   -- arg1 is the error message, but it is already in the log buffer if SMTP is enabled
   xedge.eflush{subject="The code crashed"} -- Flush email with error message immediately
   ba.thread.run(function()
      ba.sleep(5000) -- Give SMTP time to send error message
      -- Call a Lua binding that reboots the system; the following works for ESP32
      esp32.execute"restart"
   end)
end

xedge.event("error",errEvent) -- Subscribe

xedge.ha1(name, password [, realm])

Calculates and returns the MD5 HA1 digest. The realm defaults to 'Xedge' if not set.

xedge.log(formatstring, ...)

Send a message to the trace buffer, using priority 5, with the following prepended: 'Xedge:'.

xedge.lio

The virtual file system used by Xedge provides the same API as the Barracuda App Server's IO Interface.

xedge.sendmail(options [, cb])

Send email messages using the SMTP client library. The options argument is the same as the options argument used by the function mail:send(options); however, no instance needs to be created and no options need to be set when calling xedge.sendmail() if you have configured the Xedge SMTP settings. Calling xedge.sendmail() with an empty options table sends a test email to the email address configured in the Xedge SMTP settings. You typically call this function with the following options: to, subject, txtbody or htmlbody. The optional callback is called when the email has been sent or sending it failed. The callback receives two arguments (ok, err).

xedge.revcon(enable)

Persistently enables or disables the SharkTrust reverse connection configured through the Auto Certificate Management user interface. The function also updates the active ACME runtime when it is running.

xedge.ui(enable)

• Boolean enable: Determines whether to enable (true) or disable (false) the Xedge IDE and related components.

Enables or disables the Xedge Integrated Development Environment (IDE), including the Xedge 404 handler and the TraceLogger. By default, the IDE and its associated components are enabled. This function lets you programmatically insert and remove the IDE from the Virtual File System. The function is typically used in deployed applications to remove the IDE and related components, which are usually not included in the final product. See Creating a COTS Product and Security Considerations for additional information.

OTA and App Management

In the following app management functions, the name argument is either the name of the application as shown in the Xedge IDE or the path (URL) to the app, e.g., disk/test/myapp.zip.

xedge.getappcfg(name)

Returns the configuration table if the ZIP file includes a .config script. The optional .config script is explained in the tutorial Mastering Xedge Application Deployment.

xedge.upgradeapp(name,forcestart)

This function upgrades a deployed application packaged as a ZIP file. To use this function, replace the existing ZIP file with the new ZIP file before calling it. The function stops the existing application if it is running and restarts the app using the latest ZIP file if the app is running. You can set forcestart to true to force the application to start. Setting this argument to true saves the auto-start and running state in the xedge.conf file and ensures the app auto-starts at reboot.

This function also executes the upgrade function before starting the new app if the ZIP file includes a .config script and the table returned by .config includes the upgrade function, as explained in the Mastering Xedge Application Deployment tutorial. All other table fields are ignored.

xedge.stopapp(name,persistent)

Stop the application if it is running. Set the second argument to true if you want the app state to be saved in xedge.conf.

xedge.startapp(name,persistent)

Start the application if it is not running. Set the second argument to true if you want the app state to be saved in xedge.conf.

xedge.auxapp(name, io, op)

Dynamically add, start, stop, or remove an app at runtime. This function is useful for mounting apps from any Lua IO interface, including the GitHub IO.

• name (string, required): Logical name of the app. In the Xedge UI, it appears prefixed with $ (e.g., $myApp).
• io (Lua IO object, required): An IO (filesystem) interface created via ba.mkio() or ba.create.luaio(). Example: the ready-to-use GitHub IO module (created with ba.create.luaio) lets you back an app with a GitHub repo.
• op (table, optional): App control and LSP/web mapping options: {running, remove, dirname, domainname, priority} (details below).

Returns true on success and false, err if a script fails to start or stop.

Behavior

• If the app does not exist, it is created and, by default, started.
• If the app exists, calling again restarts it unless you set running=false.
• Setting remove=true unregisters the app from the UI, allowing garbage collection once you drop any other references to the IO.

Options

Lifecycle

• running (boolean, optional)
  • true: ensure the app is running (default if omitted).
  • false: ensure the app is stopped without removing it.
• remove (boolean, optional)
  • true: remove the app from Xedge. The UI entry disappears, and resources can be garbage collected.
  • In practice, remove is mutually exclusive with running; remove takes precedence.

LSP / Web App Mapping

Equivalent to configuring an app through the Xedge UI when LSP is enabled.

• dirname (string): URL base path for the app. Use "" to mount at root.
• domainname (string): Host filter for multi-homed servers. The app only triggers for matching Host headers.
• priority (number): Route priority when multiple web apps could handle the same path/host.

Examples

1) Mount an app from a GitHub repository (GitHub IO)

-- Create a GitHub-backed IO (example module name: GitHubIo.lua)
local ghio = require("GitHubIo").create{
  owner  = "your-org-or-user",
  repo   = "your-repo",
  token  = "github_pat_xxxxx",
  log=true
}

-- Start (or restart) an LSP app at /demo/ sourced from the GitHub repo
xedge.auxapp("ghio", ghio, {
  dirname    = "demo",      -- URL path: /demo/
  domainname = nil,         -- any host (default)
  priority   = 100,         -- higher wins when overlapping
  running    = true         -- explicit (default)
})

2) Stop (but don't remove) the app

xedge.auxapp("ghio", ghio, { running = false })

3) Remove the app (free it up for GC)

xedge.auxapp("ghio", ghio, { remove = true })

4) Using a Network File System (NET) as an App Source

This example shows how to mount and run an app directly from a NetIO network file system. The approach is similar to the one described in the Xedge tutorial Using the NetIO on an Embedded Device, but is implemented programmatically.

The code connects to a remote file system through HTTP, creates an IO object, and installs it as an auxiliary app with xedge.auxapp(). When the app is unloaded, it is cleanly stopped by setting running=false. To run this code, create a regular app using the Xedge IDE. A good name for this app would be Bootstrap. Create a .preload script, copy the code below, and paste it into the .preload script.

local appio=ba.mkio(ba.openio"net","http://192.168.1.100/development/luaapps/app1")
if appio then
   trace"install"
   xedge.auxapp("nettst", appio)
end

function onunload()
   xedge.auxapp("nettst", appio,{running=false})
end

Notes & Tips

• No UI config: The application is listed in the left pane of the Xedge web UI, just like any other application, but it does not include the .appcfg file since the app cannot be configured using the UI. However, you can open and work with the files just as you do with any other app.
• GitHub IO fit: Use it for versioned source. Each write is a Git commit through the GitHub Contents API.
• Latency & quotas: Remote IOs (like GitHub) incur network latency and API rate/permission constraints. Keep repos small and code-centric.
• WebDAV option: You can mount the app's IO by mounting http://localhost/rtl/apps/%24ghio/, where localhost is the domain name or IP address of the Xedge server and ghio is the name you set for the IO. If you bind the same GitHub IO to a WebDAV server, you can browse and edit the repo as a versioned network filesystem, enabling you to use an external editor instead of the web-based Xedge editor.
• UI Refresh: When adding or removing an app from the Xedge UI with xedge.auxapp(), the browser interface is not refreshed automatically. Manually reload the Xedge UI in your browser to see the changes.
• Compatibility: xedge.auxapp() operates independently and cannot be combined with other app management functions such as xedge.startapp() or xedge.stopapp().

Variables

xedge.compileTime

A variable extracted from C code and presented as seconds since January 1, 1970.

Server Port Variables

• ba.serverport, ba.serversslport: These variables define the port numbers used by the server for listening on HTTP and HTTPS, respectively. Typically, these port numbers are set to 80 (HTTP) and 443 (HTTPS). However, if the server cannot use the default ports, alternative ports may be assigned.

Listener Connection Objects

• ba.lcon, ba.slcon, ba.lcon6, ba.slcon6: These variables represent instances of objects returned by ba.create.servcon(), which are responsible for handling HTTP and HTTPS connections.
  • ba.lcon and ba.slcon: Instances for IPv4/IPv6, handling HTTP and HTTPS connections, respectively.
  • ba.lcon6 and ba.slcon6 are IPv6 instances on platforms that support IPv6. They are set only if the TCP/IP stack requires separate instances for handling IPv6; otherwise, they remain unset.

Creating a COTS Product

This section explains the simplest productization path for Xedge standalone: keep the stock Xedge firmware and IDE, package your Lua application as one or more ZIP files, and ship those files with the Xedge configuration file. This approach is useful when you want a production system without modifying the Xedge firmware image.

For advanced release builds, including embedding applications directly in firmware or removing unused Xedge resources, see Creating a Release Build in the standalone build guide.

When using Xedge as-is, assemble a multipart system with three parts: the Xedge firmware, at least one application ZIP file, and the Xedge configuration file. To prepare these files:

1. Download your Lua application: Retrieve your developed application from the Xedge device.
2. ZIP the application files: Compress the application files into a ZIP archive. Do not include the parent directory name in the ZIP file.
3. Upload the ZIP file: Transfer the ZIP file back to the device.
4. Remove unnecessary applications: Delete non-zipped development applications in the Xedge IDE.
5. Add the ZIP application: Register the compressed application as a new Xedge application in the IDE, set its state to "Running", and enable "Autostart."
6. Apply additional settings: Configure any additional application or Xedge settings required by the product.
7. Download the configuration file: Download the Xedge configuration file from the Xedge web file manager at http://device-address/rtl/apps/.

You should now have the Xedge configuration file and one or more application ZIP files. To prepare another device, make sure it is powered on and running the Xedge firmware, then upload the files:

1. Prepare the device: Use the file server at http://ip-addr/rtl/apps/disk/ to upload your application ZIP files and configuration file.
   • Command-Line Option: You can use command-line tools like curl for this task.
   • Browser Option: Alternatively, you can navigate to the URL in a web browser and simply drag and drop the files onto the web file manager interface.
2. Production startup: After upload, Xedge automatically loads the configured applications each time the device restarts.

Note: When creating a product with Xedge as-is, restrict access to the Xedge IDE unless the product is intended to expose the IDE to end users.

Security Considerations

Preventing Users from Accessing the Xedge IDE

If you want to prevent your customers from writing their own custom Lua applications, you can either prevent access to the UI by adding SSO authentication or remove the web-based Xedge UI completely from your application at startup. The following sections describe both methods:

• Using Authentication: By enabling Xedge SSO authentication, you can prevent unauthorized access to the Xedge UI. Note that you must use Single Sign-On (SSO) authentication instead of relying on a hard-coded user. A hard-coded user account can be perceived as a backdoor, which poses significant security risks and may violate industry regulations or legal standards.
• Removing Xedge UI: If you prefer, you can completely remove the Xedge UI from your application by adding the following code to your application's .preload script. This action removes the UI completely and is only reversible through reinstallation or software changes.

  -- The following code removes the Xedge user interface and the Xedge
  -- 404 handler. A new 404 handler is installed, redirecting all
  -- requests to another server.
  if "zip" == io:resourcetype() then
     trace"Detecting deployed mode: removing Xedge UI!"
     -- Remove the Xedge UI's directory object and all sub-directories
     xedge.ui(false)
  end
  

  Add this code to your application's .preload script. See function xedge.ui() for more information.

  If you do not need a web server, you can close all server connections. A BAS-powered server has at least two connections but up to four on some platforms. The following generic code should work on all platforms.

  for _,con in ipairs{ba.lcon,ba.slcon,ba.lcon6,ba.slcon6} do
     con:close()
  end