Logging for Testing and Production Mode

In this tutorial, we will go over several options for logging data during testing and debugging, but also how logging can be used by deployed production-ready products.

As explained in the introductory tutorial, under the section Understanding the Xedge32 Ecosystem, the Barracuda App Server (BAS) is the foundation for Xedge, which in turn is the foundation for Xedge32. In this tutorial, we will use an Xedge32-powered ESP32 to show how it works, but the tutorial applies to any BAS-powered device.

print(string, ...) -- BAS API
trace(string, ...) -- BAS API
tracep([info,] priority, string, ...) -- BAS API
xedge.elog(op, formatstring, ...) -- Xedge API
xedge.eflush([op]) -- Xedge API

-- Examples:

-- Function print, trace, and tracep convert all arguments to strings
trace("Socket obj:", ba.socket.connect("realtimelogic.com",80))

-- Uses the same format string as the Lua function string.format
xedge.elog({}, "%s %d", "The Answer to the Ultimate Question of Life is", 42)

See the documentation for print,trace,tracep and xedge.elog for details.

Function print, which comes from the Lua API, prints data to the console. However, in a BAS-powered environment, this function, if used from a non LSP page, may not be enabled if the device has no console. When using Xedge32, the output from this function is sent to the trace library. Function trace and tracep send data to BAS’s trace library. The trace library includes a porting layer that, for Xedge32 sends data to the UART serial connection. Function xedge.elog is an Xedge-specific logging function that either sends the message as an email or sends it to the trace library.

TraceLogger

The above functions also send data to the TraceLogger, a WebSocket endpoint a TraceLogger client can connect to and receive data from. The Xedge IDE includes a TraceLogger client in the bottom pane. You may also navigate directly to the TraceLogger client by navigating to http://xedge32.local/rtl/tracelogger/.

TraceLogger Web Client

The TraceLogger Web Client is a JavaScript-powered app that connects to your device using WebSockets. Trace data from the device is then sent over WebSockets to the HTML UI.

TraceLogger Web Client

Using the TraceLogger Web Client, the trace priority (trace level) can be changed. You can also programmatically change the trace level by controlling the object returned by function ba.create.tracelogger(). When using Xedge, the TraceLogger object is created by the startup code, thus calling ba.create.tracelogger() returns the already created object. The default trace priority set in Xedge is 9.

The trace level for function print and trace is set to zero, the highest priority level. Function xedge.elog’s level is set to 5. Function tracep lets you select any level.

The links below will take you to our online Lua tutorial server, where you can directly interact with the TraceLogger integrated into the Xedge IDE as well as the standalone TraceLogger.

Note that the TraceLogger supports a single active client connection. Should you encounter an error indicating that the TraceLogger is currently in use, you have the option to override this by forcibly disconnecting the existing client and establishing your own connection.

How to Save the Trace File on Your Host Computer

The Mako Server, Xedge32’s big brother, can be used as a TraceLogger client. The benefit of using this option is that it enables a more permanent option for receiving log data from the device. When the Mako Server is installed as a background process, the data received over the network from the device is saved in mako.log, the Mako Server's log buffer. In addition, the Mako Server’s TraceLogger Web Client will show log data in real-time as it trickles in from the device.

Download the Mako Server and the Mako Server’s TraceLogger Client to use this logging option.

For long-term logging, consider installing the Mako Server and the Mako Server’s TraceLogger client on for example, a Raspberry Pi.

Introduction to Email Logging in Xedge

Email notifications may feel old-school, but they're handy, both during development and after your product hits the market. That's why Xedge includes a straightforward email logging feature. Configure SMTP in Xedge, and voilà - crucial updates land directly in your inbox.

Why Enable Email Logging?

