105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# Building and Flashing the Frontend
|
|
|
|
The Calendink Provider uses a modern Svelte 5 frontend, built with Vite and TailwindCSS. The frontend is served directly from the ESP32's `www_0` or `www_1` LittleFS partition, allowing the user interface to be updated completely independently from the underlying firmware.
|
|
|
|
## 1. Prerequisites
|
|
|
|
Before you can build the frontend, make sure you have [Node.js](https://nodejs.org/) installed on your machine. All frontend code is located inside the `frontend/` directory.
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
```
|
|
|
|
## 2. Development Mode
|
|
|
|
During development, you don't need to rebuild and reflash the ESP32 every time you change a button color! You can run the Vite development server on your PC, and it will proxy API requests to the ESP32 over WiFi.
|
|
|
|
1. Ensure the ESP32 is powered on and connected to your local network.
|
|
2. Update `frontend/.env.development` with the IP address of your ESP32 (e.g., `VITE_API_BASE=http://192.168.50.216`).
|
|
3. Start the dev server:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## 3. Building for Production (ESP32)
|
|
|
|
When you are ready to deploy your frontend changes to the ESP32, you must package everything into a single file and compress it. Our custom build script handles this for you.
|
|
|
|
Run the following command inside the `frontend/` folder:
|
|
|
|
```bash
|
|
npm run build:esp32
|
|
```
|
|
|
|
**What this does:**
|
|
1. Runs Vite's production build.
|
|
2. Inlines all CSS and JS into `index.html` (thanks to `vite-plugin-singlefile`).
|
|
3. Runs `scripts/gzip.js` to heavily compress `index.html` down to an `index.html.gz` file (~15-20KB).
|
|
4. Outputs the final files to the `frontend/dist/` directory.
|
|
|
|
## 4. Flashing the Filesystem
|
|
|
|
Now that `frontend/dist/` contains your compressed web app, you must tell the ESP-IDF build system to turn that folder into a LittleFS binary image and flash it.
|
|
|
|
In your standard ESP-IDF terminal (from the project root, not the `frontend/` folder):
|
|
|
|
1. **Enable Web Deployment via Menuconfig (if not already done):**
|
|
```bash
|
|
idf.py menuconfig
|
|
# Navigate to: Calendink Configuration -> Deploy Web Pages
|
|
# Make sure it is checked (Y)
|
|
```
|
|
|
|
2. **Build and Flash:**
|
|
```bash
|
|
idf.py build
|
|
idf.py flash
|
|
```
|
|
|
|
Because `CONFIG_CALENDINK_DEPLOY_WEB_PAGES` is enabled, CMake will automatically:
|
|
1. Detect your `frontend/dist/` folder.
|
|
2. Run `mklittlefs` to package it into `www.bin`.
|
|
3. Flash `www.bin` directly to the active `www_0` partition on the ESP32!
|
|
|
|
## 5. Over-The-Air (OTA) Updates
|
|
|
|
Once the backend supports it (Phase 2+), you can update the frontend without using USB or `idf.py`.
|
|
|
|
1. **Build the assets**: `npm run build:esp32`
|
|
2. **Package the image**: `npm run ota:package`
|
|
- This generates a versioned binary in `frontend/bin/` (e.g., `www_v1.0.5.bin`).
|
|
- **Configuration**: If the tool is not in your PATH, add its path to `frontend/.env`:
|
|
```env
|
|
MKLITTLEFS_PATH=C:\path\to\mklittlefs.exe
|
|
```
|
|
*(Note: The script also supports `littlefs-python.exe` usually found in the `build/littlefs_py_venv/Scripts/` folder).*
|
|
3. **Upload via Dashboard**:
|
|
- Open the dashboard in your browser.
|
|
- Go to the **Frontend Update** section.
|
|
- Select the `www.bin` file and click **Flash**.
|
|
- The device will automatically write to the inactive partition and reboot.
|
|
|
|
## 6. Universal OTA Bundle
|
|
|
|
For a safer and more convenient update experience, you can bundle both the Firmware and Frontend into a single file.
|
|
|
|
See the [Universal OTA Bundle Guide](build_bundle.md) for details.
|
|
|
|
## 7. AI Agent Workflow
|
|
|
|
If you are an AI agent, you should use the automated deployment scripts to speed up your work.
|
|
|
|
### Deployment Prerequisites
|
|
- Ensure `VITE_API_BASE` in `frontend/.env` is set to the target device IP.
|
|
- Ensure `MKLITTLEFS_PATH` is correctly set if you are on Windows.
|
|
|
|
### Standard OTA Workflow
|
|
Follow the [Frontend OTA Workflow](file:///w:/Classified/Calendink/Provider/.agents/workflows/frontend-ota.md) for automated building and deployment.
|
|
|
|
**Summary of commands (run in `frontend/`):**
|
|
1. `npm run build:esp32` - Build production assets.
|
|
2. `npm run ota:package` - Create LittleFS image.
|
|
3. `npm run ota:deploy` - Upload to device via HTTP.
|