FAQ

Deployment and Startup

A microservice fails with an MQTT connection error

Check in order:

Is the EMQX container running: docker ps | grep unihh-emqx;
Is port 1883 reachable: telnet localhost 1883;
Do the application.yml files use the right MQTT credentials (unihh / unihh by default);
Does the EMQX Dashboard (http://localhost:18083) show client connections.

Is the service startup order strict?

The recommended order is gateway → admin → data → drivers. A driver started before admin still registers fine (admin re-syncs registrations when it comes up), but MySQL and EMQX must be ready first.

Services keep restarting after docker compose up?

The usual cause is MySQL still passing its health check: unihh-admin depends on the service_healthy condition, and on first start MySQL runs the full db/unihh_iot.sql import, which can take 1–2 minutes. Check in order:

docker compose ps — is unihh-mysql healthy yet?
docker compose logs unihh-mysql — did the import fail?
docker compose logs unihh-admin — DB connection errors resolve on their own once MySQL is ready (restart: always).

A host port is already taken (3306 / 1883 / 28000)?

Change the left (host) side of the mapping in docker-compose.yml — the container side must stay — e.g. "3306:3306" → "13306:3306", and update every connection string that references that port. If EMQX's 1883 bus port moves, adjust EMQX_SERVER_URI on all services and drivers.

How do I reset the Docker environment completely?

docker compose down -v   # stop and remove containers plus the mysql_data volume
docker compose up -d     # start again; MySQL re-runs the init script

down -v deletes all business data — back up first (see Deployment).

Will it run on minimal hardware?

Yes. Core services take -Xmx128m and drivers -Xmx64m (see Deployment). A 2 GB Raspberry Pi can host the minimal system: EMQX + three services + one driver.

Drivers and Acquisition

A driver shows offline — how do I debug it?

Run the channel heartbeat self-check on Driver Management; the RTT tells network issues from process issues;
Confirm the process is alive and its port is listening;
Check driver logs for MQTT errors;
The watchdog timeout is 15 seconds — brief network jitter recovers on its own.

A point keeps showing abnormal (Quality=0)?

Bad quality means the link works but the read fails. Likely causes, roughly in order:

Wrong physical register address (e.g. Modbus function-code area vs. address offset mismatch);
Data type does not match the register width (e.g. reading a DOUBLE space with INT);
Wrong byte order (see IndustrialEndianUtils in the driver SDK);
The device rejects the read (permissions, partially readable registers).

Values disagree with the field instrument?

A systematic offset is a range conversion issue: check the point's Scale and Offset — engineering value = raw × Scale + Offset. Wildly jumping values usually mean byte order.

How do I reduce RS485 bus load?

Increase the device base acquisition cycle;
Switch slowly-changing points to COV (report on change) instead of periodic sampling;
Bind only the points you actually need;
Write-back and polling are already serialized by the channel lock — no extra configuration needed.

Write-Back Control

A write-back command fails

Confirm the point's access mode is RW (read-only points cannot be written);
Check the params snapshot and failure reason in Log Audit;
Confirm the device is online and reading on the same channel;
Run the driver heartbeat self-check.

Can write-back collide with polling (interleaved frames)?

No. The driver applies a fair mutex per device channel (getChannelLock), so polling and writes queue up and execute serially — that is precisely the platform's design goal for half-duplex buses.

Data and Storage

Where do live values live?

In Redis as a live snapshot (read directly by the frontend) plus the time-series store on disk. The engine is chosen by the StorageEngineRouter strategy — see Deployment.

Can I skip TDengine?

Yes. Running db/unihh_iot.sql alone is enough; history falls back to the other configured engines or MySQL. Add TDengine when you need high-frequency time-series analytics.

Accounts and Security

What are the default credentials?

Entry	Account	Default password
Platform console	`admin`	`unihhiot`
EMQX Dashboard	`admin`	`public`
MQTT bus	`unihh`	`unihh`

Change all of them before production.

FAQ