These are the questions field teams and customers ask most often. Start from the matching entry instead of immediately editing the database, deleting files, or reinstalling the server.
I want to move the server. What should I back up?
Start with the Migration Backup section. At minimum, back up PostgreSQL, config, screens/assets, and data/screen-file-history. Windows defaults to D:\HQCONTROL or C:\HQCONTROL; Linux defaults to /opt/hqcontrol. New hardware must export a new license request from /license.
- Master data and history mainly live in PostgreSQL.
- Runtime screen assets live in
screens/assets.
- Host-level settings live in
config/hqcontrol.env and launcher settings.
- Screen publish history lives in
data/screen-file-history.
- Licensing on the new machine is handled through
/license.
Why does S7 symbolic addressing not use 102 + Rack/Slot?
S7 absolute addressing and S7 symbolic addressing use different paths. Absolute addressing uses S7 TCP, commonly port 102. Symbolic addressing uses OPC UA, commonly opc.tcp://PLC-IP:4840. Symbolic tags use symbolicAddress; DB number, byte offset, and bit offset are left empty.
- Absolute example:
DB222.DBX1.1.
- Symbolic example:
SINA_POS_DB.OverV or "MotorDB".Motor.Run.
- For symbolic mode, confirm the PLC OPC UA Server is enabled.
- Arrays, UDT, and complex structures should be split into scalar tags for V1 delivery.
The device is connected, but some tags are bad, stale, or unverified
A bad tag is not the same as a failed device. Device list status is based on connectivity, collection ability, and owner routing. Bad tags should be rechecked through Bad Check or Tag Diagnostics. unverified means an on-demand tag has not been collected yet; it is not good or bad.
- Recheck key tags with Tag Diagnostics.
- Check address mode, data type, symbolic address, or absolute address.
- On-demand tags are not kept in the base polling plan without screen, popup, trend, or diagnostic subscriptions.
- Before deleting bad tags, recheck the current
tag_latest state.
Realtime values are not refreshing
Check the chain in order: device connection, IO Worker, Redis, WebSocket, and page subscriptions. System Status exposes IO, Redis, WebSocket, IO State API, Integration Script, and module status. Reverse proxies must support WebSocket upgrade.
- Is the device online, and is this node the collection owner?
- Does IO Worker show plannedDevices, plannedBuckets, and activeHotTags?
- Is Redis healthy, and can values fall back to PostgreSQL?
- Does WebSocket show clients and subscription sources?
- Does the reverse proxy allow WebSocket upgrade?
Runtime screen is blank or menu entry does not open
Check Screen Files, menu configuration, and the public access address. Runtime assets should exist at screens/assets/<screen-code>/index.html; menu HTML entries come from the screen runtime directory scan. In reverse-proxy or federation deployments, the public access address must match the address users actually open.
- Screen Files shows the expected directory and entry HTML.
- Menu target points to an existing page.
- Browser console has no 404 or cross-origin asset errors.
/settings public host is not an old IP or temporary host name.
Which ports should be exposed on site?
After formal installation, the only user-facing endpoint is the HQControl web port, default 8080. The database, cache, and script execution are local internal services, locked to the machine by default and not for clients or the public network. IO State API also runs on 8080 with no separate port.
- Browser entry:
http://server-ip:8080.
- IO State API:
/api/v1/integration/io-state.
- WebSocket uses the same main endpoint.
- Do not expose database, Redis, or script-runner ports directly.
What can Integration Script do, and how are packages handled?
Integration Script runs server-side Python and provides ReadTag, ReadTags, and WriteTag for HQControl data. Production packages include common HTTP, database, MQTT, WebSocket, and crypto packages. Projects may also install third-party Python packages or configure local package folders.
- Use it for scheduled jobs, HTTP/MQTT integration, SQL work, and field automation.
- The runner runs only on the local machine; it is not a public API.
- Run scripts manually first and check recent execution records, timeouts, concurrency, and failure logs.
- Prefer standard configuration when it can express the behavior clearly.
How do I confirm an update package is active after overwrite upgrade?
Same-machine overwrite upgrades preserve configuration, data, logs, runtime directories, and runtime dependencies. After upgrade, check System Status, /settings, database migration records, the screen publish version, menu entries, key tags, alarms, trends, and script execution records.
- The database migration records show the target version.
- Screen Files shows the current publish version.
- Key screens can read tags, and writes remain permission-controlled.
- Alarm board, trend query, and event records work.
- Maintenance updates and later extensions follow the licensed delivery path.
