Project Structure and Files
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.
The web-src/, data/www/, data/config/ and LittleFS runtime files in the repository are ultimately reflected in the device Web console. The file management page is suitable for verifying whether configuration files, logs and Web resources on the device match the source build artifacts.
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, edition tiers, build flags, library 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: users, roles, 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 lite, standard, full tiers. When adding full-only capabilities, verify lite/standard do not reference non-existent pages or APIs.
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, edition tiers 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, user/role pages |
| 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 |
| Edition trimming changes | platformio.ini, docs/edition-comparison.md, release artifacts |
| Default config changes | data/config/*.json, first-boot and factory reset flows |