Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
# Xedge32 Introduction
Xedge32 is the ESP32 edition of Xedge. It lets you build and test Lua applications directly on an ESP32 board, while also giving Lua code access to ESP32 hardware such as GPIO, I2C, UART, PWM, ADC, RMT, camera modules, networking, storage, and firmware update services.
If you are new to BAS, Xedge, and Xedge32, start with the overview article How Xedge32, Xedge, and Barracuda App Server Work Together. It explains the relationship between the general Barracuda App Server runtime, the generic Xedge development environment, and this ESP32-specific firmware.
## What This Manual Covers
This manual focuses on what is specific to Xedge32:
- installing and configuring the ESP32 firmware,
- using the Xedge workflow on an ESP32 board, and
- controlling ESP32 hardware through the `esp32` Lua module.
It does not repeat the full generic Xedge or Barracuda App Server manuals. Use those documents when you need the broader web, security, protocol, file system, or application framework APIs:
- Xedge documentation
- Barracuda App Server Lua API
- IoT protocol APIs
## The Three Layers
Xedge32 use three layers together:
**Barracuda App Server**
The portable embedded application server foundation. It provides the web server, Lua integration, security, protocols, I/O abstractions, and runtime services.
**Xedge**
The Lua application model and browser-based development environment. It is not ESP32-specific.
**Xedge32**
The ESP32 firmware that combines Xedge with ESP32-specific Lua APIs. This is the layer that lets Lua code work with pins, buses, sensors, and other board features.
For a DIY maker, the practical result is simple: flash Xedge32, open the web interface or LuaShell32, and start testing Lua code against real hardware without first writing C firmware.
## Lua and C
The built-in APIs are Lua APIs. You normally do not need C code to read a sensor, toggle a pin, connect Wi-Fi, or build a small device dashboard.
The firmware itself is written in C and wraps selected ESP-IDF features for Lua. Developers who need custom native features can build and extend the firmware from the Xedge32 repository, but that is an advanced workflow. Start with Lua unless you have a specific reason to change the firmware.
## Callbacks and Polling
Many ESP32 peripherals can work in an event-driven style. When an API provides a callback, prefer that callback for responsive applications. Polling with a timer is still useful for slow checks, simple experiments, and one-shot reads, but callbacks are usually the better model for serial input, GPIO interrupts, RMT receive jobs, PCNT watchpoints, and similar events.
## Hardware Resource Lifetime
Most hardware APIs return Lua objects such as GPIO, UART, I2C, PWM, PCNT, RMT, ADC, or camera objects. Keep a reference to the object for as long as you need the hardware to stay open, and call `:close()` when you are done.
Short experiments can also use Lua’s `` syntax:
local led = esp32.gpio(18, "OUT")
led:value(true)
ba.sleep(1000)
This is convenient in Lua Server Pages and during hot reloading because the resource is released automatically at the end of the scope. Long-running applications should keep explicit references to active hardware objects so the garbage collector cannot release them unexpectedly.
## Pin Safety
ESP32 boards vary. A GPIO number that is safe on one board may be connected to flash, PSRAM, USB, boot strapping, a camera, an SD card, or another fixed function on another board. Start with the pinout for your exact board, avoid reserved pins, and use current-limiting resistors when driving LEDs or other loads directly.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- ADC API
- View page source
------------------------------------------------------------------------
# ADC API
The Analog-to-Digital Converter (ADC) API lets Lua code measure analog voltages using the ESP32’s built-in ADC hardware. This is the API you use when reading potentiometers, light sensors, simple analog outputs from other circuits, and similar low-bandwidth analog signals.
Xedge32 exposes two ADC usage models:
- **One-shot mode**, which is easy to use and well suited for occasional polling.
- **Continuous mode**, which samples in the background and delivers data through a callback.
For most applications, start with one-shot mode. Move to continuous mode only when you need steady high-rate sampling.
Important
The ESP32 ADC input is not tolerant of arbitrary voltages. Keep the signal within the safe input range for your exact board and attenuation setting. Use a resistor divider or sensor module output that is designed for 3.3 V logic when measuring higher voltages.
ADC readings are useful for sensors and control inputs, but they are not a precision instrument. Expect noise, board-to-board variation, and some non-linearity. For stable readings, average multiple samples or use continuous mode with the `mean` filter.
### Parameters
- `unit`: ADC unit number. ESP32 devices provide ADC unit `1` and `2`.
- `channel`: ADC channel number within the selected unit.
- `cfg`: Optional configuration table.
Supported configuration options:
- `attenuation`: One of `"0db"`, `"2.5db"`, `"6db"`, or `"11db"`. The default is `"11db"`.
- `volt`: Boolean. When `true`, `adc:read()` returns both the raw ADC value and the value converted to millivolts.
- `bitwidth`: Number from `9` to `13`. The default is `13`.
Higher attenuation settings allow a larger input range, but they do not make the ADC pin safe for voltages above the ESP32’s limits. Always check the board data sheet.
### Return Values
On success, `esp32.adc()` returns:
- an ADC object, and
- the GPIO pin number used by the selected channel.
On failure, the first return value is `nil` and the second value contains an error code or diagnostic string.
### ADC Object Methods`adc:read()`
Returns the current sample. If `volt=true` was set, the method returns both the raw value and the converted millivolt value.
`adc:close()`
Releases the ADC resources associated with the object.
### One-Shot Example
The example below opens ADC unit 1, channel 0, and polls it once per second. The configuration requests both the raw reading and the converted millivolt value.
local adc, pin = esp32.adc(1, 0, {volt = true})
if adc then
trace("ADC is using GPIO pin", pin)
local function pollADC()
local raw, volt = adc:read()
trace(string.format("ADC raw data: %d, volt: %d", raw, volt))
return true
end
ba.timer(pollADC):set(1000)
else
trace("Failed to open ADC", pin)
end
Continuous mode is designed for applications that need repeated sampling at a much higher rate than typical timer-based polling. The ESP32 samples in the background and Lua receives processed results through a callback.
Because Lua cannot handle a callback for every single hardware sample, continuous mode uses a buffering and filtering layer. Internally, the ADC may sample at rates as high as `48`` ``kHz`, but the Lua callback is limited to a much lower rate that is practical for the runtime.
On ESP32 hardware, the effective sampling rate floor is around `20,000` Hz. Keep that in mind when deciding whether continuous mode is really necessary for your application.
Function signature:
adc, pinOrErr = esp32.adc(unit, channel, cfg)
### Required continuous-mode options
When using continuous mode, set these options in `cfg`:
- `callback`: Lua function called when a processed sample block is ready.
- `fs`: Sampling frequency in Hz. The runtime adjusts values outside the supported range.
- `bl`: Block length. This controls how many samples are collected before the callback is invoked. Together with `fs`, this determines the callback rate.
- `filter`: One of `"data"` or `"mean"`.
### Filters`"data"`
Returns the sampled block as a Lua string containing 16-bit little-endian PCM values.
`"mean"`
Returns a single averaged value representing the current block of samples.
### Callback Signatures
When using `filter`` ``=`` ``"data"`:
function mycallback(data, err)
- `data`: A PCM-encoded Lua string.
- `err`: An error string when `data` is `nil`. Occasional `"overflow"` events can happen under load.
When using `filter`` ``=`` ``"mean"`:
function mycallback(raw, voltOrErr)
- `raw`: The averaged raw ADC value.
- `voltOrErr`: The converted millivolt value when `volt=true` was enabled. If `raw` is `nil`, this argument contains the error.
### Continuous Example: `mean` Filter
This example lets the runtime auto-adjust both `fs` and `bl` by setting them to zero. On ESP32 hardware, the values typically settle at `20000` and `200` respectively, which results in a fast but still manageable callback rate.
local cnt = 0
local function callback(raw, volt)
if cnt % 100 == 0 then
trace(raw, volt)
end
cnt = cnt + 1
end
local adc, pin = esp32.adc(1, 0, {
volt = true,
bl = 0,
callback = callback,
fs = 0,
filter = "mean"
})
### Continuous Example: `data` Filter
This example asks for the highest sample rate and lets the block length be auto-adjusted. The callback prints the size of the returned binary block so you can verify that data is flowing.
local cnt = 0
local function callback(data, err)
if data then
if cnt % 100 == 0 then
trace(#data)
end
cnt = cnt + 1
else
trace(err)
end
end
local adc, pin = esp32.adc(1, 0, {
volt = true,
bl = 0,
callback = callback,
fs = 48000,
filter = "data"
})
## Practical Guidance
- Use one-shot mode when you only need occasional readings.
- Use continuous mode when timing matters more than simplicity.
- Prefer the `mean` filter when you want a stable interpreted value.
- Prefer the `data` filter when you want to process raw sampled blocks in Lua or pass them into another decoding step.
- For slowly changing sensors such as light sensors, potentiometers, and soil moisture modules, a timer plus one-shot reads is usually easier to maintain than continuous mode.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- Access Point Mode
- View page source
------------------------------------------------------------------------
# Access Point Mode
After you flash the firmware for the first time, Xedge32 starts in **Access Point Mode**. In this mode, the ESP32 creates its own Wi-Fi network so you can connect to the device even before it has been configured for your local network.
The default access point name is `xedge32`. This startup mode is especially useful during first-time setup, lab work, and field service, since it gives you an immediate path to the device without requiring a pre-existing network.
## Connecting to Xedge32
Use the following sequence the first time you connect:
1. Connect your phone or computer to the `xedge32` Wi-Fi network. The default password is `12345678`.
2. Open a browser and navigate to http://xedge32.local.
3. If your computer does not support mDNS, use the default AP address `http://192.168.190.0` instead.
4. The first page you see is a default 404 page. Click the `Xedge`` ``IDE` link to open the Xedge IDE Web Editor.
Note
The default SSID and password are intended for initial onboarding. If you plan to keep a device in Access Point Mode for extended development or field use, update the configuration to match your deployment requirements.
Note
Custom firmware builds can use a different AP address. If `xedge32.local` does not resolve and the default address does not respond, open the serial console and check the boot log for the printed AP IP address.
## Access Point Mode Considerations
Access Point Mode is primarily a setup and recovery mode. It is fully usable, but there are a few details worth knowing:
- The built-in editor always works, but on computers without Internet access it falls back to a basic HTML text area instead of the richer Monaco-based editor.
- If you want the more advanced browser editor while still keeping the ESP32 in Access Point Mode, use a computer that is connected to the ESP32 over Wi-Fi and to the Internet over another interface such as Ethernet.
- This mode is also convenient when you are bringing up a device on a workbench and do not yet want it to join a production network.
Figure 1: Loading the advanced editor while the ESP32 remains in Access Point Mode.
## Switching to Station Mode
**Station Mode** is the recommended operating mode for most projects because it lets Xedge32 join your normal network and use the full set of IoT-oriented features.
To switch from Access Point Mode to Station Mode:
1. Open the web interface and click the three dots (`...`) in the upper-right corner.
2. Select **Lua Shell** to open LuaShell32.
3. Run the following command:
4. Replace `your-Wi-Fi-SSID` and `password` with your own credentials.
5. Wait while the ESP32 attempts to join the network.
If the connection succeeds, the device stays in Station Mode. If the connection attempt fails during initial configuration, Xedge32 falls back to Access Point Mode so you can correct the settings and try again.
## Reconnecting After the Mode Change
Once the ESP32 has joined your network:
- If your computer supports mDNS, reconnect by browsing to `http://xedge32.local/`.
- If your computer does not support mDNS, find the new IP address in your router’s DHCP client list. The device typically appears as `xedge`.
Note
If you were already connected to the IDE through `http://xedge32.local/` and both your computer and the ESP32 can still reach each other after the mode change, the IDE may reconnect automatically. It is normal to briefly see disconnect and reconnect messages in the IDE console before the final `connected` message appears.
## Station Mode Considerations
Once your device runs in Station Mode, one of the following connection methods is usually the most convenient:
- `http://xedge32.local/` if you are using the precompiled firmware or a custom build with mDNS enabled.
- The DHCP-assigned IP address if you prefer direct IP access.
- A DHCP reservation on your router if you want the same IP address every time.
- A permanent public URL by enabling the SharkTrust Let’s Encrypt plugin from Xedge’s configuration menu.
Additional notes:
- You can change the mDNS name by using esp32.execute(command).
- mDNS is convenient, but it may resolve more slowly than normal DNS on some networks.
- Bookmarking a stable IP address or using a DHCP reservation is often the most practical choice for long-term development.
## Switching Back to Access Point Mode
After the ESP32 has successfully connected in Station Mode at least once, it does not automatically revert to Access Point Mode if later network attempts fail. This behavior is intentional and helps prevent accidental exposure of the device as an access point.
To switch back manually, run the following command in LuaShell32:
esp32.netconnect"wifi"
This disconnects the device from Wi-Fi Station Mode and restores the original Access Point Mode behavior.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
# BME280 Module
This Lua module provides a simple, high-level interface to the Bosch BME280 sensor family. It is a convenient starting point if you want to read temperature, humidity, and pressure from Lua without writing low-level I2C register code yourself.
The module communicates with the sensor through the I2C API. If you want to understand the lower-level interaction, see the BME280 Lua source code.
Note
The module is currently included in the Xedge32 firmware, but in future versions it may be shipped separately.
## Typical Workflow
Using the module normally looks like this:
1. Create a BME280 object.
2. Call `bme:read()` whenever you want a new sensor reading.
3. Reuse the object for repeated measurements.
For a first test, power the breakout from the voltage recommended by the breakout board vendor, connect GND to ESP32 GND, and verify the I2C address with the I2C API scanner before debugging the BME280 module itself.
### Parameters
- `port`: I2C port number, for example `0`.
- `address`: I2C address of the sensor, typically `0x76`.
- `sda`: GPIO used for I2C data.
- `scl`: GPIO used for I2C clock.
- `settings`: Optional table with driver-specific configuration values.
The optional `settings` table is useful when you want to match a particular oversampling or measurement setup. See the Weather Station demo for a more advanced example.
### Return Value
The function returns a new BME280 object.
local temperature, humidity, pressure = bme:read()
This method reads the current measurement values from the sensor.
Return values:
- `temperature` in degrees Celsius,
- `humidity` in percent relative humidity, and
- `pressure` in Pascals.
local bmeModule = require"bme280"
local port = 0
local address = 0x76
local sda = 5
local scl = 6
local bme = bmeModule.create(port, address, sda, scl)
local temp, hum, pres = bme:read()
trace("Temperature:", temp)
trace("Humidity:", hum)
trace("Pressure:", pres)
This example creates the sensor object once, reads one sample, and stores the three returned values in local variables.
## Practical Notes
- The BME280 and BMP280 are closely related devices, but only BME280 sensors provide humidity readings.
- If communication fails, first verify the I2C address and the selected SDA/SCL pins.
- Many breakout boards use `0x76` or `0x77` depending on how the address pin is wired.
- Some boards are BME280-compatible at the connector but actually contain a BMP280. A BMP280 does not report humidity.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- GPIO API
- View page source
------------------------------------------------------------------------
# GPIO API
The GPIO API provides access to the ESP32’s general-purpose input and output pins. This is the API you use to read buttons, drive LEDs, control enable pins, and react to digital edge transitions.
The API supports both simple polling and interrupt-driven operation. For interactive applications and responsive hardware handling, the callback-based approach is usually the better choice.
For simple maker projects, GPIO is often the first API to try. Use it for low-current logic signals, buttons, relays with proper driver circuits, and LED experiments with a current-limiting resistor. Do not connect motors, LED strips, or other high-current loads directly to an ESP32 GPIO pin.
### Parameters
- `pin`: GPIO pin number.
- `mode`: One of the following strings:
- `"IN"`: Input only.
- `"OUT"`: Output only.
- `"OUTOD"`: Output only with open-drain behavior.
- `"INOUTOD"`: Input/output with open-drain behavior.
- `"INOUT"`: Input/output.
- `cfg`: Optional configuration table.
Configuration options:
- `pullup`: Enable the internal pull-up resistor. Default is `false`.
- `pulldown`: Enable the internal pull-down resistor. Default is `false`.
- `callback`: Lua callback function used for interrupt-driven input handling.
- `type`: Interrupt trigger type when `callback` is set.
Supported interrupt types:
- `"LOW"`: Trigger while the input level is low.
- `"HIGH"`: Trigger while the input level is high.
- `"POSEDGE"`: Trigger on rising edge.
- `"NEGEDGE"`: Trigger on falling edge.
- `"ANYEDGE"`: Trigger on both rising and falling edges.
If a callback is provided and `type` is omitted, the default interrupt type is `"POSEDGE"`.
Use edge triggers for buttons and pulse inputs when you want to react to a transition. Use level triggers only when the application really needs to know that a pin remains high or low, since a level condition can produce repeated interrupt activity while the level remains active.
### `gpio:value([val])`
If `val` is provided, this method writes the pin level:
- `true` for high
- `false` for low
If `val` is omitted, the method returns the current GPIO level.
On boards where an LED is wired as active-low, `false` turns the LED on and `true` turns it off. Check the schematic or board documentation if the output appears inverted.
### `gpio:close()`
Releases the GPIO object and frees the underlying hardware resources.
## Examples
The following examples are designed to run well as Lua Server Pages (LSP), but the same GPIO patterns also work in regular Lua application code.
### Example 1: Set GPIO 18 High
This example opens GPIO 18 as an output, drives it high, waits two seconds, and then automatically releases the GPIO object when it goes out of scope.
local pin = esp32.gpio(18, "OUT")
pin:value(true)
ba.sleep(2000)
The `` syntax is useful when you want the resource to be released automatically at the end of the current scope.
### Example 2: Toggle an LED Through Garbage Collection
This example demonstrates an Xedge32 pattern that is especially convenient during hot reloading. When the page is refreshed, the previous GPIO object becomes unreachable and can be garbage-collected, which releases the pin.
collectgarbage()
ba.sleep(2000)
local pin = esp32.gpio(18, "OUT")
pin:value(true)
If an LED is connected to GPIO 18, it turns off briefly while the previous object is collected, then turns on again when the new object is created.
### Example 3: Read a Button State
This example configures GPIO 15 as an input with a pull-down resistor and polls the pin once per second for up to 30 seconds.
local pin = esp32.gpio(15, "IN", {pulldown = true})
for i = 1, 30 do
local val = pin:value()
trace(i, val)
if val then
break
end
ba.sleep(1000)
end
### Example 4: React to a Button with an Interrupt Callback
This example listens for both rising and falling edges on GPIO 15. It is a better pattern than polling when you want fast response and less idle CPU work.
local cfg = {
pulldown = true,
type = "ANYEDGE",
callback = function(level)
trace("level", level)
end
}
trace(esp32.gpio(15, "IN", cfg))
## Practical Guidance
- Use polling when you only need occasional state checks.
- Use callbacks for buttons, pulse inputs, and other event-driven signals.
- Confirm the board pinout before using a GPIO number. Some ESP32 pins are reserved for flash, PSRAM, USB, boot mode selection, camera, or SD card hardware.
- Prefer explicit cleanup with `gpio:close()` in long-running applications.
- In short-lived LSP pages, Lua’s automatic cleanup can simplify iteration.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- Getting Started
- View page source
------------------------------------------------------------------------
# Getting Started
To start using Xedge32, you first need to install the firmware on a supported ESP32 board. The precompiled firmware targets:
- **Standard ESP32 boards with PSRAM**, such as ESP32 WROVER, with at least 4 MB flash and 4 MB RAM.
- **ESP32-S3 boards**, with at least 8 MB flash and 8 MB RAM.
If you are completely new to Xedge32, start with the precompiled firmware and the default onboarding workflow. More advanced build and upgrade paths are included later on this page.
Before flashing your first board, it can also help to read How Xedge32, Xedge, and Barracuda App Server Work Together. That article explains which parts are generic Xedge/BAS features and which parts are specific to ESP32 hardware.
## First-Time Installers
For the easiest first installation, use the web installer on the Xedge32 installation page. That installer is the quickest route to a working device because it avoids manual flash addresses and command-line tools.
If you need more control over flashing, board selection, or firmware variants, continue with the manual instructions below.
## OTA Upgrade
If Xedge32 is already installed on an ESP32-S3, you can upgrade it with the integrated Xedge32 OTA Upgrade Manager.
Typical OTA workflow:
1. Download the latest ESP32-S3 firmware ZIP file.
2. Extract the ZIP file.
3. Open the OTA Upgrade Manager.
4. Drag either `xedge.bin` or `xedge-s0.bin` onto the upgrade page.
This upgrade path is especially convenient once a board is already deployed and reachable through the Xedge32 interface.
## Advanced Installation and Upgrade
Two firmware delivery models are available:
1. Precompiled binary files that you can flash directly to the board.
2. Source code that you can build yourself with the Espressif ESP-IDF toolchain.
Important
The instructions on this page cover both ESP32 and ESP32-S3 hardware. Make sure you follow the command sequence and firmware layout that matches your specific chip.
### Firmware Option 1: Use Precompiled Firmware
The precompiled firmware can be flashed from Windows, macOS, or Linux. We begin with the Windows graphical workflow because it is the most approachable for many first-time users, then show the `esptool` command-line workflow.
#### How to Flash the Xedge32 Firmware
Download the ESPRESSIF Flash Tool and one of the following firmware packages:
- ESP32 Xedge firmware
- ESP32-S3 Xedge firmware which includes two firmware variants. See ESP32-S3 Firmware Options.
After downloading, extract the flash tool archive and the firmware ZIP file.
Then follow these steps:
1. Connect the ESP32 board to your computer.
2. Identify the COM port in Windows Device Manager.
3. Start `flash_download_tool_3.9.4.exe`.
4. Select the correct chip type, `ESP32` or `ESP32-S3`, and click OK.
5. On the `SPIDownload` page, set the correct COM port and set the speed to `115200`.
6. Click ERASE and wait for the erase operation to complete.
7. Use the browse buttons to select the firmware file or files.
8. Apply one of the following flash layouts.
##### Option 1: Merged Firmware File
Use this when flashing `merged-xedge.bin`:
| Binary File | Address |
|---------------------------------------------|--------------------------------|
| `merged-xedge.bin` | `0x0` |
Select the checkbox to the left of the file entry after adding it.
##### Option 2: Separate Firmware Files
Use this when flashing the individual binary components:
| Binary File | ESP32 Address | ESP32-S3 Address |
|------------------------------------------------|------------------------------------|------------------------------------|
| `bootloader.bin` | `0x1000` | `0x0` |
| `partition_table.bin` | `0x8000` | `0x8000` |
| `xedge.bin` | `0x10000` | `0x20000` |
Enable all three checkboxes after selecting the files.
##### Finish the Flash Process
9. Leave the remaining tool settings unchanged.
10. Click START and wait for the upload to finish.
11. Open a serial terminal such as PuTTY.
12. Watch the boot log.
13. When `LuaShell32`` ``ready` appears, continue with Configure the ESP32.
The screenshot above shows the flash tool on the left and a terminal window on the right. The merged firmware option is simpler because it packages the required firmware parts into a single file.
#### Common Flashing Issues
- Some boards require you to hold the boot button while connecting USB. Once the board is detected, you can release the button.
- On ESP32-S3 boards with both USB-OTG and USB-UART, use the USB-UART port for flashing. If needed, use the other port for the runtime console.
- If PuTTY does not show LuaShell32, prepare the serial terminal first, then press the board’s reset button and immediately open the terminal connection.
#### Linux, macOS, and Windows with esptool
The following examples use Linux syntax, but the same `esptool` commands can be adapted for macOS and Windows.
Install the required tool:
#### ESP32-S3 Firmware Options
Two runtime variants are provided for ESP32-S3 boards:
**\`\`xedge.bin\`\` / \`\`merged-xedge.bin\`\`**
Best for boards such as the XIAO ESP32-S3 that expose a single USB port. This build provides LuaShell32 over that USB connection.
**\`\`xedge-s0.bin\`\` / \`\`merged-xedge-s0.bin\`\`**
Best for boards that use UART0 for flashing or console access through a USB-to-UART bridge such as CP210x or FTDI.
Note
If you flash `xedge.bin` over a USB-to-UART adapter on a two-port board, you may need to move to the other USB port after flashing in order to access the runtime console. If you use `xedge-s0.bin`, you can usually keep using the same USB-to-UART connection.
### Firmware Option 2: Compile the Code
If you need to customize the firmware itself, use the source tree and build instructions in the GitHub repository.
Compiling the firmware is the right approach when you need custom C extensions, build-time configuration changes, or tighter control over the final image.
## Configure the ESP32
After flashing, reboot the ESP32. On first boot, Xedge32 starts in Access Point Mode. From there, you can either connect over serial or connect to the device’s Wi-Fi access point and use the web-based shell.
Relevant guides:
- LuaShell32 for serial or web-shell access
- Access Point Mode for browser-based onboarding
If you want the device to join your normal network instead of staying in Access Point Mode, open LuaShell32 and run one of the following commands.
On a successful connection, the configuration is stored so the device can reconnect automatically after the next restart.
## Next Step
Once Xedge32 is connected to your network, continue with Xedge32 to learn how to upload examples, create applications, and work with the IDE.
## Firmware Upgrade Options
For ESP32-S3 boards, ongoing upgrades are usually simpler than the initial install. You can either:
1. Repeat the firmware flashing procedure and upload only `xedge.bin` or `xedge-s0.bin`.
2. Use the drag-and-drop OTA workflow described earlier on this page.
## Support and Discussions
If you run into issues, want to compare notes with other users, or need help choosing a board or workflow, visit the project’s discussion forum:
Xedge32 Discussions on GitHub
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- I2C API
- View page source
------------------------------------------------------------------------
# I2C API
The I2C API lets Xedge32 communicate with sensors, displays, EEPROMs, and other peripherals that use the I2C bus. It exposes a straightforward master-side API that is well suited for both direct register access and small driver modules written in Lua.
The typical workflow is:
1. Create an I2C master object.
2. Probe the device address if needed.
3. Read from or write to the target device.
4. Close the bus object when you are done.
I2C is a shared two-wire bus. Many sensors can use the same SDA and SCL pins as long as each device has a unique address. Most small breakout boards already include pull-up resistors, but bare sensors often do not. If the bus behaves unreliably, check power, ground, address selection, and pull-ups before changing the Lua code.
### Parameters
- `port`: I2C controller number, for example `0`.
- `pinSDA`: GPIO pin used for the SDA line.
- `pinSCL`: GPIO pin used for the SCL line.
- `speed`: Bus speed in Hertz.
Use the 7-bit I2C address shown in the device data sheet, for example `0x76`. Do not left-shift the address; Xedge32 passes the address to the ESP-IDF driver in normal 7-bit form.
### Return Value
The function returns an I2C master object.
Note
Some operations may block for up to the specified timeout. If predictable responsiveness matters, consider running longer I2C transactions in a separate thread or on a dedicated LSP page. See the Lua thread library documentation.
### `i2cm:probe(address`` ``[,`` ``timeout])`
Checks whether a device responds at the given address.
Parameters:
- `address`: I2C device address.
- `timeout`: Optional timeout in milliseconds. Default is `500`.
Returns `true` if the device responds. Otherwise returns `nil,`` ``error`.
### `i2cm:read(address,`` ``len`` ``[,`` ``timeout])`
Reads raw data directly from the device without first selecting a register.
Parameters:
- `address`: I2C device address.
- `len`: Number of bytes to read.
- `timeout`: Optional timeout in milliseconds. Default is `500`.
Returns the data as a Lua string on success, otherwise `nil,`` ``error`.
### `i2cm:readfrom(address,`` ``registerOrBytes,`` ``len`` ``[,`` ``timeout])`
Reads data from a specific device register. This method performs the common write-then-read transaction without issuing a stop condition between the two phases, which results in a repeated start.
Parameters:
- `address`: I2C device address.
- `registerOrBytes`: Register selector to write before reading. This can be a single numeric byte such as `0xF7` or a Lua string when the device needs a multi-byte register address.
- `len`: Number of bytes to read.
- `timeout`: Optional timeout in milliseconds. Default is `500`.
Returns the data as a Lua string on success, otherwise `nil,`` ``error`.
### `i2cm:write(address,`` ``data`` ``[,`` ``timeout])`
Writes data to the target device.
Parameters:
- `address`: I2C device address.
- `data`: Either a Lua string or a single byte value.
- `timeout`: Optional timeout in milliseconds. Default is `500`.
Returns `true` on success, otherwise `nil,`` ``error`.
### `i2cm:close()`
Closes the I2C master object and releases the associated resources.
Returns `true` on success, otherwise `nil,`` ``error`.
## Example
The example below demonstrates the same style of operations typically used in a BME280 Module driver: probing the device, writing a configuration register, reading from a specific register, and then performing a plain read.
-- Initialize the I2C master
local i2cm = esp32.i2cmaster(0, 21, 22, 400000)
-- Probe the device at address 0x76
local found = i2cm:probe(0x76)
if found then
print("Device found at address 0x76")
else
print("Device not found")
end
-- Write a value to a register
i2cm:write(0x76, "\xF4\x27")
-- Read multiple bytes from a specific register
local data = i2cm:readfrom(0x76, 0xF7, 8)
print("Data read from register:", data)
-- Perform a simple read without specifying a register
local simple_data = i2cm:read(0x76, 4)
print("Simple data read:", simple_data)
-- Close the I2C connection when done
i2cm:close()
## Simple Address Scanner
If you do not know which address a sensor uses, scan the common 7-bit address range:
local i2cm = esp32.i2cmaster(0, 21, 22, 100000)
for address = 0x03, 0x77 do
if i2cm:probe(address, 50) then
trace(string.format("I2C device found at 0x%02X", address))
end
end
## Practical Guidance
- Use `probe` during bring-up when you are not yet sure which address a device is using.
- Use `readfrom` for most register-based sensors.
- Use `read` for devices or protocols that stream data without a register pointer phase.
- If every address fails, verify that SDA and SCL are not swapped and that the sensor shares ground with the ESP32.
- If communication works at `100000` but not `400000`, the bus wiring, pull-ups, or sensor may not support the faster speed reliably.
- Close the bus object when a transaction sequence is complete, especially in longer-running applications.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
# LuaShell32
LuaShell32 is the interactive Lua prompt included with Xedge32. You can access it either through a USB serial connection or through the web interface. It is the quickest way to test commands, inspect the current runtime environment, and configure networking without having to create a full application first.
Think of LuaShell32 as your live control console for the device. You can use it for one-off experiments, hardware bring-up, diagnostics, and small setup tasks.
## Starting the Shell
You can open LuaShell32 in two ways:
- **USB/serial**: Connect the ESP32 to your computer, open a serial terminal, and connect at the appropriate baud rate, typically `115200`.
- **Web shell**: In the Xedge editor, click the three dots (`...`) in the upper-right corner and select **Lua Shell**.
Note
The web-based shell keeps previously entered text in the editor. Before you run a new command, clear out old input so you do not accidentally submit a longer command sequence than intended.
## What the Prompt Looks Like
After the ESP32 finishes booting, the shell displays a prompt like this:
>
The `>` character means LuaShell32 is ready to accept Lua code.
## Running Your First Command
Type a Lua expression or statement and press Enter. For example:
print("Hello, world!")
LuaShell32 runs the code immediately and prints the result:
> print("Hello, world!")
Hello, world!
## Working Interactively
You are not limited to single-line commands. You can create variables, call functions, and explore APIs directly from the shell.
For example:
x = 42
y = x + 8
print(y)
This produces:
> x = 42
> y = x + 8
> print(y)
50
## What You Can Access
Inside LuaShell32 you have access to:
- the standard Lua libraries,
- the Barracuda App Server APIs,
- the generic Xedge APIs, and
- the Xedge32 ESP32-specific APIs documented in this manual.
This makes the shell a practical place to try hardware calls such as `esp32.gpio(...)`, inspect network information, or test a sensor before you wrap the code in an LSP page or application.
## When to Use LuaShell32
LuaShell32 is especially useful for:
- entering Wi-Fi credentials during first-time setup,
- verifying pin mappings and peripheral behavior,
- testing small snippets before turning them into reusable code,
- checking event delivery and network state, and
- troubleshooting a device in the field.
For larger development work, the Web-Based Lua REPL in Xedge usually provides a better experience because you can edit LSP pages, reload them in the browser, and keep your code organized in files.
See Xedge32 for the broader development workflow.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- PCNT API
- View page source
------------------------------------------------------------------------
# PCNT API
The PCNT API exposes the ESP32 pulse counter hardware to Lua. Pulse counters are useful when you need to count edges, track direction, or monitor quadrature signals from devices such as rotary encoders, tachometers, flow sensors, and other pulse-producing hardware.
Xedge32 mirrors the underlying ESP-IDF PCNT model closely enough that the official ESP-IDF PCNT documentation is still a useful reference when you need hardware-level background.
## Why Use PCNT
The PCNT peripheral is much better suited than ordinary GPIO polling when you need reliable counting at higher edge rates. It moves the edge handling into hardware and lets Lua read the accumulated result or respond to watchpoints.
## Key Features
- **16-bit signed counter** Each PCNT unit contains a signed 16-bit counter register. The hardware can handle input frequencies up to 40 MHz.
- **Two configurable channels per unit** Each channel can be programmed to increment, decrement, or hold the counter based on edge and level conditions.
- **Separate signal and control inputs** The signal input is used for edge detection, while the control input modifies how those edges affect the counter.
- **Optional glitch filtering** A hardware filter can ignore very short pulses that are likely to be noise.
- **Watchpoints with callbacks** You can trigger Lua callbacks when the counter reaches selected values such as zero, thresholds, or high and low limits.
For a deeper hardware description, see Chapter 17 of the ESP32 Technical Reference Manual.
The `cfg` argument is a Lua table that describes the counter limits, optional filters, optional watchpoints, and one or two channel definitions.
## Top-Level Configuration Fields`high`
Upper limit for the pulse counter.
`low`
Lower limit for the pulse counter.
`accumulator`
Optional boolean. When `true`, the driver accumulates values instead of resetting at the limits. Default is `false`.
`glitch`
Optional glitch-filter duration in nanoseconds. Default is `0` which means no filter.
`watch`
Optional watchpoint configuration table.
`channels`
Required array of channel definitions.
## Watchpoint Configuration
If `watch` is provided, it must contain:
`points`
Array of counter values that should trigger a callback.
`callback`
Function called when one of the watchpoints is reached.
Callback signature:
function(count, crossmode)
Arguments:
- `count`: The watchpoint value that triggered the callback.
- `crossmode`: How the counter crossed zero most recently.
Possible zero-cross modes:
- `0`: `+N`` ``->`` ``0`
- `1`: `-N`` ``->`` ``0`
- `2`: `-N`` ``->`` ``+M`
- `3`: `+N`` ``->`` ``-M`
## Channel Configuration
Each entry in `channels` is a table with `gpio` and `action` sub-tables.
`gpio` fields:
- `edge`: GPIO used for edge detection.
- `level`: GPIO used for control/level detection.
`action.edge` fields:
- `positive`: Action on positive edge.
- `negative`: Action on negative edge.
Valid edge actions:
- `"HOLD"`
- `"INCREASE"`
- `"DECREASE"``action.level` fields:
- `high`: Behavior when the control level is high.
- `low`: Behavior when the control level is low.
Valid level actions:
- `"KEEP"`
- `"INVERSE"`
- `"HOLD"`
## PCNT Object Methods
The object returned by `esp32.pcnt()` provides the following methods:
`pcnt:start()`
Starts counting.
`pcnt:stop()`
Stops counting.
`pcnt:count()`
Returns the current counter value.
`pcnt:clear()`
Clears the current counter value.
## Rotary Encoder Example
The following example mirrors the functionality of Espressif’s rotary encoder PCNT example.
The example assumes the encoder signals are already pulled to a valid logic level. Many rotary encoder modules include pull-up resistors. If you use a bare mechanical encoder, add suitable pull-ups or pull-downs for your board.
## How the Example Works
This configuration is designed for a quadrature rotary encoder:
- Channel 1 looks at `gpioA` as the edge source and `gpioB` as the control level.
- Channel 2 swaps the two signals.
- The level configuration inverts counting direction depending on the state of the other encoder line.
That is what allows the counter to move up or down as the encoder is rotated in different directions.
## Hardware Setup
The example assumes:
- an ESP development board, and
- an EC11 rotary encoder or another encoder that outputs quadrature waveforms.
### Wiring Example
Connect the encoder as follows:
In this setup:
- encoder pin **A (CLK)** connects to GPIO 0,
- encoder pin **B (DT)** connects to GPIO 2, and
- encoder **GND** connects to board **GND**.
With the example configuration above, one full rotary detent typically changes the PCNT counter by four counts because the hardware sees four signal edges per quadrature cycle.
The PCNT API configures the pulse counter peripheral. It does not, by itself, turn on GPIO pull-up or pull-down resistors. Treat signal conditioning as part of the hardware setup.
## Practical Guidance
- Use the glitch filter when mechanical switches or noisy signals cause false counts.
- Use watchpoints when you want low-overhead notifications at important count thresholds.
- For rotary encoders, expect to do some board-specific tuning of pull-ups, filter values, and direction mapping.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- PWM API
- View page source
------------------------------------------------------------------------
# PWM API
The PWM API is built on top of the ESP-IDF LEDC peripheral. Although LEDC was originally designed for LED dimming, it is also a general-purpose PWM engine that works well for tasks such as:
- LED brightness control,
- RGB color mixing,
- simple tone generation,
- fan and motor control interfaces, and
- hobby servo signaling.
The ESP32 LEDC peripheral provides 16 channels that can generate independent waveforms. These channels are divided into two groups of eight. One group runs in **high-speed mode**, where duty updates are handled fully in hardware. The other group runs in **low-speed mode**. For background information, see the ESP-IDF LEDC documentation.
## Typical PWM Workflow
Using PWM in Xedge32 normally follows three steps:
1. Configure a timer with `esp32.pwmtimer()`.
2. Open one or more output channels with `esp32.pwmchannel()`.
3. Change the duty cycle with `channel:duty()` or perform hardware-driven transitions with `channel:fade()`.
The timer controls the shared timing: frequency and duty resolution. The channel controls the actual output pin and duty value. Several channels can use the same timer when they should run at the same frequency.
## Quick Start Example
The example below configures timer 0, opens channel 0 on GPIO 18, drives the output at full duty cycle for two seconds, then turns it off again.
local ok, err = esp32.pwmtimer{
mode = "LOW",
bits = 13,
timer = 0,
freq = 5000,
}
if ok then
local led, chErr = esp32.pwmchannel{
mode = "LOW",
timer = 0,
channel = 0,
gpio = 18,
duty = 2^13 - 1,
}
if led then
ba.sleep(2000)
led:duty(0)
led:close()
else
trace(chErr)
end
else
trace(err)
end
This function configures a timer. Call it before opening any channel that uses that timer. A given timer only needs to be configured once.
Required `config` fields:
- `mode`: `"LOW"` or `"HIGH"`.
- `bits`: Duty resolution in bits.
- `timer`: Timer number.
- `freq`: Output frequency in Hertz.
The duty range is determined by `bits`. For example, `bits`` ``=`` ``13` gives a range from `0` to `8191`. A 50 percent duty cycle is therefore roughly `4096`.
Some newer ESP32 targets do not provide the same high-speed LEDC mode as the original ESP32. If high-speed mode is not available on the selected target, the firmware uses the supported low-speed mode internally.
Return values:
- `true` on success
- `nil,`` ``err` on failure
This function opens a channel object that is bound to a previously configured timer.
`config` fields:
- `mode`: Required. Must match the mode used by `esp32.pwmtimer()`.
- `timer`: Required. Must match the timer configured earlier.
- `channel`: Required. Channel number to use.
- `gpio`: Required. Output GPIO pin.
- `duty`: Optional initial duty cycle from `0` to `2^bits`` ``-`` ``1`.
- `hpoint`: Optional initial hpoint value. Default is `0`.
- `callback`: Optional Lua callback used with hardware-supported fading.
Use a callback only when you need to know that a fade has completed. For simple brightness or servo-position updates, `channel:duty()` is usually enough.
Return values:
- channel object on success
- `nil,`` ``error` on failure
### `channel:duty(pwmDutyCycle`` ``[,`` ``hpoint])`
Sets the channel duty cycle immediately.
Parameters:
- `pwmDutyCycle`: Value from `0` to `2^bits`` ``-`` ``1`.
- `hpoint`: Optional updated hpoint value.
Use this method when you want direct, immediate control over the output level.
### `channel:fade(pwmDutyCycle,`` ``time)`
Uses the hardware fade engine to transition from the current duty cycle to a new target duty cycle.
Parameters:
- `pwmDutyCycle`: Target duty cycle from `0` to `2^bits`` ``-`` ``1`.
- `time`: Maximum fade duration in milliseconds.
To use fading, the channel must be created with a callback. The callback is invoked when the fade operation completes.
### `channel:close()`
Releases the PWM channel and the resources associated with it. Closing a channel also stops its output.
## Example 1: LED Fading with Callback
This example demonstrates interrupt-driven fading. The callback is invoked when each fade completes, and it starts the next fade in the opposite direction.
local bits = 13
local maxPwmDuty = 2^bits - 1
local ok, err = esp32.pwmtimer{
mode = "HIGH",
bits = bits,
timer = 0,
freq = 5000,
}
if ok then
local duty, led = 0, 0
local function callback()
trace("led callback triggered", duty)
duty = duty == 0 and maxPwmDuty or 0
led:fade(duty, 1000)
end
led, err = esp32.pwmchannel{
callback = callback,
mode = "HIGH",
channel = 0,
timer = 0,
gpio = 18,
}
if led then
callback()
else
trace(err)
end
else
trace(err)
end
Why this pattern is useful:
- It keeps the animation logic in Lua.
- It lets the hardware perform the actual ramp.
- It avoids manually updating duty cycle values in a timer loop.
## Example 2: Servo Sweep
The next example uses PWM to move a hobby servo between two end positions. It follows the same callback-driven pattern as the LED example, but uses a 50 Hz timer and duty-cycle values chosen for a typical 0 to 180 degree servo range.
local ok, err = esp32.pwmtimer{
mode = "LOW",
bits = 13,
timer = 0,
freq = 50,
}
if ok then
local minServoDuty, maxServoDuty = 409, 819
local duty = maxServoDuty
local servo
local function callback()
trace("servo callback triggered", duty)
duty = duty == minServoDuty and maxServoDuty or minServoDuty
servo:fade(duty, 3000)
end
servo, err = esp32.pwmchannel{
callback = callback,
mode = "LOW",
channel = 0,
timer = 0,
gpio = 14,
}
if servo then
callback()
else
trace(err)
end
else
trace(err)
end
The two duty values in this example were derived from the `calculatePwmDutyCycle()` logic used in the servo.lsp example.
## Important Runtime Note
If you place a callback-driven PWM example in an LSP page, remember that the Lua object can be garbage-collected after the page finishes executing if no reference is kept alive. That is convenient during quick experiments, but in a real application you normally store the PWM object somewhere persistent.
## Practical Guidance
- Use **high-speed mode** when you want the cleanest hardware-driven duty-cycle updates.
- Use **low-speed mode** when that matches your application or existing design.
- Choose the timer `bits` value based on the balance you need between duty resolution and frequency.
- Use `channel:duty()` for immediate updates and `channel:fade()` when you want hardware-assisted transitions without building your own timer loop.
- For motors and LED strips, use the proper driver hardware. A GPIO/PWM pin is a control signal, not a power output.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- RMT API
- View page source
------------------------------------------------------------------------
# RMT API
The ESP32 RMT peripheral, short for **Remote Control**, is a timing-oriented signal engine that can both transmit and receive precisely timed digital pulse sequences. It was originally introduced for infrared remote-control protocols, but it is far more general than the name suggests.
In practice, the RMT peripheral is a very useful tool whenever a protocol is defined in terms of pulse widths rather than bytes on a conventional bus. This makes it a strong fit for:
- infrared protocols,
- 1-wire devices,
- addressable LED strips such as WS2812B,
- custom pulse-encoded signaling,
- pulse measurement and decoding tasks, and
- other applications where sub-microsecond timing matters.
Because the peripheral handles timing in hardware, it is often a better choice than trying to generate or measure pulse trains directly from Lua.
For beginners, the easiest way to decide whether RMT is the right API is to ask whether the protocol is described by pulse widths. If the device talks in bytes, try UART, I2C, or another bus first. If the device talks in high/low timings, RMT is usually the correct tool.
## Application Examples
Two especially common uses for RMT in Xedge32 projects are:
- **1-wire communication** Timing is critical in 1-wire protocols, and RMT provides the precision needed for reliable reads and writes.
- **Addressable LED strips** LED strips such as WS2812B require very specific pulse timing. RMT lets you generate those waveforms in hardware instead of bit-banging them from Lua.
## RMT Symbol Layout
The RMT hardware represents a waveform as a sequence of **RMT symbols**. Each symbol contains timing and logic-level information describing two consecutive pulse segments.
Bit fields in an RMT symbol as defined by the hardware.
Each RMT symbol contains:
- a **duration value** for the first segment,
- a **logic level** for the first segment,
- a **duration value** for the second segment, and
- a **logic level** for the second segment.
Duration values are expressed in **RMT clock ticks**, not in seconds directly. The tick duration depends on the configured channel resolution.
## Understanding Tick Resolution
The configured `resolution` determines how to interpret durations:
- at `1,000,000` Hz, one tick is `1`` ``us`,
- at `10,000,000` Hz, one tick is `0.1`` ``us`,
- at `80,000,000` Hz, one tick is `12.5`` ``ns`.
This is one of the most important ideas when working with RMT. The symbol data does not store human-friendly time units. It stores counts that are meaningful only when combined with the selected resolution.
## Lua RMT Symbol Representation
In Lua, a single RMT symbol is represented as a four-element table:
{ level0, duration0, level1, duration1 }
Example:
{
1, 350, 0, 800
}
If the channel resolution is `1`` ``MHz`, the symbol above means:
- drive the line high for `350`` ``us`,
- then drive it low for `800`` ``us`.
This table format is compact, but it is helpful to think of it as a small waveform fragment rather than as generic numeric data.
## Lua RMT Byte Encoding
Many pulse protocols define how each data bit is encoded as a pair of pulses. For example:
- a binary `0` might be sent as a short-high then long-low pulse pair,
- a binary `1` might be sent as a long-high then short-low pulse pair.
Xedge32 supports a convenient Lua structure for describing this pattern at the byte level:
Fields:
- `booleanMsbFirst`: `true` to transmit the most-significant bit first, `false` for least-significant-bit first.
- `symbolForBit0`: RMT symbol that represents a transmitted zero bit.
- `symbolForBit1`: RMT symbol that represents a transmitted one bit.
- `{`` ``byteArray`` ``}`: Array of bytes to encode and transmit.
Example at `10`` ``MHz` resolution:
This function creates a transmit channel object. The channel starts out disabled, so you must call `rmttx:enable()` before transmitting.
The optional `rx` argument lets you pair a TX and RX channel on the same GPIO so they can cooperate on a bidirectional bus such as 1-wire.
## TX Configuration Options
Required fields:
- `gpio`: Output GPIO pin.
- `resolution`: Tick resolution in Hertz.
Optional fields:
- `mem`: Memory or DMA buffer sizing. Default is `64`.
- `queue`: Transaction queue depth. Default is `4`.
- `invert`: Invert the outgoing logic level. Default is `false`.
- `dma`: Enable DMA backend. Default is `false`.
- `opendrain`: Configure the GPIO in open-drain mode. Default is `false`.
- `callback`: Function called when transmission completes.
Optional carrier modulation fields:
- `dutycycle`: Carrier duty cycle.
- `frequency`: Carrier frequency in Hertz. Maximum is `80000000`.
- `polaritylow`: Select the logic level on which the carrier is applied.
### `rmttx:enable()`
Enables the RMT TX channel and prepares it for transmission.
### `rmttx:disable()`
Disables the TX channel and stops further activity. This is especially useful for transmissions that were started in loop mode.
### `rmttx:transmit(cfg,`` ``symbols)`
Queues or starts transmission of one or more RMT symbols.
Parameters:
- `cfg`: Transmission options.
- `symbols`: Either an array of direct RMT symbols or one or more byte-encode structures as described earlier.
Supported `cfg` fields:
- `loop`: Number of repeat loops. Use `-1` for infinite looping.
- `eot`: Output level to hold at end of transmission.
### `rmttx:close()`
Closes the TX channel and releases its resources.
## TX Example 1: Musical Score
The following example plays a simple melody, Beethoven’s *Ode to Joy*, by transmitting a square wave for each note frequency. The score table is adapted from Espressif’s musical buzzer example.
### How the Musical Example Works
The `play()` function runs as a Lua coroutine. That lets the code look sequential even though the actual note timing is event-driven.
For each note:
1. The frequency is converted into a half-period duration.
2. A single RMT symbol is transmitted in a loop to generate a square wave.
3. The coroutine yields.
4. The TX callback resumes the coroutine after the note duration finishes.
This is a useful general RMT pattern: let hardware perform the timing while Lua coordinates higher-level sequencing.
## TX Example 2: WS2812B LED Strip
The following example drives a WS2812B-compatible LED strip by defining the timing for bit `0` and bit `1` and then repeatedly retransmitting updated color data.
local leds = 1
local gpioPin = 48
local rmt, err
local data = {}
for i = 1, leds * 3 do
table.insert(data, ba.rnd(0, 0xFF))
end
local function transmit()
rmt:transmit({}, {
{
true,
{1, 4, 0, 8},
{1, 8, 0, 4},
data
},
{0, 150, 0, 150}
})
end
rmt, err = esp32.rmttx{
gpio = gpioPin,
resolution = 10000000,
callback = function()
for i = 1, #data do
local c = data[i] + 1
if c > 0xFF then
c = 0
end
data[i] = c
end
transmit()
end
}
if rmt then
rmt:enable()
transmit()
else
trace(err)
end
function onunload()
trace"Stopping wled"
if rmt then
for i = 1, #data do
data[i] = 0
end
transmit()
transmit = function()
rmt:close()
end
end
end
### Breaking Down the LED Example
Preparing color data:
- `data` contains three bytes per LED.
- Each group of three bytes represents one RGB color value.
Transmit function:
- The first item in the transmit table describes byte encoding for the LED protocol.
- `true` selects MSB-first transmission.
- `{1,`` ``4,`` ``0,`` ``8}` defines the waveform for a zero bit.
- `{1,`` ``8,`` ``0,`` ``4}` defines the waveform for a one bit.
- `{0,`` ``150,`` ``0,`` ``150}` adds the reset pulse after the color data.
Continuous animation:
- The TX callback updates the color table after each completed transfer.
- The callback then starts the next frame.
- This creates a continuous animation loop without a separate timer.
Cleanup:
- `onunload()` turns the LEDs off before closing the channel.
- This matters when the code runs as an `.xlua` page and may be reloaded or stopped while the previous transmission is still active.
### `rmtrx:receive(cfg)`
Starts a receive job and returns immediately.
Receive `cfg` fields:
- `min`: Minimum valid pulse duration in nanoseconds. Shorter pulses are treated as glitches.
- `max`: Maximum valid pulse duration in nanoseconds. Longer pulses are treated as a stop signal and end the receive operation.
- `len`: Optional receive buffer length in RMT symbols. Default is `512`.
- `defer`: Optional boolean. Relevant when TX and RX are linked to the same GPIO.
When `defer` is used with a linked TX/RX pair:
- `false` means reception starts immediately, so transmitted symbols may also appear in the receive result.
- `true` delays reception until the linked TX channel finishes transmitting.
### `rmtrx:close()`
Closes the RX channel and releases its resources.
## RX Example: 1-Wire Temperature Read
The following example shows how RMT can be used to implement a 1-wire temperature transaction against a DS18B20-style sensor.
1local tInsert = table.insert
2local cResume, cYield = coroutine.resume, coroutine.yield
3
4local function decodeBytes(symbols)
5 local mask, byte, t = 1, 0, {}
6 for _, sym in ipairs(symbols) do
7 if sym[2] <= 15 then
8 byte = byte | mask
9 end
10 mask = mask << 1
11 if 256 == mask then
12 tInsert(t, byte)
13 mask, byte = 1, 0
14 end
15 end
16 return t
17end
18
19local function readTemp(gpio, callback)
20 local coro
21
22 local function tempThread()
23 local txCfg = {eot = 1}
24
25 local rx = esp32.rmtrx{
26 gpio = gpio,
27 resolution = 1000000,
28 callback = function(symbols)
29 cResume(coro, symbols)
30 end
31 }
32
33 local tx = esp32.rmttx({
34 gpio = gpio,
35 opendrain = true,
36 resolution = 1000000,
37 }, rx)
38
39 local function busReset()
40 rx:receive{min = 2000, max = 480 * 2 * 1000}
41 tx:transmit(txCfg, {{0, 480, 1, 70}})
42 local symbols = cYield()
43 if #symbols < 2 then
44 callback(nil, "No sensors connected")
45 end
46 return #symbols < 2
47 end
48
49 local function sendCommand(cmd)
50 rx:receive{min = 900, max = 70 * 1000}
51 tx:transmit(txCfg, {
52 {
53 false,
54 {0, 60, 1, 2},
55 {0, 6, 1, 56},
56 cmd
57 }
58 })
59 return cYield()
60 end
61
62 local function readBytes(len)
63 local t = {}
64 for i = 1, len do
65 tInsert(t, 0xFF)
66 end
67 return sendCommand(t)
68 end
69
70 tx:enable()
71 tx:transmit(txCfg, {{1, 1, 1, 0}})
72 if busReset() then
73 return
74 end
75
76 sendCommand{0xCC, 0x44}
77 ba.timer(function()
78 cResume(coro)
79 end):set(1000, true)
80 cYield()
81
82 if busReset() then
83 return
84 end
85
86 sendCommand{0xCC, 0xBE}
87 local data = decodeBytes(readBytes(2))
88 local raw = (data[2] << 8) + data[1]
89 callback(raw * 0.0625)
90 end
91
92 coro = coroutine.create(tempThread)
93 cResume(coro)
94end
95
96readTemp(1, function(temp, err)
97 trace(temp, err)
98end)
### Understanding the 1-Wire Example
This example is dense, so it helps to break it into pieces.
1-wire background:
- A bus reset begins communication by pulling the line low for at least `480`` ``us`.
- A device indicates presence by pulling the line low in response.
- Bit timing determines whether the transmitted or received value is a zero or a one.
How the Lua code is organized:
- `tempThread()` is written as a coroutine so the protocol can be expressed in sequential steps.
- The RX callback resumes the coroutine whenever a receive operation completes.
- TX and RX share the same GPIO pin, which is required for 1-wire signaling.
What `decodeBytes()` does:
- It examines the low-duration part of each received symbol.
- Short low pulses are interpreted as binary `1`.
- Longer low pulses are interpreted as binary `0`.
- Bits are shifted into bytes in least-significant-bit-first order.
Protocol flow:
1. Reset the bus.
2. Send `0xCC` and `0x44` to skip ROM selection and start temperature conversion.
3. Wait for the conversion to complete.
4. Reset the bus again.
5. Send `0xCC` and `0xBE` to read the scratchpad.
6. Decode the returned bytes into a temperature value.
Why the example uses `0xFF` during reads:
In 1-wire, the master must still generate timing slots while reading. Sending a series of one bits creates those read slots, and the sensor alters the observed pulse widths to encode its response.
### Garbage-Collection Consideration
One subtle issue in coroutine-driven code like this is object lifetime. The example intentionally keeps the logic focused on protocol flow, but a production implementation should keep an explicit reference to the coroutine or wrap the entire behavior in a long-lived object.
Without a stable reference, Lua’s garbage collector could reclaim the coroutine while it is waiting for an event. If that happened, the callback would never resume the protocol.
## Practical Guidance
- Start by choosing a resolution that makes your protocol timing easy to reason about.
- Use direct symbols when you are hand-crafting pulse sequences.
- Use byte encoding when the protocol naturally describes timing for bit `0` and bit `1`.
- Pair TX and RX channels on the same GPIO for bidirectional single-wire buses.
- Always think about cleanup and object lifetime when running long-lived RMT activity from LSP or hot-reloaded code.
- If your timing values are hard to read, lower the resolution so common pulse widths convert to simple integer tick counts.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
# Modbus RTU Module
This Lua module extends the Barracuda App Server Modbus TCP client so it can communicate over Modbus RTU on serial links such as RS-232 and RS-485. In practice, the module acts as a transport adapter: it keeps the familiar Modbus client API while using the UART API for the underlying serial communication.
Note
The module is currently included in the Xedge32 firmware, but it may be moved into a separately distributed Lua module in a future release.
### Return Value
The function returns a Modbus object with the same method set as the Modbus TCP client.
The returned object is preconfigured for asynchronous cosocket operation, which means you should provide a callback for each Modbus operation.
local cfg = {
baudrate = 9600,
txpin = 42,
rxpin = 41,
onclose = function(err)
trace("Serial Comm. Err.", err)
end
}
-- Does not return errors, but may throw on incorrect settings
local mb = require"modbus.rtu".connect(1, cfg)
local function mycallback(data, err, transaction, client)
trace("table" == type(data) and ba.json.encode(data) or data, err)
end
local unitId = 1
mb:wholding(0, {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20}, unitId, mycallback)
mb:rholding(0, 20, unitId, mycallback)
## RS-232, Full-Duplex RS-485, and Half-Duplex RS-485
The first example configures the UART for RS-232 or full-duplex RS-485.
For half-duplex two-wire RS-485, you also need collision-detection support and a suitable transceiver such as ADM483 wired to the RTS GPIO pin. In that case, enable the UART `rs485` option:
## Modbus Test Bench
The image below shows a simple two-wire RS-485 test setup.
### Test Bench Components
- ESP32-S3
- ANMBEST MAX485 RS485 transceiver module
- USB-to-RS485 converter
- A Modbus slave simulator running on Windows and connected to the converter
### Wiring Example
The following wiring matches the half-duplex configuration shown earlier.
Power connections:
- **VCC** on MAX485 to **5V** on the ESP32
- **GND** on MAX485 to **GND** on the ESP32
Data connections:
- **DI** on MAX485 to GPIO 42 on the ESP32 for **TX**
- **RO** on MAX485 to GPIO 41 on the ESP32 for **RX**
Control pin:
- **RE** and **DE** connected together, then wired to GPIO 40 for **RTS**
RS-485 bus terminals:
- **A** and **B** on the MAX485 to the matching **A** and **B** lines on the USB-to-RS485 converter
For longer RS-485 wiring, also consider termination and biasing. Short bench tests may work without them, but production wiring should follow normal RS-485 bus design rules.
## Practical Guidance
- Use RS-232 or full-duplex RS-485 when the wiring and hardware already support separate send and receive paths.
- Use half-duplex RS-485 when you need a multidrop industrial bus, but make sure your transceiver and RTS wiring are configured correctly.
- Keep the callback-based programming style from the Modbus client API; the RTU transport layer is designed around asynchronous requests and responses.
- If requests time out, first verify baud rate, parity, slave unit ID, A/B polarity, and shared ground before changing the Lua code.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- UART API
- View page source
------------------------------------------------------------------------
# UART API
The UART API provides access to the ESP32’s Universal Asynchronous Receiver/Transmitter hardware. Use it when you need serial communication with sensors, modems, external MCUs, industrial adapters, or RS-232/RS-485 transceivers.
Xedge32 supports both polling and callback-driven receive handling. In most cases, the callback-based approach is preferred because it is more responsive and avoids constant polling from Lua.
The transmit side can also operate efficiently in a semi-asynchronous style as long as the TX ring buffer has enough free space to accept the outgoing data.
Important
ESP32 UART pins use 3.3 V logic. Do not connect them directly to classic RS-232 voltage levels. Use the correct level shifter, RS-232 transceiver, or RS-485 transceiver for the device you are connecting.
### Parameters`port`
UART port number, for example `0`.
Be careful with UART0 on boards where it is also used for flashing or the serial console. For external devices, UART1 or UART2 is often easier to dedicate to the project.
`config`
Optional table with the following settings:
- `callback`: Receive callback function. Setting this enables interrupt-driven RX handling.
- `databits`: Data bits from `5` to `8`. Default is `8`.
- `baudrate`: Baud rate. Default is `9600`.
- `rxbufsize`: Receive buffer size. Default is `1024`.
- `txbufsize`: Transmit buffer size. Default is `1024`.
- `txpin`: TX GPIO. Defaults to the port’s default pin.
- `rxpin`: RX GPIO. Defaults to the port’s default pin.
- `rtspin`: RTS GPIO. Disabled by default.
- `ctspin`: CTS GPIO. Disabled by default.
- `stopbits`: Stop-bit setting. Use `1` or `2` explicitly. Values other than `1` and `2` are interpreted as `1.5`.
- `parity`: Either `"EVEN"` or `"ODD"`.
- `flowctrl`: Either `"RTS"`, `"CTS"`, or `"CTSRTS"`.
- `rs485`: Enables RS-485 half-duplex mode. Requires `rtspin` when used with a suitable transceiver such as ADM483.
- `timeout`: Default `0`. Without `pattern`, this defines how long to wait before triggering the callback, measured in UART character times.
- `pattern`: Enables pattern detection, for example `"+++"`. Requires a callback.
Additional options when `pattern` is enabled:
- `maxlen`: Maximum number of recorded pattern positions. Default is `0`.
- `timeout`: Maximum gap allowed between characters in the same pattern.
- `postidle`: Minimum idle time required after the pattern.
- `preidle`: Minimum idle time required before the pattern.
For the lower-level hardware behavior behind pattern detection, see the ESP-IDF function uart_enable_pattern_det_baud_intr().
## Receive Callback Signatures
When using a callback, Xedge32 calls one of the following forms:
`function(data,`` ``pattern)``data` is a Lua string containing one or more received characters. `pattern` is a boolean set to `true` when the data corresponds to a detected pattern.
`function(nil,`` ``emsg)`
Called for receive-side errors or special UART conditions.
Possible `emsg` values:
- `"full"`: RX buffer full; queue reset.
- `"overflow"`: RX FIFO overflow; queue reset.
- `"frame"`: Framing error.
- `"parity"`: Parity error.
- `"databreak"`: Data-and-break event.
- `"break"`: Break event.
### `uart:read([timeout])`
Reads data from the RX queue and optionally waits up to `timeout` milliseconds. Do not combine this method with a receive callback on the same object.
Use `read` for quick tests or request/response protocols where your code knows when a reply should arrive. Use a callback when the device may send data at any time.
### `uart:write(data)`
Writes data to the UART. The call blocks until the data has been pushed into the TX FIFO or TX ring buffer. If the transmit side is full, the call waits.
### `uart:txsize()`
Returns the remaining free space in the TX ring buffer. This is useful when you want to decide how much data you can queue without blocking.
### `uart:close()`
Releases the UART object and its associated resources.
## UART Echo Example
The following example opens UART port 2, configures GPIO 4 and GPIO 5 as TX and RX, and echoes all received data back to the sender.
local uart
local cfg = {
baudrate = 115200,
txpin = 4,
rxpin = 5,
callback = function(data, err)
if data then
uart:write(data)
else
trace("Err", err)
end
end
}
uart = esp32.uart(2, cfg)
This callback-driven pattern is a good default when you need responsive serial input handling without writing your own polling loop.
## Practical Guidance
- Prefer callbacks over `uart:read()` when the device should react to incoming serial data promptly.
- Use `uart:txsize()` if you are streaming large bursts and want to avoid unexpected blocking.
- Enable `rs485` only when your hardware design specifically requires half-duplex RS-485 control through RTS.
- Match baud rate, parity, stop bits, and wiring to the external device before troubleshooting higher-level protocol code.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
## Creating and Managing Xedge32 Applications
An Xedge32 application is typically packaged as a ZIP file containing Lua code and, when needed, supporting assets such as HTML, CSS, JavaScript, images, and configuration scripts. Xedge32 can run this ZIP file directly, which makes deployment simple and keeps the upload workflow friendly for both development and production use.
This packaging model is helpful because it lets you move a complete application onto the device as a single artifact instead of uploading individual files one by one.
## Uploading Your Application
You can install an application ZIP file in several ways:
1. **Firmware Update & App Upload page** Open the page from the three-dot menu in the upper-right corner of the Xedge32 interface and drag the ZIP file into the browser window.
2. **Web File Manager** Upload the ZIP file manually, then add it as an application from the Xedge32 IDE.
3. **WebDAV** Mount the device as a drive, copy the ZIP file over, and then enable it as an application from the IDE.
The first method is the easiest for most users because it uploads and installs the ZIP file in one step. Some packaged applications also depend on this path because they include post-installation configuration scripts that should run automatically during installation.
## ZIP File Applications
A ZIP file uploaded as an application is treated as a ready-to-run deployment unit. This is different from editing loose Lua files directly on the device.
This approach gives you two useful workflows:
- keep the application packaged when you want a clean deployment artifact, or
- unpack and modify the application on the device when you want to iterate directly in Xedge32.
Note
You can inspect files stored inside an uploaded ZIP archive, but you cannot save changes back into the archive itself. If you want to edit files on the device, unpack the application first.
## Creating an Xedge32 Application
To build your own application package:
1. Gather your Lua files and any supporting assets.
2. Place them in a directory structure exactly as you want them to appear in the application.
3. Create a ZIP file from the *contents* of that directory, not from the directory itself.
In practice, this means files such as `.preload` or `.config` must be at the root of the ZIP archive if you want Xedge32 to detect them correctly.
## Optional `.config` Script
An application may include a `.config` script for metadata and installation hooks. If present, the script must return a Lua table with any of the following optional fields:
- `name`: String shown for the application in the Xedge32 left-hand pane. If omitted, the ZIP filename is used.
- `autostart`: Boolean that enables automatic startup and marks the app as running after installation.
- `install`: Function called for a new installation.
- `upgrade`: Function called when an existing application is updated.
-- Argument 'io' is the application's IO instance
local function install(io)
trace("install", io:realpath(""))
return "This message is sent to the browser and displayed after installation"
end
local function upgrade(io)
return "This message is sent to the browser and displayed after upgrade"
end
return {
name = "MY APP",
autostart = true,
install = install,
upgrade = upgrade
}
The `install` and `upgrade` hooks are a good place to perform first-run setup, initialize directories, migrate stored data, or provide a helpful status message back to the browser.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- Camera API
- View page source
------------------------------------------------------------------------
# Camera API
Xedge32 includes the ESP32 camera driver together with a Lua interface for capturing images from supported camera modules. This API is typically used on boards such as ESP32-CAM and ESP32-S3 camera variants where the camera wiring is fixed by the board design.
The basic workflow is:
1. Create a camera object with `esp32.cam(cfg)`.
2. Call `cam:read()` whenever you want a frame.
3. Call `cam:close()` when you are finished.
Note
The camera API is still evolving, so this page focuses on the currently documented setup and configuration model.
There are two camera paths in the firmware:
- classic ESP32/ESP32-S3 camera support using the ESP-IDF camera driver and a parallel camera pin map, and
- ESP32-P4 camera support using the V4L2/PPA pipeline.
Use the section that matches your target board.
### `cam:read()`
Captures and returns a new image from the camera.
### `cam:close()`
Closes the camera object and releases the associated hardware resources.
## Configuration Table
The configuration table maps the camera’s parallel data bus and control signals to GPIO pins on the ESP32. In most cases, you copy the mapping used by your specific board design and only adjust optional settings when needed.
### Required fields
- `d0` to `d7`: Pixel data pins.
- `xclk`: Camera master clock output.
- `pclk`: Pixel clock input.
- `vsync`: Vertical synchronization signal.
- `href`: Horizontal reference signal.
- `sda`: SCCB data line.
- `scl`: SCCB clock line.
- `reset`: Camera reset pin.
- `freq`: XCLK frequency, typically between 10 MHz and 20 MHz.
### Optional fields
- `pwdn`: Camera power-down pin.
- `frame`: Frame size, for example `"HD"`.
- `format`: Pixel format such as `"RGB565"`, `"YUV422"`, `"GRAYSCALE"`, or `"JPEG"`.
- `vflip`: Boolean that flips the image vertically.
- `hmirror`: Boolean that mirrors the image horizontally.
## ESP32-P4 Configuration
On ESP32-P4 builds, `esp32.cam(cfg)` uses a V4L2/PPA camera pipeline. The configuration is shorter because the driver negotiates the video pipeline and uses width/height settings instead of the full classic parallel pin map.
Common ESP32-P4 fields:
- `scl`: SCCB/I2C clock pin. Default is `8`.
- `sda`: SCCB/I2C data pin. Default is `7`.
- `xclk`: Camera master clock pin. Default is `22`.
- `format`: `"JPEG"`, `"YUV422"`, or `"RGB565"`.
- `width` and `height`: Requested frame size in pixels.
- `frame`: Convenience size when width/height are not supplied. Supported values include `"QVGA"`, `"VGA"`, `"SVGA"`, and `"HD"`.
- `quality`: JPEG quality from `1` to `100` when JPEG output is used.
- `vflip` and `hmirror`: Flip or mirror the final image.
Example:
local cam, err = esp32.cam{
format = "JPEG",
frame = "VGA",
quality = 80,
sda = 7,
scl = 8,
xclk = 22
}
if cam then
local jpg = cam:read()
trace("JPEG bytes:", #jpg)
cam:close()
else
trace(err)
end
## Practical Guidance
- Start with a known-good pin map for your exact board.
- If camera initialization fails, the first thing to verify is the board’s pin mapping.
- If the image orientation is wrong, try `vflip` and `hmirror` before changing anything else.
- Lower clock rates can sometimes improve stability during bring-up.
- Camera support depends on the firmware build. If `esp32.cam` is not available, the current firmware was built without camera support.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
# License
Xedge32 is built on top of components from the Barracuda App Server amalgamated C code library. That library is available under multiple licensing options, including GPLv2, a free commercial license, and a standard royalty-free commercial license.
The ESP32-specific south bridge implementation for Xedge32 is available in the Xedge32 source repository and is licensed under the permissive MIT license.
If you plan to embed Xedge32 in a commercial product, review both the Barracuda App Server licensing terms and the Xedge32 repository licensing details so your deployment model matches the correct license option.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- Miscellaneous API
- View page source
------------------------------------------------------------------------
# Miscellaneous API
The `esp32` module also includes a set of utility functions that do not fit under a single peripheral category. These functions cover Wi-Fi information, network connection management, SD card setup, device control actions, event subscriptions, and OTA firmware updates.
This page groups those helpers into one place so you can quickly find common system-level operations.
## `esp32.apinfo()`
Returns a Lua table describing the currently connected Wi-Fi network.
One of the most useful fields is `rssi`, the Received Signal Strength Indicator. RSSI is reported in dBm and is usually a negative number.
General RSSI guidance:
- `-30`` ``dBm`: Outstanding signal strength.
- `-50`` ``dBm`: Excellent signal strength.
- `-60`` ``dBm`: Good for normal use.
- `-70`` ``dBm`: Fair, but performance may start to degrade.
- `-80`` ``dBm` or lower: Weak and potentially unstable.
Example using the serpent module for formatting:
local serpent = require("serpent")
print(serpent.block(esp32.apinfo()))
## `esp32.loglevel(level)`
Controls the ESP32 system log verbosity.
Parameter:
- `level`: One of `"none"`, `"error"`, `"warn"`, `"info"`, `"debug"`, or `"verbose"`.
Meaning of each level:
- `"none"`: Disable log output.
- `"error"`: Show only error messages. This is the default.
- `"warn"`: Show errors and warnings.
- `"info"`: Show errors, warnings, and informational messages.
- `"debug"`: Add debug messages.
- `"verbose"`: Show the most detailed available output.
Note
The maximum available log level depends on the firmware build settings in `menuconfig`. If you request a level that exceeds the compiled maximum, the function raises an error.
## `esp32.mac()`
Returns the ESP32 base MAC address as a 6-byte Lua string.
Example:
local mac = esp32.mac()
print(mac:gsub(".", function(x)
return string.format("%02X", string.byte(x))
end))
## `esp32.wscan([print])`
Scans for visible Wi-Fi networks and returns a list of tables, one table per network.
If the optional argument is `true`, the function also prints the result to LuaShell32.
Example:
local fmt = string.format
for _, net in pairs(esp32.wscan()) do
print(fmt(
"SSID: %s\nChannel: %d\nRSSI: %d\nAuthmode: %s\nPChiper: %s\nGCipher: %s\n",
net.ssid, net.channel, net.rssi, net.authmode, net.pchiper, net.gcipher
))
end
Note
Wi-Fi scanning takes time. Plan for a noticeable delay before the function returns.
## `esp32.netconnect(network,`` ``cfg)`
Starts a Wi-Fi or wired network connection in the background and returns immediately. Connection progress and status messages are shown in LuaShell32.
If the connection succeeds, the configuration is stored in NVRAM so the device can reconnect automatically after a restart.
By default, an unconfigured system starts in Access Point Mode with SSID `xedge32` and password `12345678`.
### Network Parameters`network`
One of:
- `"wifi"`: Connect through Wi-Fi.
- `"W5500"` or `"DM9051"`: Connect through SPI Ethernet when the firmware includes support for that controller.
- `"IP101"`, `"RTL8201"`, `"LAN87XX"`, `"DP83848"`, or `"KSZ80XX"`: Connect through RMII Ethernet when the firmware and board support that PHY.
`cfg`
Configuration table. Required fields depend on the selected network type.
Wi-Fi configuration fields:
- `ssid`: Wi-Fi network name.
- `pwd`: Wi-Fi password.
SPI Ethernet configuration fields:
- `spi`: SPI bus number.
- `clk`: SPI clock GPIO.
- `mosi`: MOSI GPIO.
- `miso`: MISO GPIO.
- `cs`: Chip-select GPIO.
- `irq`: Interrupt GPIO.
- `freq`: SPI clock frequency in Hertz.
- `rst`: Optional PHY reset GPIO.
RMII Ethernet configuration fields:
- `rst`: PHY reset GPIO.
- `mdio`: MDIO GPIO.
- `mdc`: MDC GPIO.
If `cfg` is omitted while the device is already running in Wi-Fi Station Mode, the device switches back to Access Point Mode.
Examples:
Note
Ethernet support is build-dependent. If an adapter name is rejected or the driver fails to start, verify that the firmware was built with the matching Ethernet PHY support and that the board wiring matches the selected adapter.
## `esp32.sdcard(width)`
Registers a new disk named `sd` when the board provides an SDMMC interface. After configuration, you can open the device through the IO interface with `ba.openio("sd")`.
Supported call forms:
### Return Behavior
- Returns `nil,`` ``error` if the SD card cannot be detected.
- On success, stores the configuration in NVRAM and reboots the system.
- Calling the function without arguments removes an existing SD card configuration.
Custom SD card pins are only available on targets where the SDMMC peripheral can be routed through the GPIO matrix. On original ESP32 targets, use the fixed IO-MUX-connected SDMMC pins.
Examples:
-- Initialize a 1-bit SD card bus using the default pin mapping
esp32.sdcard(1)
-- Example custom mappings for specific boards
esp32.sdcard(1, 39, 38, 40) -- ESP32-S3-WROOM CAM Board
esp32.sdcard(1, 7, 6, 5) -- LilyGO T-ETH-Lite
esp32.sdcard(1, 7, 9, 8) -- XIAO ESP32S3 Sense
## `esp32.execute(command)`
Performs device-level control actions.
Supported commands:
- `"erase"`: Erase the first FAT partition, reformat it on reboot, and restart the device. Use this if the internal FAT filesystem becomes corrupt.
- `"restart"`: Restart the ESP32.
- `"killmain"`: Stop the main process that powers LuaShell32 and reclaim its memory.
- `"mdns"`: Change the mDNS name.
Example:
After restarting, the device can be reached at `http://myesp.local` if mDNS is available on your network.
## `xedge.event()`
Xedge32 extends the generic Xedge event mechanism so Lua code can subscribe to network-related runtime events.
Function signature:
xedge.event(event, callback [, unsubscribe])
All Xedge32-generated events are retained. That means a late subscriber can still receive the most recent event state when appropriate.
### Event Types`"wifi"`
Reports Wi-Fi state changes and Wi-Fi-related warnings or errors.
Callback arguments:
- `"up"` when Wi-Fi transitions to connected.
- `"down"` when Wi-Fi transitions to disconnected.
- an ESP-IDF warning or error number as a string.
- a second argument, `"ap"` or `"sta"`, identifying Access Point or Station mode.
`"wip"`
Reports that Wi-Fi has received IP configuration from DHCP.
Callback arguments:
- IP address
- netmask
- gateway
`"eth"`
Reports that Ethernet has received IP configuration from DHCP.
Callback arguments:
- IP address
- netmask
- gateway
`"sntp"`
Reports that the system time has been synchronized over SNTP.
This event is especially important before opening TLS connections, because certificate validation depends on the device clock being correct.
xedge.event("wifi", function(status)
if status == "up" then
trace("Wi-Fi connected")
elseif status == "down" then
trace("Wi-Fi disconnected")
else
trace("Wi-Fi error:", status)
end
end)
xedge.event("wip", function(ip, mask, gw)
trace("IP address:", ip, "network mask", mask, "gateway", gw)
esp32.execute"killmain"
end)
xedge.event("eth", function(ip, mask, gw)
trace("IP address:", ip, "network mask", mask, "gateway", gw)
end)
xedge.event("sntp", function()
trace("Time synchronized")
end)
### One-Time SNTP Subscription Example
The following example subscribes to the `"sntp"` event, records the first time synchronization, and then unregisters itself.
local sntp
function onunload()
xedge.event("sntp", sntp, true)
end
sntp = function()
onunload()
startTime = ba.datetime"NOW"
xedge.elog({ts = true}, "Boot time=%s", startTime:tostring())
xedge.eflush({subject = "App starting"})
end
xedge.event("sntp", sntp)
Note
All arguments supplied by C-generated Xedge32 events are represented as Lua strings, including values that conceptually represent numbers.
## Xedge32 OTA
Xedge32 provides core OTA support through `esp32.ota`.
Call forms:
- `esp32.ota()` returns the current firmware version table.
- `esp32.ota"begin"` starts an upgrade session and returns an OTA object.
### Examples
Retrieve the current firmware version:
local ver = esp32.ota()
for k, v in pairs(ver) do
trace(k, v)
end
Begin an OTA upgrade:
local ota, err = esp32.ota"begin"
### OTA Object Methods`ota:write(data)`
Writes a chunk of firmware data. Keep calling this method until the full image has been written.
local ok, err = ota:write(data)
`ota:commit()`
Finalizes the upgrade. Returns `true` on success, otherwise `nil,`` ``error`.
local ok, err = ota:commit()
`ota:abort()`
Cancels the current OTA session.
ota:abort()
## Practical Guidance
- Use `apinfo` and `wscan` during network bring-up and troubleshooting.
- Use `netconnect` for both first-time network configuration and automated reconnect logic.
- Use `xedge.event("sntp",`` ``...)` before TLS-dependent application startup if accurate time matters.
- Use OTA only after verifying image integrity and transport reliability in your application workflow.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
-
- Tutorials and AUX APIs
- View page source
------------------------------------------------------------------------
# Tutorials and AUX APIs
This documentation set focuses on the Xedge32-specific south bridge APIs. In practice, most Xedge32 projects also make use of the broader Lua, Xedge, and Barracuda App Server documentation. The links below are the quickest way to expand beyond the ESP32 hardware pages in this manual.
## Recommended Learning Resources
- How Xedge32, Xedge, and Barracuda App Server Work Together The best first read when you need to understand which documentation set to use for each layer.
- Xedge32 Tutorials A collection of step-by-step guides focused on getting productive with Xedge32.
- Online Interactive Lua Tutorial A hands-on introduction to Lua for users who are new to the language.
- GitHub Xedge32 Examples Ready-to-run example programs and reference code for ESP32 targets.
- Mako Server Tutorials Broader tutorials that often apply directly to Xedge32 because both products share the same underlying development model.
## How Xedge32 Fits Together
Xedge32 is easiest to understand when you view it as three layers working together:
1. **Barracuda App Server** This is the underlying runtime and IoT foundation. It provides the majority of the network, protocol, security, storage, and web capabilities used by Xedge32 applications.
- Lua API
- IoT Protocols
- Product page
2. **Xedge** Xedge is the Lua-oriented development environment and workflow layer. It gives you the browser-based editor, rapid prototyping model, and application runtime used on several platforms, not only ESP32.
- Xedge API and how-to documentation
- Online demo
3. **Xedge32 for ESP32** This is the ESP32-specific extension layer documented in this manual. It adds the south bridge API for GPIO, ADC, UART, RMT, camera access, and other peripherals.
- Introduction
## Why This Matters
New users often start by reading only the ESP32 peripheral pages. That is a good starting point, but most real applications combine:
- Xedge32 peripheral access,
- generic Xedge application behavior, and
- Barracuda App Server networking or IoT protocol features.
If you keep those three layers in mind while learning, the rest of the documentation becomes much easier to navigate.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
# Xedge32
Xedge32 is a development environment for embedded edge devices. It combines a web-based interface with Lua-driven application development so you can build, test, and iterate directly on the target device.
Xedge itself is available on multiple platforms, but this guide focuses on the ESP32-specific workflow. For the broader Xedge feature set, see the Xedge main documentation.
## Working with Example Applications
The LSP-Examples repository contains a good set of ESP32-oriented examples. A practical way to learn Xedge32 is to upload these examples, open them in the browser IDE, and run them directly on the device.
Basic workflow:
1. Download the ESP32 example files to your computer.
2. Upload them to the ESP32 using WebDAV or the built-in Web File Manager.
3. Create a new application from the uploaded directory.
4. Open the example files in the IDE and run them one by one.
## Uploading Files to the ESP32
You can use the combined WebDAV and Web File Manager endpoint at `http://ip-address/rtl/apps/`.
If you want a walkthrough for mounting the device as a WebDAV drive, see the WebDAVhow-tovideo.
If you prefer the browser workflow:
1. Open `http://ip-address/rtl/apps/`.
2. Click the + button and create a directory named `Lua-Examples`.
3. Open the new directory at `http://ip-address/rtl/apps/Lua-Examples/`.
4. Drag and drop the downloaded example files into the browser window.
The upload starts as soon as you drop the files into the page.
## Creating an App from the Uploaded Directory
After the files have been uploaded:
1. Navigate to `http://ip-address/rtl/`.
2. Expand disk in the left pane.
3. Right-click the `Lua-Examples` directory.
4. Select New App.
5. Enable Running and LSP App.
6. Click Save.
You can now expand the example application in the left pane, open any example file in the editor, and run it directly from the IDE.
## Using an External IDE
The built-in web IDE is excellent for quick iteration, but an external editor or IDE may be more comfortable for larger projects. You can edit files directly on the ESP32 by mounting the device as a WebDAV drive.
For operating-system-specific instructions, see the How to Mount a WebDAV Drive guide.
The WebDAV URL is:
https://ip-address/rtl/apps/
## Debugging Lua Code
Remote debugging is supported through the Barracuda App Server Lua debug module. This workflow integrates with Visual Studio Code and lets you debug Lua running on the device.
One important detail is that breakpoints pause the server. Because of that, the device’s WebDAV service is also paused while the debugger is stopped. For this reason, it is better to keep your source files on the host computer and let the device access them through NetIo during a debug session.
For the NetIo background, see the additional Xedge documentation.
## Debugging Workflow
Follow the How to Debug Lua Code Using Visual Studio Code guide and complete the prerequisites listed there.
Then:
1. Copy the File Server directory into `xedge-ESP32/BAS/examples/xedge/FileServer` on your host machine.
2. Start the Mako Server from `xedge-ESP32/BAS/examples/xedge`:
mako -l::FileServer
If `mako` is not in your path:
/path/2/mako -l::FileServer
3. When the File Server opens in the browser, click `Lua-Examples` and copy the full URL shown by the file server.
4. In Xedge32, open `http://ip-address/rtl/`, right-click net, and paste that URL into the app dialog.
5. Enable Running and LSP App, then click Save.
As soon as the device connects to the File Server app, you should see a message similar to:
Creating 'Visual Studio Code' config file: Lua-Examples/.vscode/launch.json
## Starting the First Debug Session
1. Open the local directory `xedge-ESP32/BAS/examples/xedge/Lua-Examples` in Visual Studio Code.
2. Open `httpclient.lsp` and add the following lines near the top of the file:
3. In a browser, open `http://ip-address/LuaExamples/httpclient.lsp`.
4. The page will appear to hang. That is expected because the web server is now waiting for the debugger to attach.
5. Press `F5` in Visual Studio Code to start debugging.
Once the debugger attaches, execution stops automatically. You can now step through the code, resume execution, and set breakpoints for later runs.
When you refresh the page again, the new breakpoint is hit. You can even step into library code such as httpm, including Lua code embedded in the firmware image.
Built with [Sphinx](https://www.sphinx-doc.org/) using a [theme](https://github.com/readthedocs/sphinx_rtd_theme) provided by [Read the Docs](https://readthedocs.org).
Two runtime variants are provided for ESP32-S3 boards:
**\`\`xedge.bin\`\` / \`\`merged-xedge.bin\`\`**
Best for boards such as the XIAO ESP32-S3 that expose a single USB port. This build provides 
