Deploy, Flash & Test

This page consolidates the key commands for FastBee-Arduino from online flashing, source build, release packaging to device verification. It covers development, field deployment, release packaging and pre-production checks. For a first-time experience, see Quick Start; for browser-based flashing, open the Online Flasher.

Source repository: FastBee-Arduino.

Flow Overview

Firmware & Environment Selection

Select the PlatformIO environment that matches your hardware to avoid Flash/PSRAM mismatches.

Environment	Tier	Chip	Flash / PSRAM	Use Case
esp32c3-F4R0	Lite	ESP32-C3	4MB / —	Low-cost WiFi/MQTT node
esp32c6-F4R0	Lite	ESP32-C6	4MB / —	WiFi 6 low-cost node
esp32-F4R0	Standard	ESP32	4MB / —	Standard ESP32 dev board
esp32s3-F8R0	Standard+OTA	ESP32-S3	8MB / —	S3 8MB module, OTA enabled
esp32-F8R4	Full	ESP32	8MB / 4MB	ESP32-WROVER or PSRAM module
esp32s3-F8R4	Full	ESP32-S3	8MB / 4MB	ESP32-S3 N8R4
esp32s3-F16R8	Full	ESP32-S3	16MB / 8MB	Full features, long-run & release

F = Flash size, R = PSRAM size. Feature differences are detailed in Edition Comparison; build switches in Build Configuration.

Online Flashing

For quick trials and field recovery, use the Online Flasher. The built-in firmware is a merged image containing bootloader, partition table, application firmware and LittleFS web filesystem, flashed at address 0x0.

1. Open the online flasher with Chrome or Edge.
2. Connect the ESP32 board and select the serial port.
3. Select the built-in firmware matching your chip, Flash and PSRAM.
4. Keep address 0x0, click flash and wait for auto-reset.

The merged firmware includes all partitions — no additional files need to be flashed separately. Default peripherals and exec rules are safe templates; verify pins and power before first wiring.

If the page is abnormal after flashing, confirm the firmware tier matches the hardware. When switching partition tables or if old configs cause issues, erase the entire Flash first and re-flash.

Source Deployment

For development and debugging, use the unified deploy script. It checks the environment, builds and uploads the LittleFS web filesystem and firmware for the target environment.

cd D:\project\gitee\FastBee-Arduino
powershell -ExecutionPolicy Bypass -File scripts\doctor.ps1 -Port COM6
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32-F4R0 -Port COM6

Common deploy commands:

# ESP32 Standard
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32-F4R0 -Port COM6

# ESP32-S3 16MB + 8MB PSRAM Full
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6

# Build only, no flash
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -BuildOnly

# Open serial monitor after deploy
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -Monitor

# Skip doctor (environment already verified)
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -SkipDoctor

# Only update filesystem
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -SkipFirmware

# Only update firmware
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -SkipFs

Before flashing, the script automatically: cleans residual processes → checks build cache integrity → runs doctor. Build failures trigger automatic clean + rebuild.

Release Packaging

powershell -ExecutionPolicy Bypass -File scripts\build-all-artifacts.ps1 -CleanOutput

dist\firmware\all-latest\manifest.json records environment, version, hardware, deploy commands, file sizes, SHA-256 and smoke status placeholders. Naming convention: fastbee-{chip}-F{flash}R{psram}.bin.

To flash an existing release package directly:

powershell -ExecutionPolicy Bypass -File scripts\flash-release.ps1 -Env esp32s3-F16R8 -Port COM6

This writes the merged image from dist\firmware\all-latest for the target environment (default baud 921600), suitable for interrupted upgrade recovery or mass production. Add -DryRun to preview without writing.

First Access Verification

