Welcome to the official guide for EnergyLink360 EMS — a web-based energy management platform for monitoring, metering, reporting, and administration across multi-site facilities.
About this manual
This manual is organized like an online book. Use the table of contents on the left to jump between chapters. The outline on the right (on wide screens) lists sections within the current chapter. Use the search box in the top menu to find topics across all chapters.
Tip
Bookmark a chapter by copying the page address with its section link, for example the Troubleshooting chapter (#troubleshoot).
What is EnergyLink360 EMS?
EnergyLink360 EMS (Energy Management System) collects real-time and historical data from connected meters and controllers, organizes it by site and group, and presents it through dashboards, trend charts, alarms, an interactive E-Map, and billing reports.
Administrators configure devices, models, users, and permissions. Operators monitor live data, review trends, respond to alarms, and generate reports for day-to-day energy management.
Who should read which chapter?
Audience
Recommended chapters
New users
Overview, System Concepts, Operator Guide
System administrators
All chapters, especially Administrator Guide and Troubleshooting
Understanding these core terms will help you navigate EMS menus, configure devices, and interpret reports consistently.
Core terminology
Term
Description
Site
A top-level facility or building entry under the Sites sidebar menu (e.g. Rojana, Demo). Used to organize folders and group items for navigation and reporting.
Site folder
A subfolder inside a site (e.g. Floor A, Folder B). Folders can contain other folders or group items.
Group item
A device collection under a site or folder (e.g. Group Energy, Monthly Report). Opens a live point/tag table where operators monitor selected registers from connected devices.
Configuration group
A separate concept under Configuration → Group-Template — reusable device layouts, not the same as a Sites group item.
Device / Loop
A physical meter, controller, or gateway connected via Modbus, BACnet, MBUS, or another supported protocol.
Point
An individual register on a device — voltage, current, power, energy, status, or alarm.
Model
A reusable template defining points, scaling, and units for a device type. Applied when adding new devices.
Permission Group
View / Add / Edit / Remove rights per menu item, assigned to user accounts.
How data flows through the system
Field devices are polled over their communication protocol. Readings are stored in the EMS database. The web interface reads that data to render dashboards, trends, alarms, the E-Map, and billing reports.
Configuration changes — adding devices, models, group templates, or users — are made through the Configuration and Administration menus and take effect immediately for users with the appropriate permissions.
Devices communicate with EMS polling services (Modbus, BACnet, etc.).
Services write readings and status into the database.
The web UI reads from the database for live views, history, and exports.
Administrators change configuration through EMS pages; operators consume the results.
Supported device and protocol types
Protocol / type
Typical use
Digital Meter
Native EMS digital metering devices
BACnet
Building automation controllers and meters
Modbus TCP / RTU
Industrial meters and gateways
MQTT Device
Devices that publish/subscribe over MQTT (e.g. Tasmota, ESP-based sensors, gateways) — read by topic + JSON path, write by command topic/payload template. See the MQTT Device chapter.
A device built from a Model whose Properties are mapped one-to-one to BACnet points of one or more controllers (loop protocol 10). Values, history, alarms and commands follow the mapped BACnet source; clearing a mapping or deleting the source never deletes history. Mappings can also be managed by the AI assistant — see the MCP chapter.
Custom
Site-specific or custom integrations
Modules
EMS integrates the modules below. Each entry shows where to find it in the sidebar menu.
Browse protocol loops and individual meters; view live point values for all supported protocols.
Virtual Meter
Devices → Virtual Meter
Derived meters that combine values from physical source meters. Drag meters from the tree onto a Virtual Meter to add sources. See Operator Guide → Virtual Meter.
Mod Scan 360
Devices → [loop] → right-click → Mod Scan 360
Modbus register debugger for Digital Meter, Modbus RTU, and Modbus TCP loops. Pauses one loop, reads/writes registers, and shows TX/RX frames. See Operator Guide → Mod Scan 360.
Organize devices into groups; save layouts as reusable templates.
Models
Configuration → Models
Define reusable point templates (registers, scaling, units) for device types. Click a model name to open the Model Editor.
Model Library
Configuration → Models → Library
Central repository for sharing device models across EMS sites. Publish, download, rate, and version-control point templates. See the Model Library chapter.
E-Map
E-Map
Visual floor-plan / site map for device location and status.
Logic Studio
Logic Studio
Visual node editor for building automation logic — timers, math, conditional logic, alarms, and point read/write. See the Logic Studio chapter.
Trend & History
Trend & History
Historical trend charts (General), real-time Demand Chart, and bulk backfill from Excel. See Operator Guide → Import History.
Alarms & Events
Alarms
Offline devices, pending alarms, and event history.
Schedule
Schedule
Weekly time schedules for automatic Start/Stop commands on writable Modbus points, plus site-wide and per-template holiday handling. See Operator Guide → Time Schedule and Holidays.
Billing
Billing
Fixed Rate, TOD, TOU, and site-specific energy bill formats.
Reports
Reports
Solar Energy Comparison, CPM Monthly Operation Log Sheet, IAQ (air quality) history export, and related exports. See Operator Guide → IAQ Report.
Personal font, date/time, regional, and interface settings.
Plug-ins
Plug-ins
Node-RED, Line, email alerts, and site-specific integrations.
MCP
Plug-Ins → MCP
Connect an AI assistant (Claude, Cursor) to EMS: tokens, Edit Mode, Change Set approval and audit. See the MCP / AI Assistant chapter.
Billing formats
Depending on your site license and configuration, billing may include Normal (Fixed Rate), Time of Day (TOD), Time of Use (TOU), or custom formats such as Hotel, Plaza, MS Siam Tower, SAP, SathonPrime, and Boonthavorn.
Administrator Guide
Step-by-step procedures for configuring and maintaining the EMS platform.
Installer & configure
Server-side steps for system administrators after a new EMS deployment, upgrade, or migration. Run these commands on the Linux host where the EMS web application is installed (paths below assume the default document root /var/www/html/ems81).
The PHP web server user (typically www-data on Ubuntu/Debian) must be able to write to several runtime folders. If a folder is missing or not writable, features such as database backup, model import, exports, meter-history cache, or E-Map V2 marker uploads will fail silently or show a permission error.
Writable folders
Directory
Purpose
backup/
MySQL dumps from Administration → Database → Backup
uploads/
Temporary uploads — model/BACnet CSV import, user profile images, and similar import workflows
temp/
Temporary SQLite files used while calculating kWh consumption bars
log/
PHP error logs written by EMS scripts
excel/, pdf/
Generated report/export downloads (auto-cleaned after about one hour)
File cache for kWh consumption, pie/rank charts, and billing kWh APIs
map_editor/data/
E-Map V2 local SQLite store (marker positions and icon metadata)
map_editor/images/markers/
E-Map V2 custom marker icon uploads
/opt/meter/data/Waveform/ (Linux)
COMTRADE files, meter FTP configs, and Waveform API logs (must be writable by www-data)
E-Map V2 map canvas data itself is stored in the MySQL tables emap_map / emap_page (created by Administration → Database → Update). The folders above are still required on the server for marker binding storage and icon uploads.
Create folders and set permissions
Create all runtime folders once after install or upgrade, then assign ownership to the web server user and mode 775:
If your EMS files live in a different path, replace /var/www/html/ems81 with your actual web root. If PHP runs as a user other than www-data, substitute that account name in the chown command.
Verify permissions
Confirm folders exist: ls -la /var/www/html/ems81/backup /var/www/html/ems81/uploads /var/www/html/ems81/cache /var/www/html/ems81/map_editor/data
Run Administration → Database → Backup — a new .sql file should appear under backup/.
Import a model CSV or upload a profile image — a short-lived file should appear under uploads/.
Open E-Map V2, upload a custom marker icon — a file should appear under map_editor/images/markers/ and map_editor/data/ems_floor.db should be writable.
Open a meter history or kWh chart — new .json cache files should appear under cache/dm_log/ or cache/meter_kwh/. Optional: check DevTools response headers X-Dm-Log-Cache or X-Meter-Kwh-Cache (MISS first load, HIT on repeat).
Meter history API cache (TTL)
Data range
Cache TTL
Historical (end date before today)
30 days
Includes today (live data)
5 minutes
Expired cache files are removed automatically when the same API is requested again. To force a fresh read during troubleshooting, append ?nocache=1 to the API URL.
Note
Runtime folders such as backup/, uploads/, temp/, log/, and cache/ are listed in .gitignore and are not deployed from Git — they must exist on each server with correct permissions. Deleting cache files is safe; EMS rebuilds them on the next request.
REST API for 3rd-party integration
EMS exposes a REST API for reading live values, trend history, device offline status, and pending alarms, plus (with a write-enabled key) creating, editing, and removing loops and devices. All endpoints are protected by a shared secret (sdk_key), managed under Settings → API (Admin only) where read/write access can each be enabled independently and the key can be rotated.
Tip
See the full API Reference chapter for endpoint URLs, parameters, and example requests/responses.
Managing users and permission groups
Open Administration → Users → Manage.
Create, edit, or disable user accounts and assign each user to a permission group.
Open Administration → Users → Permission.
For each menu item, set View, Add, Edit, and Remove rights per group.
Save changes. Users may need to refresh or re-login to see updated menu access.
Note
New menu modules are hidden from all existing groups by default. Enable View (and Add/Edit/Remove as needed) before users in that group can see or use the module.
Adding devices and models
Define a model under Configuration → Models — register addresses, data types, scaling, and units. Alternatively, download a ready-made model from the Model Library.
Add device instances under Devices → [protocol].
Assign the model and enter connection details (IP address, unit ID, port, etc.).
Verify live data appears in Site Explorer.
Optionally save a group layout as a template under Configuration → Group-Template for reuse at similar sites.
For step-by-step instructions on defining MODBUS points inside a model, see Model Editor — MODBUS Registers below. To probe registers on a live loop before editing a model, use Mod Scan 360 in the Operator Guide.
Model Editor — MODBUS Registers
The Model Editor is where you define every MODBUS point in a device model — register address, data type, scaling, units, and display options. Devices that use this model inherit these point definitions when polling the field.
Opening the Model Editor
Open Configuration → Models from the sidebar.
In the model list, click the model name link (document icon) for the model you want to edit.
The page opens with the model name in the header and the subtitle MODBUS registers.
You can bookmark the page in your browser (users still need login and permission to open it).
Page layout
Area
Description
Header bar
Back button, model name, and Action dropdown (Import, Export, Open Link).
Add form (top panel)
Form for creating new points only. Click Add to save, or Clear to reset all fields to defaults. Editing existing points uses a separate popup (see below).
Point list table (bottom)
Points in the model (10 per page). Columns include Point ID, View, Point Name, Description, Unit, Register Type, Data Type, Register, Bit, Category, Scale, Byte Order, and row actions: Edit, Copy, Remove.
Pagination
Previous / Next buttons below the table. The list shows 10 points per page.
Add vs Edit vs Copy
Add uses the form at the top of the page. Edit opens the Edit Point popup (pencil icon). Copy (copy icon) duplicates a row — either into another model immediately, or into the Add form via Paste to Add form so you can review before clicking Add.
Permissions
Access is controlled under Administration → Users → Permission for the Models menu item:
Right
What you can do on Model Editor
View
Open the page and read the point list. Without Add/Edit, form fields and action buttons are hidden or read-only.
Add
Use Add and Clear on the add form, Upload Image, Import, Export in the Action menu, and the Copy icon on table rows.
Edit
Click the pencil (Edit) icon to open the Edit Point popup and change an existing point.
Remove
Click the trash (Remove) icon to delete a point from the model.
Adding a new point
Fill in the add form at the top of the page (see Field reference below).
Select an unused Point ID from the dropdown (IDs already in use are not listed).
Enter a Point Name (required). Optionally fill Description, Unit, and register settings.
Click Add.
On success, the new row appears in the table and the Point ID dropdown refreshes. The Register field auto-advances to the next address based on the selected Data Type (e.g. Float32 skips 2 registers).
To discard entries and start over, click Clear next to Add. This resets text fields, checkboxes, and dropdowns to default values (including your last saved choices for Register Type, Data Type, Category, and related options) and reloads the next free Point ID.
Tip
Hover the help icons (? circle) next to fields such as Bit, Scale factor, CT Scale, Byte Order, Invert Bit, Formula, and Multi State Text for short explanations.
Editing an existing point
In the point list table, click the Edit (pencil) icon on the row you want to change.
The Edit Point popup opens with all fields loaded for that point, including the same help icons as the add form.
Change values as needed. The Point ID dropdown lists available IDs (the current point remains selectable).
Click Save Change to apply, or Cancel / the X button / Esc / click outside the popup to close without saving.
On success, the table row updates in place and the popup closes.
Copying a point
Each table row has a Copy icon (between Edit and Remove). Click it to open the Copy Point popup. Requires Add permission.
Action in Copy Point popup
Description
Paste to Add form
Loads the source point’s register settings into the Add form on the current page. Point ID is set to the next free ID automatically; the name becomes original name copy. The page scrolls to the add form so you can adjust values and click Add. Use this to duplicate a point in the same model with small changes.
Copy to model
Creates a new point immediately in the selected Target Model. New Point ID is auto-selected (next free ID 1–255); you can change it and edit the new name before confirming. If the target is the current model, the table refreshes after success.
Click the Copy icon on a row.
Review the source Point ID and name shown at the top of the popup.
Either click Paste to Add form (review in add form, then Add), or choose a Target Model, confirm New Point ID and New Point Name, then click Copy to model.
Tip
To clone many similar registers in one model, use Paste to Add form repeatedly: copy a row, paste, tweak Register or name, Add, then repeat.
Removing a point
Click the Remove (trash) icon on the row.
Confirm the deletion when prompted.
The row is removed and the Point ID becomes available again in the add form dropdown.
Warning
Removing a point from a model may affect devices already using that model and any formulas referencing pid.<n>. Review dependent devices and virtual points before deleting.
Browsing the point list
Use Previous and Next to move through pages of 12 points.
After adding or editing a point, the table scrolls to the page containing that Point ID when possible.
The View column shows a checked icon when the point is visible in device views, or a hidden-eye icon when View is disabled.
Action menu (header)
Click Action in the top-right corner of the page:
Menu item
Description
Import
Import point definitions from a CSV file into this model (replaces or merges points depending on file content). Requires Add permission.
Export
Download the current model points as a CSV file. You can edit the file name in the confirmation dialog. Requires Add permission.
Open Link
Opens the current Model Editor URL in a new browser tab — useful for side-by-side comparison or sharing with a colleague.
Importing points from CSV
Click Action → Import. The Import Model popup opens.
Confirm the model ID and name (read-only).
Choose File Version:
Energy Link 360 (.csv) — current EMS export format (recommended).
E-Data (old) (.csv) — legacy format for older exports.
Use File Selected → Upload to choose your CSV. Wait until the file name appears (not ---).
Click Import. A loading message appears while the file is processed; the point table reloads when import completes.
A success message asks whether to reset the system so polling services pick up the new model immediately. Choose Yes, reset now on production changes, or No, just close if you will reset later from Administration.
Exporting a model to CSV
Click Action → Export.
A brief Exporting model… message appears while data is prepared.
Enter the file name when prompted (defaults to the model name).
Confirm to download a .csv file containing all points in the model.
Use this file for backup, editing in a spreadsheet, or importing into another model.
Uploading a model image
In the add form panel, click Upload Image below the model picture (left side).
Select an image file. The preview updates after upload.
The image is stored with the model and shown on the Models list and Model Editor header area.
Field reference
Field
Description
View
When checked, the point appears in device / site views. Uncheck to hide from operators while keeping the register mapped.
Category
Groups the point for menus and reports (e.g. Voltage, Current, Energy). Changing category may show or hide CT-related fields.
CT Scale Multiply
Enable when the meter requires CT ratio scaling for current, kW, and kWh. Shows CT Primary and CT Secondary fields.
Point ID
Unique number (1–255) for this point in the model. Referenced in formulas as pid.<id>.
Write enable
Allows write commands to this register when supported by the device and protocol.
Point Name
Display name (required). Shown in Site Explorer, trends, and reports.
Description
Optional longer description for documentation.
Unit
Engineering unit shown with values (e.g. V, A, kW, kWh, m², m³, µg/m³). Plain text field — see the tip below for entering superscript characters.
Register Type
MODBUS table: Coil, Discrete Input, Holding Registers, or Input Registers.
Data Type
How raw register words are interpreted — Bit, Int16, UInt16, Int32, Float32, Float64, etc.
Register
Starting MODBUS register address (1-based in this editor).
Bit (Begin..End)
For bit extraction within a word, e.g. 0..15 for the full 16-bit range.
Scale factor
Multiplier applied to the raw value (default 1.0).
Offset
Value added after scaling.
Byte Order
Little endian or Big endian for multi-byte types.
State text (true) / (false)
Display labels for boolean / coil points (e.g. ON / OFF).
CT Primary / CT Secondary
Current transformer ratio (e.g. 50 / 5) when CT Scale Multiply is enabled.
Invert Bit
Swaps 0 and 1 for boolean values.
Formula Expression
Optional calculated value. Use =x + 15 or reference other points: =x + pid.1 + (pid.2 + pid.3) where x is the current raw value.
Multi State Text
Maps integer states to labels, e.g. {0:OFF, 1:ON, 2:ERROR, 3:UNKNOWN}.
Tip — superscript units (m², m³, µg/m³)
The Unit box is a plain text field: it cannot make part of the text superscript the way a word processor does. To show a raised exponent like ³, type the actual superscript Unicode character instead of a regular digit — for example type m² or µg/m³ directly, not m2/µg/m(U+0033) or similar notation.
Copy a ready-made character from here and paste it into the field: ² (superscript 2), ³ (superscript 3), ° (degree), µ (micro).
Windows: hold Alt and type 0178 (²) or 0179 (³) on the numeric keypad.
Linux (GTK apps): press Ctrl+Shift+U, type b2 (²) or b3 (³), then press Enter or Space.
Once entered correctly, the unit displays as typed in Site Explorer / Run Time values, Excel export, and PDF report export.
Remembered defaults and Clear
When you add points in one session, EMS remembers your last choices for Register Type, Data Type, Byte Order, Category, CT Scale, and Invert Bit in this browser. The next point you add starts with those defaults — useful when entering a block of similar registers.
Click Clear on the add form to restore those defaults and empty text fields without reloading the page.
Typical workflow — new meter model
Create the model shell under Configuration → Models (name and description).
Open the model in the Model Editor.
Optionally upload a device photo.
Add points one by one, use Copy → Paste to Add form to duplicate similar registers, or Import from a manufacturer CSV / a previous EMS export.
Verify Register addresses and Data Types match the meter manual.
Export a backup CSV when finished.
Assign the model when adding Modbus devices under Devices.
Confirm live values in Site Explorer match expected units and scaling.
Typical workflow — copy points to another model
Open the source model in the Model Editor.
Click Copy on the row to duplicate.
Choose the destination under Target Model, confirm auto Point ID and name, then click Copy to model.
Open the target model and verify the new row. Reset the system if devices must reload the model immediately.
Model Editor — MQTT Device
MQTT points are configured on the point's MQTT tab next to Modbus Register: Subscribe Topic, JSON Path and Value Type for reading; Command Topic, Command Payload, Write Mode (State / Range), State Options, Min/Max/Step and Readback Topic/Path for writing. Topics use {device_key} and Topic Variables so one Model serves many devices. The full guide — broker loop, device setup, a Tasmota example, commands and troubleshooting — is in the MQTT Device chapter.
Database maintenance
Before any update on production, run Administration → Database → Backup.
Run Administration → Database → Update to apply database changes for new versions or modules.
Use Restore only when you need to recover from a known-good backup.
Warning
Always take a backup before running Database Update on a production system. Restore overwrites current data.
System administration
Administration → System provides Hardware Info (server diagnostics), Software License / License Terms, and Services (background polling status). If devices stop updating, check Services first.
On the Services page you can restart the main EMS polling service and, when Waveform is installed, start / stop / restart the separate Waveform API process (port 8095). See Waveform (administrator) below.
COMTRADE Waveform (administrator)
Waveform pulls event oscillograms (COMTRADE .cfg / .dat) from PowerLogic PM8000-class meters over FTP, stores them on the EMS server, and shows voltage/current traces in the browser. It runs as a separate Python service from the main EMS poller — not inside ems_main.
Enable the feature
Open Administration → Settings → Waveform.
Turn on Enable COMTRADE Waveform and save. The feature is off by default.
Only Modbus TCP meters whose model is listed as Waveform-capable (shown on that Settings tab) will show FTP fields and the meter Waveform icon.
Install / start the Waveform API (Linux)
On the EMS host, install the systemd unit once (code lives under /opt/meter/ems/waveform/):
That script installs ems-waveform-api.service, enables it at boot, and adds a sudoers rule so the Services page can Start / Stop / Restart the API as www-data.
After install, open Administration → System → Services and confirm the Waveform API panel shows Online. Use Start / Stop / Restart there for day-to-day control (requires Edit on the Services menu).
Note
Data and meter FTP configs are stored under /opt/meter/data/Waveform/ (not inside the code folder). Event files are arranged like EMS history: {meter_id}/COMTRADE_n/MM-YYYY/DD/. Display timezone follows Preferences (exported for the API when timezone settings change).
Per-device FTP configuration
Open the meter under Devices → Modbus TCP (or the matching TCP loop).
Edit the device and open the Waveform tab.
Enable Waveform FTP, set host (often the same as the loop IP), user, password, and remote folders (default COMTRADE_1 … COMTRADE_3).
Save. EMS writes /opt/meter/data/Waveform/configs/meter_{id}.json for the API.
Operator workflow (summary)
Operators open the Waveform viewer from the meter header, click Sync from meter to download new captures, then select an event to plot. Full UI steps are in the Operator Guide → COMTRADE Waveform.
Software License
Administration → System → Software License manages the license key(s) that authorize this installation and shows how many field devices are currently in use against how many are licensed.
Adding and activating a license
Open Administration → System → Software License.
Click the + button in the header and enter the license key you were given, then Add. The key appears in the table with status Inactive.
Click Activate on that row. The Activate dialog shows this machine's HW ID (hardware id) and license key.
Click Get Online Token Key to request an activation token automatically (requires internet access to the license server), or paste a token you were given manually (offline activation).
Click Activate. On success you are prompted to restart the EMS service so it picks up the new license immediately.
Note
A license token is bound to this machine's HW ID. Activating on one machine and copying the token to another fails with an HWID mismatch error — request a new token for the other machine's HW ID instead.
Reading the license status
Where
What it shows
License page banner
Whether any license is currently active, and (if active) devices used vs. licensed.
Bell (notification) menu — top navbar
Bell turns red and the License row shows Inactive, Over limit, or a live "Stops in Xh Ym" countdown.
Sidebar banner (bottom of the tree)
Appears only while the background service is actually counting down its grace period (see below), with a Fix now link to this page.
Grace period and device limit
If the background EMS service does not find a valid, matching license for this machine at startup (no license activated, wrong HW ID, or the license has expired), it does not stop immediately — Modbus, BACnet, and meter polling keep running normally for a grace period (a few hours) so live monitoring is not interrupted. A countdown to when the service will stop is shown in the places listed above. Restarting the service (after activating a valid license) grants a fresh grace period and clears the countdown.
Separately, once a license is active, adding new field devices is blocked once the number of enabled devices reaches the licensed quota. Remove or disable unused devices, or activate a license with a higher device count, to add more.
Tip
An install that has never activated any license is not subject to the device-limit block — the block only applies once a license has actually been activated on this machine.
Audit Log
Administration → Audit Log records significant account and configuration activity: logins (success and failed attempts) and logouts, user and permission changes, password changes, device commands and service restarts, data create/update/delete actions, and report exports. It also records automatic writes sent by the Time Schedule runtime (category Command), so you can see which point a template drove, to what value, and why (weekly block, exception day, or gap/fallback) — separate from commands a user sends manually.
Open Administration → Audit Log.
Use the filters (date range, user, category, action, status, free text) and click Filter to narrow the list, or Clear to reset.
Click View in the Details column to see the full details for an entry in a popup.
Use the export buttons in the page header to export the filtered results to PDF or Excel.
Note
The Audit Log is view-only and available to Administrators by default.
Audit log retention
Audit log entries are kept for a configurable number of days, then removed automatically by a scheduled background job.
Open Administration → General.
Set Keep Audit Log (Days) to the number of days to retain entries (default 90).
Click Save.
Enabling a new menu module
Confirm the module appears in the sidebar for an administrator account.
Open Administration → Users → Permission.
Select each affected permission group.
Enable View for the new menu item; enable Add, Edit, Remove as required.
Ask affected users to refresh the browser or log in again.
Model Library
Model Library Central is a shared repository for device models. Teams can publish, download, rate, and version-control MODBUS point templates across multiple EMS sites from a single library.
Overview
Instead of recreating point definitions on every EMS installation, engineers publish a model once to the central library. Other sites can then download it — with the correct registers, data types, scaling, and units — in seconds. The library also keeps a full revision history so you can roll back to any previous version.
Feature
Description
Publish / Update
Push a local model (with points and image) from EMS to the central library.
Download / Import
Pull a model from the library into the local EMS — as a new model or to update an existing one.
Revision history
Every publish or point-change snapshot creates a version. Older versions can be downloaded or rolled back.
Star rating
Each site can rate a model 1–5 stars. Ratings appear in the model list to help engineers pick proven templates.
CSV import
Upload point definitions from a legacy EMS CSV export directly into the library — data-type codes and byte-order are converted automatically.
Documents & Notes
Attach datasheets, manuals, or Modbus maps to a model. Add comments for team discussion.
How Model Library Central works
Model Library Central is a separate site that stores shared device models. Each EMS installation connects using an access key configured by your administrator.
Component
Description
Library Central website
Browse, upload, rate, and manage models in a web dashboard.
EMS integration
Publish, Pull, and Import from Library on Configuration → Models.
Initial setup
Your administrator installs Model Library Central on the library server and completes the first-time setup wizard.
Copy the admin access key shown during setup — it is displayed only once.
On this EMS site, ask your administrator or EMS support to register the library connection URL and access key.
Log in to Library Central with the administrator account created during setup (change the default password on first login).
Note
Each EMS site that connects to the library should use its own access key. Additional keys are created under API Keys in Library Central (admin only).
Publishing a model to the library
Publishing sends a local model (with all points and image) from EMS to the central library. If the model was published before, it updates the existing library entry and bumps the version.
Open Configuration → Models.
In the model list, click the three-dot menu (⋮) on the row of the model you want to publish.
Select Publish to Library.
Enter a device name (project/site name for identification in the library) and click Publish.
On success, the toast shows "Published v1" (first time) or "Updated to v3" (subsequent publishes).
Tip
After the first publish, the model stays linked to the same library entry. Subsequent publishes update that entry. The previous version is saved as a revision automatically.
Downloading a model from the library
You can download a model from the library to create a new local model — either from the Add Model dialog or the Model Library browser.
From Add Model dialog
Open Configuration → Models and click the + button.
Switch to the From Library tab.
Search or browse the model list. Star ratings are shown next to each model if rated.
Click a model to open the detail view.
The detail view shows:
Model info — name, description, brand, category, point count.
Rating — average stars and your own rating (click stars to rate).
Version selector — radio buttons for each version. The latest version is pre-selected with a Latest + Recommended badge.
Select a version and click Download.
The model is imported as a new local model with all points and image.
From Model Library browser
In the model list header, click the three-dot menu (⋮) → Model Library.
The library opens as a large dialog with search. Click any model for the same detail/version/rating view.
Select version and click Download.
Pulling updates from the library
If a model was previously published (linked to the library), you can pull the latest version to replace local points.
Open Configuration → Models.
Click the three-dot menu (⋮) on the linked model → Pull from Library.
Confirm the pull. A snapshot of the current local points is saved before overwriting.
On success, the toast shows the new version and point count.
Note
Pull replaces all local points with the library version. If there are no changes since the last pull or publish, the pull is skipped with a message.
Rolling back to a snapshot
Every pull creates a local snapshot. You can roll back to any previous snapshot if a pull introduced unwanted changes.
Click the three-dot menu (⋮) → Rollback on the model row.
A list of up to 10 recent snapshots appears (with date, action, and source version).
Select a snapshot and click Restore. The current points are saved as a before_rollback snapshot first.
Star rating
When browsing models in the From Library tab or the Model Library browser, each model shows its average star rating and rating count. Ratings help engineers identify proven, widely-used templates.
Open a model's detail view (click the model row).
In the Your rating area, hover over the stars and click to rate 1–5.
The rating is saved immediately and the average updates.
Each EMS site (API key) can rate a model once. Re-rating updates the previous vote.
Revision history and Save Revision
The library tracks model versions. A new revision is created when:
A model is published or updated from EMS (automatic).
An administrator clicks Save Revision in the Library Central UI after editing points.
Saving a revision in Library Central
Open a model in Library Central.
Edit, add, or delete points as needed. A dark bar appears at the top: "Points have been modified — N changes".
Click Save Revision.
Enter an optional change note (e.g. "Added Voltage L3, fixed Energy register") and confirm.
The current points are snapshotted, the version bumps (e.g. v2 → v3), and the bar clears.
Tip
You can make multiple point changes and then save one revision. The revision captures the state at the moment you click Save Revision, not each individual edit.
Downloading a specific revision
When downloading from the library (Add Model → From Library), the version selector shows all available revisions. Select an older version to download its point snapshot instead of the latest.
Uploading models (JSON and CSV)
Library Central accepts model files in JSON (exported from EMS or the library) and CSV (legacy EMS export format).
JSON upload
Drop or browse a .json file exported from EMS or the library. The preview shows model name, points, and image. Fill in the From Project field and click Publish to Library.
CSV upload (legacy EMS format)
For models exported from older EMS versions as CSV, the upload page converts them automatically:
Drop or browse a .csv file. The file badge shows CSV.
The parser detects headers automatically and converts old data-type codes (16→UInt16, 64→Float32, etc.).
A preview table shows the parsed points with converted data types.
Enter a Model Name (CSV files do not contain a name), From Project, and optional overrides.
Click Publish to Library.
Data type conversion
The CSV parser maps old EMS codes to standard codes: 16→UInt16, 24→Int16, 32→UInt32, 36→Int32, 64→Float32. Swap variants (e.g. Float32(Swap), code 128) set byte order to Little Endian automatically. The @ separator in formula and multi-state fields is converted back to commas.
Documents and notes
In the Library Central UI, each model has a Documents tab and inline Notes (comments).
Documents
Open a model detail page and switch to the Documents tab.
Click Add Document, select a type (Manual, Modbus, Catalog, Datasheet, Other), and upload a file (PDF, DOC, XLS, CSV, TXT, PNG, JPG, ZIP — max 20 MB).
Documents are shown with a type badge and download link in both the model list and detail page.
Notes
In the model list, click the comment icon next to a model name to expand the notes panel. Type a comment and press Enter or click the send button. Notes are visible to all library users.
API key management
Each EMS site needs an API key to connect. Keys are managed in the Library Central UI under API Keys (admin only).
All read actions plus publish, update, delete, rate, add points/notes/docs.
admin
Full access including user and key management.
Library Central UI pages
Page
Description
Models
Browse all models with search, category/brand filter, ratings, document icons, and notes. Duplicate, export, or delete models.
Upload
Upload JSON or CSV files to create new models in the library.
Model Detail
View/edit model info, points (add, edit, delete), documents, revision history. Save Revision button after changes.
Users
Manage library UI users (admin only). Separate from EMS user accounts.
API Keys
Create/revoke API keys for EMS sites (admin only).
Activity
Audit log of all library actions — publish, update, delete, duplicate, etc.
Troubleshooting
"Model Library not configured"
The library connection URL or access key is not set on this EMS site. Ask your administrator to complete Model Library setup, then refresh the page.
"Cannot connect to Library"
Confirm Library Central is running and reachable from the EMS server (same network or VPN).
Ask your administrator to verify the library site was installed and updated successfully.
Check that the connection URL in EMS settings matches the address you use in a browser.
"Invalid API key" (403)
The access key in EMS does not match a key registered in Library Central. Create a new key in Library Central or re-enter the correct key in EMS settings.
"This API key does not have write permission"
The key is read-only. An administrator must grant write or admin permission on the API Keys page in Library Central.
Model name already exists when importing
A local model with the same name exists. Rename the local model first, or use Pull instead of Import if it is the same model.
"Already up to date" when pulling
The local points are identical to the library version. No changes were made since the last pull or publish.
E-Map Editor
The E-Map Editor is a full-featured vector drawing tool for creating interactive floor plans, single-line diagrams, and SCADA-style dashboards. Maps can display live data from connected meters through data binding.
Opening the editor
Navigate to E-Map in the sidebar, then double-click a map name or click Edit on a map entry.
You can also open a map in view-only mode from the map list when available. In view mode, press E to switch to editing.
Workspace layout
The editor workspace is divided into several areas:
The drawing area — scroll to pan, mouse wheel to zoom
Properties panel
Right sidebar
Position, size, rotation, corner radius, opacity, and data binding for the selected object
Layer selector
Toolbar, beside drawing tools
Choose which layer to draw on. Click the layer icon to open the layer manager
Status bar
Bottom
Mouse coordinates (x, y) and save status
Menus
File menu
Item
Description
Save to Database
Saves the current map to the server database
Load from Database
Reloads the last saved version, discarding local changes
Open JSON file
Opens a local .json file exported previously
Import JSON (merge)
Merges objects from a JSON file into the current map
Export as JSON
Downloads the map as a .json file for backup or transfer
Page Properties
Set canvas width/height (100 – 10,000 px), background color, and linked template
Preferences
Default text font/size/color, default shape fill/stroke, grid size, and snap settings
Open in new tab
Opens the runtime (preview) view in a new browser tab
Edit menu
Item
Shortcut
Undo
Ctrl+Z
Redo
Ctrl+Y or Ctrl+Shift+Z
Cut
Ctrl+X
Copy
Ctrl+C
Paste
Ctrl+V
Delete
Delete or Backspace
Undo/Redo supports up to 10 levels of history.
View menu
Item
Description
Zoom In / Out
Scale the canvas view
Fit to Screen
Auto-zoom to show the entire canvas
Reset View
Center canvas at 100% zoom
Properties Panel
Toggle the right-side properties panel
Pan Mode
Toggle hand/pan tool for scrolling the canvas
Show Grid
Toggle the background grid overlay
Snap to Grid
Toggle snapping objects to grid intersections
Show Template
Toggle display of the linked template layer behind the map
Widget Library
Open the pre-built widget panel (icons, electrical symbols, gauges, etc.)
Preview / Play
Enter preview mode to see live data and test interactions
3D View
Open the 3D floor view (if configured)
Layers menu
Click Add Layer to open the layer manager. Layers allow you to organize objects by function (e.g. background, equipment, labels). Each layer has:
Name — editable label
Visibility — show/hide all objects on the layer
Opacity — adjust transparency (0 – 100%)
Reorder — drag to change the stacking order
Delete — remove a layer (objects move to the default layer)
The active drawing layer is selected from the toolbar dropdown beside the drawing tools.
Object menu
Item
Shortcut
Description
Group
Ctrl+G
Combine selected objects into one group
Ungroup
Ctrl+U or Ctrl+Shift+G
Break a group back into individual objects
Lock
—
Prevent an object from being moved or edited
Unlock
—
Re-enable editing for a locked object
Rotate 90°
—
Rotate the selected object 90 degrees clockwise
Flip Horizontal
—
Mirror the object left-to-right
Flip Vertical
—
Mirror the object top-to-bottom
Alignment (requires 2+ selected objects)
Action
Description
Align Left / Center / Right
Align selected objects horizontally
Align Top / Middle / Bottom
Align selected objects vertically
Distribute Horizontal
Space objects evenly side-by-side (requires 3+)
Distribute Vertical
Space objects evenly top-to-bottom (requires 3+)
Drawing tools
Select a drawing tool from the toolbar, then click and drag on the canvas to create a shape. Press Escape to cancel and return to the Pointer tool.
Tool
Icon
How to use
Pointer
Click to select objects. Click empty area to deselect. Drag to marquee-select multiple objects. Hold Shift to add/remove from selection
Rectangle
Click and drag to draw a rectangle. Hold Shift to constrain to a square
Circle
Click and drag to draw an ellipse. Hold Shift to constrain to a perfect circle
Arc
Click and drag to draw an arc shape
Line
Click and drag to draw a line. Hold Shift to constrain to 0°/45°/90° angles. Lines support arrow endpoints (set via context menu or properties)
Polygon
Click to place vertices. Double-click or press Enter to finish. Press Escape to cancel. Creates a closed polygon shape
Image
Opens a file dialog to select an image (PNG, JPG, SVG). The image is placed on the canvas at the cursor position
Insert Animation
Opens the animation import dialog to build a multi-frame animated sprite (see Animation sprites)
Text
Click on the canvas to place a text box, then type. Double-click existing text to edit it
Tip
After drawing a shape, the tool automatically switches back to the Pointer. To draw multiple shapes of the same type, re-select the tool after each draw.
Animation sprites
Use the Insert Animation tool () to turn a short image sequence into an animated object on the map — for example a spinning fan blade close-up, a flashing arrow, or a multi-step icon animation that a plain Rotate/Blink action can't produce.
Click Insert Animation on the drawing toolbar
Click Add Frames and select 1–10 PNG or JPEG images, in playback order
Frames are automatically cropped to a common size and combined into a single sprite sheet
Set the frame rate (frames per second)
Check the preview animation, then click Insert to place it on the canvas
An inserted animation does not play automatically. Select it, open its Data Binding section, and enable the Play Animation display action to start/stop playback based on a live value — the same condition-rule system used by every other display action.
Note
Resize an animation object using its corner handles like any other shape — it scales as a whole rather than re-cropping the frames.
Selecting and manipulating objects
Click an object to select it — blue handles appear around the object
Shift+Click to add or remove an object from the selection
Marquee select: click on empty canvas and drag a rectangle to select all objects inside
Ctrl+A: select all objects on the canvas
Click empty area: deselect all
Drag a selected object to move it
Drag a handle to resize
Arrow keys: nudge selected objects by 1 pixel (hold Shift for 10 px steps)
Text editing
Use the text toolbar to set font, size, style, and colors before placing text, or select existing text to change its properties.
Font family: choose from the font dropdown (Arial, Roboto, Courier New, etc.)
Bold / Italic: toggle with toolbar buttons or use the style options
Font size: type a value (6 – 200 px)
Fill color: background fill of the text box
Stroke color: text foreground color
Text position: choose where the label appears relative to a marker (Top, Bottom, Left, Right, Center, Hidden)
Double-click on existing text to enter inline editing mode. Press Escape or click outside to finish.
Shape styling
Selected shapes can be styled via the toolbar, properties panel, or right-click context menu:
Fill
Solid color — pick from color swatches or the native color picker
Linear gradient — two-color gradient with direction control
Radial gradient — circular gradient from center outward
No fill — transparent background
Stroke (border)
Color — pick stroke color from the color picker
Width — 0 (none), 1, 1.5, 2, 3, 4, or 6 px
Style — Solid, Dashed, Dotted, Dash-dot, Long dash
No stroke — remove the border entirely
Line arrows
Lines and polygons can display arrow endpoints. Set via the context menu > Appearance > Line Arrow:
No Arrow, End arrow, Start arrow, Both ends, Triangle, Round cap, Square cap
Opacity
Set object transparency from the context menu > Appearance > Opacity (10% – 100%).
Corner radius
Rectangles support rounded corners. Set the radius in the Properties panel (right sidebar).
Polygon node editing
After drawing a polygon, you can edit individual vertices:
Select a polygon and double-click it (or right-click > Edit Nodes)
Blue vertex handles appear — drag them to reshape the polygon
Right-click a vertex to access node options:
Add Node — insert a new vertex between this point and the next
Delete Node — remove this vertex (also available via Delete key)
Corner — make this vertex a sharp corner
Smooth — convert this vertex to a Bézier curve
Finish Editing — exit node edit mode
You can also convert multiple lines into a single polygon via the context menu > Convert Lines to Polygon
Press Escape to exit polygon node editing mode.
Object ordering (z-order)
Control which objects appear in front of or behind others:
Action
Shortcut
Context menu
Move one level up
Page Up
Ordering > Move Up
Move one level down
Page Down
Ordering > Move Down
Bring to front
End
Ordering > Bring to Top
Send to back
Home
Ordering > Send to Bottom
Context menu (right-click)
Right-click on any object to access quick actions:
Cut / Copy / Paste / Delete
Group / Ungroup
Lock / Unlock
Rotate 90°
Ordering — submenu for z-order (Top, Up, Down, Bottom)
Move to Layer — reassign the object to a different layer
Appearance — submenus for Fill type, Stroke, Line width, Line style, Line arrows, Opacity
Widget Properties — open advanced properties for widgets
Status: Check OK, Error/Fail, Warning, Info, Power Off
Electrical Engineering (EE)
Standard single-line diagram symbols: Transformer, Circuit Breaker, Fuse, Ammeter, Voltmeter, Motor, Generator, Capacitor Bank, Switchgear, Bus Bar, Ground, Lightning Arrester, and more.
Analog-style dial gauges that can display live values via data binding.
Graphs
Embeddable chart widgets that can display trend data from bound data points.
To use a widget: click it in the library panel — it will be placed on the canvas at the center of the current view.
Properties panel
The right-side panel shows properties for the selected object. Toggle it from View > Properties Panel.
Property
Description
X, Y
Position on the canvas (top-left corner)
W, H
Width and height in pixels
Rotation
Rotation angle in degrees
Corner Radius
Rounded corners for rectangles (0 = sharp)
Opacity
Transparency (0 – 100%)
Data binding
Any shape, text, or widget can be bound to a live data point from a connected meter. When the map is in Preview or Runtime mode, bound objects update automatically.
Binding a data point
Select an object on the canvas
In the Properties panel, find the Data Binding section
Choose the binding type and point using the point picker — BACnet, Modbus TCP, Modbus RTU, Digital Meter, Software Module, or a built-in System point (date/time, page title, memory, etc.)
Configure one or more display actions
Tip — Drag a point directly onto the canvas
Instead of using the point picker, drag a meter point from the sidebar tree straight onto the canvas. This places a bound text label automatically pre-filled with the correct binding type, device, and point — the fastest way to build a map full of live readouts.
Display actions
Open an action's settings icon to configure its condition rules and options.
Action
Description
Display Value
Show the live numeric/text value on the object. Configure number format, unit/suffix, state-text mapping (e.g. 0/1 → OFF/ON), and text alignment
Change Text Color
Change the text color based on value conditions (e.g. red when > 100)
Hide / Show
Toggle object visibility based on value conditions (e.g. show alarm icon when value = 1)
Blink / Flash
Make the object blink when conditions are met. Speed options: slow, normal, fast, or custom interval
Rotate
Animate rotation when conditions are met. Configure speed and direction (clockwise/counter-clockwise). The object rotates around its own visual center
Play Animation
Start/stop a multi-frame animation (see Animation sprites) when conditions are met
Change Fill Color
Change the fill color based on value conditions, with a default color when no rule matches
Fill Level
Grow/shrink the object like a level indicator (e.g. tank fill) between a min/max value, in a chosen direction
Change Image
Swap an image object's source based on value conditions (e.g. door-open.png vs door-closed.png)
Move Item
Move the object between a start and end position proportionally to the value (e.g. a damper or slider indicator)
Change Stroke
Change the border color/width based on value conditions
Change Opacity
Fade the object in/out proportionally to the value between a min/max range
Analog Color
Smoothly blend fill color across 2+ color stops based on the value (e.g. blue → green → red as temperature rises)
Each action supports condition rules: compare the live value against thresholds using operators (=, ≠, >, <, ≥, ≤) and apply the effect when the condition is true.
Every action's settings popup also has a Show hover tooltip checkbox (enabled by default). It controls one shared, per-object setting: whether hovering the object in Preview/Runtime shows a tooltip with its tag name and live value. Uncheck it from any action's popup to silence the tooltip for that object without affecting its binding or other display actions.
Editing display actions for multiple objects at once
Select 2 or more bound objects (Shift+Click or marquee-select) and the Properties panel switches to batch mode: the same Display Actions list appears, seeded from the first selected object. Enabling an action or changing its settings applies immediately to every selected object.
Only display actions are editable in batch mode — the Binding Type, Device, and Point fields are hidden and cannot be changed this way
Each object keeps its own point binding untouched; only the shared display-action configuration is copied across the selection
Undo (Ctrl+Z) reverts a batch edit across the whole selection in a single step
This is the fastest way to apply the same Blink rule, color rule, or tooltip setting to a whole row of point labels after placing them.
Preview mode and Runtime view
There are two ways to see a map as end users will see it, with live data polling and interactive widgets:
Preview — click on the toolbar, or View > Preview, or press Ctrl+R, to test the map without leaving the editor. If there are unsaved changes, a prompt asks to save or discard first. All toolbar and panels are hidden; only the map is visible
Runtime view — the same live, read-only rendering opened as its own page (File > Open in new tab, or the map's entry in the map list) for dashboards, kiosk displays, or sharing a link. It has no editor chrome at all, not even a way to switch back to editing
Both modes activate the same data binding actions (values update, colors change, objects blink/rotate/animate) and share the same hover tooltip and performance-overlay behavior described below.
Hover tooltip
In Preview/Runtime, hovering a bound object shows a small tooltip with its tag name and current value. This is on by default for every bound object; turn it off per-object from any of that object's display-action settings popups via the Show hover tooltip checkbox.
Performance overlay
Press Ctrl+Alt+P in Preview or Runtime view to toggle a small diagnostic panel showing FPS, JS memory usage (Chrome/Edge only), node/shape counts, how many objects are currently Rotating/Blinking/Animating, and live-data polling stats (payload size, request duration, error count). It's a lightweight tool for checking whether a map with many live points or animations is running smoothly — it has no effect on the map itself and updates only while the panel is open.
Preview shortcuts
Key
Action
Esc
Exit preview, return to editor
E
Exit preview, return to editor
Ctrl+R
Open runtime view in a new tab
Ctrl+Alt+P
Toggle the performance overlay
F11
Toggle fullscreen
Page properties
Access from File > Page Properties. Configure:
Canvas width (100 – 10,000 px)
Canvas height (100 – 10,000 px)
Background color
Linked template — overlay a template map behind the current map (useful for floor plan backgrounds)
Preferences
Access from File > Preferences. Settings are saved per-browser using localStorage:
Default text: font family, font size, text color
Default shape: fill color, stroke color, stroke width
Grid size: spacing in pixels (2 – 200)
Snap to grid: on/off by default
Keyboard shortcuts reference
Shortcut
Action
Context
Ctrl+S
Save map to database
Editor
Ctrl+Z
Undo
Editor
Ctrl+Y
Redo
Editor
Ctrl+Shift+Z
Redo (alternative)
Editor
Ctrl+A
Select all objects
Editor
Ctrl+C
Copy selected objects
Editor
Ctrl+X
Cut selected objects
Editor
Ctrl+V
Paste from clipboard
Editor
Ctrl+G
Group selected objects
Editor
Ctrl+U
Ungroup
Editor
Ctrl+Shift+G
Ungroup (alternative)
Editor
Ctrl+R
Enter Preview mode
Editor
Delete / Backspace
Delete selected objects
Editor
Escape
Cancel current operation / exit polygon edit / exit pan mode
Editor
Arrow keys
Nudge selection by 1 px
Editor
Shift+Arrow keys
Nudge selection by 10 px
Editor
Page Up
Move object one level up (z-order)
Editor
Page Down
Move object one level down (z-order)
Editor
End
Bring to front
Editor
Home
Send to back
Editor
Shift+Drag
Constrain shape / snap line angle (0°/45°/90°)
Drawing
Enter
Finish polygon drawing
Polygon tool
Esc
Exit preview mode
Preview
E
Switch to editor
Preview
Ctrl+Alt+P
Toggle the performance overlay
Preview / Runtime
F11
Toggle fullscreen
Preview
Scroll wheel
Zoom in / out
Editor
Middle-click drag
Pan the canvas
Editor
Tips and best practices
Tip — Copy and paste markers
When you copy a marker icon (Ctrl+C) and paste (Ctrl+V), the name auto-increments. For example, Door1 becomes Door2, Door3, and so on.
Tip — Paste images from clipboard
You can paste images directly from your clipboard (Ctrl+V). Screenshot a floor plan, copy it, and paste it directly onto the canvas as a background image.
Tip — Use layers for complex maps
Organize your map into layers: put the floor plan image on a bottom layer, equipment icons on a middle layer, and labels/text on the top layer. Lock the background layer to avoid accidentally moving the floor plan.
Tip — Templates for consistent layouts
Create a template map with your building floor plan, then link it in Page Properties. The template appears as a non-editable background, keeping your layout consistent across multiple maps.
Tip — Align objects precisely
Select multiple objects, then use Object > Align or the align toolbar dropdown to line them up evenly. Use Distribute (requires 3+ objects) to space them equally.
Tip — Quick zoom navigation
Use the scroll wheel to zoom in/out centered on your cursor. Click Fit to Screen to see the full map, or Reset View to return to 100% zoom.
Tip — Line connections
When drawing lines, endpoints snap to nearby shapes automatically. This creates visual connections for single-line diagrams. Drag a line endpoint near a shape border to attach it.
Tip — Export and backup
Regularly export your maps as JSON files (File > Export as JSON) for backup. You can import them on another system or restore after accidental changes.
Tip — Drag points from the tree
You can drag meter points from the sidebar tree directly onto the canvas to create bound marker icons. This is the fastest way to populate a map with live data points.
Logic Studio
Logic Studio is a web-based visual node editor for building automation logic — read meter/point values, apply timers, math, and conditional logic, then write results back out as alarms, commands, or point values. This chapter explains the editor itself and documents every node's inputs, outputs, properties, and behavior in detail.
Note
Logic Studio is not a PLC programming environment. It is an automation logic engine tightly integrated with EMS81 — the visual editor only edits a workflow (saved as JSON); a separate Python runtime service executes that workflow on a fixed scan cycle, independent of whether anyone has the editor open.
Opening Logic Studio
Open a logic file from the Logic Studio tree in the sidebar (folder/file icons, similar to Sites). Each file is a separate, independently-run workflow with its own nodes, wiring, and Run/Pause/Stop state. Double-click a file to open it in the editor.
Editor basics
Action
How
Add a node
Drag an item from the left or right toolbox onto the canvas.
Bind a meter point
Drag a point from the sidebar tree directly onto an Input Tag or Output Tag node (or drop it on empty canvas to create one).
Connect nodes
Drag from an output socket (right edge of a node) to an input socket (left edge) of another node. A wire only connects sockets of the same type — value-to-value or bool-to-bool.
Remove a wire
Click the wire, then press Delete, or drag from the input socket away and release on empty canvas.
Pan / Zoom
Drag empty canvas to pan; scroll wheel to zoom; Fit button frames all nodes.
Undo / Redo
Toolbar buttons, or Ctrl+Z / Ctrl+Y.
Save
Toolbar Save button — writes the workflow JSON for this file and reloads the runtime if it is currently running.
Import / Export
Export the current workflow as a JSON file, or import a previously exported file.
Search
Toolbar Search — jump to a node by its label or bound tag name.
Run / Pause / Stop and live monitoring
The Run, Pause, and Stop buttons control this file's workflow independently of every other Logic Studio file:
State
Meaning
Run
The Python runtime evaluates this workflow every scan cycle. The editor polls live values once per second and shows them on each node (rounded to 2 decimal places); errors show directly on the node that produced them.
Pause
The runtime stops scanning but keeps its current state (timer elapsed time, counter values, latch/memory state) so you can resume later without losing progress.
Stop
The runtime stops and clears its state. The next Run starts fresh (counters at 0, timers reset, memory back to its initial value).
Editing is locked while running
Adding, removing, or rewiring nodes is blocked while a workflow is Running or Paused (moving nodes around for readability is still allowed). Click Stop first if you need to change the logic itself.
Node reference
Every node reads its wired inputs, evaluates, and writes its outputs once per scan cycle. An input port left unconnected uses a sensible default (usually 0 or false) unless noted otherwise below.
Inputs
Input Tag — reads a live value from a bound meter/point (or, for Software Module points, a writable internal tag). Drag a point from the sidebar tree onto this node to bind it; the node then displays Device.Point. If the source point is offline, downstream nodes receive no value for this scan (treated as unwired) rather than a stale reading.
Port
I/O
Description
Value
Output (value)
The point's current reading, or nothing while the point is offline.
Constant — a fixed number you type directly into the node. Use it to feed a threshold, setpoint, or multiplier into other nodes without needing a real meter point.
Port
I/O
Description
Value (property)
Property
The number to output, edited directly on the node.
Value
Output (value)
Always equal to the property above.
Boolean / Logic
Compare — compares two values and outputs a single true/false result. Set the operator property to >, <, >=, <=, ==, or !=.
Port
I/O
Description
A, B
Input (value)
The two values to compare. Unwired defaults to 0.
Operator (property)
Property
One of > < >= <= == !=. An unrecognized value produces Err: bad op.
Result
Output (bool)
A (operator) B.
AND — true only when every connected input is true. Right-click the node to change its input count between 2 and 3.
Port
I/O
Description
A, B (, C)
Input (bool)
2–3 inputs depending on the node's input count. Unwired counts as false.
Result
Output (bool)
True only if all connected inputs are true.
OR — true when either input is true.
Port
I/O
Description
A, B
Input (bool)
Unwired counts as false.
Result
Output (bool)
A OR B.
NOT — inverts a single boolean.
Port
I/O
Description
A
Input (bool)
Unwired counts as false (so Result defaults to true).
Result
Output (bool)
NOT A.
XOR — true only when A and B are different.
Port
I/O
Description
A, B
Input (bool)
Unwired counts as false.
Result
Output (bool)
True if A and B disagree (one true, one false).
Select (SEL / 2-way MUX) — chooses between two values based on a condition, like an IF/ELSE for values instead of logic states.
Port
I/O
Description
SEL
Input (bool)
The condition. Unwired counts as false.
A (true)
Input (value)
Passed through to Result when SEL is true. Unwired defaults to 0.
B (false)
Input (value)
Passed through to Result when SEL is false. Unwired defaults to 0.
Result
Output (value)
A copy of whichever of A/B was selected — values pass through unchanged, including non-numeric tag values.
Tip
Need to choose between more than two values? Chain multiple Select nodes (Select's Result can feed another Select's A or B input).
Hysteresis (deadband / Schmitt trigger) — like Compare, but with two thresholds instead of one, so Q does not chatter while the input idles right at a single trip point. Q only turns true once IN reaches the High threshold, and only turns false again once IN drops all the way to the Low threshold.
Port
I/O
Description
IN
Input (value)
The value to monitor. Unwired defaults to 0.
High (property + High wire)
Property / Input (value)
Upper trip point. If a wire is connected to the High input it overrides the property value, same as a Timer's PT.
Low (property + Low wire)
Property / Input (value)
Lower trip point, same override rule as High.
Q
Output (bool)
Starts false. Becomes true once IN ≥ High; becomes false again once IN ≤ Low; holds its last value in between.
Example: cooling relay control — set High = 26, Low = 24 on a room temperature Input Tag, and wire Q to an Output Tag or Alarm. The relay switches on at 26°C and off at 24°C, instead of buzzing on and off around a single setpoint.
Timers
All four timer nodes share the same property/port shape: a PT (preset time, in seconds) that can be typed directly into the node or overridden by wiring a value into the PT input port.
Node
Ports
Behavior
TON (On-Delay)
IN (bool in), PT (property/value in), Q (bool out)
Q becomes true only after IN has been continuously true for PT seconds. Q goes false immediately the instant IN goes false — the delay only applies to turning on.
TOF (Off-Delay)
IN, PT, Q
The mirror of TON: Q follows IN true immediately, but stays true for PT seconds after IN goes false before finally dropping.
TP (Pulse)
IN, PT, Q
On the rising edge of IN, Q turns true for exactly PT seconds regardless of how long IN itself stays true, then turns false — a fixed-width one-shot pulse.
Debounce
IN, PT, Q
Q only follows IN after IN has held the same new value continuously for PT seconds — filters out rapid chatter on a noisy digital input in either direction.
Use TON to delay an alarm so a brief glitch doesn't trigger it. Use TOF to keep a fan running for a few minutes after its trigger condition clears. Use TP to turn a continuous condition into a fixed-length pulse (e.g. a single relay click). Use Debounce on a noisy digital status input before feeding it into other logic.
Counters
Counter Up and Counter Down each track a running count (CV) that only changes on a rising edge of their trigger input — holding the trigger true does not keep counting every scan, it counts once per false→true transition. Reset always clears CV back to 0 and takes priority over counting if both happen on the same scan.
Node
Ports
Behavior
Counter Up
CU (bool in), Reset (bool in), CV (value out)
CV increases by 1 on each rising edge of CU.
Counter Down
CD (bool in), Reset (bool in), CV (value out)
CV decreases by 1 on each rising edge of CD.
Note
These are simple event counters, not a full IEC 61131-3 CTU/CTD block — there is no built-in preset/threshold output. To trigger something once CV reaches a target, wire CV into a Compare node (for example CV >= 10).
Example: count how many times a pump has started today — wire the pump's run status through an RTrig (see Outputs, below) into Counter Up's CU, and wire a daily schedule pulse into Reset.
Math
Node
Inputs
Behavior
Add
2–6 (A…F)
Sum of all connected inputs. Right-click to change the input count.
Subtract
A, B
A − B.
Multiply
A, B
A × B.
Divide
A, B
A ÷ B. B = 0 produces Err: ÷0 instead of crashing the workflow.
Min
2–6 (A…F)
Smallest of all inputs; an unwired port counts as 0.
Max
2–6 (A…F)
Largest of all inputs; an unwired port counts as 0.
Average
2–6 (A…F)
Mean of only the wired inputs (unwired ports are excluded, not counted as 0).
Abs
A
Absolute value, |A|.
Every Math node's Result output shows Err: NaN or Err: overflow instead of a number if the calculation is undefined or too large to represent — see Error indicators below.
EMS
PUE (Power Usage Effectiveness) — the standard data-center efficiency ratio.
Port
I/O
Description
Total (kW)
Input (value)
Total facility power draw.
IT (kW)
Input (value)
IT equipment power draw.
PUE
Output (value)
Total ÷ IT. A value near 1.0 is ideal; typical data centers run 1.2–2.0. IT = 0 produces Err: ÷0.
Wet Bulb — estimates wet-bulb temperature from dry-bulb temperature and relative humidity, using the Stull (2011) empirical approximation (no iterative psychrometric solve). Accurate to about ±0.3°C for −20–50°C and 5–99% RH.
Port
I/O
Description
Dry Bulb (°C)
Input (value)
Measured air temperature.
RH (%)
Input (value)
Relative humidity, 0–100 (values outside this range are clamped).
Wet Bulb (°C)
Output (value)
Estimated wet-bulb temperature. At 100% RH this equals the dry-bulb input, as expected physically.
Useful for cooling tower approach-temperature calculations and free-cooling/economizer decisions.
Variable
Assign and Move — both are simple pass-through nodes that also remember their last value internally; the difference only matters when their input becomes unwired or the source goes offline.
Node
Ports
Behavior
Assign
Value in, Result out
Result always equals the current Value input (0 if unwired).
Move
Value in, Result out
Result equals Value when wired; if Value has no incoming data this scan, Result holds the last value it saw instead of resetting to 0.
Memory — a manually-latched value: it only updates when told to, otherwise it holds whatever was last written, even across a Pause/Resume.
Port
I/O
Description
Initial (property)
Property
Starting value the first time this node runs (or after Stop clears state).
Value
Input (value)
The value to store, applied only while Write is true.
Write
Input (bool)
Gate — while true, Stored is overwritten with Value every scan; while false, Stored is left untouched.
Stored
Output (value)
The currently held value.
Outputs
Output Tag — writes a value to a bound meter/point (typically a Software Module point, or another writable point). Drag a point from the tree onto this node to bind it.
Port
I/O
Description
Value
Input (value)
The value written to the bound point every scan (0 if unwired).
Alarm — raises an EMS alarm event while its trigger is true (feeds the same alarm pipeline as protocol-level alarms — visible in Alarms & Events).
Port
I/O
Description
Message (property)
Property
Text shown in the alarm list/notifications.
Trigger
Input (bool)
While true, the alarm is active; going false clears it.
SR Latch — a set/reset flip-flop; once set, it stays true until explicitly reset (Reset always wins if S and R are both true at once).
Port
I/O
Description
Initial state (property)
Property
Q's value the first time this node runs (or after Stop).
S
Input (bool)
Set — a true pulse sets Q true.
R
Input (bool)
Reset — a true pulse sets Q false; takes priority over S.
Q
Output (bool)
Holds its value until the next S or R pulse.
RTrig (Rising-edge trigger) — converts a signal that stays true into a single one-scan pulse at the moment it first becomes true.
Port
I/O
Description
IN
Input (bool)
The signal to watch.
Q
Output (bool)
True for exactly one scan, only on the false→true transition of IN.
Feed RTrig's Q into a Counter Up/Down's CU/CD input to count events rather than measure duration.
Misc
Comment — a free-text note placed on the canvas. It does not run any logic and has no inputs or outputs; use it to document what a section of the workflow is for.
Error indicators
When a node cannot produce a valid result, its output shows a short error label directly on the canvas instead of a number, so the problem is visible without checking logs.
Label
Meaning
Err: ÷0
A Divide or PUE node's divisor input was 0.
Err: invalid
An input that should be numeric could not be parsed (for example a Constant with non-numeric text, or a wired value that is not a number).
Err: no input
An Average node has no wired inputs at all.
Err: NaN
The calculation produced an undefined result.
Err: overflow
The result is too large to represent.
Err: bad op
A Compare node's operator property is not one of > < >= <= == !=.
Operator Guide
Day-to-day tasks for monitoring energy data and responding to events.
Logging in and navigating
Log in with your assigned username and password.
Use the sidebar treeview to open modules — each item loads in the main content area.
Click folder (caret) items to expand groups; click a leaf item to open that page.
Sites, folders, and group items
The Sites menu (under Home → Sites in the sidebar) is the main way to organize facilities and curated point collections for day-to-day monitoring. Changes made in the list view and in the sidebar treeview stay synchronized — adding, renaming, or deleting an item updates both panes without a full page reload.
Hierarchy
Level
Example
What it is
Sites root
Sites
Top of the Sites tree. Lists all site entries.
Site
Rojana
A facility or building. Can contain folders and group items directly.
Folder
Folder A
Organizes items inside a site. Can contain subfolders and group items.
Group item
Group Energy, Monthly Report
A named collection of device points/tags shown as a live data table.
Icons and colors
Icons are consistent in the sidebar tree and in the list view:
Item type
Icon
Color
Opens
Site
Building
Default (dark)
Folder list for that site
Folder
Folder
Slate gray
Contents of that folder
Group item
Layer group (stacked layers)
Blue
Live point/tag table for the collection
View modes
Each Sites page has a List View dropdown in the header:
Icon View — large cards for quick visual browsing.
List View — compact table with name and description (default for most levels).
Edit — shows reorder handles, edit, and delete controls. Drag rows to change display order.
Open Link — opens the current page in a new browser tab.
Inside a group item, the dropdown also offers Export Live Data, Export History, and Export Consumption for spreadsheet export of the collection.
Adding items from the list view
Toolbar buttons depend on the current level. You need Add permission on the Sites menu.
Page
Toolbar buttons
Creates
Sites root
Add Site
A new top-level site entry
Inside a site or folder
Add Group Item Collection Add Folder
A group item or subfolder
Inside a group item
Add tag or point
A point or tag row in the live table
Fill in the modal form and click Add. The name field is required — empty or whitespace-only names are blocked with an inline hint before save. The modal stays open if validation fails so you can correct the input.
Adding items from the sidebar tree
Right-click a Sites node (or use the tree context menu where available).
Choose Add:
On Sites root — Site or Folder.
Inside a site folder — Folder (subfolder) or Item (group item / device collection).
Enter the name and optional description in the prompt.
The new node appears in the tree and in the open list view for that parent.
Editing and deleting
From Edit view — click the pencil icon on a row to change name, description, and parent folder. Click the trash icon to delete.
From the tree — right-click → Rename or Delete. Rename updates the tree label and refreshes the list view.
Inside a group item — switch to Edit to reorder, edit, or remove individual points. Use Empty (All) to clear every point in the collection (requires Remove permission).
Warning
Deleting a site, folder, or group item removes it from navigation. Deleting points inside a group item removes them from that collection only — the underlying device registers are not deleted.
Working inside a group item
Open a group item from the tree or list (e.g. Group Energy).
Review live values in the paginated table. Use the header breadcrumb to move back up the hierarchy.
Click Add tag or point to pick registers from connected devices and add them to the collection.
Users with Add permission can drag devices from the sidebar tree onto the group item page to add points quickly.
Use export modes from the view dropdown when you need Excel output for live data, history, or energy consumption.
Permissions
Sites uses the Sites permission entry in Administration → Users → Permission:
Right
Controls
View
See the Sites menu, tree nodes, and list pages.
Add
Add Site / folder / group item / point buttons; drag-and-drop into a group item.
Edit
Edit view, rename, reorder, and save changes.
Remove
Delete icons, Empty (All), and tree delete.
Tip
If toolbar icons or styles look outdated after an upgrade, hard-refresh with Ctrl+F5. Hidden toolbar placeholders (search/export) no longer leave empty gaps when those tools are not shown for the current view mode.
Monitoring live data
Open Devices and select the protocol (Digital Meter, BACnet, Modbus, etc.).
Browse loops and meters to locate the device.
Review live readings; icons indicate online or offline status.
For curated multi-point views organized by facility, use Sites and open a group item instead (see Sites, folders, and group items above).
Virtual Meter — derived meters and source groups
A Virtual Meter is a calculated device under Devices → Virtual Meter. It uses a reference model (point template) and one or more source meters from physical loops. Live readings are derived from those sources rather than from a dedicated Modbus connection.
Opening a Virtual Meter loop
In the sidebar, expand Devices → Virtual Meter.
Click a Virtual Meter loop (for example TES) to open the device list (data.php) in the main panel.
Click a Virtual Meter device name (for example SSS) to open its live page — the same style of live point table used by physical meters.
Use the edit (pencil) icon on the list, or Sources / settings links, when you need the detailed Virtual Meter configuration page.
Reordering Virtual Meter devices
Change the display sequence of devices under a loop (for example SSS, ASS, TEST under TES) by dragging in the sidebar tree. The same works for devices under other protocol loops (Digital Meter, Modbus TCP, and so on):
Expand the loop in the left tree.
Drag a device onto another device in the same loop.
Drop onto another device in the same loop — drag up places it before that device; drag down places it after. The list panel refreshes to match.
Tip
Keep the pointer over the left tree while reordering. Dropping a physical meter from another loop onto a Virtual Meter in the main panel list adds it as a source — that is a different action (see below).
Adding source meters by drag-and-drop
The fastest way to add physical meters into a Virtual Meter’s source group is to drag them from the sidebar tree onto the Virtual Meter list.
Open the Virtual Meter loop list (for example Devices → Virtual Meter → TES).
In the left tree, expand a physical protocol loop (Digital Meter, Modbus RTU, Modbus TCP, and so on) and locate the meter to add.
Drag the meter device (not a point/tag leaf) from the tree.
Drop it onto the target Virtual Meter row or icon card in the list. A blue outline highlights the target while you hover.
Wait for the confirmation. The Sources count on that row updates after sources are added.
Tip
A blue hint bar on the Virtual Meter list page reminds you: “Drag meters from the left tree and drop onto a Virtual Meter to add sources.” You can also drop sources on a Virtual Meter’s live page or settings page when that page is open — useful when you are already configuring one device.
Requirements
You need Add permission on the Virtual Meter menu.
Drag a meter node (for example Meter4), not an individual point under it.
Source meters should generally share the same model family as the Virtual Meter’s reference model. Mismatched models may be skipped or added with a warning.
You cannot add a Virtual Meter as a source of itself.
Creating a new Virtual Meter
On the Virtual Meter loop list, click the + (Add) header button.
Enter a device name and description.
Select one or more source meters from the picker (filter by loop or search by name).
Click Create Virtual Meter. The reference model is taken from the primary selected source; you can add more sources later by drag-and-drop.
View modes on the list page
Icon View — cards with a Sources badge; drop onto a card.
List View / Edit — table rows with a Sources column; drop onto a row.
Time Schedule — weekly template automation
The Schedule menu provides a folder tree (like Sites or E-Map) for weekly time-block templates. Each schedule file opens a canvas editor (schedule/editor.php?id=…) where you draw colored blocks across Monday–Sunday, plus an Exception1 row used only on holiday dates (see Holidays, below). Each block selects one of 8 states (0–7) defined for that template.
Schedule file — opens the weekly editor in a new tab (schedule/editor.php?id=…). Old links to schedule/demo.php still work — that page now simply forwards to the editor.
The sidebar tree and folder list stay synchronized when you add, rename, move, or delete items.
Copy / Paste in the tree context menu duplicates a folder (with children) or a schedule file including its saved blocks, state definitions, and holiday settings.
Weekly and Holidays tabs
The editor has two tabs at the top: Weekly (the Monday–Sunday canvas) and Holidays (this template's holiday calendar). Switching tabs does not lose unsaved changes on either one.
Editing the weekly canvas
Open a schedule file and use Template States (0–7) at the top to rename states (max 32 characters) and pick swatch colors; Default resets all 8 back to the built-in labels (State 0 “Off”, State 1 “On”, States 2–7 numbered) and colors.
Drag on the grid to create a time block, or use the context menu (Add, Edit, Delete).
Each block is assigned a State 0–7 (not a direct point write). Double-click a block to set exact begin/end times and the state index.
The 8th row, Exception1, is a separate set of time blocks that only apply on a date you've flagged as an Exception1 holiday for this template — leave it empty to fall back to Off/last-value on those dates instead.
Click the save icon in the header (or Save all in the canvas menu) to persist blocks, state definitions, and the Gap/Fallback settings below.
Gap and Fallback
Two toolbar dropdowns (next to Precision) control what happens when the current time falls outside every block on the Weekly canvas (a “gap”):
Gap — “Reset to fallback state” drives every point on this template to the Fallback state during a gap; “Maintain last schedule value” leaves points at whatever state their last active block set.
Fallback — the State (0–7) to apply when Gap mode is “Reset to fallback state”. Only used in that mode.
Gap and Fallback are set once per template, not per point — every point assigned to this template shares the same setting.
Note
Earlier versions of EMS set Fallback per point on the point's Detail page. That control has moved here, to the template. The Detail page now only shows the template's current Gap/Fallback setting as read-only text, with a link back to this editor.
Assigning a template to a point
Templates are not bound to points inside the schedule editor. On a writable point's Detail page (and equally from the Tag Settings 360° detail view), open the Command & Schedule tab:
Manual command — Post URL, option value, and State 0 (Off) / State 1 (On) write values.
Enable — check “Run weekly schedule on this point” to have this point follow a template.
Template — choose which schedule file drives this point.
A gray helper line below the Template dropdown shows that template's current Gap/Fallback setting for reference (e.g. “Empty time: Reset to fallback state — Fallback: State 0 (Off)”). To change it, open the template in the Schedule editor and use the Gap/Fallback dropdowns described above — this page does not edit it directly.
Click Save to apply.
The Python EMS service evaluates schedules every minute at :00, queues Modbus writes only when the required state changes, and records each automatic write to the Audit Log.
Holidays — site-wide calendar and per-template exceptions
Holidays let a schedule template behave differently on specific dates — for example, running the Exception1 row instead of the normal weekday blocks, or simply going Off. There are two layers: one shared site-wide Holiday calendar, and per-template Exceptions that only affect one schedule file.
Site-wide Holiday calendar
Open Schedule → Holidays to manage one shared list of holiday dates for the whole site. Any template with “Use site-wide holidays” turned on (see below) treats every date here as a holiday.
Browse to the month/year with the ‹ / › buttons, or click Today.
Click a date to open the Holiday dialog. Enter a Short name (max 16 characters, e.g. “New Year”) and click Save.
Click an existing holiday date again to rename it, or click Remove to delete it.
Site-wide holidays always use the default runtime behavior (digital/state points go Off; analog points keep their last value) — there is no Exception1 option here.
To bulk-load holidays instead of adding them one by one, click the Import Thai public holidays button in the page header. This copies the recurring holiday dates already configured for billing into the Holiday calendar for the current year (and next year), tagging them so re-importing later only updates names rather than creating duplicates.
Template holidays (Holidays tab in the schedule editor)
Open a schedule file and switch to the Holidays tab to manage holiday behavior for that template specifically:
“Use site-wide holidays (Schedule → Holidays)” — when on (the default), this template also treats every site-wide Holiday date as a holiday, in addition to any dates set here. Turn it off to make this template ignore the site calendar and use only its own dates below.
Click a date on the calendar to open the same Holiday dialog as the site-wide page, plus an Exception type choice: Default (Off), or Exception1 to run this template's Exception1 row on that date instead.
If the date is already a site-wide holiday and you haven't overridden it here, the name field is read-only (it shows the site holiday's name) — choosing Exception1 and saving creates a template-specific override; leaving it as Default and saving does nothing extra, since the site calendar already covers it.
The calendar legend shows which dates come from the Site calendar, which are Template only, and which are Both (a site date with a template-specific override).
How a holiday date is resolved
For any date, if this template has its own Exception entry, that entry's type (Default or Exception1) and name win. Otherwise, if the date is only a site-wide holiday and “Use site-wide holidays” is on, the date uses Default (Off) behavior with the site holiday's name. Deleting a schedule template also deletes all of its Exception entries.
Export Settings — copying a template to other schedules
Use this to copy one template's Weekly canvas and/or Holiday configuration onto one or more other schedule files, instead of rebuilding them by hand.
Open the source schedule file and click the Export settings icon in the header (next to the PDF export icon).
Check Weekly (blocks, states, gap/fallback, Exception1) and/or Holidays (template dates + Exception overrides) — both are checked by default.
Under Target schedules, click All/None or check individual templates (the current template is not listed).
Click Export. The source template is saved first so the export always uses your latest edits, then a confirmation shows how many templates were updated (and how many failed, if any).
Exporting only copies the Weekly/Holiday configuration — it does not change which points are assigned to the target templates.
Mod Scan 360 — Modbus register debug
Mod Scan 360 is an integrated Modbus debugger for commissioning and troubleshooting. It pauses normal meter polling for one loop only, reads registers on demand, shows raw TX/RX frames, and can write holding registers or coils. Other loops and protocols keep running.
When to use it
Verify slave ID, register address, and data type before building a model.
Confirm a device responds on the wire when live values show offline.
Test a single write (setpoint, coil command) without changing the model.
Inspect frame-level errors (CRC, exception codes, no response).
Supported protocols
Mod Scan 360 is available only on these loop types under Devices:
Protocol
Connection shown in Mod Scan 360
Digital Meter
Serial/RTU port or UDP RTU gateway (from loop configuration)
Modbus RTU
Local serial port (COM or /dev/tty*)
Modbus TCP
TCP socket to gateway IP and port
It is not available for BACnet, MBUS, Virtual Meter, Software Module, or other protocol branches.
Opening Mod Scan 360
In the sidebar under Devices, expand Digital Meter, Modbus RTU, or Modbus TCP.
Right-click the loop (the loop row, not an individual meter/device).
Choose Mod Scan 360 from the context menu.
Read the confirmation dialog, then click Pause & open.
Mod Scan 360 opens in a modal overlay on top of the main EMS window.
Important
While Mod Scan 360 is active, normal polling for that loop is paused. Live values for meters on that loop will not update until you click Resume, close the modal, or the idle timer expires. Other loops are unaffected.
Debug session and auto-resume
Control
Action
Countdown timer (top bar)
Shows time until auto-resume. Default idle timeout is 5 minutes.
+5 min
Extends the debug session by five minutes (useful when the timer turns amber near expiry).
Resume
Ends the debug session immediately and restarts normal meter polling for this loop.
Close modal (× or backdrop)
Requests resume before closing; polling should restart within a few seconds.
Idle timeout
If you do nothing for 5 minutes, polling resumes automatically.
While paused, the loop icon in the sidebar tree may show a search/debug indicator so other users can see that the loop is in a debug session.
Only one Mod Scan 360 session per loop is allowed at a time. If another user already has the loop paused, wait for them to resume or ask them to click Resume.
Register scan
Use the Register scan panel to read Modbus data:
Field
Description
Slave
Modbus unit ID (0–247). Usually 1 unless your device uses another address.
Big or Little — word order for 32-bit and 64-bit types (same as Model Editor).
Results show register index, decoded Value, hex, and binary columns. Use Prev / Next when the read spans more than one page.
Your last Slave, Function, Register, Length, data type, and byte order choices are remembered in a browser cookie for the next session.
Function codes (FC)
The Function dropdown selects which Modbus table to read. Mod Scan 360 uses the same four read function codes as the Model Editor register types. The Register field is always the 0-based PDU address (not the 1-based “40001” style label printed on some datasheets).
FC
UI label
Modbus table
Typical use
Writable?
Max length
01
01 Coil
Coils (0xxxx)
Digital outputs, relay commands, on/off control
Yes — double-click Value (uses FC05)
2000 bits
02
02 Discrete Input
Discrete inputs (1xxxx)
Digital inputs, limit switches, status bits
No — read-only
2000 bits
03
03 Holding
Holding registers (4xxxx)
Measurements, setpoints, configuration (most common for energy meters)
Yes — double-click Value (FC06 / FC16)
125 registers
04
04 Input Reg
Input registers (3xxxx)
Read-only measurements from the device
No — read-only
125 registers
Address examples (0-based PDU):
Datasheet / Modbus label
FC to select
Enter in Register field
Coil 00001
01 Coil
0
Discrete input 10001
02 Discrete Input
0
Input register 30001
04 Input Reg
0
Holding register 40001
03 Holding
0
Holding register 40100
03 Holding
99 (40001 + 99 = 40100)
Note
When you add the point in the Model Editor, register addresses are entered in 1-based form (e.g. holding 40001). Mod Scan 360 uses 0-based PDU — subtract one from the 4xxxx/3xxxx number, or use the conversion table above.
Choosing the right FC: If the meter manual lists a point under “Holding registers” or “4xxxx”, use 03 Holding. If it is under “Input registers” or “3xxxx”, use 04 Input Reg. Using the wrong FC often returns exception codes or nonsense values even when the address number looks correct.
When FC 01 or 02 is selected, the result table shows one row per bit and the Data type dropdown is limited to Bit only.
Data type and byte order (Big / Little)
After a successful read, Mod Scan 360 combines one or more 16-bit register words and decodes them as the selected Data type. Options match the Model Editor exactly — use the same type and byte order in both places so live EMS values match what you see in Mod Scan 360.
The Data type and Big / Little dropdowns are in the result table header (not in the scan form). Changing them re-decodes the last response immediately without sending a new Modbus request.
Data type
Registers consumed
Description
Bit
1 per row (FC01/02) or 1 word (FC03/04)
For coils/discrete inputs: 0 or 1 per bit. For register FCs: least significant bit of each 16-bit word.
Int8 / UInt8
1
Low byte of one 16-bit register (signed or unsigned).
Int16 / UInt16
1
Single 16-bit integer — the most common type for simple meter values.
Int32 / UInt32
2 consecutive registers
32-bit integer spanning two registers starting at the address you entered.
Float32
2 consecutive registers
IEEE 754 single-precision float (typical for kW, voltage, power factor on many meters).
Int64 / UInt64
4 consecutive registers
64-bit integer (e.g. large energy counters).
Float64
4 consecutive registers
IEEE 754 double-precision float.
Each decoded row advances by the number of registers that type needs. For example, with Float32 at register 0, row 1 uses registers 0–1, row 2 uses registers 2–3, and so on. Set Length high enough to cover all registers you want to inspect.
Big endian vs Little endian
The Big / Little dropdown controls register word order when a value spans more than one 16-bit register (32-bit and 64-bit types). It uses the same rule as Byte Order in the Model Editor.
Setting
Effect
Big (default)
Registers are combined in the order returned by the device — first register is the high word.
Little
The two 16-bit words are swapped before decoding (low word first). Use this when the decoded Float32 or Int32 looks wrong with Big.
Example: A Float32 at holding registers 40020–40021 returns raw words 0x41A0 and 0x0000. With the correct type and byte order you might see 20.0; with the wrong order you might see a very large or NaN value. Try Float32 with Big first, then switch to Little if the value does not match the device front panel.
For single-register types (Int16, UInt16, Int8, UInt8), Big and Little produce the same result — byte order only matters for multi-register types.
Tip
Commissioning workflow: read with 03 Holding or 04 Input Reg, try UInt16 first for integer points, then Float32 for engineering values. Toggle Big / Little until the Value column matches the meter display, then copy the same Data type and Byte Order into the Model Editor.
Connection and frame log
Connection — summarizes how EMS reaches the loop (TCP IP:port, serial port, or UDP gateway).
Frame statistics — TX, RX, OK, Fail, CRC, exception, and no-response counts. Click Reset to clear counters.
TX / RX frames — expandable log of raw hex frames (up to 200 entries). Use Copy to paste into a ticket or compare with a standalone Modbus tool.
Writing a value (test write)
Run a read on Holding registers (FC03) or Coils (FC01).
Double-click the decoded Value cell in the result table.
Enter the new value in the write dialog (coils: 0 or 1; registers: numeric value matching the selected data type).
Click Write. FC05 (single coil), FC06 (single register), or FC16 (multi-register for 32-bit types) is used automatically.
Note
Test writes go directly to the field device. Use only on equipment you are allowed to control. Input registers and discrete inputs are read-only.
Permissions
Opening Mod Scan 360 requires View permission on the protocol menu (Digital Meter, Modbus RTU, or Modbus TCP) under Administration → Users → Permission. Users without access to that menu cannot open the tool.
Typical workflow — find the correct register for a model
Open Mod Scan 360 on the target loop and confirm the connection line matches your gateway or serial port.
Set Slave to the device unit ID.
Choose 03 Holding, enter a guessed Register address (0-based), set Length to 10, and press Play.
Adjust Data type and Byte order until the decoded value matches the device display or datasheet.
Click Resume when finished so normal polling restores live data.
Tip
If live values stay stale after closing Mod Scan 360, click Resume once more or refresh the device list. The EMS background service must be running (Administration → System → Services).
COMTRADE Waveform — oscilloscope viewer
Use Waveform to review disturbance captures from PowerLogic PM8000 (and similar) meters. Files are downloaded over FTP in COMTRADE format and plotted as dual Voltage / Current panes.
When the Waveform icon appears
On a meter detail page, the header Waveform icon () appears only when all of the following are true:
Administration → Settings → Waveform → Enable COMTRADE Waveform is on.
The meter is on a Modbus TCP loop.
The device model is Waveform-capable (e.g. PM8000 family as listed in Settings).
Waveform FTP is enabled on that device (Waveform tab) with a user name saved.
If the icon is missing, ask an administrator to complete Waveform setup and confirm the Waveform API is Online on the Services page.
Open the viewer
Open the meter under Devices.
Click the Waveform icon in the meter header — a modal loads the viewer, or use Open in new window.
Alternatively open waveform.php?meter_id=… directly.
Sync and browse events
Click Sync from meter to download new COMTRADE pairs from the meter FTP folders. Status shows downloaded / skipped / repaired / failed counts.
The left list shows events ordered by capture time (dd/mm/yyyy hh:mm:ss, using the site timezone from Preferences). The secondary line is the event id (includes folder path such as COMTRADE_1/08-2026/01/…).
Select an event to load channels. Toggle V1–V3 / I1–I3 and use zoom / pan on each pane (Voltage and Current use separate scales).
Every N pts downsamples dense captures for smoother plotting. Export PNG or CSV (CSV includes time_ms, absolute timestamp, and selected channels).
Note
COMTRADE timestamps in the .cfg file are treated as UTC and converted for display using the EMS Preferences timezone (e.g. Asia/Bangkok). Sync does not run automatically at boot — use Sync from the viewer when you need fresh captures.
Viewing trends and history
Open Trend & History → General, select points and a date range.
For peak load, open Demand Chart under the same menu.
Import History — backfilling from Excel (XLS)
Open Trend & History → Import History to bulk-load historical readings from an Excel export into one or more devices at once. This is the same file layout produced by IAQ Report's "one sheet per device" / "devices across columns" Excel exports (see IAQ Report) and by similar EMS history exports, so a common workflow is: export history from one site, then import it into another site or a replacement device.
Upload — drag the file onto the drop zone, or click to browse. Only .xls / .xlsx are accepted here, max 50MB (see the format rules below).
Pair devices — EMS reads the device blocks from the file header and lists them on the left; for each one, choose a Target device (a loop or regular meter you have edit permission on) from the dropdown on the right. Unpaired blocks are skipped.
Property mapping — one shared mapping applies to every paired block (properties are assumed identical across devices in the same file): match each column in the file to a point on the target device's model, or leave it Ignore to skip that column.
Begin date / Start time — pre-filled from the file (either the first Time value found, or the date encoded in the filename). Only used as a fallback for rows where the Time cell itself is empty.
Preview (optional) — shows a sample of parsed rows plus row/error counts before anything is written, so you can catch a bad mapping early.
Import — writes the data. The result summary shows counts for New rows (no existing reading for that point + timestamp), Replace rows (an existing reading at that exact timestamp gets overwritten with the imported value), and Error rows (could not be parsed — listed with the reason).
Required Excel layout
The parser expects a fixed 3-part layout — device names, then property names, then data — with time always in column A:
A
Meter-101
Meter-102
Time
kW
kWh
kW
kWh
2026-07-17 00:00:00
12.4
1050.2
8.1
640.0
2026-07-17 00:05:00
12.6
1051.3
8.0
640.3
Row 1 — one device name per block of columns. A new name starts a new device block; it continues until the next non-blank name (so it can span several columns without repeating the name in every cell).
Row 2 — the property/point name for each column within its device block. A column with no name in row 2 is not offered for mapping.
Row 3 onward — data. At least one data row is required (file needs 3+ rows and 2+ columns total, or the upload is rejected).
Column A ("Time") — either a full timestamp YYYY-MM-DD HH:MM:SS, or a date-only value YYYY-MM-DD ("month mode"), which is treated as that day at 00:00:00. DD/MM/YYYY, MM/DD/YYYY, and 12-hour AM/PM formats are also recognized. If a row's Time cell is blank, EMS falls back to the detected/entered begin date + start time + 5 minutes per row.
Numeric values — plain numbers; both . and , are accepted as the decimal separator (e.g. 12.4 or 12,4).
Filename matters
The uploaded filename must end with a date, e.g. history20260717174902.xls (YYYYMMDD, optionally followed by HHMMSS) — this is the fallback date/time source when the Time column can't be read. A file renamed to something like report.xls is rejected before the sheet is even opened.
Importing into a single device
Each device's detail page (Devices → [loop] → meter) also has its own Import history icon in the header. It uses the same engine but targets one meter at a time, accepts .csv as well as .xls/.xlsx, and lets you map each column to a point manually instead of auto-detecting device blocks — useful for a plain CSV export from another system, or a file that doesn't follow the multi-device layout above.
Handling alarms
Check the Alarms section for offline devices and pending events.
Review alarm history and notify an administrator if action is required.
Generating reports and bills
Open Billing, select the bill type and reporting period.
Generate and export the report. Use Reports for Solar Comparison or CPM Monthly Log Sheet.
IAQ Report — indoor air quality (AQI) history export
Open Reports → IAQ Report to export historical readings from air-quality sensors (PM2.5, PM10, CO2, TVOC, temperature, humidity, and similar points) as Excel, PDF, or CSV.
Source — Group pulls every device already in a Group item (same groups as Sites / Group-Template); Device lets you pick a Group Template (for the column layout) and select individual devices directly.
Begin / End — the export window; limited to 31 days per export.
Interval — sampling step from 1 minute to 1 hour.
Decimal places and Export Date/Time format — cosmetic formatting for the exported file (4 date/time formats available, including 12-hour AM/PM).
Output — choose the file shape independently of format:
Excel — one sheet with devices across columns (recommended), one workbook with one sheet per device, or a separate workbook per device (zipped).
PDF — one combined file, or a separate PDF per device (zipped).
CSV — one file, devices across columns.
The Sheet Header tab controls what appears on each exported sheet/page: device name, loop name, description, and/or custom free text, plus an optional report title and logo (used on PDF pages only). Enable Include Min / Max / Average summary rows to append per-column statistics — like the "Summary" row in Group Value tables (see Modules), blank and non-numeric cells are excluded from these statistics rather than counted as zero.
Excel output that other EMS tools can read back
The "devices across columns" / "one sheet per device" Excel outputs use the same row layout that Import History expects on the way back in (device name row, property name row, Time in column A) — so an IAQ Report export is a ready-made way to move air-quality history between sites or restore it onto a replacement device.
Using the E-Map
The E-Map shows sites and devices on a floor plan. Click a device icon to jump to its live data view.
Personal settings
Open My Profile to update account details and password.
Open Preferences for font, date/time, and interface options.
LINE Messaging
EMS can send alarm notifications to LINE users using rich message templates. This chapter covers setup, quota management, templates, and user registration.
Overview
The LINE Messaging system sends real-time alarm notifications (High Alarm, Low Alarm, Device Offline, etc.) as rich Flex messages to registered LINE users. It supports:
Multi-site support with site isolation
Customizable Flex message templates per alarm priority
Alarm deduplication — only sends on state change, never repeats the same status
Minute batching — first alarm sends immediately, subsequent alarms batch until the next minute
FREE / PAID mode with daily message quota control
Opening LINE Messaging Setting
Open Administration → LINE Setting from the sidebar menu.
The page is organized into 4 tabs: Setting, Quota, Templates, and Users.
Tab 1 — Setting
Core configuration for the LINE bot connection.
Field
Description
Enable
Master toggle — when disabled, no LINE messages are sent regardless of alarm state.
Description
A label for this configuration (e.g. "Factory A alerts"). For your reference only.
LINE BOT
The LINE Official Account ID (e.g. @145fxlho). Used to identify the webhook site and fetch registered users. Upload or fetch the QR code image for easy user registration.
Webhook URL
The webhook base URL provided by your LINE Webhook Manager. Use the HTTPS address supplied for your deployment.
Tip
Click Fetch QR from Webhook to automatically load the QR code image from the Webhook Manager if it has been uploaded there.
Save & Test Push
Save — persists all settings to the database.
Test Push — sends a test message to all registered LINE users to verify the connection is working.
Tab 2 — Quota
Controls how many LINE messages can be sent per day to stay within the LINE API free tier limits.
Field
Description
Mode
FREE — enforces a daily message limit. PAID — unlimited messages (no quota check).
Daily Limit
Maximum messages per day in FREE mode. Default: 10. One send to 5 users counts as 5 messages.
Usage
Progress bars showing today's usage and monthly cumulative usage against the limit.
Note
Monthly limit is calculated as daily limit × 30 (e.g. 10/day = 300/month). This matches the LINE free tier allocation of 200–500 messages/month depending on your plan.
How quota is counted
When an alarm triggers, the system counts the number of active LINE users.
If today's usage plus the number of recipients would exceed the daily limit, the message is skipped and noted in the service log.
After a successful send, the usage count is updated for the current day.
Reset Today
Click Reset Today to clear today's usage count. This deletes all log entries for the current day, restoring the full daily quota. Useful if messages were sent during testing and you want to reset before production hours.
Tab 3 — Templates
Alarm notifications use Flex message templates stored in the database. Each template defines the visual appearance of the LINE notification.
Template cards
Templates are displayed as color-coded cards. Click a card to open the template editor with:
Field
Description
Name
Template display name (e.g. Critical, Warning, Info).
Color
Header background color of the Flex message.
Icon
Emoji icon shown in the template header.
Enabled
Only enabled templates can be selected in the priority mapping.
Flex JSON
The message layout definition. Supports placeholders: {{site_name}}, {{alarm_rows}}, {{timestamp}}, {{count}}.
Priority → Template Mapping
Below the template cards is the priority mapping table. Each alarm priority level (P1–P10) is mapped to a template. When an alarm fires, the system selects the template based on the highest priority among the alarm events.
Select a template from the dropdown for each priority level.
Click Save to persist the mapping.
Tab 4 — Users
Shows all LINE users registered with the bot. Users register by adding the LINE Official Account as a friend and sending a message (e.g. "register").
Column
Description
Display Name
The user's LINE display name with profile picture.
User ID
The LINE internal user ID (starts with U).
Status
active — receives notifications. blocked / unfollowed — will not receive messages.
Registered
Date and time the user first interacted with the bot.
Click Refresh to reload the user list from the webhook service.
How alarm notifications work
The end-to-end flow from alarm detection to LINE delivery:
Detection — The EMS polling service detects an alarm condition (value exceeds threshold, device goes offline, binary state changes).
Deduplication — The alarm is checked against a persistent cache. If the same point already has the same status, it is skipped. Only state changes generate notifications.
Batching — The first alarm in a minute sends immediately. Additional alarms within the same minute are buffered and sent as a batch at the start of the next minute.
Quota check — In FREE mode, the system checks if the daily limit allows sending to all active users. If not, the message is skipped and logged.
Template selection — The alarm priority determines which Flex template to use via the priority mapping.
Delivery — The notification is sent to all active registered users.
Alarm message content
Each notification includes:
Field
Source
Time
Timestamp of the alarm event
Point name
{Device Name} : {Alias Name} format. Falls back to model point name if no alias is set.
Value
Current value with unit. Binary points show state text (ON/OFF) instead of 0/1.
Check Enable toggle is ON. Verify the Webhook URL is reachable. Ask your administrator to review EMS service status under Administration → System → Services.
Messages stopped after working
In FREE mode, the daily quota may be exhausted. Check the Quota tab. Click Reset Today if you were testing during the day.
Same alarm sent repeatedly
This should not happen — the system sends only when alarm status changes. If it does, restart the EMS background service so notification state reloads cleanly.
Test Push works but alarms don't
Alarm delivery uses the background polling service, not the web pages alone. Restart the EMS service from Administration → System → Services and try again.
Users not showing
Users must add the LINE Official Account as a friend and send at least one message. Click Refresh on the Users tab.
Troubleshooting & FAQ
Common issues and recommended resolution steps. Search for keywords such as permission, offline, or Malwarebytes.
Pages load slowly or styles fail to load
Symptoms
Browser status shows "Transferring data from …" for a long time.
Pages inside the main frame appear blank or load very slowly.
Warnings that a stylesheet could not load even though the server is running.
Cause: browser security extensions
Extensions such as Malwarebytes Browser Guard inspect network requests. On local or intranet EMS addresses, this can delay or block page resources.
Warning
Do not disable security software permanently. Whitelist your EMS URL instead.
Resolution steps
Temporarily disable the suspect extension and reload EMS.
Or test in a private window with extensions disabled.
Whitelist your EMS site address in the extension.
Hard-refresh (Ctrl+F5) and retry.
Still slow after whitelisting?
Check Administration → System → Services.
Review server/database performance with IT.
Use the browser developer tools (F12 → Network) to find requests with long Waiting time.
A menu item is missing from the sidebar
Ask an administrator to enable View under Administration → Users → Permission.
A new site folder or group item does not appear in the tree
Confirm you have Add on the Sites permission.
Hard-refresh (Ctrl+F5) if the list updated but the sidebar did not.
Expand the parent site or folder caret in the tree — new items are added under the correct parent.
If you added the first child under a new empty folder, expand that folder once; the tree upgrades the node automatically.
Sites Add or Save shows a name validation hint and the modal stays open
The name field cannot be empty or whitespace only. Enter a visible name and click Add or Save Change again. This applies to sites, folders, group items, and related rename dialogs.
"Authentication failed, please login again"
Your session expired. Log in again. If this repeats, verify your account is active.
A device shows offline or values are not updating
Verify device network and configuration under Devices → [protocol].
Check Administration → System → Services.
For Modbus loops (Digital Meter, Modbus RTU, Modbus TCP), open Mod Scan 360 on the loop to test raw register reads and inspect TX/RX errors.
Waveform icon is missing on the meter page
Confirm Administration → Settings → Waveform → Enable COMTRADE Waveform is on.
Confirm the meter is Modbus TCP and uses a Waveform-capable model.
On the device edit dialog → Waveform tab, enable Waveform FTP and save a user (and host/password/folders as needed).
Hard-refresh (Ctrl+F5) and reopen the meter.
Waveform Sync fails or the event list stays empty
On Administration → System → Services, confirm Waveform API is Online (port 8095). Use Start / Restart if it is Offline.
Verify meter FTP credentials and that COMTRADE_1 (etc.) exist on the meter.
Check that /opt/meter/data/Waveform/ is writable by the web/API user (www-data on Linux).
Ask an administrator to re-save the device Waveform settings so configs/meter_{id}.json is refreshed under the data root.
Confirm you are on the Virtual Meter loop list page (not another protocol), and drop onto a Virtual Meter row or card — a blue outline should appear while hovering.
Drag a meter device from a physical loop in the tree, not a point/tag leaf.
Confirm your account has Add permission on the Virtual Meter menu.
Right-click a loop row under Digital Meter, Modbus RTU, or Modbus TCP — not a meter/device row, and not BACnet or other protocols. Ask an administrator to grant View on the protocol menu if you see a permission error when opening.
"Session busy" or another user has the loop paused
Only one debug session per loop is allowed. Wait for the countdown to expire, or ask the other user to click Resume or close their Mod Scan 360 modal.
"Could not pause loop" or Play stays disabled
Confirm the EMS background service is running (Administration → System → Services).
Check that the loop is enabled in the loop list.
Retry after a hard refresh (Ctrl+F5).
Reads fail (CRC, exception, no RX) but the device works in another tool
Confirm Slave ID and 0-based register address (40001 → 0).
Match Function to the register table (holding vs input).
For TCP/RTU gateways, verify the loop IP, port, or serial settings under Devices → [protocol] → Edit loop.
Compare raw frames in the TX/RX log with your standalone Modbus client.
Live values did not return after closing Mod Scan 360
Click Resume in the modal before closing, or wait for the 5-minute idle auto-resume. If values are still stale, refresh the device view or restart the loop from the loop list.
License shows "Inactive", "HWID mismatch", or a stop countdown
Open Administration → System → Software License and click Activate on the license key row.
Confirm the HW ID shown in the Activate dialog matches the machine you requested the license for — a token generated for a different machine's HW ID always fails with an HWID mismatch, even if the license key itself is correct.
Request or paste a token for the correct HW ID, then Activate and restart the service when prompted.
If the countdown reaches zero, the background EMS service stops until the license is fixed and the service is restarted — the web pages themselves keep working, but live device data stops updating. See Software License in the Administrator Guide.
"Device limit reached" when adding a new device
The number of enabled devices has reached the quota on the currently active license(s). Disable or remove devices you no longer need, or activate a license with a higher device count, under Administration → System → Software License.
"No permission to add/edit/remove" when saving
An administrator can grant the missing right under Administration → Users → Permission. On the Model Editor, Add controls the add form (Add, Clear), Import/Export, Upload Image, and the Copy icon; Edit controls the Edit icon and Edit Point popup; Remove controls the trash icon.
Model Editor — common issues
Add, Clear, Copy, Import, or Export is missing
Your group needs Add on the Models permission. Ask an administrator to enable it under Administration → Users → Permission.
Edit icon or Save in popup is missing
Your group needs Edit on the Models permission.
"Input Point Name is empty" or "Input Register number is empty"
Point Name and Register are required before Add or Save Change will succeed.
Import or Export shows nothing / no popup
Hard-refresh the page (Ctrl+F5).
For Import, upload a CSV first — the file name must appear before Import will run.
Check the browser developer console (F12) for errors.
Edit or Copy popup does not open or only works once
Hard-refresh the page (Ctrl+F5) to reload the page fully.
Check the browser developer console (F12) for errors.
Ensure browser extensions are not blocking scripts (see the Pages load slowly section in Troubleshooting / FAQ).
"No available Point ID" when copying
All Point IDs 1–255 are used in the target model. Remove an unused point or pick another model.
Paste to Add form did not fill fields
Open the Copy popup from a row first (so source data loads), then click Paste to Add form. If the add form was edited manually, click Clear before pasting again.
Imported points do not appear on devices
After import, accept reset the system when prompted, or reset services from Administration → System → Services so polling reloads the model.
Point ID not in dropdown when adding
All IDs 1–255 may be in use, or the ID is reserved. Remove an unused point or choose another ID.
A report or bill export does not download
Allow pop-ups and downloads from the EMS site.
Confirm the date range contains data.
Wait for large exports to finish.
The page area is blank after clicking a menu item
Rule out browser extensions (see above).
Refresh (F5), clear cache, or try another browser.
A database update failed
Run Administration → Database → Backup before retrying.
Note the exact error and contact support.
Finding this manual again
Open Administration → User Manual. Use the search box to find topics across all chapters. See Version History for release notes and upgrade steps.
API Reference
This REST API returns live meter point values from the EMS system, plus trend history, device
offline status, pending alarms, and (with a write-enabled key) loop/device management. Each
record includes point name, description, and unit
so third-party applications can display data without maintaining a separate tag list.
Authentication
Your EMS operator will provide a private API key (sdkey). Include it on every
request using the query parameter sdkey or the HTTP header X-API-Key.
Do not publish or embed this key in public client-side code. Keys are managed from
Settings → API (Admin only).
Each response combines live values (always read from EMS in real time) with
point metadata (device name, loop, point name, description, unit from the EMS database).
Metadata is cached on the server for about 300 seconds per
meter_id so repeated calls are faster.
Third-party clients normally do not need refresh_cache. Use it only when
point names or units were changed in EMS and the API must show the updated definitions immediately.
Parameters
Name
Required
Description
sdkey
Yes
API key issued by your EMS operator (or send the same value in header X-API-Key)
meter_id
Yes
Device ID (numeric identifier for the meter / station)
port
No
EMS JSON service port (default 8080)
refresh_cache
No
Optional. Set to 1 to bypass the metadata cache and reload
device and point names/units from the database for this request.
Omit for normal polling (default). Live value / alarm fields are never cached.
Refresh metadata example
After EMS operator changes a meter model or point list, call once with refresh_cache=1:
Global point reference (device_id×1000 + point_id)
point_id
Point index within the device model
point_name
Tag name from model
point_description
Description from model
unit
Engineering unit from the point definition
value
Current value
online
Point online status
alarm_low / alarm_high / alarm
Alarm flags
state_text
Alarm / state message if any
2) Trend / log history API
Returns historical samples for one point over a requested time range.
The response includes point metadata (reference_id, full_name, point_name, point_description, unit, and device/loop fields)
and a flat data array of time_stamp/value samples for charting or export.
Returns the current list of offline meters/devices (same information shown on the
EMS “Device Offline” page). Each row includes device name, loop, address, model, and last-known offline time.
Returns active pending alarms (same information as the EMS
“Alarm Pending” page). Each row includes device, point, alarm message, value, unit, and status.
Endpoint
Recommended URL:
https://your-ems-server/api/alarm_pending/
Local (8080): https://your-ems-server/api/alarm_pending/?sdkey=YOUR_SDKEY&mode=local
Central (8081): https://your-ems-server/api/alarm_pending/?sdkey=YOUR_SDKEY&port=8081
Read, create, edit, or remove loops (RTU/TCP/BACnet/Digital Meter/Virtual Meter/Software
Module transports). GET (read) only needs an sdkey with read access — the
same scope used by the APIs above. POST/PUT/DELETE (write) require an
sdkey with write access enabled from Settings → API; a read-only key is
rejected on those methods.
Endpoint
https://your-ems-server/api/loops/
Methods: GET (read) | POST (create) | PUT (edit) | DELETE (remove) | Response: JSON
Read (GET)
List all loops: https://your-ems-server/api/loops/?sdkey=YOUR_SDKEY
Single loop by id: https://your-ems-server/api/loops/?sdkey=YOUR_SDKEY&id=7
Single loop by loop_number: https://your-ems-server/api/loops/?sdkey=YOUR_SDKEY&loop_number=1
With id or loop_number, the response is {"status":"O.K.","code":200,"loop":{...}} — one object with id, loop_name, loop_number, loop_ip, loop_port, loop_enable, loop_description, loop_protocol, device_count (RTU loops also include decoded loop_serial_port/loop_baud/loop_parity/loop_stopbits/loop_bytesize). Without either param, the response is {"status":"O.K.","code":200,"count":N,"loops":[...]} listing every loop in the same shape. Field names match the POST/PUT body, so a GET response can be edited and sent straight back as a PUT.
Read, create, edit, or remove devices (meters) on an existing loop. GET
(read) only needs read access; POST/PUT/DELETE (write) require a
write-enabled sdkey, same as the loop API above.
Endpoint
https://your-ems-server/api/devices/
Methods: GET (read) | POST (create) | PUT (edit) | DELETE (remove) | Response: JSON
Read (GET)
List all devices: https://your-ems-server/api/devices/?sdkey=YOUR_SDKEY
List devices on one loop: https://your-ems-server/api/devices/?sdkey=YOUR_SDKEY&loop=1
Single device by id: https://your-ems-server/api/devices/?sdkey=YOUR_SDKEY&id=6
With id, the response is {"status":"O.K.","code":200,"device":{...}} — one object with id, name, loop, addr, model, description, enable, sn, remark, ct_pri, ct_sec, retry, loop_name. With loop or no params, the response is {"status":"O.K.","code":200,"count":N,"devices":[...]} listing matching devices in the same shape. Field names match the POST/PUT body, so a GET response can be edited and sent straight back as a PUT.
Read-only lookup of models in the Model Library (id + name), e.g. to resolve the
model id used by the device management API above into a display name.
Same read-access sdkey scope as the other read-only endpoints — no write access needed.
Endpoint
https://your-ems-server/api/models/
Method: GET | Response: JSON
Parameters
Name
Required
Description
sdkey
Yes
API key (or header X-API-Key)
id
No
Return a single model instead of the full list
Without id, the response is {"status":"O.K.","code":200,"count":N,"models":[...]} — every model, sorted by name, each with id, model_name, model_description. With id, the response is {"status":"O.K.","code":200,"model":{...}} — a single object in the same shape.
{"status":"O.K.","code":200,"count":2,"models":[{"id":1,"model_name":"CVM-C10","model_description":""},{"id":7,"model_name":"PM2230","model_description":"Power Meter Schneider"}]}
Errors (all APIs)
HTTP
result
Cause
401
ERROR
Invalid or missing sdkey (loop/device APIs also return 401 when the key is valid but write access is not enabled)
400
ERROR
Missing or invalid parameters (e.g. live: meter_id; history: begin/end/pointId)
502
ERROR
Service unreachable or no usable JSON (check port and that the EMS/Central service is running)
Endpoint base URL may differ per site; use the value shown above (generated from this request).
Version History
Release notes for EnergyLink360 EMS — the same platform behind the live Demo.
C-Loop Meter loop (protocol 11) — loop:create accepts a serial port. The default frame is 1200 8E1. The description is stored as the note. One serial port still belongs to only one loop.
Digital Meter C-Loop (protocol 0) — meter_framecloop stores {"frame":"cloop","note":"..."}. EMS stays the UDP client and sends C-Loop frames to the configured IP and port. Omit meter_frame, or set modbus, and the loop stays Modbus RTU over UDP with a plain-text description.
v2.9.0
October 2026
AI assistant integration (MCP) with Change Set approval, Logical Device loops that mirror BACnet points, MQTT write and readback completed end to end and manageable through MCP, cloud Model versions as major.minor, and several list and event fixes.
MCP / AI Assistant — new Plug-Ins → MCP page (Overview, Access Tokens, Edit Mode up to 6 hours, Change Sets, Model Image, Audit Log). An AI assistant reads EMS through 174 tools and proposes changes as Change Sets that a person approves; the home page shows a popup with field-level Before/After when approval is pending. See the new MCP / AI Assistant manual chapter.
MCP can manage loops, devices, models and points, Cloud Library import, Model images, sites, device groups and templates, schedules and holidays, point detail, E-Map pages and objects, and read alarms, live values, history and reports.
Administrator auto-apply — an administrator write token can apply directly with a pre-change backup and read-back verification; deletes need explicit confirmation. Retries with the same request id return the same Change Set; impact preview shows what a delete or Model change would break.
Logical Device (loop protocol 10) — a device whose Model Properties are mapped to BACnet points. Mapping page with live values and status (mapped / unmapped / broken / incompatible), history and commands through the mapped source, runtime reload without restart. Logical Devices do not use a license slot.
BACnet through MCP — background discovery jobs with status and cancel, point import that keeps point ids and marks vanished objects missing, manual BACnet device add with duplicate check, BACnet settings, multi-point live values with quality and source timestamp, and point commands that return the controller's real result.
MQTT — MQTT Model points (read, write, state options, min/max/step, readback) and MQTT devices (Device Key, Topic Variables, offline timeout) can be created and edited through MCP; JSON paths accept $.a.b; an operator click republishes a command even when the priority slot already holds that value. New full MQTT Device manual chapter.
Model Library — Publish and Download let you choose the next cloud version as a minor or a new major (v1.2 / v2.0); a model whose saved library link is missing on the selected cloud publishes as v1.0.
Device tree — offline devices are shown in red (disabled stays gray). Admin API tokens read every loop and report live device online state.
Models page and the device list (List / Edit view) show 16 rows per page with Previous / Next always at the bottom.
Real Time Event — a device that stays online (e.g. Software Module devices) no longer logs "Device Online" every cycle; only real Online/Offline changes are logged.
Database Update adds BACnet discovery columns and tables, Change Set retry columns and the BACnet discovery timeout setting. The API no longer changes the schema itself and answers schema_update_required until Database Update has run.
v2.8.10
September 2026
MQTT Device write configuration can now live at the Model level, {device_key}-templated just like the read (Subscribe) side — so one Model's Write setup (state options, min/max/step, readback) works for every device pulled from it, instead of requiring the full Write tab to be re-entered per device. Model-level write config also now travels through CSV export/import and cloud Model Library publish/pull.
Model-level MQTT Write config — the Model Editor's point MQTT tab gained Write Mode (State/Range), State Options (value/label/payload rows), Min/Max/Step, and Readback Topic fields, matching what was previously only settable per device. A device with no Write override configured now falls back to the Model's write template, rendered with that device's own {device_key}/Topic Variables — exactly mirroring how Subscribe Topic already worked.
A device-level Write override (per-device literal topic, set from the device's own MQTT Point Bindings) still takes priority when present — this is purely an additional fallback, not a behavior change for existing per-device configuration.
Cloud Model Library — a published model's Write config (state options, min/max/step, readback topic template) now travels with it through publish/pull/rollback/revision snapshot, so pulling a Model from the library gives a fully working read+write device once a Device Key is set, with no additional per-point setup.
CSV export/import extended to round-trip the new Write fields alongside the existing MQTT read fields.
Fixed a latent bug in the local model/cloud change-detection hash: an MQTT write-mapped point would always be reported as "changed" during Pull Preview even when nothing actually differed, due to an internal field only present on one side of the comparison.
Live reload on Model edit — saving, deleting, importing (CSV), pulling, or rolling back a Model Point now automatically hot-reloads every MQTT Device loop that has a device built from that Model, so a Model-level MQTT change (read or write) takes effect immediately instead of only after someone separately edits a Loop/Device or restarts the EMS service.
v2.8.9
September 2026
MQTT Device write path completed end-to-end (priority writes, readback confirmation, REST API persistence), reusable {device_key} topic templates, Model Library moved to a DB-backed multi-provider setting with cloud API v1/v2, and several MQTT read/display fixes (Formula Expression, Multi State Text, Time Stamp).
MQTT Device — write path: point commands now go through the same priority-based write arbitration as Modbus/BACnet; optional readback confirmation (present value withheld until a configured reply topic/path confirms the write, or the write times out); outbound publish handled by the EMS service runtime.
REST API — api/loops and api/devices now persist MQTT loop/device configuration on create and update (previously silently dropped for protocol 9).
Reusable topic templates — Model point topics support a {device_key} placeholder; a new Device Key field (Add/Edit Device) lets one Model be reused across many devices with the same JSON schema, with no per-point topic editing.
Topic templates — a topic can now use any number of named placeholders beyond {device_key} (e.g. building/{building}/{zone}/{device_key}/sensors), resolved per-device from a new Topic Variables (JSON) field on the device (previously only {device_key} was accepted, anywhere).
Formula Expression now applies to MQTT points (previously silently ignored), using the same =x + pid.N evaluator as Modbus; the Modbus evaluator itself was also hardened so a malformed formula can no longer crash the point read.
Multi State Text now resolves correctly on the MQTT Live value display (state label instead of a raw number) when the point's Data Type marks it as non-numeric.
Time Stamp (catagory 8) display fixed for MQTT points carrying an ISO-8601 / string timestamp (e.g. Tasmota sn.Time), alongside the existing numeric Unix-timestamp case — both now render as dd/mm/yyyy HH:mm:ss.
Security — CSRF checks added to remove_loop.php, remove_device.php, remove_model.php, remove_model_point.php, and the E-Map write-command API; E-Map Editor gained a CSRF token bootstrap (previously missing entirely); MQTT point-mapping edits in add_model_point.php / update_model_point.php now check menu write permission.
CSV export / import now round-trips a model's MQTT point configuration (previously dropped on export/import).
Model Library — the cloud endpoint URL and API key moved from a hardcoded configure.php setting to a DB-backed Library Settings modal (single active library, extensible for future providers/versions); each library now targets API v1 (frozen) or v2 (MQTT-aware).
Model Library — Upload to Cloud on a v2 library now requires re-confirming the current login password.
Cloud Library UI (model_detail.php) — new MQTT tab for viewing/editing a model point's MQTT read/write mapping.
Add Model dialog — fixed dialog size across the Manual / From Library tabs, and pagination on the Library browse tab.
Fixed a Save crash on a Model Point whose Register Type, Data Type, Category, or Byte Order did not match any dropdown option (common on MQTT-only points).
Fixed htmlspecialchars(): Passing null deprecation warnings on several meter-detail fields in meter.php.
User Manual — new Model Editor — MQTT Device administrator guide chapter (loop/device setup, the {device_key} reuse pattern, MQTT point field reference, and troubleshooting).
v2.8.8
August 2026
MQTT Device protocol (read/write mapping), COMTRADE Waveform for PM8000, and E-Map Editor multi-select / alignment improvements.
MQTT Device — new Modbus-alternative protocol path: loops/devices, subscribe topics, point mapping in Models, and EMS service runtime (mqtt_device_service).
MQTT service — JSON Pointer (/a/0/b) and legacy dotted paths; direct scalar payloads; freshness timeout 0 for retained / event-driven devices; status debug logging.
E-Map Editor — multi-select and alignment tools; animation import and binding / poller polish; optional write-command binding helpers.
Waveform API — separate service from ems_main (/opt/meter/ems/waveform/, port 8095); data under /opt/meter/data/Waveform/ as {meter_id}/COMTRADE_n/MM-YYYY/DD/.
Waveform UI — meter header viewer (dual Voltage/Current), Sync from meter, event times from CFG (+ Preferences timezone), PNG/CSV export; Services page Start / Stop / Restart.
User Manual — MQTT/Waveform operator and administrator notes, Modules entry, and Troubleshooting FAQ for Waveform.
EMS service — localhost Realtime Catalog bridge for Waveform sync events.
v2.8.7
July 2026
SQLite history save hardening for BACnet/FX80 bad values, BACnet discovery Replace and tree icons, and MySQL connection reliability.
EMS service — meter history SQLite: fix Diagnostic saveHistSqlite failed: no such column: None when FX80/JC BACnet points return None / NaN / Inf / empty values (sanitize to 0, parameterized inserts, per-row insert so one bad point cannot abort the whole loop).
EMS service — history flush: single-flight lock (wait for all loop writers); meter_value and state_change commits are split; invalid state events are dropped instead of rebuffered forever; retention delete runs only at 15:30.
EMS service — BACnet poll: sanitize presentValue + offset before store; safe point lookup so a missing point does not abort the RPM group.
BACnet — Discovery Replace: if the instance already exists but name/unit differ, UPDATE and keep the existing point_id.
BACnet — Sites / Devices tree icons for analog and binary write metadata; kWh trend uses bacnet_point.catagory for chart category.
EMS service — MySQL connect / close helpers with bounded retries for global settings and related loops.
v2.8.6
July 2026
Meter history import tools, IAQ report / mail export upgrades, Sites tree drag-and-drop fixes, and faster report exports.
Schedule — weekly Exception2 row (except type 2) in the editor, holidays modal, PDF export, and runtime evaluator; restart the EMS service after upgrade.
Schedule — editor UX: clearer grid contrast, toolbar icon grouping, readable Konva labels, and holiday intro text shortened.
Schedule / Logic / Software Module — modal helper fix for Bootstrap 5.0 beta (getOrCreateInstance missing) so Add / Edit dialogs open reliably.
Modbus TCP — per-loop Timeout (1–10 s) on Add / Edit Loop; stored in loop_setup.loop_timeout and applied by the Modbus TCP reader (hot-apply on edit).
Edit Group — toolbar and table layout aligned with Real Time group view; cleaner meter selection UI.
Sites — device list and explorer UI improvements with clearer sync between tree and iframe content.
EMS service — BACnet write queue: each device thread dequeues only its own IP (no shared .clear() racing other loops).
EMS service — alarm checks use safe point lookup to avoid KeyError when a meter/point is purged mid-scan.
EMS service — MQTT sync_config drain under lock; nested data_value point snapshot under one runtime lock (TOCTOU fix).
v2.8.3
July 2026
Schedule module, REST API expansions, Digital Meter log tooling, and license / backup hardening.
Mod Scan 360 — User Manual chapter: opening from the loop context menu, debug session (pause / 5 min auto-resume), Function codes FC01–FC04, data types, and Big / Little endian decoding.
Mod Scan 360 — register scan, TX/RX frame log, frame statistics, and test write (double-click Value) for Digital Meter, Modbus RTU, and Modbus TCP loops.
Sites — recursive delete for folders and groups with confirmation counts; cleans up child site_point rows and item_order.
Sites — deep Copy/Paste for folders and group items (nested children, points, and display order).
Sites — drag-and-drop reorder and move between folders in the Sites tree.
Modbus TCP — per-loop start/stop when creating or deleting loops without restarting the entire EMS background service (same behaviour as Modbus RTU).
Reports — improved PDF and Excel export for device detail and trend tables.
License — online token verification via the local EMS service (with decrypt_lic fallback); license key format normalization when adding a key.
Device tree — context menu and icon sync fixes after site and loop changes.
v2.7.0
July 2026
Software Module simulators, Real Time Event diagnostics, and database upgrades for restored sites.
Mod Scan 360 — integrated Modbus register debugger for Digital Meter, Modbus RTU, and Modbus TCP loops (pause polling, scan, frame log, test write).
Software Module — simulator point types: Fixed, Sine wave, Random analog (range), Random bit (configurable interval), and Other.
Software Module — edit point Type after create; Decimal places field (0–6, default 2) for analog display.
Database update — Software Module upgrades for simulator settings run automatically from Administration → Database → Update.
Real Time Event — Diagnostic category shows service errors (serial port, loop link, Logic Studio runtime, data save failures). Filter by Category → Diagnostic.
Logic Studio — opens in Run mode by default (v0.2.8).
Software Device — short save confirmation without countdown progress bar.
Background service — improved serial fault reporting; compatible with databases restored from older backups after Database Update.
v2.6.88
2026
Modbus RTU trunk and session stability.
Modbus RTU trunk support for multi-device serial loops.
Session handling fixes for embedded device pages.
v2.6.87
2026
E-Map Editor, site treeview, and Model Library production connection.
E-Map Editor documentation and UI colour unification for site device icons and group layers.
Site treeview sync improvements and map UI updates.
Model Library connection switched to production server.
Improved site rename error handling and parent/child validation.
v2.6.86
2026
LINE settings, site management, and database update enhancements.
Database update — LINE bot ID and QR image settings.
Refined modal dialogs and site list pagination.
Site management icon handling updates.
v2.6.54
2026
Model Library integration and meter UI pagination.
Model Library central — publish, download, and revision snapshots.
Meter points table pagination and unified modal styling across device pages.
Older versions
Installations restored from backups earlier than 2.6.54 may need a full Database Update and service restart. Contact your EMS administrator or support if errors persist after upgrading.
MQTT Device
MQTT Device (loop protocol 9) reads and controls field devices that talk to an MQTT broker — Tasmota and ESP-based sensors, IoT gateways, PLC bridges, or any device that publishes JSON. EMS subscribes to the device's topics, extracts each point with a JSON path, and can publish commands back with a payload template. It is a different feature from Cloud MQTT, which only sends EMS's own data out to a cloud broker.
The short version
1) Create an MQTT Device loop pointing at your broker. 2) Build a Model whose points use topic templates with {device_key}. 3) Add a Device under the loop, pick the Model, and type that device's Device Key. One Model then serves every device with the same payload format.
How it works
The EMS service keeps one broker connection per MQTT loop and subscribes to every topic the loop's devices need.
When a message arrives, EMS finds the points that use that topic, reads each value from the payload with the point's JSON Path, converts it with Value Type, applies the Model's Factor / Offset / Formula Expression, and stores it as the live value.
A device is online while messages keep arriving. With Offline timeout = 0 it stays online until the broker connection drops (good for retained or event-driven devices).
A command (from the point's write dialog, a Schedule, Logic Studio or the API) goes through the same priority arbitration as Modbus/BACnet, then EMS publishes the Command Payload to the Command Topic. With a readback configured, the new value is only shown once the device confirms it.
Step 1 — Create the MQTT loop (broker)
Open Devices, click Add Loop and choose protocol MQTT Device.
Field
Description
IP Address / Port
Broker host and port. Usually 1883, or 8883 with TLS.
Client ID
Leave blank to auto-generate. If you set one, it must be unique on the broker — two clients with the same ID keep kicking each other off.
Username / Password
Only when the broker requires login. The password is stored on the server and never shown again; leave it blank on Edit to keep the saved one.
TLS
Encrypted connection to the broker.
Clean session
Start each connection without broker-side session state.
Keepalive / QoS
Keepalive in seconds, and the loop's default QoS (0, 1 or 2). A point can override QoS.
Broker credentials can only be set in this web form. The Configuration API / MCP can add devices to an existing MQTT loop but never reads or writes broker passwords.
Step 2 — Configure the Model (MQTT tab)
Open Configuration → Models, open the Model, and edit a point. On the point's MQTT tab, turn on MQTT Mapping. Model settings are shared by every device that uses the Model; saving them hot-reloads the MQTT loops that use the Model, so no service restart is needed.
Read (subscribe) fields
Field
Description
MQTT Mapping
Read/write this point over MQTT. Off = the point has no MQTT mapping.
Subscribe Topic
Topic template, e.g. tele/{device_key}/SENSOR. {device_key} and any Topic Variable (see Step 3) are replaced per device. MQTT wildcards (+, #) are not allowed — each point names its exact topic.
JSON Path
Where the value is in the payload. Accepted forms:
Dotted: ENERGY.Power, sn.ENERGY.Power
JSON Pointer: /ENERGY/Power, arrays as /sensors/0/temp (not [0])
JSONPath style: $.room_temperature — stored as room_temperature
$ — the whole payload is the value (a topic that publishes just 23.5 or ON)
Optional path to the device's own timestamp (e.g. Time). Unix seconds and ISO-8601 strings are both accepted. Blank = time the message arrived.
Write (command) fields
Leave Command Topic blank for a read-only point.
Field
Description
Command Topic
Topic to publish to, e.g. cmnd/{device_key}/POWER. Same placeholders as Subscribe Topic.
Command Payload
Payload template. {{value}} (double braces) is replaced with the commanded value: {{value}}, {"setpoint":{{value}}}.
Write Mode
State / Enum — the operator picks from a fixed list (ON/OFF, Auto/Hand/Off). Range Value — the operator types a number between Min and Max.
State Options
State mode only: one row per allowed value with Value, Label (shown on the button) and Payload (what is published). A blank Payload falls back to Command Payload with {{value}}. 1–64 rows.
Min / Max / Step
Range mode: a value below Min or above Max is clamped before publishing; Step sets the input increment (e.g. 0.5).
QoS
Per-point QoS. Default uses the loop's QoS.
Retain
Publish with the retain flag. Use with care: a retained command is replayed to the device every time it reconnects.
Readback Topic
Optional topic the device answers on after a command (e.g. stat/{device_key}/POWER). Setting it turns on confirmation: EMS waits for a reply on this topic that carries the commanded value. Blank = no confirmation.
Readback Path
Where the confirmed value sits in the reply on Readback Topic. Blank = the whole payload ($).
Formula Expression and Multi State Text
Formula Expression works as on Modbus: =x/10, or another point of the same device with =x + pid.1. It runs after the JSON value is extracted.
Multi State Text (e.g. 0:OFF,1:ON) is shown on the live display only when Data Type is Bit. With a numeric Data Type the number is shown.
Step 3 — Add devices
Open the MQTT loop and click Add Device. Choose the Model, then fill in:
Field
Description
Device Key
Replaces {device_key} in every topic of the Model, e.g. tasmota_A1B2C3. No / or spaces.
Topic Variables
Optional JSON object for extra placeholders: {"building":"A","zone":"3F"} makes site/{building}/{zone}/{device_key}/state work. A device missing a variable that a topic needs only loses that one point.
Offline timeout
Seconds without a message before the device is marked offline. 0 = never time out (retained / event-driven devices).
The device's MQTT tab shows MQTT Point Bindings — the rendered topic of every point for this device, with Read and Write sub-tabs. Reload Model Points refreshes the list after the Model changed. A Write setting entered here is a device override: it wins over the Model's write template for this one device only. Leave it empty to inherit the Model.
Example — Tasmota smart plug
Tasmota publishes tele/<topic>/SENSOR with {"ENERGY":{"Power":42,"Voltage":229}} and accepts cmnd/<topic>/POWER with ON / OFF, answering on stat/<topic>/POWER.
Every plug then only needs its own Device Key (its Tasmota topic name).
Sending commands
Open the device, click a writable point and choose a state button (State mode) or type a value (Range mode).
Commands use the same priority levels as BACnet/Modbus. Schedules and Logic Studio can drive MQTT points too.
With a Readback Topic: the value changes only after the device confirms. No confirmation within 10 seconds → the command is reported as failed and the previous value stays.
Without a Readback Topic: the command is reported as sent once it is queued for publishing. That does not prove the device switched — add a Readback Topic when you need confirmation.
Clicking the same state again re-publishes the command (useful when a device restarted and missed it); a schedule that keeps the same value does not re-publish.
Import, export and Model Library
Model CSV export/import includes all MQTT read and write fields.
Publishing to / pulling from the cloud Model Library (API v2 libraries) carries the MQTT mapping, so a pulled Model works after you set each device's Device Key.
Pull, rollback and CSV import hot-reload the MQTT loops that use the Model.
The AI assistant (see the MCP chapter) can create and edit MQTT Model points and MQTT devices through Change Sets; broker settings stay web-only.
Troubleshooting
Symptom
What to check
Whole loop offline
Broker host/port, TLS on/off, username/password. Another client using the same Client ID. Firewall between EMS and broker.
Device offline, others fine
Device Key typo — compare the rendered topic in MQTT Point Bindings with what the device really publishes (an MQTT tool such as MQTT Explorer helps). Offline timeout shorter than the device's publish interval.
Point stays blank
JSON Path does not match the payload (case-sensitive), or the payload is a bare value and the path should be $. Messages without that path leave the previous value in place.
Wrong number
Value Type (Integer truncates decimals), Factor / Offset / Formula on the Model point.
Command "failed" but device switched
Readback Topic / Path does not match the device's reply, or the reply's value differs from the commanded value (e.g. device answers ON while the option value is 1 — set the option Value to what the device reports).
Command does nothing
Command Topic placeholder not filled (Device Key / Topic Variables), point not writable, or no Edit permission.
Device gets the old command after reboot
Retain is on for that command — turn it off and clear the retained message on the broker.
MCP — AI Assistant Integration
MCP (Model Context Protocol) lets an AI assistant such as Claude or Cursor read EMS configuration and live data, and propose configuration changes, in plain language. The assistant never touches the database directly: it calls the EnergyLink360 MCP server, which calls the EMS Configuration API. Every change goes through a Change Set that a person approves in the EMS web UI, unless an administrator token is explicitly allowed to auto-apply.
Who should read this
Administrators who connect an AI assistant to EMS, and operators who approve its Change Sets. Tokens shown in this chapter are placeholders — never paste a real token, approval code or password into a chat.
How it fits together
Layer
What it does
AI client (Claude, Cursor, …)
Chooses tools and shows you the results. Talks to the MCP server over stdio (local) or Streamable HTTP (/mcp).
energylink-mcp (/opt/energylink-mcp)
174 tools. Reads with a read token, writes with a separate write token. Strips secrets from every answer and refuses paths, URLs, SQL and shell commands.
Configuration API (/ems81/api/v1)
Checks token scopes, the token owner's menu and loop permissions, Edit Mode and approvals, then reads or changes EMS.
EMS web + EMS service
Store the change and, where possible, reload the affected loop at runtime.
Plug-Ins → MCP page
Open Plug-Ins → MCP (menu 74; View permission to open, administrator for changes).
Tab
Use
Overview
Status, plus two switches: MCP access (master on/off — when off, every MCP call fails within one second, including open sessions) and Edit mode.
Access Tokens
Create read or write tokens for an owner and choose their scopes. The token text is shown once; EMS stores only a hash. Revoke tokens here.
Edit Mode
Opens a write window from 5 minutes to 6 hours. Needs a reason and your administrator password. Reads always work; writes only inside the window. Turning it off invalidates open sessions and pending approvals.
Change Sets
Everything the assistant proposed, with Before/After per field. Approve and Apply, Approve (apply later from the assistant), or approve a rollback of an applied change.
Model Image
Stage a PNG/JPEG for 15 minutes so the assistant can attach it to a Model (see Models below).
Audit Log
Every preview, approval, apply, rollback and command, with token owner and target.
When a Change Set waits for approval, the home page (index.php) also shows a popup with the field-level Before/After so you can approve without opening the MCP page.
Safety rules
Read and write are separate tokens. A read token can never change anything.
Scopes limit what a write token may touch (table below). A missing scope is reported by name, e.g. forbidden scope=devices:write.
Owner permissions apply. The token acts as its owner: menu rights (View / Edit / Add / Remove) and loop/site access are checked on every call. Administrator owners see all loops.
Edit Mode must be on for any write.
Preview first. A write tool only creates a Change Set and shows what would change. Nothing is saved yet.
A person approves in the web UI. The assistant cannot approve its own Change Set. Approval is bound to the exact target and Before/After; if the row changed in the meantime, apply fails with stale_preview and the assistant must preview again.
Rollback of an applied Change Set needs its own approval and only works if nobody changed the same item afterwards.
At most 50 operations per Change Set.
Administrator auto-apply
An administrator-owned write token may send admin_auto_apply=true. EMS then takes a pre-change database backup, applies, waits until the change is saved and reads it back, and returns status=applied — no web approval step. Rules:
Only for token owners with member type Administrator; Edit Mode and scopes still apply.
Any delete needs confirm_delete=true as well.
mode=preview_only forces the normal Preview → Approve → Apply flow even for an administrator.
The backup id is returned and listed in the Change Set; use rollback or restore it if needed.
Retries, impact and bulk
request_id (a UUID): sending the same request again returns the same Change Set instead of a duplicate. The same id with different operations is refused (idempotency_conflict).
Impact preview (get_impact) shows what a delete or a Model change would break before anything is proposed. Nothing is ever deleted silently in cascade.
Bulk tools validate every item and report ok/error per item; only valid items are proposed.
The HTTP server listens on 127.0.0.1:8765/mcp and is published through the Apache /mcp reverse proxy. Remote clients send Authorization: Bearer <ENERGYLINK_MCP_TOKEN> — a third token that is different from the read and write API tokens.
After an EMS or MCP upgrade
The MCP server loads its tools at start. Restart it (or toggle the server off/on in the AI client) so new tools appear. Existing tokens and configuration stay as they are.
What the assistant can do
Read tools never change anything. Write tools create Change Sets (one tool, write_point_value, sends a live command — see below).
Area
Main tools
Status
health, get_config_capabilities (field rules, encodings, MQTT rules — the assistant reads this before writing)
list_offline_devices, list_pending_alarms, list_realtime_events, event history
Change Sets
get_change_set_status, apply_change_set, rollback_change_set (after web approval)
MQTT through MCP
The assistant creates and edits MQTT Model points and MQTT devices with the normal Model / Device tools by adding an mqtt object. Broker settings (host, password, TLS) stay web-only; the assistant uses an existing MQTT loop (see the MQTT Device chapter).
Send only the keys you change; the rest are kept. mapping_enabled=false removes the MQTT mapping of that point.
json_path accepts a.b, /a/0/b, $ and $.a.b (stored as a.b).
write_type also accepts words like enum, digital, boolean (→ state) and numeric, setpoint (→ analog). If omitted: analog when min/max/step is set or the payload contains {{value}} without state options, otherwise state.
State points need 1–64 state_options; analog payloads must contain {{value}}.
Topics, JSON paths and Device Keys are validated with the same rules as the EMS service before the Change Set is created.
BACnet discovery and Logical Devices through MCP
Discovery is a background job.start_bacnet_discovery returns a job_id immediately; poll get_bacnet_discovery_job. A second request for the same target returns the running job. Cancel stops after the current BACnet request.
Import keeps ids. Re-importing after rediscovery keeps every existing BACnet point id, keeps names you set (the controller's name goes to discovered name), and marks vanished objects missing instead of deleting them.
Logical Device mappings map a Model Property of a Logical Device to a BACnet point. Clearing a mapping never deletes the BACnet point or history. Deleting a BACnet device turns its mappings Broken but keeps the Logical Device.
Changing a Logical Device's Model first answers with the list of mappings that will be kept and dropped; it only proceeds when the assistant resends with confirm_mapping_drops=true.
Sites: detach removes the device from the site only. Attaching a Logical Device and its BACnet source to the same site tree gives a double-counting warning.
Live point commands
write_point_value moves real equipment
It sends a command now — there is no Change Set. It needs points:write plus the owner's Edit right on BACnet / Logical Device, and is audited with target and source. Only allow it for points you intend the assistant to operate.
Uses the normal EMS command pipeline with BACnet priority 1–16 (default 16); relinquish=true releases that priority.
A Logical Device point writes to its mapped BACnet source.
The answer is the controller's real result: ok/confirmed, write_failed, timeout_* or bacnet_unavailable — never "success" just because it was queued.
Models, images and the Library through MCP
Model point encodings (data type, byte order, register type, zero-based register) come from get_config_capabilities; the assistant must not guess codes.
Model image: the assistant can send a PNG/JPEG as base64, or you stage one on Plug-Ins → MCP → Model Image or the Model page (Prepare image for MCP) and give it the Model id. File paths and URLs are refused.
Library import replacing a Model that devices use reports runtime_refresh=restart_required.
Reading the results
Result
Meaning
status=previewed, approval_required
Waiting for a person in Plug-Ins → MCP or the home-page popup.
status=applied
Saved and read back.
loop_id_reload
The affected loop was reloaded at runtime — no restart needed.
restart_required / "Meter runtime restart is required"
Saved, but the EMS service must be restarted to use it (e.g. new BACnet devices, BACnet settings). EMS never restarts itself.
warnings
Saved with a note, e.g. possible double counting.
Example requests
"Which devices in loop JC-SNE are offline right now?"
"Show the last 24 hours of supply air temperature for AHU-01."
"Create an MQTT model for Tasmota plugs with Power, Voltage and a relay ON/OFF, then add three plugs with keys plug01–plug03 to loop MQTT-1." → review and approve the Change Set.
"Discover points on BACnet device 1101 and import them." → the assistant starts a job, shows the import preview, then proposes the import.
"Map AHU-01's Supply Temp to BACnet AI:1 of controller SIM-AHU."
Troubleshooting
Message
What to do
MCP access is disabled / every call fails
Turn on MCP access in Plug-Ins → MCP → Overview.
edit mode is disabled
Open a window in the Edit Mode tab.
forbidden with scope=…
Create a write token with that scope (Access Tokens tab).
forbidden without a scope
The token owner lacks the menu right or loop/site access.
Write token is not configured
The MCP server has no write token; reads still work.
stale_preview
Someone changed the item after the preview. Ask the assistant to preview again.
approval_must_be_web
Expected — approve in the web UI.
mapping_impact
A Model change would drop Logical Device mappings; review the list and confirm.