The Web App

AudioLux WebApp

The web app presents a graphical user interface allowing the configuration of the device. The application is served by a web server in the firmware. Once running, the application will communicate with the embedded server through an API.

Architecture

The application is very simple and based on Preact.js, a minified version of React. Even though it is very small, Preact.js provides all the main functionality of its big sibling. There is not enough complexity in the application to merit it being implemented in a MVVM or MVC pattern, so there is no model. Nonetheless, a modest effort is invested in providing some decoupling and modularization.

This is a high-level view of the current implementation:

Building the Web App

To get started, you will need node and npm installed in your system. Currently, the build process is based on Node.js version 14.17.1 and npm version 6.14.13. If you don't have node in your system consult the official installing guide. It is highly suggested that you use a node version manager like nvm (or nvm-windows). Check the install guide formore information.

Once you have node and npm in your system, clone the repo, go to the WebApp folder and use the CLI commands below to install, build, and run the application.

CLI Commands

# install dependencies
npm install

# serve with hot reload at localhost:8080
npm run dev

# build for production with minification
npm run build

# test the production build locally
npm run serve

# run tests with jest and enzyme
npm run test

For a detailed explanation of how things work, check out the CLI Readme.

Uploading the app to the AudioLux device

The Web App is separate from the firmware that runs on the AudioLux device. Once the Web App is built, it must be transferred to the device where it is saved in a memory partition configured as persistent storage with a simple file system.

The web is built for deployment using the npm run build command, as mentioned above. Once done, the app files will be in a build directory of the Web App folder. The following files and folders must be copied to the device:

• The assets folder and its contents.
• All the .html, .js, and .json files.
• All the .css files.

Do not copy the map files. Do not copy the ssr-build folder.

See below for instructions on how to send the web app to the device.

NOTE: deploying the app to the device will delete any state saved to disk. All settings will revert to defaults; this means it will lose any local network configuration it might have saved.

Setting up the file system for the Web App

As mentioned above, the Web App served by the AudioLux is not part of the firmware executable. Instead, the web files are stored in a 'filesystem' that resides in a different area of the flash in the ESP32 and acts in a way that loosely resembles a hard disk. Creating this storage area and loading the app is separate from the regular compile/upload flow of the Arduino build. The procedure below shows how to install the required tools and upload the Web app to flash.

Assumptions

This procedure assumes the user is running Windows and the Arduino IDE Setting Guide has been completed.

File System

The AudioLux firmware uses a LittleFS ESP33 library to access external storage (really just a memory partition in the on-chip flash). The Arduino IDE needs a plugin to upload files to this storage area. To install the plugin:

1. Download the latest release of the plugin.

2. Unzip the file.

3. You must copy esp32fs.jar to the tool directory of your Sketchbook location. To find your Sketchbook location, in the Arduino Ide go to Preferences:

   

4. Ensure that the Sketchbook location has the path: tools/ESP32FS/tool/. For example, if the Sketchbook location is <homedir>/Documents/Arduino, then the path <homedir>/Documents/Arduino/tools/ESP32FS/tool/ must exist. If it doesn't create all the required folders to complete it.

5. Copy esp32fs.jar to tools/ESP32FS/tool/

   

6. The plugin depends on an external executable, mklittlefs.exe, that is not included with the Arduino IDE. To get that program, download the latest release (for Windows, get the x86_64-w64-mingw32 variant).

7. Unzip the file and copy the executable to <homedir>\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.6\tools.

   

8 Restart the Arduino IDE.

Uploading files to the ESP32

Once the plugin is installed, there should be a new item in the Tools menu:

The plugin expects a Sketch to be open and that a folder called data exists in the Sketch's directory.

Whatever is in the data directory will be copied to the flash area designed as external storage.

To send files to the ESP32:

1. Copy the files and/or folders to the data directory. Then select Tools->ESP32 Sketch Data Upload.

2. In the dialog box that appears, make sure LittleFS is selected, and click OK.

   

The plugin will initialize the storage area and upload the files.

By following these steps, you can successfully build the AudioLux WebApp, deploy it to the device, and set up the file system for storing the application files.