After deployment, open a browser and navigate to the device IP (or http://fastbee.local). Verify:

1. Login page loads, authenticate with default credentials.
2. Dashboard shows device status (uptime, heap, flash).
3. Network page shows connected status and IP.
4. Peripheral and PeriphExec pages load without errors.

If the dashboard is accessible but status is empty, the device may still be starting up or the session has expired — refresh and re-login.

Test Layers

Test layering follows a pyramid approach from low-cost to high-fidelity; daily development prioritizes lower layers, release verification must cover device and long-run layers.

Layer	Entry Point	Coverage	When
Static checks	scripts\test-all.ps1 -Checks static	UTF-8, test registration, API matrix, build matrix, doc links, default config safety, i18n, web assets, Git whitespace	Every commit
Native unit tests	scripts\test-all.ps1 -Checks native	Host-side C++ unit tests (CommandBus, ErrorHandler, OTA, RuleScript, Batch/SSE, PeriphExec)	Core logic/API/config changes
Full build	scripts\test-all.ps1 -Checks build	7 release environments: ESP32, ESP32-C3, ESP32-C6, ESP32-S3 Lite/Standard/Full	Firmware or build switch changes
Release artifacts	scripts\test-all.ps1 -Checks artifacts	Merged firmware, LittleFS, manifest.json	Preparing release or delivery
Device smoke	scripts\test-all.ps1 -Checks device-smoke	Login, system, capabilities, network, device, protocol, MQTT, peripherals, PeriphExec, logs/files/OTA/users	After flashing a real device
Device stability	scripts\test-all.ps1 -Checks device-soak	Multi-round API cycling, capabilities, low-memory protection, auth stability, response latency	After critical changes and before release
Browser quick	scripts\test-all.ps1 -Checks browser-quick	62 @quick-tagged core cases: login/dashboard/network/MQTT/peripherals/rules	Daily development and firmware smoke
Browser full	scripts\test-all.ps1 -Checks browser	273 full Playwright cases: all page interactions and edge cases	Pre-release full regression

Version Matrix

PlatformIO Env	Chip/Hardware	Tier	Required Checks
esp32c3-F4R0	ESP32-C3 4MB Flash	lite	static, build, lite device smoke
esp32c6-F4R0	ESP32-C6 4MB Flash	lite	static, build, lite device smoke
esp32-F4R0	ESP32 4MB Flash	standard	static, native, build, standard device smoke
esp32s3-F8R0	ESP32-S3 8MB Flash	standard	static, native, build, standard device smoke
esp32-F8R4	ESP32 8MB Flash + 4MB PSRAM	full	static, build, full device smoke
esp32s3-F8R4	ESP32-S3 8MB Flash + 4MB PSRAM	full	static, build, full device smoke
esp32s3-F16R8	ESP32-S3 16MB Flash + 8MB PSRAM	full	static, native, build, artifacts, full device smoke & stability

4MB environments use fastbee.csv (no OTA); 8MB use fastbee-8MB.csv (OTA dual partition); 16MB use fastbee-16MB.csv (full long-run and file/log features).

Common Test Commands

All tests share a single entry point scripts\test-all.ps1, with -Checks to specify which checks to run (supports multiple).

# Quick pre-commit check (static + build)
powershell -ExecutionPolicy Bypass -Command ".\scripts\test-all.ps1 -Checks static,build"

# Full local matrix, no real device
powershell -ExecutionPolicy Bypass -Command ".\scripts\test-all.ps1 -Checks static,native,build,artifacts"

# Real device API smoke test
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks device-smoke -BaseUrl http://192.168.5.116 -DeviceProfile full

# Real device long-term stability test, CSV output to .pio/test-results
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks device-soak -BaseUrl http://192.168.5.116 -DeviceProfile full -SoakRounds 100

# Quick browser test (recommended for daily development)
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks browser-quick -BaseUrl http://192.168.5.116 -DeviceProfile full

# Full browser test (pre-release regression)
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks browser -BaseUrl http://192.168.5.116 -DeviceProfile full

# Run multiple checks in one pass
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks static,build,device-smoke,browser-quick -BaseUrl http://192.168.5.116 -DeviceProfile full

-Checks Values

Value	Description	Requires Device Params
static	Static checks: UTF-8, test registration, API matrix, build matrix, doc links, default config safety, i18n, web assets, Git whitespace	No
native	Host-side C++ unit tests (CommandBus, ErrorHandler, OTA, RuleScript, Batch/SSE, PeriphExec)	No
build	Full build across 7 release environments (ESP32/C3/C6/S3 Lite/Standard/Full)	No
artifacts	Generate merged firmware, LittleFS, manifest.json release artifacts	No
device-smoke	Device API smoke: login, system, capabilities, network, device, protocol, MQTT, peripherals, logs/files/OTA/users	Yes
device-soak	Device long-run: multi-round API cycling, low-memory protection, auth stability, response latency	Yes
browser-quick	62 @quick-tagged core cases: login/dashboard/network/MQTT/peripherals/rules	Yes
browser	273 full Playwright cases: all page interactions and edge cases	Yes
all	Run all checks (equivalent to all values above)	Yes

-BaseUrl and -DeviceProfile are required for device-accessing checks (device-smoke, device-soak, browser-quick, browser); omitting them will cause connection errors.

Common Parameters

Parameter	Default	Description
-Checks	static,native,build	Checks to run, supports multiple
-BaseUrl	http://192.168.4.1	Device web address (AP or STA)
-DeviceProfile	full	Device capability tier: lite/standard/full
-Username / -Password	admin / admin123	Web login credentials
-SoakRounds	10	Long-run test cycle count
-Environments	All 7	PlatformIO environments to build
-ContinueOnError	false	Continue running after a check fails
-DeviceSerial	empty	Serial port for browser test device pre-check
-BrowserHeaded	false	Show browser window (for debugging)
-ReportDir	.pio\test-results	Long-run CSV report output directory
-RequireNetworkConnected	false	Smoke test requires device online
-RequireMqttConnected	false	Smoke test requires MQTT connected

If the local Windows environment lacks gcc/g++, native will fail. This is not a firmware build failure — install MinGW/MSYS2 or run native tests in CI/Linux.

-DeviceProfile must match the firmware tier: Lite, Standard, and Full have different API surfaces — a mismatched profile will flag correctly-trimmed endpoints as failures.

Browser Automation Testing

Browser tests use Playwright to drive the device Web console, covering login, dashboard, network/device/MQTT configuration, peripheral management, rule scripts, logs/files/users, and other page interactions.

Quick vs Full Tests

Mode	Config File	Cases	Est. Time	Use Case
Quick (browser-quick)	playwright.quick.config.ts	62	~22 min	Dev-stage fast validation, CI quick regression, firmware smoke
Full (browser)	playwright.config.ts	273	30–37 min	Pre-release full acceptance, deep regression

Quick tests filter core cases tagged @quick from each spec file, covering auth, dashboard, network, device, MQTT, peripheral CRUD, rule scripts, logs/files/users, and other critical paths.

Running Playwright Directly

Bypass test-all.ps1 and call Playwright directly for finer-grained control:

cd test\browser
$env:DEVICE_IP = "192.168.5.116"

# Run quick / full tests
npx playwright test -c playwright.quick.config.ts        # Quick
npx playwright test                                       # Full

# Run specific tests
npx playwright test -g "AUTH-001"                        # Filter by name
npx playwright test -g "@quick" --project=smoke           # Combined filter

# View HTML report
npx playwright show-report reports\quick-html             # Quick test
npx playwright show-report reports\html                   # Full test

Timing Comparison Report

After running quick tests, run the comparison script to see timing differences vs the last full run:

node scripts\compare-test-timing.js

Output includes total time, per-file breakdown, top 10 slowest cases, and speedup multiplier.

@quick Tag Maintenance

Core test cases include the @quick tag in their title; the quick config filters via --grep @quick:

test('AUTH-001: Login with valid credentials @quick', async ({ page }) => { ... });

When adding new tests, decide whether to include them in the quick set:

• Covers core user paths (login, config save, protocol connect) → add @quick
• Boundary values, error scenarios, detailed form field validation → full tests only

Progress Display

Both modes use the list reporter to show real-time pass/fail status and duration for each test. Quick mode has no retries (retries: 0), so failures are reported immediately for fast diagnosis.

Device Smoke Coverage

Device API tests are driven by scripts\device-api-test-matrix.json, covering:

Category	Checks
Auth	Login, Bearer Token priority, multi-session
System	/api/health, /api/system/health, /api/system/info, /api/system/status, /api/system/web-runtime, /api/system/capabilities
Metrics	/api/system/metrics, heap, memguard, runtime metrics
Network	/api/network/status, /api/network/config, connection, IP, network type, AP/STA config
Device	/api/device/config, /api/device/info, /api/device/time
Protocol	MQTT status, MQTT config, compact protocol config, Modbus status (Standard/Full)
Peripherals	List, types, param validation, exec rules, exec controls, triggers, static/dynamic events, batch API
Capabilities	lite, standard, full capability switch semantics
Full-only	Filesystem, logs, OTA, RuleScript, users, roles, permissions
Edition boundary	Modbus or Full-only APIs should return proper unavailable status on Lite/Standard

Three-Edition Stability Baseline

All editions share the same long-run requirements:

Acceptance	Lite	Standard	Full
Auto-start on power	Required	Required	Required
WiFi/AP provisioning	Required	Required	Required
Auto-reconnect network	Required	Required	Required
Auto-reconnect MQTT	Required	Required	Required
Config error protection	Required	Required	Required
Watchdog/health	Required	Required	Required
Key logs/error codes	Basic	Full	Full
OTA	Not required	Optional	Required
Long-run test	72h minimum	72h min, 7d recommended	7 days minimum

Smoke Test Checklist

#	Test Item	Lite	Standard	Full	Pass Criteria
SMK-01	Full build	Required	Required	Required	No PIO build errors
SMK-02	Firmware flash	Required	Required	Required	Serial flash complete, auto-reboot
SMK-03	Power-on boot	Required	Required	Required	Boot logs appear, no crash loop
SMK-04	Filesystem mount	Required	Required	Required	/config/*.json readable
SMK-05	AP/STA network	Required	Required	Required	AP accessible, STA gets IP
SMK-06	Web/API health	Required	Required	Required	/api/health returns OK
SMK-07	Edition capability	Required	Required	Required	/api/system/capabilities matches firmware
SMK-08	MQTT connection	Required	Required	Required	MQTT connected, platform sees online
SMK-09	Data upload	Required	Required	Required	Platform receives property/event
SMK-10	Command dispatch	Recommended	Required	Required	Device executes and returns result
SMK-11	Reboot recovery	Required	Required	Required	Network, protocol, config auto-restore
SMK-12	Modbus status	Skip	Required	Required	Poll results normal when enabled
SMK-13	OTA status	Skip	Optional	Required	/api/ota/status matches capability
SMK-14	Logs/files/users	Skip	Optional	Required	Full-only APIs work

Functional Test Matrix

#	Module	Case	Lite	Standard	Full	Expected
FUN-01	Boot init	First boot, default config, AP	Required	Required	Required	Default config loads
FUN-02	Network	WiFi SSID/password persist	Required	Required	Required	Survives reboot
FUN-03	Network	Static IP/DHCP switch	Optional	Required	Required	Status page correct
FUN-05	MQTT	Connect, subscribe, publish, LWT	Required	Required	Required	Platform online correct
FUN-06	Data collect	GPIO/ADC/basic sensor read	Required	Required	Required	Correct format, no blocking
FUN-07	PeriphExec	Timer/event/platform trigger	Recommended	Required	Required	Conditions and actions match config
FUN-08	Modbus	Slave scan, register poll, control	Skip	Required	Required	Stable polling
FUN-09	Web/API	Login, Bearer Token, multi-session	Required	Required	Required	Auth/session correct
FUN-10	Files/Logs	Log viewer, file list, config I/O	Skip	Optional	Required	Full: available
FUN-15	Boundary	Empty config, oversized fields	Required	Required	Required	Error codes, no crash
FUN-16	Resource	Low memory, concurrent API, SSE	Required	Required	Required	Graceful degradation

Disconnect/Reconnect Test

#	Scenario	Steps	Pass Criteria
NET-01	No network at boot	Disconnect router, power on	AP/Web accessible, no crash loop
NET-02	WiFi disconnect during run	Kill router for 5 min	Logs record disconnect, main loop continues
NET-03	Network recovery	Restore router	Auto IP, MQTT reconnect, platform online
NET-04	MQTT unreachable	Stop broker	Backoff reconnect, local Web/PeriphExec unaffected
NET-05	DNS failure	Block DNS	Connection failure reported, auto-recover on restore
NET-06	Weak network	Add latency/packet loss	Timeout recoverable, no memory decline

Power Loss Recovery Test

#	Scenario	Steps	Pass Criteria
PWR-01	Normal operation power loss	Power off during stable run, restore	Config intact, auto-recover online
PWR-02	Data upload power loss	Power off during continuous upload	Main loop, MQTT, peripherals normal after reboot
PWR-03	Config save power loss	Power off during config save	Old or new config valid, no corrupt JSON
PWR-04	Filesystem update power loss	Power off during config import	Filesystem mountable, files re-writable
PWR-05	OTA upload power loss	Power off during OTA upload (Full)	Old firmware boots or recoverable state
PWR-07	Rapid power cycling	10 consecutive power on/off cycles	No config loss, no boot hang

Pre-Release Checklist

1. Run scripts\test-all.ps1 -Checks static,native,build,artifacts.
2. Flash target chips, confirm -Env matches chip edition.
3. Run node scripts\validate-config-defaults.js --staging-root .pio\fs-staging --latest-only.
4. Confirm default peripherals.json templates and periph_exec.json rules are disabled at factory.
5. Run device smoke test for each delivery edition (-Checks device-smoke).
6. Run quick browser tests (-Checks browser-quick) to verify core page interactions.
7. Run at least 100 soak rounds on esp32s3-F16R8 or editions with logs/files/users.
8. Check /api/system/info heap, maxAlloc, PSRAM and edition tier.
9. Check Web pages: login, network, protocol, peripherals, PeriphExec, logs, files, users, roles, RuleScript.
10. Generate release artifacts and verify dist\firmware\all-latest\manifest.json.

Long-Run Test Report Template

Project: FastBee-Arduino IoT System
Test Type: Long-run Stability
Edition Tier: Lite / Standard / Full
PlatformIO Env:
Hardware Model:
Flash/PSRAM:
Firmware SHA-256:
LittleFS SHA-256:
Test Location/Network:
Platform/Broker:
Start Time:
End Time:
Total Runtime:

Key Metrics:
- Abnormal reboots:
- Network disconnects:
- Auto-recoveries:
- MQTT disconnects:
- Total data uploads:
- Upload success rate:
- Total commands:
- Command response rate:
- Min heapFree:
- Min heapMaxAlloc:
- Full: psramTotal/psramFree:
- Low-memory triggers:
- OTA status checks:
- Error code stats:

Conclusion:
- Pass / Fail:
- Known issues:
- Release recommendation:

Recommended stability targets:

Metric	Lite	Standard	Full
Continuous run	>= 72h	>= 72h, 7d recommended	>= 7 days
Abnormal reboots	0 (or documented cause)	0 (or documented cause)	0 (or documented cause)
Network recovery	100% auto	100% auto	100% auto
Upload success	>= 99%	>= 99%	>= 99%
Command response	>= 98%	>= 99%	>= 99%
Memory trend	No decline	No decline	heap/PSRAM stable

FAQ

Symptom	First Check
Serial port not found	Confirm USB cable supports data; install CH340/CP210x driver; close Arduino IDE / PIO Monitor
Stuck waiting for sync	Hold BOOT during flash, release when write starts; press EN/RST to retry
Web console not loading	Confirm LittleFS was uploaded; use deploy.ps1 or run uploadfs before upload
Full firmware unstable	Verify PSRAM present via /api/system/info (psramTotal > 0)
Config lost after flash	Erase full Flash first when switching partition tables or migrating from other firmware
-DeviceProfile mismatch	Must match firmware tier; full-only APIs flagged as missing on Lite/Standard
native build fails	Windows lacks gcc/g++; install MinGW/MSYS2 or run in CI/Linux
Browser test timeout	Check -BaseUrl IP and device reachability; globalSetup prints a warning if device is unreachable
Flaky browser results	Ensure no other process uses the serial/Web port; increase TEST_DELAY_MS to 800 for stability; full tests auto-retry (retries: 2), quick tests do not (retries: 0)
soak heap declining	Likely memory leak; confirm MQTTS memguard degradation is present; check /api/system/metrics heapMinFree; Full editions also monitor psramFree