User Manual

This guide covers hands-on wiring and Web configuration, from initial setup to peripheral configuration, PeriphExec rules, sensor integration, import/export and troubleshooting.

1. Preparation

Before starting, complete these prerequisites:

• Choose the hardware environment: Match the chip, Flash and PSRAM exactly. See Hardware and Environments.
• Flash firmware: Use the deploy script to flash matching LittleFS filesystem and firmware. See Deploy, Flash & Test.
• Initial configuration: Connect to device AP → enter Web console → configure WiFi → confirm network online → configure MQTT. See Network Config and MQTT Config for step-by-step instructions.

For the full quick-start steps, see Quick Start.

After deployment, the browser Web console should show the dashboard with device data.

2. Peripheral Configuration

The live peripheral configuration is stored in LittleFS at /config/peripherals.json. The repository file data/config/peripherals.json is only the factory template used to build the filesystem image. Each peripheral requires at minimum:

{
  "id": "relay_01",
  "name": "Relay 1",
  "type": 12,
  "enabled": false,
  "pinCount": 1,
  "pins": [26, 255, 255, 255, 255, 255, 255, 255],
  "params": {}
}

Quick type reference:

Type	type	Common Modules
I2C	2	SHT31, AHT20, BH1750, OLED, BMP280, MPU6050
GPIO Input	11/13/14	Button, PIR, vibration, reed switch, digital obstacle
GPIO Output	12	LED, relay, buzzer, laser
ADC	15/26	Photoresistor, soil moisture, smoke, rain, voltage, current
SENSOR	38	DHT, HC-SR04, generic sensor placeholder
ONE_WIRE	44	DS18B20
NeoPixel	45	WS2812B
TM1637	47	4-digit display
Modbus Device	51	RS485 slave control when Modbus is active
DEVICE_EVENT	60	Logical event source

Complete peripheral type enumeration, pin assignment rules and configuration flow are detailed in the Peripheral Guide.

Best practice: Save new peripherals as disabled first; enable after confirming pins and power supply. If a saved peripheral doesn't work at runtime, verify that the page fields, peripherals.json, runtime driver and rule references all use the same peripheral ID.

3. PeriphExec Rules

The live PeriphExec configuration is stored in LittleFS at /config/periph_exec.json; the repository file with the same name is only the factory template. A rule consists of triggers and actions:

{
  "id": "exec_temp_relay",
  "name": "High temp opens relay",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:dht11_01_temperature",
      "operatorType": 2,
      "compareValue": "35"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "relay_01",
      "actionType": 0,
      "actionValue": "",
      "useReceivedValue": false,
      "syncDelayMs": 0,
      "execMode": 0
    }
  ],
  "reportAfterExec": true
}

Common triggers:

triggerType	Name	Use Case
0	Platform	MQTT/platform command dispatch
1	Timer	Periodic collection, scheduled control
4	Event	Button, data source threshold, system event
5	Poll	Local data source condition check; Modbus polling requires the Modbus feature

Common actions:

actionType	Name	Use Case
0/1	GPIO High/Low	Relay, LED, buzzer
2/3	Blink/Breathe	LED, buzzer indication
4/5	PWM/DAC	Dimming, speed control, analog output
10	Call Peripheral	Stepper, NeoPixel, UART composite
15	Command Script	Multi-step GPIO/PWM/delay when command scripts are active
19	Sensor Read	ADC, DHT, DS18B20, HC-SR04, SHT31, etc.
21	Trigger Event	Send logical event to platform or local rules
24/25/26/27	Display	TM1637, OLED display actions

Complete trigger/action type tables, condition operators and platform trigger fields are in the PeriphExec Guide.

Best practice: Keep rules disabled on first deploy; use "Execute Once" to observe logs and peripheral state before enabling. Before enabling, confirm: unique ID, clear trigger source, valid action target peripheral, logging and rollback available.

4. Sensor Read Action

actionType: 19 uses a JSON string to describe the read parameters. The Web form auto-generates this:

{
  "periphId": "sht31_i2c",
  "sensorCategory": "SHT31",
  "dataField": "temperature",
  "sensorLabel": "Temperature",
  "unit": "C",
  "decimalPlaces": 1,
  "driverParams": {
    "addr": "0x44",
    "sda": 21,
    "scl": 22
  }
}

