Device Firmware and Gateways

This page distinguishes ESP32 device firmware from the industrial gateway. Both can connect to the cloud, but their hardware resources, configuration, and current capability boundaries differ. Use their dedicated guides for complete procedures.

1. ESP32 Device Firmware

1.1. When should I use ESP32 firmware versus an industrial gateway?

ESP32 firmware connects an individual sensor, switch, or controller directly to the cloud through WiFi or another supported link. An industrial gateway runs on x86, ARM, Raspberry Pi, or similar hardware and aggregates RS485, PLC, meter, and other field devices for upstream communication.

Both can use platform Thing Models and Topics, but platform troubleshooting cannot replace device-side serial, pin, and firmware logs. See ESP32 Device Documentation and the Industrial Gateway Overview.

1.2. How do I troubleshoot flashing failure, an occupied COM port, or an ESP32-C3 stuck in download mode?

Close serial monitors or other flashing clients using the port, and verify the data cable and USB enumeration. For an ESP32-C3 stuck in download mode, check reset timing as described in the troubleshooting guide and physically reconnect USB if necessary.

Do not terminate tasks you do not own or delete build locks to bypass port occupancy. See Device Firmware Troubleshooting.

1.3. Can ESP32-C6 serial silence or peripheral-initialization panic be caused by pin configuration?

Yes. Some C6 pins are used by the UART0 console, so incorrect assignment can hide serial logs. Pins outside the usable GPIO range or reserved for in-package Flash/PSRAM can also cause initialization panic.

Check chip-reserved pins and peripheral assignments rather than relying only on application logs. See Device Firmware Troubleshooting.

1.4. Why are pages broken, login blank, or resources abnormal after flashing?

A common cause is a mismatch between firmware and web filesystem resources, or use of historical assets from another build. Check firmware/web digests and API compatibility, then choose application-only or web-only update according to the release process.

Do not erase and flash everything by default or use an unverified historical data/www directory. See Device Firmware Troubleshooting.

1.5. Why is a device reachable only through its AP hotspot even though the WiFi credentials are correct?

The device may have fallen back to AP after STA failure, or it may have loaded different network configuration than expected. Read serial startup logs to distinguish configuration loading, NVS fallback, and STA failure, then verify SSID and authentication through an available management entry.

Do not erase the entire NVS partition merely because stale configuration is suspected. Back up identity and the original image before offline recovery. See Network Mode Switching and Troubleshooting.

1.6. Why does a .local name fail or resolve slowly, and why is 4G remote access unavailable?

Prefer direct IP access in the field. Windows mDNS depends on components such as Bonjour and can resolve slowly or intermittently. With multiple devices, also verify actual hostnames and conflicts.

mDNS is not a remote-access mechanism in 4G mode, and IoT SIMs normally use NAT addresses. Connect to the device AP and manage it through 192.168.4.1. See mDNS and Device Discovery.

1.7. Does "saved" in MQTT configuration mean the device is connected?

No. Saving only writes configuration. Confirm connected in device status or /api/mqtt/status, and verify actual message exchange with the platform.

If disconnected, check DNS, server/port, credentials, Client ID, TLS enablement, and system time. See Device Communication Protocols.

1.8. What are the current MQTT QoS and Modbus master/slave boundaries on the device?

The current PubSubClient publish path uses QoS 0. A publish qos=1 setting in the page does not guarantee QoS 1 delivery; subscription and last-will QoS must be evaluated separately.

Modbus slave responses are disabled by default, and the firmware currently provides master capability by default. Do not configure the device as a Modbus slave. See Device Communication Protocols.

1.9. How do I handle device OTA 501/503, interrupted upload, or API 401 after upgrade?

• 501: verify that the active partition layout actually has an OTA slot. The 4MB production layout does not provide dual application slots; do not change it arbitrarily to hide the error.
• 503: memory gating may be active. Close other pages/connections and retry after Retry-After.
• Interrupted upload: verify the final OTA state, device identity, firmware version/digest, and reset reason; recovery alone does not prove success.
• 401 after upgrade: restart clears in-memory sessions, so log in again.

See Device OTA and Troubleshooting.

1.10. How do I troubleshoot unresponsive peripherals, inactive rules, or API 503 caused by memory pressure?

For peripherals, check power, pins, type, and enablement. For rules, check trigger source, target peripheral, and action-type compatibility; use "run once" before enabling.

For memory-pressure 503, reduce concurrent requests and retry later. If persistent, inspect memory-heavy features, long-lived connections, and heap trends. See Device Quickstart and Troubleshooting.

2. Industrial Gateway

2.1. Can I develop and debug without real industrial equipment?

Yes. Use an x86 development machine, Stub drivers, a simulated backend, or a Modbus simulator to validate configuration and flows. Simulation supports development but does not replace acceptance with real serial links, electrical connections, device protocols, and long-running stability.

See Industrial Gateway Deployment and the Industrial Gateway Overview.

2.2. Why does gateway web access fail, static content go missing, or MQTT not take effect after saving?

For web access, verify the actual HTTP port, listening process, working directory, and static-resource paths; do not treat an unimplemented HTTPS port as the default. For MQTT, check Broker reachability, authentication/TLS, configuration decryption, and runtime logs.

Saving configuration does not mean every field triggers an automatic reconnect. Validate or restart in a controlled window according to the current operations guide. See Industrial Gateway Operations.

2.3. Why are there no collected values, writes fail, or a driver is automatically isolated?

First confirm the current development-preview baseline: the official operations guide states that the application does not yet register configured drivers with TagEngine, which is a global blocker for a real collection workflow. Correct configuration cannot bypass this blocker. If your version has not fixed it, do not treat Modbus configuration or simulated results as deliverable real-device collection.

After confirming that the blocker is fixed, check that drivers, devices, and Tags use runtime fields, Modbus addresses use zero-based registerAddr, and the active driver is real rather than a Stub result. For serial links, inspect RS485 A/B wiring, termination resistors, baud rate, slave addresses, and bus load. For isolated drivers, inspect health and consecutive error counts, fix the underlying communication problem, and observe automatic recovery. See Industrial Gateway Operations.

2.4. Why does a gateway alarm not trigger or flap around its threshold?

For missing alarms, check rule enablement, ongoing Tag updates, thresholds, and comparison conditions. For flapping, configure deadband as appropriate so small changes around the threshold do not repeatedly change alarm state.

See Industrial Gateway Operations.

2.5. Are offline store-and-forward, configuration reconnect, OTA, factory reset, and cloud control fully implemented?

Do not assume so. The current operations guide explicitly identifies incomplete areas: the active reporting path does not fully use SQLite offline caching for retransmission, some saved configuration does not automatically reconnect, and factory reset, OTA, and production reverse control have unfinished boundaries.

Validate the actual version instead of treating design goals as delivered capabilities. See Industrial Gateway Capability Boundaries.

2.6. What are the security boundaries for gateway debug APIs and production operations endpoints?

Debug reads/writes, system restart, and diagnostic endpoints can create real device load or system impact. Do not expose them to untrusted users or networks. Restrict tokens, network sources, and role permissions, and fix or isolate risky debug endpoints first.

High-risk calls are intentionally not reproduced in this FAQ. See Industrial Gateway Operations.