Email logging acts as your Xedge device's guardian, offering several key benefits:

  • Immediate Exception Alerts: Nobody's perfect, and if your Lua program encounters an error, it gets logged to the trace buffer, but with email logging, Xedge takes it a step further by dispatching a detailed exception report to your designated email. This means you're informed in real time about crashes, enabling continuous monitoring of your products.
  • Programmatic Notifications: Need tailored alerts? The xedge.elog() function lets you craft email notifications triggered by specific events in your Lua scripts. This can be invaluable for receiving updates on critical events or data points you've determined to be important.
  • Efficient Message Handling: Xedge respects your inbox. Non-urgent messages are intelligently batched together and sent when they reach a specific size or after a specified time interval. This bulk sending ensures you receive updates without being overwhelmed by a flood of separate emails.
  • Emergency Flush Capability: For urgent matters, Xedge can bypass the batching process and send an immediate alert using the flush attribute. This ensures that the most critical information reaches you without any delay.
  • Smart Disable Feature: Xedge is smart about when to send emails. Email messaging is automatically turned off when a browser is actively connected to the Xedge IDE, preventing unnecessary email traffic when actively developing code.

With Xedge, you can choose any email service provider for your notifications. Setting up a dedicated Gmail account for receiving these alerts works quite well. Below, we'll guide you through enabling logging with a Gmail address. However, remember that these instructions are adaptable to the SMTP settings of any email provider you prefer.

Configuring Email Settings in Xedge Using Gmail's SMTP Server

To configure email settings in Xedge using Gmail's SMTP server, you need to have two-factor authentication (2FA) enabled on your Gmail account and use a unique app password instead of your regular Gmail password. If you've already set up 2FA, you can skip ahead to generating the app password. Here's how to get everything up and running:

Enable Two-Factor Authentication (2FA) for Your Gmail Account:

  1. Sign into your Gmail account.
  2. Navigate to the 2-Step Verification page . You may be prompted to log in again.
  3. Click on 'Get started' and follow the on-screen instructions to enable 2FA.

Generate an App Password for Xedge:

  1. Once 2FA is enabled, return to your Google Account settings.
  2. Use the search box at the top to find 'app passwords' or go directly to the App passwords page.
  3. If prompted, sign in with your Gmail credentials.
  4. On the App passwords page, click on 'Select app' and choose 'Other (Custom name)'.
  5. Enter 'Xedge' as the name and click on 'Generate'.
  6. Copy the 16-character password displayed in the popup. Store it securely, as you won't be able to retrieve it once you navigate away from this page.

Configure SMTP Settings in Xedge:

  1. Access the Xedge IDE by navigating to http://xedge32.local/rt/.
  2. Open the menu by clicking the three dots at the top and select 'SMTP Server'.
  3. Fill in the SMTP settings as follows:
    • Email Address: Your Gmail email address.
    • SMTP Server: smtp.gmail.com.
    • Port: 465 (This port is for TLS).
    • Username: Your full Gmail address (e.g., yourusername@gmail.com).
    • Password: The app password you generated.
    • Ensure the 'TLS' checkbox is ticked.
  1. Click 'Save' to apply the settings. Xedge will send a test email to confirm everything is working correctly.

Enable Email Logging:

  1. In the Email Log settings, provide a default subject for the email log entries.
  2. Activate (Enable) the service to start logging emails.

Xedge32 Tutorials:

Keep exploring and have fun with our Xedge32 tutorial series.


Navigating Complexities? We've Got You!

Our consulting services are your first line of defense when complexities arise in networking, security, or device management. And for those keen to take the reins, our extensive tutorials on embedded web servers and IoT are your perfect companion. With Real Time Logic, expertise meets empowerment. Your vision, our mission.



OPC-UA

OPC-UA Client & Server

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

Edge Controller

Edge Controller

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

On-Premises IoT

On-Premises IoT Platform

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

Embedded Web Server

Barracuda Embedded Web Server

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

WebSocket Server

Microcontroller Friendly

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

WebDAV Server

Network File System

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

HTTP Client

Secure HTTP Client Library

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

WebSocket Client

Microcontroller Friendly

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

SMTP Client

Secure Embedded SMTP Library

Send alarms and other notifications from any microcontroller powered product.

Crypto Library

RayCrypto C Library

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

Embedded PKI Service

Automatic SSL Certificate Management for Devices

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

Modbus

Modbus TCP client

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

Posted in Xedge32