Common sensorCategory values: dht11/dht22 (temperature/humidity), ds18b20 (temperature), ultrasonic (distance), SHT31/AHT20 (I2C temperature/humidity), BH1750 (I2C illuminance), BMP280 (I2C pressure), and MPU6050 (I2C motion). I2C sensors require the i2cSensors runtime feature.

Complete sensor categories and register-level config parameters are in the Sensor Guide.

5. Typical Scenarios

All scenarios follow the closed loop: Sense → Decide → Act → Report → Review. Start with a single sensor, single rule, single action; combine display, alarm and platform reporting after confirmation. More examples are in Examples.

Temperature Threshold Relay

1. Configure DHT11/DHT22/SHT31/AHT20.
2. Create timer collection rule with reportAfterExec: true.
3. Create event trigger rule using eventId: ds:<peripheralID>_<field>.
4. Action: relay HIGH or LOW depending on module effective level.

Low Light Auto-On

1. Configure BH1750 or photoresistor ADC.
2. Timer read illuminance or voltage.
3. Event trigger operatorType: 3 (less than), e.g., value 50.
4. Action: turn on relay or LED.

Current Overload Cutoff

1. Configure ACS712 current sensor ADC.
2. Sensor read advanced params: sensitivity, zeroOffset, vRef, adcMax.
3. Event trigger: current > 15.
4. Action: close relay, optionally trigger actionType: 21 to report over_current event.

Modbus Sensor Collection

1. Select any matching release environment, then confirm Modbus is compiled and active in /api/features/status.
2. Configure serial port, baud rate and slave addresses in Protocol / Modbus RTU.
3. Add Modbus sub-devices or register mappings.
4. Use poll trigger or Modbus action in PeriphExec to read data and report via MQTT.

6. Import/Export

• All documentation examples default to enabled: false; verify pins before enabling after import.
• Export peripherals.json and periph_exec.json before every batch modification.
• Imported configuration is accepted only for features compiled into the selected environment; unsupported or memory-rejected features remain inactive and are reported by the feature-status API.
• I2C devices can share SDA/SCL, but addresses must not conflict.
• GPIO6-GPIO11 are typically connected to Flash — do not use as peripheral pins.
• GPIO34-GPIO39 are input-only — suitable for ADC/digital input, not relay output.

Detailed pin assignment rules and hardware constraints are in the Peripheral Guide.

Recommended workflow: backup before every change, validate JSON before import, verify with dashboard, logs and feature pages after import.

7. Field Deployment Checklist

Before field deployment, verify each item:

Item	Confirm
Firmware environment	-Env matches chip, Flash, and PSRAM
Network config	WiFi SSID/password correct, or Ethernet/4G configured
MQTT connection	Server, port, ClientID, credentials filled; connection test returns connected
Peripherals enabled	Pins verified, enabled one-by-one, dashboard status confirmed
Rules validated	Rules disabled first → "Execute Once" to verify → enable after confirmation
Config backup	Exported peripherals.json and periph_exec.json backup
Smoke test	Ran smoke-test-device.ps1 confirming basic API pass

8. Troubleshooting

Symptom	Check
Web page loads but peripheral no action	Peripheral enabled? Correct pins? Relay effective level inverted?
Sensor reading empty	Collection rule enabled? periphId exists? Sample interval too short?
I2C sensor init fail	SDA/SCL swapped? Correct address? Pull-up resistors? 3.3V power?
ADC value abnormal	Exceeds 3.3V? Need voltage divider? ADC attenuation/calibration correct?
Threshold rule not triggering	Confirm collection rule generates ds:<id>_<field> data source first
MQTT test fails	Confirm network online first, then check server, port, ClientID, credentials, topic
Ethernet/4G menu unavailable	Confirm the selected environment compiled the feature, then check wiring and the runtime feature switch
Modbus unavailable	Check /api/features/status, UART/RS485 configuration, and the selected environment
fastbee.local unreachable	Confirm PC and device on same LAN; use router-assigned IP instead
No language switch	Check the compiled Web asset profile and the runtime feature status for the selected environment

For detailed error codes and field recovery procedures, see the Stability & Release Checklist.