Project Directory and Files
This document describes the main directories, key files and generated artifacts in the FastBee-Arduino repository. When maintaining the project, prioritize the boundaries defined here to avoid mixing generated files, source code and release artifacts.
web-src/, data/www/, and data/config/ contain the Web sources, generated assets, and factory configuration respectively. Export selected runtime configuration from Device Configuration > Advanced Configuration; validate Web resources with the build artifact checks.
Directory boundaries can be understood as an artifact map: source code, configuration and Web resources are inputs; .pio/ is the build cache; dist/ is the release output; only traceable build artifacts and acceptance records should be referenced during delivery.
Top-Level Directories
| Path | Description |
|---|---|
include/ | C++ header files defining core framework, network, peripheral, system service, security auth and utility interfaces |
src/ | Firmware source code implementation, organized by include/ module divisions |
web-src/ | Web console source files including CSS, page fragments, runtime modules, admin modules and i18n |
data/ | LittleFS file system source data; data/www is built from web-src, compressed for device-side Web resources |
scripts/ | Build, deploy, Web asset processing, test matrix and diagnostic scripts |
test/ | PlatformIO native/host test code, mocks and test utilities |
docs/ | User manual, development guide, peripheral/protocol/scenario docs and project maintenance docs |
dist/ | Release firmware output directory, generated by scripts, should not be manually maintained |
.pio/ | PlatformIO build cache, library dependencies, temporary file system staging and test output, should not be committed |
platformio.ini | PlatformIO master config defining chip environments, unified flags, hardware overrides, dependencies and extra scripts |
README.md, README.en.md | Project entry descriptions in Chinese and English |
setup-toolchain.ps1 | Local toolchain initialization helper script |
Firmware Source Code
include/
| Path | Description |
|---|---|
include/core/ | FastBee core framework, chip capabilities, peripheral config, peripheral execution, task and rule types |
include/network/ | Network management, Web config, routing context, request handler declarations |
include/security/ | User, role, permission, session and authentication management |
include/systems/ | File system, logging, OTA, NTP, configuration, task and other system service interfaces |
include/peripherals/ | Sensor, display, GPIO, bus and other peripheral abstraction interfaces |
include/utils/ | Common utilities such as PSRAM JSON document, string/response helpers |
src/
| Path | Description |
|---|---|
src/main.cpp | Firmware boot entry, initializes framework, network, Web, peripherals and system tasks |
src/core/ | Framework lifecycle, peripheral management, peripheral executor, rule scheduling and other core logic |
src/network/ | WiFi/AP/STA, Web server, route registration, request context and network state |
src/network/handlers/ | REST API route implementations: system, network, peripheral, batch, log, file, auth |
src/security/ | Login authentication, session management, Token and Cookie compatibility logic |
src/systems/ | File system, logging, OTA, task management, time sync, system status |
src/peripherals/ | Concrete peripheral driver and sensor read/write implementations |
When modifying APIs, also check src/network/handlers/, Web frontend calls, scripts/device-api-test-matrix.json and related documentation.
Web Console
| Path | Description |
|---|---|
web-src/css/ | Web console CSS, unified widget styles maintained here |
web-src/js/ | Startup, request handling, state management, notifications, module loading and other common runtime code |
web-src/modules/runtime/ | Device runtime page modules: dashboard, network, peripherals, peripheral execution |
web-src/modules/admin/ | Admin page modules: logs, users and rule scripts |
web-src/pages/ | HTML pages and dialog fragments |
web-src/i18n/ | Internationalization resources |
data/www/ | Compressed assets written to device LittleFS after build, usually generated by scripts |
After modifying Web source, use scripts\build-web-modules.js, scripts\gzip-www.js or scripts\deploy.ps1 to generate device-side assets. Do not modify only data/www/*.gz without updating web-src source files.
Configuration Data
| Path | Description |
|---|---|
data/config/peripherals.json | Default peripheral configuration and templates |
data/config/users.json | Default users, roles, security config and session policy |
data/www/ | Device-side Web static assets and pages |
Default configuration must work across all nine release environments. When adding an optional capability, verify that unavailable pages stay hidden and APIs return a documented unavailable status.
Scripts Directory
Scripts are located in the
scripts/directory of the FastBee-Arduino firmware repository, not in this documentation repository.
Core groups:
| Group | Key Files |
|---|---|
| Test Matrix | test-all.ps1, device-api-test-matrix.json, smoke-test-device.ps1, soak-test-device.ps1 |
| Deploy & Release | deploy.ps1, build-all-artifacts.ps1, collect-artifacts.ps1, fastbee-artifacts.py |
| Web Build | build-web-modules.js, gzip-www.js, generate-sw-manifest.js, web-smoke-test.js |
| Quality Checks | check-utf8-text.js, validate-i18n.js, web-profile.js, web-asset-report.js |
| Diagnostics | serial-diagnostics.py, kill-stale-processes.py |
Test Directory
Test code is located in the
test/directory of the FastBee-Arduino firmware repository, not in this documentation repository.
| File | Coverage Focus |
|---|---|
test_main.cpp | Test entry and base framework |
test_web_api.cpp | Web API behavior |
test_network_config.cpp | Network configuration |
test_mqtt_protocol.cpp | MQTT configuration and protocol |
test_system_stability.cpp | Stability and boundary conditions |
test_e2e_scenarios.cpp | Combined scenarios |
Real device API tests are not in test/ but executed via scripts\smoke-test-device.ps1 and scripts\soak-test-device.ps1.
Documentation Directory
| Path | Description |
|---|---|
overview.md | Project overview |
quick-start.md | Quick start |
testing.md | Test matrix and pre-release verification |
project-structure.md | This file, directory and key file description |
architecture.md | System architecture |
core-framework.md | Core framework overview |
development-guide.md | Development guide |
user-manual.md | User manual |
examples/ | Peripheral and scenario examples |
peripherals/ | Peripheral configuration reference |
periph-exec/ | Peripheral execution rules, triggers and actions |
protocols/ | MQTT, Modbus and other protocol docs |
system/ | System management, feature state and configuration |
Generated Artifacts & Cleanup Rules
| Path/File | Type | Handling |
|---|---|---|
.pio/ | PlatformIO build cache | Can be deleted and regenerated |
dist/business/firmware/ | Release firmware output | Generated by build-all-artifacts.ps1 |
data/www/*.gz | Compressed Web assets | Generated by Web build scripts, must be retained before release |
scripts/*.pyc | Python runtime cache | Can be deleted, should not be committed |
compile_commands.json | Compilation database | Can be generated by tools, used for IDE/clangd |
upload_log.txt | Local flash log | Debug artifact, should not be maintained as source |
Modification Sync Rules
| Modification Type | Sync Check Required |
|---|---|
| New API | Web calls, scripts/device-api-test-matrix.json, related docs |
| Auth/session changes | smoke/soak, browser login, Users page, role and permission APIs |
| Network/4G/Ethernet changes | Network pages, MQTT status, device smoke matrix |
| Web style changes | web-src/css/main.css, related page logs and Web smoke |
| Build capability changes | platformio.ini, hardware/environment docs, capability tests and release artifacts |
| Default config changes | data/config/*.json, first-boot and factory reset flows |