Description is outdated

https://wokwi.com/projects/356860098426595329

DESCRIPTION IS PARTIALLY OUTDATED

What this project is?

This is project, aim of what is to create ESP32 web server, capable of hosting js apps, based of different frameworks.

What it can do?

1. Host small webserver. Server can be based on JS frameworks like Vue, React, etc.
2. Interact with devices, connected to microcontroller (sensors, actuators, anything).
3. Using API calls, do different actions with connected devices, send / receive data. For example, you can create app, what will measure temperature every 10 seconds and save it on SD card. Then on web app request, it will read this data from SD and send to server, where it can be shown in form of graph.

How it works?

ESP32 acts as webserver, answering on incoming http requests. It reads data from sd card, and sends it to user device, as any other web server does. This project uses VS Code PlatformIO project as base.

What is project structure?

Backend part is just default async web server on C++.

Frontend part is list of apps with what you can interact. Each app is separate module, what can be built on any framework or even without it. Each app has its name, icon, and directory under x-frontend-modules directory

So many folders...

If not touch default Platformio project folders, structure is next:

/SD/

Folder, containing compiled JS/HTML/CSS code what should be loaded on real microcontroller SD card.

/SD/modules/

Here should be located folders with compiled code of your apps

/SD/modulesIcons/

Here should be located icons, what you are going to use for your app in sidebar menu and desktop app menu. Names of this images should be written in project.config.js for each project. Icons should be square.

!IMPORTANT!
Dont make icons too big, 128*128 is more than enough. If you make it bigger, then icons loading from server can take too long.

/x-frontend-common/

Folder, containing common elements for projects, for example Vue3 page template.

/x-frontend-modules/

Folder, containing frontend apps / modules. Each folder is separate app.

Apps

Apps by themselves are just pages, on each of what you can have anything.

project.config.js

project.config.js contains information about your apps, and also build mode (this can be changed for running app locally, more in next chapters)
project.config.js has next props what you can edit:

• projects
• modulesDirRelativePath
• modulesDirFullPath
• base

projects

projects is for your apps. Every app you want to add should be added into this array. Structure is next:

• name: name of project, must be same as project folder name in /modules/ folder.
• fullName: name of project, shown in desktop app menu and sidebar menu. Can be anything, it just to show app name. For example: Measurement App Example
• categories: array of categories this app belongs to. You should import these categories from project.categories.js, what is located in same directory as project.config.js. You can add your own categories.
• roundIconName, round icon file name, used in sidebar. This icon will be completely round in sidebar. Icon itself must be placed into /SD/modulesIcons/ folder, as described above. For example: measurement-app-example.png.
• iconName: same as above, but will remain square and should have white background.
• hideInDesktop: if this property is true, then this app won't be shown in desktop app menu.

modulesDirRelativePath

Relative path to /SD/modules/ directory from app root. For example, if you keep /SD/modules/ in same place as it is now and place your app under /x-frontend-modules/{app name}, then that would be ../../SD/modules
This is used to configure your app config, in case of Vite it is used to set up outDir folder.

modulesDirFullPath

Path to /SD/modules from your computer disk root, without disk letter. Used in local app build and launch, more information below.
For example, if I have /SD/modules folder located under C:\Users\exampleuser\Documents\PlatformIO\Projects\exampleproject\SD\modules, then this variable value should be Users\exampleuser\Documents\PlatformIO\Projects\exampleproject\SD\modules

base(projectName)

Function returning path /SD/modules/{app name} for exact app. Needed to configure Vite.

Address

Each app is located under {root}/modules/{appName} path.

How to properly create a new app?

1. Go to /x-frontend-modules/ directory and create a new app folder by any way. For example, I am creating Vue 3 Vite based app, so I write npm create vue@3.
2. Go to /SD/ (or real sd location) and put project icons in modulesIcons folder.
3. Go to /x-frontend-modules/project.config.js and add your application description object in projects array. Description must contain project name, what must be same as project folder name, array of categories, what this app belongs to, and this app icons names.
4. Setup your project that way, when compiled files are automatically placed into SD folder, and also ensure that all sources path is like /modules/{appName}/... . In case you are creating Vite app, you can do this through setting Vite config outDir to ${Config.modulesDirRelativePath}/${appName} and base to /modules/{appName}
5. PROFIT. Now when you build your app, its assets files should be located under /SD/modules/{appName} directory, and in same directory is located index.html, what will run app.

Run app locally

To run app locally (just for frontend testing purposes), you should check how it works for package manager you use. In Vite case, this can be done quite simply:

1. Copy project icons folder from /SD/ to /public/ folder of project
2. Set mode to Modes.SINGLE_MODULE_LOCAL_DEBUG in project.config.js
3. In project.config.js set modulesDirFullPath to absolute path for /modules/ folder excluding your disk name. For example: /Users/exampleuser/Documents/PlatformIO/Projects/exampleproject/SD/modules
4. Build app using npm run build from app directory
5. Run app using npm run preview from app directory
6. Use localhost link you will see in console to open launched app page in browser

This case you will be able to open your app page and interact with frontend part, but no links to other project or api calls to ESP32 server won't be accessible.

Shortcuts

All these shortcuts are for case when you use Vite. In other cases steps you have to do can differ.

Build all apps

1. Go to /x-frontend-modules/ directory
2. In package.json in build script add npm script to run your app build script.
   For example:
   npm run build --prefix measurement-example & npm run build --prefix desktop
   --prefix value here must be name of your app folder

Quickly run app build with watcher and automatic local server launch

1. Go to /x-frontend-modules/ directory
2. Ensure what you have concurrently package in your package.json dependencies
3. Add script following next structure: concurrently "npm run watch --prefix {project name}" "npm run preview --prefix {project name}
   Remember what double quotes must be shielded
4. Run script.