Logo

EnergyLink360 EMS User Manual

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?

AudienceRecommended chapters
New usersOverview, System Concepts, Operator Guide
System administratorsAll chapters, especially Administrator Guide and Troubleshooting
Support / ITSystem Concepts, Modules, Installer & configure, COMTRADE Waveform, Mod Scan 360, Logic Studio, Troubleshooting / FAQ, Version History
Developers / integratorsAPI Reference

System Concepts

Understanding these core terms will help you navigate EMS menus, configure devices, and interpret reports consistently.

Core terminology

TermDescription
SiteA 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 folderA subfolder inside a site (e.g. Floor A, Folder B). Folders can contain other folders or group items.
Group itemA 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 groupA separate concept under Configuration → Group-Template — reusable device layouts, not the same as a Sites group item.
Device / LoopA physical meter, controller, or gateway connected via Modbus, BACnet, MBUS, or another supported protocol.
PointAn individual register on a device — voltage, current, power, energy, status, or alarm.
ModelA reusable template defining points, scaling, and units for a device type. Applied when adding new devices.
Permission GroupView / 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.

  1. Devices communicate with EMS polling services (Modbus, BACnet, etc.).
  2. Services write readings and status into the database.
  3. The web UI reads from the database for live views, history, and exports.
  4. Administrators change configuration through EMS pages; operators consume the results.

Supported device and protocol types

Protocol / typeTypical use
Digital MeterNative EMS digital metering devices
BACnetBuilding automation controllers and meters
Modbus TCP / RTUIndustrial meters and gateways
MQTT DeviceDevices 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.
MBUSUtility meters (heat, water, gas where supported)
Link 360Link 360 device integration
Virtual MeterCalculated or derived values from other meters — see Operator Guide → Virtual Meter
Logical DeviceA 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.
CustomSite-specific or custom integrations

Modules

EMS integrates the modules below. Each entry shows where to find it in the sidebar menu.

ModuleMenu pathDescription
SitesHome → SitesOrganize facilities into sites, folders, and group items; browse live point collections. See Operator Guide → Sites, folders, and group items.
Site Explorer & DevicesDevicesBrowse protocol loops and individual meters; view live point values for all supported protocols.
Virtual MeterDevices → Virtual MeterDerived 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 360Devices → [loop] → right-click → Mod Scan 360Modbus 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.
COMTRADE WaveformDevices → meter header → WaveformOscilloscope-style voltage/current capture from PM8000 (and similar) meters via FTP COMTRADE files. See Operator Guide → COMTRADE Waveform and Administrator Guide → Waveform.
Groups & Group TemplatesConfiguration → Group-TemplateOrganize devices into groups; save layouts as reusable templates.
ModelsConfiguration → ModelsDefine reusable point templates (registers, scaling, units) for device types. Click a model name to open the Model Editor.
Model LibraryConfiguration → Models → LibraryCentral repository for sharing device models across EMS sites. Publish, download, rate, and version-control point templates. See the Model Library chapter.
E-MapE-MapVisual floor-plan / site map for device location and status.
Logic StudioLogic StudioVisual node editor for building automation logic — timers, math, conditional logic, alarms, and point read/write. See the Logic Studio chapter.
Trend & HistoryTrend & HistoryHistorical trend charts (General), real-time Demand Chart, and bulk backfill from Excel. See Operator Guide → Import History.
Alarms & EventsAlarmsOffline devices, pending alarms, and event history.
ScheduleScheduleWeekly 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.
BillingBillingFixed Rate, TOD, TOU, and site-specific energy bill formats.
ReportsReportsSolar Energy Comparison, CPM Monthly Operation Log Sheet, IAQ (air quality) history export, and related exports. See Operator Guide → IAQ Report.
AdministrationAdministrationUsers, permissions, database tools, license, hardware info, services.
PreferencesPreferencesPersonal font, date/time, regional, and interface settings.
Plug-insPlug-insNode-RED, Line, email alerts, and site-specific integrations.
MCPPlug-Ins → MCPConnect 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

DirectoryPurpose
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)
restore/Staging area for database restore jobs
cache/dm_log/File cache for device log / trend chart / table / export APIs
cache/meter_kwh/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:

sudo mkdir -p /var/www/html/ems81/cache/{dm_log,meter_kwh}
sudo mkdir -p /var/www/html/ems81/{backup,uploads,temp,log,excel,pdf,restore}
sudo mkdir -p /var/www/html/ems81/map_editor/{data,images/markers}
sudo chown -R www-data:www-data \
  /var/www/html/ems81/cache \
  /var/www/html/ems81/backup \
  /var/www/html/ems81/uploads \
  /var/www/html/ems81/temp \
  /var/www/html/ems81/log \
  /var/www/html/ems81/excel \
  /var/www/html/ems81/pdf \
  /var/www/html/ems81/restore \
  /var/www/html/ems81/map_editor/data \
  /var/www/html/ems81/map_editor/images/markers
sudo chmod -R 775 \
  /var/www/html/ems81/cache \
  /var/www/html/ems81/backup \
  /var/www/html/ems81/uploads \
  /var/www/html/ems81/temp \
  /var/www/html/ems81/log \
  /var/www/html/ems81/excel \
  /var/www/html/ems81/pdf \
  /var/www/html/ems81/restore \
  /var/www/html/ems81/map_editor/data \
  /var/www/html/ems81/map_editor/images/markers

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

  1. 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
  2. Run Administration → Database → Backup — a new .sql file should appear under backup/.
  3. Import a model CSV or upload a profile image — a short-lived file should appear under uploads/.
  4. 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.
  5. 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 rangeCache 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

  1. Open Administration → Users → Manage.
  2. Create, edit, or disable user accounts and assign each user to a permission group.
  3. Open Administration → Users → Permission.
  4. For each menu item, set View, Add, Edit, and Remove rights per group.
  5. 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

  1. Define a model under Configuration → Models — register addresses, data types, scaling, and units. Alternatively, download a ready-made model from the Model Library.
  2. Add device instances under Devices → [protocol].
  3. Assign the model and enter connection details (IP address, unit ID, port, etc.).
  4. Verify live data appears in Site Explorer.
  5. 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

  1. Open Configuration → Models from the sidebar.
  2. In the model list, click the model name link (document icon) for the model you want to edit.
  3. The page opens with the model name in the header and the subtitle MODBUS registers.
  4. You can bookmark the page in your browser (users still need login and permission to open it).

Page layout

AreaDescription
Header barBack 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.
PaginationPrevious / 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:

RightWhat you can do on Model Editor
ViewOpen the page and read the point list. Without Add/Edit, form fields and action buttons are hidden or read-only.
AddUse Add and Clear on the add form, Upload Image, Import, Export in the Action menu, and the Copy icon on table rows.
EditClick the pencil (Edit) icon to open the Edit Point popup and change an existing point.
RemoveClick the trash (Remove) icon to delete a point from the model.

Adding a new point

  1. Fill in the add form at the top of the page (see Field reference below).
  2. Select an unused Point ID from the dropdown (IDs already in use are not listed).
  3. Enter a Point Name (required). Optionally fill Description, Unit, and register settings.
  4. Click Add.
  5. 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

  1. In the point list table, click the Edit (pencil) icon on the row you want to change.
  2. The Edit Point popup opens with all fields loaded for that point, including the same help icons as the add form.
  3. Change values as needed. The Point ID dropdown lists available IDs (the current point remains selectable).
  4. Click Save Change to apply, or Cancel / the X button / Esc / click outside the popup to close without saving.
  5. 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 popupDescription
Paste to Add formLoads 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 modelCreates 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.
  1. Click the Copy icon on a row.
  2. Review the source Point ID and name shown at the top of the popup.
  3. 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

  1. Click the Remove (trash) icon on the row.
  2. Confirm the deletion when prompted.
  3. 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 itemDescription
ImportImport point definitions from a CSV file into this model (replaces or merges points depending on file content). Requires Add permission.
ExportDownload the current model points as a CSV file. You can edit the file name in the confirmation dialog. Requires Add permission.
Open LinkOpens 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

  1. Click Action → Import. The Import Model popup opens.
  2. Confirm the model ID and name (read-only).
  3. Choose File Version:
    • Energy Link 360 (.csv) — current EMS export format (recommended).
    • E-Data (old) (.csv) — legacy format for older exports.
  4. Use File Selected → Upload to choose your CSV. Wait until the file name appears (not ---).
  5. Click Import. A loading message appears while the file is processed; the point table reloads when import completes.
  6. 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

  1. Click Action → Export.
  2. A brief Exporting model… message appears while data is prepared.
  3. Enter the file name when prompted (defaults to the model name).
  4. Confirm to download a .csv file containing all points in the model.
  5. Use this file for backup, editing in a spreadsheet, or importing into another model.

Uploading a model image

  1. In the add form panel, click Upload Image below the model picture (left side).
  2. Select an image file. The preview updates after upload.
  3. The image is stored with the model and shown on the Models list and Model Editor header area.

Field reference

FieldDescription
ViewWhen checked, the point appears in device / site views. Uncheck to hide from operators while keeping the register mapped.
CategoryGroups the point for menus and reports (e.g. Voltage, Current, Energy). Changing category may show or hide CT-related fields.
CT Scale MultiplyEnable when the meter requires CT ratio scaling for current, kW, and kWh. Shows CT Primary and CT Secondary fields.
Point IDUnique number (1–255) for this point in the model. Referenced in formulas as pid.<id>.
Write enableAllows write commands to this register when supported by the device and protocol.
Point NameDisplay name (required). Shown in Site Explorer, trends, and reports.
DescriptionOptional longer description for documentation.
UnitEngineering 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 TypeMODBUS table: Coil, Discrete Input, Holding Registers, or Input Registers.
Data TypeHow raw register words are interpreted — Bit, Int16, UInt16, Int32, Float32, Float64, etc.
RegisterStarting 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 factorMultiplier applied to the raw value (default 1.0).
OffsetValue added after scaling.
Byte OrderLittle 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 SecondaryCurrent transformer ratio (e.g. 50 / 5) when CT Scale Multiply is enabled.
Invert BitSwaps 0 and 1 for boolean values.
Formula ExpressionOptional 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 TextMaps 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

  1. Create the model shell under Configuration → Models (name and description).
  2. Open the model in the Model Editor.
  3. Optionally upload a device photo.
  4. 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.
  5. Verify Register addresses and Data Types match the meter manual.
  6. Export a backup CSV when finished.
  7. Assign the model when adding Modbus devices under Devices.
  8. Confirm live values in Site Explorer match expected units and scaling.

Typical workflow — copy points to another model

  1. Open the source model in the Model Editor.
  2. Click Copy on the row to duplicate.
  3. Choose the destination under Target Model, confirm auto Point ID and name, then click Copy to model.
  4. 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

  1. Before any update on production, run Administration → Database → Backup.
  2. Run Administration → Database → Update to apply database changes for new versions or modules.
  3. 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

  1. Open Administration → Settings → Waveform.
  2. Turn on Enable COMTRADE Waveform and save. The feature is off by default.
  3. 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/):

sudo /opt/meter/ems/waveform/deploy/install_waveform_systemd.sh
curl -s http://127.0.0.1:8095/health

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

  1. Open the meter under Devices → Modbus TCP (or the matching TCP loop).
  2. Edit the device and open the Waveform tab.
  3. Enable Waveform FTP, set host (often the same as the loop IP), user, password, and remote folders (default COMTRADE_1 … COMTRADE_3).
  4. 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

  1. Open Administration → System → Software License.
  2. 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.
  3. Click Activate on that row. The Activate dialog shows this machine's HW ID (hardware id) and license key.
  4. 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).
  5. 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

WhereWhat it shows
License page bannerWhether any license is currently active, and (if active) devices used vs. licensed.
Bell (notification) menu — top navbarBell 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.

  1. Open Administration → Audit Log.
  2. Use the filters (date range, user, category, action, status, free text) and click Filter to narrow the list, or Clear to reset.
  3. Click View in the Details column to see the full details for an entry in a popup.
  4. 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.

  1. Open Administration → General.
  2. Set Keep Audit Log (Days) to the number of days to retain entries (default 90).
  3. Click Save.

Enabling a new menu module

  1. Confirm the module appears in the sidebar for an administrator account.
  2. Open Administration → Users → Permission.
  3. Select each affected permission group.
  4. Enable View for the new menu item; enable Add, Edit, Remove as required.
  5. 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.

FeatureDescription
Publish / UpdatePush a local model (with points and image) from EMS to the central library.
Download / ImportPull a model from the library into the local EMS — as a new model or to update an existing one.
Revision historyEvery publish or point-change snapshot creates a version. Older versions can be downloaded or rolled back.
Star ratingEach site can rate a model 1–5 stars. Ratings appear in the model list to help engineers pick proven templates.
CSV importUpload point definitions from a legacy EMS CSV export directly into the library — data-type codes and byte-order are converted automatically.
Documents & NotesAttach 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.

ComponentDescription
Library Central websiteBrowse, upload, rate, and manage models in a web dashboard.
EMS integrationPublish, Pull, and Import from Library on Configuration → Models.

Initial setup

  1. Your administrator installs Model Library Central on the library server and completes the first-time setup wizard.
  2. Copy the admin access key shown during setup — it is displayed only once.
  3. On this EMS site, ask your administrator or EMS support to register the library connection URL and access key.
  4. 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.

  1. Open Configuration → Models.
  2. In the model list, click the three-dot menu (⋮) on the row of the model you want to publish.
  3. Select Publish to Library.
  4. Enter a device name (project/site name for identification in the library) and click Publish.
  5. 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

  1. Open Configuration → Models and click the + button.
  2. Switch to the From Library tab.
  3. Search or browse the model list. Star ratings are shown next to each model if rated.
  4. Click a model to open the detail view.
  5. 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.
  6. Select a version and click Download.
  7. The model is imported as a new local model with all points and image.

From Model Library browser

  1. In the model list header, click the three-dot menu (⋮) → Model Library.
  2. The library opens as a large dialog with search. Click any model for the same detail/version/rating view.
  3. 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.

  1. Open Configuration → Models.
  2. Click the three-dot menu (⋮) on the linked model → Pull from Library.
  3. Confirm the pull. A snapshot of the current local points is saved before overwriting.
  4. 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.

  1. Click the three-dot menu (⋮) → Rollback on the model row.
  2. A list of up to 10 recent snapshots appears (with date, action, and source version).
  3. 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.

  1. Open a model's detail view (click the model row).
  2. In the Your rating area, hover over the stars and click to rate 1–5.
  3. 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

  1. Open a model in Library Central.
  2. Edit, add, or delete points as needed. A dark bar appears at the top: "Points have been modified — N changes".
  3. Click Save Revision.
  4. Enter an optional change note (e.g. "Added Voltage L3, fixed Energy register") and confirm.
  5. 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:

  1. Drop or browse a .csv file. The file badge shows CSV.
  2. The parser detects headers automatically and converts old data-type codes (16→UInt16, 64→Float32, etc.).
  3. A preview table shows the parsed points with converted data types.
  4. Enter a Model Name (CSV files do not contain a name), From Project, and optional overrides.
  5. 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

  1. Open a model detail page and switch to the Documents tab.
  2. 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).
  3. 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).

PermissionAllowed actions
readList, detail, image, revisions, documents, notes (read-only access).
writeAll read actions plus publish, update, delete, rate, add points/notes/docs.
adminFull access including user and key management.

Library Central UI pages

PageDescription
ModelsBrowse all models with search, category/brand filter, ratings, document icons, and notes. Duplicate, export, or delete models.
UploadUpload JSON or CSV files to create new models in the library.
Model DetailView/edit model info, points (add, edit, delete), documents, revision history. Save Revision button after changes.
UsersManage library UI users (admin only). Separate from EMS user accounts.
API KeysCreate/revoke API keys for EMS sites (admin only).
ActivityAudit 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"

  1. Confirm Library Central is running and reachable from the EMS server (same network or VPN).
  2. Ask your administrator to verify the library site was installed and updated successfully.
  3. 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:

AreaLocationDescription
Menu barTop-leftFile, Edit, View, Layers, Object menus
Action toolbarTop row, centerSave, Copy, Cut, Paste, Undo, Redo, Delete buttons
Text toolbarTop row, after actionsFont family, Bold, Italic, font size, fill/stroke color pickers, text position
Drawing toolbarTop row, right sideDrawing tools (Pointer, Rectangle, Circle, Arc, Line, Polygon, Image, Text), Group/Ungroup, Lock/Unlock, Settings, Align
View toolbarTop-right cornerGrid, Snap, Fit-to-screen, Pan, Zoom In/Out, Reset view, Preview
CanvasCenterThe drawing area — scroll to pan, mouse wheel to zoom
Properties panelRight sidebarPosition, size, rotation, corner radius, opacity, and data binding for the selected object
Layer selectorToolbar, beside drawing toolsChoose which layer to draw on. Click the layer icon to open the layer manager
Status barBottomMouse coordinates (x, y) and save status

Menus

File menu

ItemDescription
Save to DatabaseSaves the current map to the server database
Load from DatabaseReloads the last saved version, discarding local changes
Open JSON fileOpens a local .json file exported previously
Import JSON (merge)Merges objects from a JSON file into the current map
Export as JSONDownloads the map as a .json file for backup or transfer
Page PropertiesSet canvas width/height (100 – 10,000 px), background color, and linked template
PreferencesDefault text font/size/color, default shape fill/stroke, grid size, and snap settings
Open in new tabOpens the runtime (preview) view in a new browser tab

Edit menu

ItemShortcut
UndoCtrl+Z
RedoCtrl+Y or Ctrl+Shift+Z
CutCtrl+X
CopyCtrl+C
PasteCtrl+V
DeleteDelete or Backspace

Undo/Redo supports up to 10 levels of history.

View menu

ItemDescription
Zoom In / OutScale the canvas view
Fit to ScreenAuto-zoom to show the entire canvas
Reset ViewCenter canvas at 100% zoom
Properties PanelToggle the right-side properties panel
Pan ModeToggle hand/pan tool for scrolling the canvas
Show GridToggle the background grid overlay
Snap to GridToggle snapping objects to grid intersections
Show TemplateToggle display of the linked template layer behind the map
Widget LibraryOpen the pre-built widget panel (icons, electrical symbols, gauges, etc.)
Preview / PlayEnter preview mode to see live data and test interactions
3D ViewOpen 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

ItemShortcutDescription
GroupCtrl+GCombine selected objects into one group
UngroupCtrl+U or Ctrl+Shift+GBreak 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)

ActionDescription
Align Left / Center / RightAlign selected objects horizontally
Align Top / Middle / BottomAlign selected objects vertically
Distribute HorizontalSpace objects evenly side-by-side (requires 3+)
Distribute VerticalSpace 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.

ToolIconHow to use
PointerClick to select objects. Click empty area to deselect. Drag to marquee-select multiple objects. Hold Shift to add/remove from selection
RectangleClick and drag to draw a rectangle. Hold Shift to constrain to a square
CircleClick and drag to draw an ellipse. Hold Shift to constrain to a perfect circle
ArcClick and drag to draw an arc shape
LineClick 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)
PolygonClick to place vertices. Double-click or press Enter to finish. Press Escape to cancel. Creates a closed polygon shape
ImageOpens a file dialog to select an image (PNG, JPG, SVG). The image is placed on the canvas at the cursor position
Insert AnimationOpens the animation import dialog to build a multi-frame animated sprite (see Animation sprites)
TextClick 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.

  1. Click Insert Animation on the drawing toolbar
  2. Click Add Frames and select 1–10 PNG or JPEG images, in playback order
  3. Frames are automatically cropped to a common size and combined into a single sprite sheet
  4. Set the frame rate (frames per second)
  5. 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:

  1. Select a polygon and double-click it (or right-click > Edit Nodes)
  2. Blue vertex handles appear — drag them to reshape the polygon
  3. 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
  4. 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:

ActionShortcutContext menu
Move one level upPage UpOrdering > Move Up
Move one level downPage DownOrdering > Move Down
Bring to frontEndOrdering > Bring to Top
Send to backHomeOrdering > 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
  • Polygon node editing — Add Node, Delete Node, Corner, Smooth, Finish Editing (when editing polygon vertices)
  • Convert Lines to Polygon — merge connected lines into a polygon

Grid and snapping

The grid and snap features help align objects precisely:

  • Toggle Grid ( toolbar button or View menu): show/hide a dot grid on the canvas
  • Toggle Snap ( toolbar button or View menu): when enabled, objects snap to the nearest grid intersection while moving or resizing
  • Grid size: configurable in File > Preferences (range: 2 – 200 px, default: 20 px)

Panning and zooming

  • Scroll wheel: zoom in/out centered on the cursor position
  • Middle-click drag or Shift+drag on empty area: pan the canvas
  • Pan tool (): click to toggle pan mode — drag anywhere to scroll. Press Escape to exit pan mode
  • Zoom In / Zoom Out buttons: step zoom from the toolbar
  • Fit to Screen (): auto-zoom to show the entire canvas
  • Reset View (): center canvas at 100% zoom

Widget Library

Open the Widget Library from View > Widget Library or the toolbar. It contains 77 pre-built widgets in 5 categories:

Icons (50+ items)

Scalable vector icons for building equipment and systems:

  • HVAC: Fan, Exhaust Fan, Chiller/AC, Temperature, Ventilation, Pump, Water, Boiler
  • Electrical: Bolt, Power Plug, Charging Station, Battery/UPS, Solar Panel, Lighting, Power Tower
  • Safety: Fire, Extinguisher, Security Shield, CCTV, Monitoring, Alarm, Siren
  • Access: Door Open, Door Closed, Locked, Unlocked, Key, Elevator, Stairs, Building
  • Network: WiFi, Network, Server, Sensor/IoT, Satellite
  • 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.

Buttons

Interactive UI elements: Push Button, Toggle Switch, Alert Button, Status LED, Alarm Indicator, Flat buttons (Primary, Success, Warning, Danger), Outline buttons, 3D buttons, Pill buttons, Power/Play/Stop icon buttons.

Gauges

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.

PropertyDescription
X, YPosition on the canvas (top-left corner)
W, HWidth and height in pixels
RotationRotation angle in degrees
Corner RadiusRounded corners for rectangles (0 = sharp)
OpacityTransparency (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

  1. Select an object on the canvas
  2. In the Properties panel, find the Data Binding section
  3. 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.)
  4. 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.

ActionDescription
Display ValueShow 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 ColorChange the text color based on value conditions (e.g. red when > 100)
Hide / ShowToggle object visibility based on value conditions (e.g. show alarm icon when value = 1)
Blink / FlashMake the object blink when conditions are met. Speed options: slow, normal, fast, or custom interval
RotateAnimate rotation when conditions are met. Configure speed and direction (clockwise/counter-clockwise). The object rotates around its own visual center
Play AnimationStart/stop a multi-frame animation (see Animation sprites) when conditions are met
Change Fill ColorChange the fill color based on value conditions, with a default color when no rule matches
Fill LevelGrow/shrink the object like a level indicator (e.g. tank fill) between a min/max value, in a chosen direction
Change ImageSwap an image object's source based on value conditions (e.g. door-open.png vs door-closed.png)
Move ItemMove the object between a start and end position proportionally to the value (e.g. a damper or slider indicator)
Change StrokeChange the border color/width based on value conditions
Change OpacityFade the object in/out proportionally to the value between a min/max range
Analog ColorSmoothly 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

KeyAction
EscExit preview, return to editor
EExit preview, return to editor
Ctrl+ROpen runtime view in a new tab
Ctrl+Alt+PToggle the performance overlay
F11Toggle 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

ShortcutActionContext
Ctrl+SSave map to databaseEditor
Ctrl+ZUndoEditor
Ctrl+YRedoEditor
Ctrl+Shift+ZRedo (alternative)Editor
Ctrl+ASelect all objectsEditor
Ctrl+CCopy selected objectsEditor
Ctrl+XCut selected objectsEditor
Ctrl+VPaste from clipboardEditor
Ctrl+GGroup selected objectsEditor
Ctrl+UUngroupEditor
Ctrl+Shift+GUngroup (alternative)Editor
Ctrl+REnter Preview modeEditor
Delete / BackspaceDelete selected objectsEditor
EscapeCancel current operation / exit polygon edit / exit pan modeEditor
Arrow keysNudge selection by 1 pxEditor
Shift+Arrow keysNudge selection by 10 pxEditor
Page UpMove object one level up (z-order)Editor
Page DownMove object one level down (z-order)Editor
EndBring to frontEditor
HomeSend to backEditor
Shift+DragConstrain shape / snap line angle (0°/45°/90°)Drawing
EnterFinish polygon drawingPolygon tool
EscExit preview modePreview
ESwitch to editorPreview
Ctrl+Alt+PToggle the performance overlayPreview / Runtime
F11Toggle fullscreenPreview
Scroll wheelZoom in / outEditor
Middle-click dragPan the canvasEditor

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

ActionHow
Add a nodeDrag an item from the left or right toolbox onto the canvas.
Bind a meter pointDrag 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 nodesDrag 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 wireClick the wire, then press Delete, or drag from the input socket away and release on empty canvas.
Pan / ZoomDrag empty canvas to pan; scroll wheel to zoom; Fit button frames all nodes.
Undo / RedoToolbar buttons, or Ctrl+Z / Ctrl+Y.
SaveToolbar Save button — writes the workflow JSON for this file and reloads the runtime if it is currently running.
Import / ExportExport the current workflow as a JSON file, or import a previously exported file.
SearchToolbar 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:

StateMeaning
RunThe 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.
PauseThe runtime stops scanning but keeps its current state (timer elapsed time, counter values, latch/memory state) so you can resume later without losing progress.
StopThe 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.

PortI/ODescription
ValueOutput (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.

PortI/ODescription
Value (property)PropertyThe number to output, edited directly on the node.
ValueOutput (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 !=.

PortI/ODescription
A, BInput (value)The two values to compare. Unwired defaults to 0.
Operator (property)PropertyOne of > < >= <= == !=. An unrecognized value produces Err: bad op.
ResultOutput (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.

PortI/ODescription
A, B (, C)Input (bool)2–3 inputs depending on the node's input count. Unwired counts as false.
ResultOutput (bool)True only if all connected inputs are true.

OR — true when either input is true.

PortI/ODescription
A, BInput (bool)Unwired counts as false.
ResultOutput (bool)A OR B.

NOT — inverts a single boolean.

PortI/ODescription
AInput (bool)Unwired counts as false (so Result defaults to true).
ResultOutput (bool)NOT A.

XOR — true only when A and B are different.

PortI/ODescription
A, BInput (bool)Unwired counts as false.
ResultOutput (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.

PortI/ODescription
SELInput (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.
ResultOutput (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.

PortI/ODescription
INInput (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.
QOutput (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.

NodePortsBehavior
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, QThe 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, QOn 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.
DebounceIN, PT, QQ 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.

NodePortsBehavior
Counter UpCU (bool in), Reset (bool in), CV (value out)CV increases by 1 on each rising edge of CU.
Counter DownCD (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

NodeInputsBehavior
Add2–6 (A…F)Sum of all connected inputs. Right-click to change the input count.
SubtractA, BA − B.
MultiplyA, BA × B.
DivideA, BA ÷ B. B = 0 produces Err: ÷0 instead of crashing the workflow.
Min2–6 (A…F)Smallest of all inputs; an unwired port counts as 0.
Max2–6 (A…F)Largest of all inputs; an unwired port counts as 0.
Average2–6 (A…F)Mean of only the wired inputs (unwired ports are excluded, not counted as 0).
AbsAAbsolute 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.

PortI/ODescription
Total (kW)Input (value)Total facility power draw.
IT (kW)Input (value)IT equipment power draw.
PUEOutput (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.

PortI/ODescription
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.

NodePortsBehavior
AssignValue in, Result outResult always equals the current Value input (0 if unwired).
MoveValue in, Result outResult 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.

PortI/ODescription
Initial (property)PropertyStarting value the first time this node runs (or after Stop clears state).
ValueInput (value)The value to store, applied only while Write is true.
WriteInput (bool)Gate — while true, Stored is overwritten with Value every scan; while false, Stored is left untouched.
StoredOutput (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.

PortI/ODescription
ValueInput (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).

PortI/ODescription
Message (property)PropertyText shown in the alarm list/notifications.
TriggerInput (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).

PortI/ODescription
Initial state (property)PropertyQ's value the first time this node runs (or after Stop).
SInput (bool)Set — a true pulse sets Q true.
RInput (bool)Reset — a true pulse sets Q false; takes priority over S.
QOutput (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.

PortI/ODescription
INInput (bool)The signal to watch.
QOutput (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.

LabelMeaning
Err: ÷0A Divide or PUE node's divisor input was 0.
Err: invalidAn 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 inputAn Average node has no wired inputs at all.
Err: NaNThe calculation produced an undefined result.
Err: overflowThe result is too large to represent.
Err: bad opA 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

  1. Log in with your assigned username and password.
  2. Use the sidebar treeview to open modules — each item loads in the main content area.
  3. 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

LevelExampleWhat it is
Sites rootSitesTop of the Sites tree. Lists all site entries.
SiteRojanaA facility or building. Can contain folders and group items directly.
FolderFolder AOrganizes items inside a site. Can contain subfolders and group items.
Group itemGroup Energy, Monthly ReportA 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 typeIconColorOpens
SiteBuildingDefault (dark)Folder list for that site
FolderFolderSlate grayContents of that folder
Group itemLayer group (stacked layers)BlueLive 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.

PageToolbar buttonsCreates
Sites root Add SiteA 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 pointA 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

  1. Right-click a Sites node (or use the tree context menu where available).
  2. Choose Add:
    • On Sites root — Site or Folder.
    • Inside a site folder — Folder (subfolder) or Item (group item / device collection).
  3. 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

  1. Open a group item from the tree or list (e.g. Group Energy).
  2. Review live values in the paginated table. Use the header breadcrumb to move back up the hierarchy.
  3. Click Add tag or point to pick registers from connected devices and add them to the collection.
  4. Users with Add permission can drag devices from the sidebar tree onto the group item page to add points quickly.
  5. 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:

RightControls
ViewSee the Sites menu, tree nodes, and list pages.
AddAdd Site / folder / group item / point buttons; drag-and-drop into a group item.
EditEdit view, rename, reorder, and save changes.
RemoveDelete 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

  1. Open Devices and select the protocol (Digital Meter, BACnet, Modbus, etc.).
  2. Browse loops and meters to locate the device.
  3. Review live readings; icons indicate online or offline status.
  4. 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

  1. In the sidebar, expand Devices → Virtual Meter.
  2. Click a Virtual Meter loop (for example TES) to open the device list (data.php) in the main panel.
  3. 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.
  4. 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):

  1. Expand the loop in the left tree.
  2. Drag a device onto another device in the same loop.
  3. 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.

  1. Open the Virtual Meter loop list (for example Devices → Virtual Meter → TES).
  2. In the left tree, expand a physical protocol loop (Digital Meter, Modbus RTU, Modbus TCP, and so on) and locate the meter to add.
  3. Drag the meter device (not a point/tag leaf) from the tree.
  4. Drop it onto the target Virtual Meter row or icon card in the list. A blue outline highlights the target while you hover.
  5. 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

  1. On the Virtual Meter loop list, click the + (Add) header button.
  2. Enter a device name and description.
  3. Select one or more source meters from the picker (filter by loop or search by name).
  4. 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.

Tree and list view

  • Folder — organizes schedule files; right-click for New, Open, Rename, Delete, Copy, Paste.
  • 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

  1. 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.
  2. Drag on the grid to create a time block, or use the context menu (Add, Edit, Delete).
  3. 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.
  4. 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.
  5. 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.

  1. Browse to the month/year with the ‹ / › buttons, or click Today.
  2. Click a date to open the Holiday dialog. Enter a Short name (max 16 characters, e.g. “New Year”) and click Save.
  3. Click an existing holiday date again to rename it, or click Remove to delete it.
  4. 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.

  1. Open the source schedule file and click the Export settings icon in the header (next to the PDF export icon).
  2. Check Weekly (blocks, states, gap/fallback, Exception1) and/or Holidays (template dates + Exception overrides) — both are checked by default.
  3. Under Target schedules, click All/None or check individual templates (the current template is not listed).
  4. 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:

ProtocolConnection shown in Mod Scan 360
Digital MeterSerial/RTU port or UDP RTU gateway (from loop configuration)
Modbus RTULocal serial port (COM or /dev/tty*)
Modbus TCPTCP 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

  1. In the sidebar under Devices, expand Digital Meter, Modbus RTU, or Modbus TCP.
  2. Right-click the loop (the loop row, not an individual meter/device).
  3. Choose Mod Scan 360 from the context menu.
  4. Read the confirmation dialog, then click Pause & open.
  5. 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

ControlAction
Countdown timer (top bar)Shows time until auto-resume. Default idle timeout is 5 minutes.
+5 minExtends the debug session by five minutes (useful when the timer turns amber near expiry).
ResumeEnds 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 timeoutIf 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:

FieldDescription
SlaveModbus unit ID (0–247). Usually 1 unless your device uses another address.
FunctionModbus function code (FC) — see Function codes (FC) below.
Register0-based PDU address (same convention as ModScan). Example: holding register 40001 → enter 0.
LengthNumber of coils/bits or registers to read. FC01/02: 1–2000 bits; FC03/04: 1–125 registers.
Play (▶)Starts auto-read every 1 second. Click again to stop.
Data type (table header)How raw register words are decoded — see Data type and byte order.
Byte order (table header)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).

FCUI labelModbus tableTypical useWritable?Max length
0101 CoilCoils (0xxxx)Digital outputs, relay commands, on/off controlYes — double-click Value (uses FC05)2000 bits
0202 Discrete InputDiscrete inputs (1xxxx)Digital inputs, limit switches, status bitsNo — read-only2000 bits
0303 HoldingHolding registers (4xxxx)Measurements, setpoints, configuration (most common for energy meters)Yes — double-click Value (FC06 / FC16)125 registers
0404 Input RegInput registers (3xxxx)Read-only measurements from the deviceNo — read-only125 registers

Address examples (0-based PDU):

Datasheet / Modbus labelFC to selectEnter in Register field
Coil 0000101 Coil0
Discrete input 1000102 Discrete Input0
Input register 3000104 Input Reg0
Holding register 4000103 Holding0
Holding register 4010003 Holding99 (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 typeRegisters consumedDescription
Bit1 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 / UInt81Low byte of one 16-bit register (signed or unsigned).
Int16 / UInt161Single 16-bit integer — the most common type for simple meter values.
Int32 / UInt322 consecutive registers32-bit integer spanning two registers starting at the address you entered.
Float322 consecutive registersIEEE 754 single-precision float (typical for kW, voltage, power factor on many meters).
Int64 / UInt644 consecutive registers64-bit integer (e.g. large energy counters).
Float644 consecutive registersIEEE 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.

SettingEffect
Big (default)Registers are combined in the order returned by the device — first register is the high word.
LittleThe 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)

  1. Run a read on Holding registers (FC03) or Coils (FC01).
  2. Double-click the decoded Value cell in the result table.
  3. Enter the new value in the write dialog (coils: 0 or 1; registers: numeric value matching the selected data type).
  4. 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

  1. Open Mod Scan 360 on the target loop and confirm the connection line matches your gateway or serial port.
  2. Set Slave to the device unit ID.
  3. Choose 03 Holding, enter a guessed Register address (0-based), set Length to 10, and press Play.
  4. Adjust Data type and Byte order until the decoded value matches the device display or datasheet.
  5. Note the register address and type, then add the point in Configuration → Models (see Model Editor — MODBUS Registers).
  6. 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

  1. Open the meter under Devices.
  2. Click the Waveform icon in the meter header — a modal loads the viewer, or use Open in new window.
  3. Alternatively open waveform.php?meter_id=… directly.

Sync and browse events

  1. Click Sync from meter to download new COMTRADE pairs from the meter FTP folders. Status shows downloaded / skipped / repaired / failed counts.
  2. 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/…).
  3. Select an event to load channels. Toggle V1–V3 / I1–I3 and use zoom / pan on each pane (Voltage and Current use separate scales).
  4. 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

  1. Open Trend & History → General, select points and a date range.
  2. 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.

  1. 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).
  2. 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.
  3. 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.
  4. 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.
  5. Preview (optional) — shows a sample of parsed rows plus row/error counts before anything is written, so you can catch a bad mapping early.
  6. 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:

AMeter-101Meter-102
TimekWkWhkWkWh
2026-07-17 00:00:0012.41050.28.1640.0
2026-07-17 00:05:0012.61051.38.0640.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

  1. Check the Alarms section for offline devices and pending events.
  2. Review alarm history and notify an administrator if action is required.

Generating reports and bills

  1. Open Billing, select the bill type and reporting period.
  2. 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.

  1. 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.
  2. Begin / End — the export window; limited to 31 days per export.
  3. Interval — sampling step from 1 minute to 1 hour.
  4. Decimal places and Export Date/Time format — cosmetic formatting for the exported file (4 date/time formats available, including 12-hour AM/PM).
  5. 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

  1. Open My Profile to update account details and password.
  2. 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

  1. Open Administration → LINE Setting from the sidebar menu.
  2. The page is organized into 4 tabs: Setting, Quota, Templates, and Users.

Tab 1 — Setting

Core configuration for the LINE bot connection.

FieldDescription
EnableMaster toggle — when disabled, no LINE messages are sent regardless of alarm state.
DescriptionA label for this configuration (e.g. "Factory A alerts"). For your reference only.
LINE BOTThe 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 URLThe 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.

FieldDescription
ModeFREE — enforces a daily message limit. PAID — unlimited messages (no quota check).
Daily LimitMaximum messages per day in FREE mode. Default: 10. One send to 5 users counts as 5 messages.
UsageProgress 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

  1. When an alarm triggers, the system counts the number of active LINE users.
  2. If today's usage plus the number of recipients would exceed the daily limit, the message is skipped and noted in the service log.
  3. 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:

FieldDescription
NameTemplate display name (e.g. Critical, Warning, Info).
ColorHeader background color of the Flex message.
IconEmoji icon shown in the template header.
EnabledOnly enabled templates can be selected in the priority mapping.
Flex JSONThe 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.

  1. Select a template from the dropdown for each priority level.
  2. 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").

ColumnDescription
Display NameThe user's LINE display name with profile picture.
User IDThe LINE internal user ID (starts with U).
Statusactive — receives notifications. blocked / unfollowed — will not receive messages.
RegisteredDate 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:

  1. Detection — The EMS polling service detects an alarm condition (value exceeds threshold, device goes offline, binary state changes).
  2. 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.
  3. 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.
  4. 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.
  5. Template selection — The alarm priority determines which Flex template to use via the priority mapping.
  6. Delivery — The notification is sent to all active registered users.

Alarm message content

Each notification includes:

FieldSource
TimeTimestamp of the alarm event
Point name{Device Name} : {Alias Name} format. Falls back to model point name if no alias is set.
ValueCurrent value with unit. Binary points show state text (ON/OFF) instead of 0/1.
StatusCustom alarm message if configured (e.g. "Over Voltage!"), otherwise "High Alarm" / "Low Alarm" / "Normal".

Troubleshooting LINE notifications

ProblemSolution
No messages receivedCheck 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 workingIn 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 repeatedlyThis 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'tAlarm delivery uses the background polling service, not the web pages alone. Restart the EMS service from Administration → System → Services and try again.
Users not showingUsers 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

  1. Temporarily disable the suspect extension and reload EMS.
  2. Or test in a private window with extensions disabled.
  3. Whitelist your EMS site address in the extension.
  4. Hard-refresh (Ctrl+F5) and retry.

Still slow after whitelisting?

  1. Check Administration → System → Services.
  2. Review server/database performance with IT.
  3. 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

  1. Confirm you have Add on the Sites permission.
  2. Hard-refresh (Ctrl+F5) if the list updated but the sidebar did not.
  3. Expand the parent site or folder caret in the tree — new items are added under the correct parent.
  4. 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

  1. Verify device network and configuration under Devices → [protocol].
  2. Check Administration → System → Services.
  3. 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

  1. Confirm Administration → Settings → Waveform → Enable COMTRADE Waveform is on.
  2. Confirm the meter is Modbus TCP and uses a Waveform-capable model.
  3. On the device edit dialog → Waveform tab, enable Waveform FTP and save a user (and host/password/folders as needed).
  4. Hard-refresh (Ctrl+F5) and reopen the meter.

Waveform Sync fails or the event list stays empty

  1. On Administration → System → Services, confirm Waveform API is Online (port 8095). Use Start / Restart if it is Offline.
  2. Verify meter FTP credentials and that COMTRADE_1 (etc.) exist on the meter.
  3. Check that /opt/meter/data/Waveform/ is writable by the web/API user (www-data on Linux).
  4. Ask an administrator to re-save the device Waveform settings so configs/meter_{id}.json is refreshed under the data root.
  5. See Operator Guide → COMTRADE Waveform and Administrator Guide → Waveform.

Virtual Meter — drop does not add a source

  1. 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.
  2. Drag a meter device from a physical loop in the tree, not a point/tag leaf.
  3. Confirm your account has Add permission on the Virtual Meter menu.
  4. Hard-refresh (Ctrl+F5) and try again. See Operator Guide → Adding source meters by drag-and-drop.

Mod Scan 360 — common issues

"Mod Scan 360" is missing from the context 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

  1. Confirm the EMS background service is running (Administration → System → Services).
  2. Check that the loop is enabled in the loop list.
  3. Retry after a hard refresh (Ctrl+F5).

Reads fail (CRC, exception, no RX) but the device works in another tool

  1. Confirm Slave ID and 0-based register address (40001 → 0).
  2. Match Function to the register table (holding vs input).
  3. For TCP/RTU gateways, verify the loop IP, port, or serial settings under Devices → [protocol] → Edit loop.
  4. 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

  1. Open Administration → System → Software License and click Activate on the license key row.
  2. 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.
  3. 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

  1. Hard-refresh the page (Ctrl+F5).
  2. For Import, upload a CSV first — the file name must appear before Import will run.
  3. Check the browser developer console (F12) for errors.

Edit or Copy popup does not open or only works once

  1. Hard-refresh the page (Ctrl+F5) to reload the page fully.
  2. Check the browser developer console (F12) for errors.
  3. 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

  1. Allow pop-ups and downloads from the EMS site.
  2. Confirm the date range contains data.
  3. Wait for large exports to finish.

The page area is blank after clicking a menu item

  1. Rule out browser extensions (see above).
  2. Refresh (F5), clear cache, or try another browser.

A database update failed

  1. Run Administration → Database → Backup before retrying.
  2. 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).

1) Live meter values — endpoint

Recommended URL (folder path, no .php):

https://your-ems-server/api/meter_values/

Example: https://your-ems-server/api/meter_values/?sdkey=YOUR_SDKEY&meter_id=4&port=8080

Method: GET  |  Response: JSON

Legacy URL: https://your-ems-server/api/meter_values.php

Point metadata cache

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

NameRequiredDescription
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:

https://your-ems-server/api/meter_values/?sdkey=YOUR_SDKEY&meter_id=4&port=8080&refresh_cache=1

Subsequent requests can omit refresh_cache; updated metadata is stored in the cache again.

Reference ID formula

reference_id = (device_id × 1000) + point_id
Example: device 4, point 1 → 4001.

Example request (normal)

curl -G "https://your-ems-server/api/meter_values/" --data-urlencode "sdkey=YOUR_SDKEY" --data-urlencode "meter_id=4" --data-urlencode "port=8080"

Browser / HTTP client:

https://your-ems-server/api/meter_values/?sdkey=YOUR_SDKEY&meter_id=4&port=8080

Example response

{
    "result": "O.K.",
    "time_stamp": "2026-05-28 15:30:00",
    "device": {
        "device_id": 4,
        "device_name": "station1",
        "loop_number": 1,
        "loop_name": "loop1",
        "model_id": 16,
        "hwid": "",
        "local_meter_id": 0
    },
    "Records": [
        {
            "key": 4001,
            "reference_id": 4001,
            "point_id": 1,
            "device_id": 4,
            "point_name": "wind_speed",
            "point_description": "Wind speed",
            "unit": "m\/s",
            "value": 2.4,
            "online": true,
            "is_number": true,
            "alarm_low": false,
            "alarm_high": false,
            "alarm": false,
            "state_text": "",
            "catagory": 0
        },
        {
            "key": 4005,
            "reference_id": 4005,
            "point_id": 5,
            "device_id": 4,
            "point_name": "humidity",
            "point_description": "Relative humidity",
            "unit": "%",
            "value": 69,
            "online": true,
            "is_number": true,
            "alarm_low": false,
            "alarm_high": false,
            "alarm": false,
            "state_text": "",
            "catagory": 0
        }
    ]
}

Record fields

FieldDescription
time_stampCurrent server date/time when the response was generated (Y-m-d H:i:s)
deviceObject: device_id, device_name, loop_number, loop_name, model_id, hwid, local_meter_id
Records[]Array of measurement points with metadata below
key / reference_idGlobal point reference (device_id×1000 + point_id)
point_idPoint index within the device model
point_nameTag name from model
point_descriptionDescription from model
unitEngineering unit from the point definition
valueCurrent value
onlinePoint online status
alarm_low / alarm_high / alarmAlarm flags
state_textAlarm / 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.

Endpoint

Recommended URL:

https://your-ems-server/api/meter_history/

Example: https://your-ems-server/api/meter_history/?sdkey=YOUR_SDKEY&begin=2026-05-13%2000:00:00&end=2026-05-20%2013:49:59&pointId=107001&time=30&loop_number=1&data_type=0&hwid=&local_id=0&loop_local_number=0

Legacy: https://your-ems-server/api/meter_history.php

Method: GET  |  Response: JSON

Parameters

NameRequiredDescription
sdkey Yes Same API key as live values (or header X-API-Key)
begin, end Yes Range Y-m-d H:i:s (URL-encoded when used in a browser)
pointId Yes Point reference: device_id × 1000 + point_id (same as trend / log charts)
time Yes Sample interval in minutes (same as trend UI “time”)
loop_number Digital meter Loop number used to locate SQLite log files (omit or 0 when using Link 360 path)
data_type Yes 0 = numeric (default), 1 = binary / discrete table
hwid 360 only When non-empty, selects Link 360 / remote device history (provided by your EMS operator)
local_id 360 Local device id for 360 (often 0)
loop_local_number 360 Loop number used inside the 360 SQLite folder (same as trend loop_local_number)

Response shape

  • result — O.K. or ERROR
  • source — digital_meter (station meter log) or link_360 (Link 360 device log)
  • point — metadata for requested reference (includes reference_id, full_name, point_name, point_description, unit, and related device/loop fields)
  • query — normalized request window and interval (begin, end, time, data_type)
  • data — array of points; each item has time_stamp and value

Example request

curl -G "https://your-ems-server/api/meter_history/" --data-urlencode "sdkey=YOUR_SDKEY" --data-urlencode "begin=2026-05-27 00:00:00" --data-urlencode "end=2026-05-28 17:49:59" --data-urlencode "pointId=136001" --data-urlencode "time=5" --data-urlencode "loop_number=4" --data-urlencode "data_type=0" --data-urlencode "hwid=D7E7F748" --data-urlencode "local_id=136" --data-urlencode "loop_local_number=1"
https://your-ems-server/api/meter_history/?sdkey=YOUR_SDKEY&begin=2026-05-13%2000:00:00&end=2026-05-20%2013:49:59&pointId=107001&time=30&loop_number=1&data_type=0&hwid=&local_id=0&loop_local_number=0

Example response

{
    "result": "O.K.",
    "source": "link_360",
    "point": {
        "reference_id": 136001,
        "device_id": 147,
        "point_id": 1,
        "device_name": "DCP-B",
        "point_name": "V1",
        "point_description": "Phase 1 Voltage",
        "unit": "V",
        "full_name": "DCP-B \/ V1",
        "model_id": 5,
        "loop_number": 4,
        "loop_name": "NT_SRI_Loop1",
        "hwid": "D7E7F748",
        "local_id": "136",
        "loop_local_number": 1
    },
    "query": {
        "begin": "2026-05-13 00:00:00",
        "end": "2026-05-20 13:49:59",
        "time": 30,
        "data_type": 0
    },
    "data": [
        {
            "time_stamp": "2026-05-13 00:00:00",
            "value": 51.7
        },
        {
            "time_stamp": "2026-05-13 00:30:00",
            "value": 51.7
        }
    ]
}

3) Device offline API

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.

Endpoint

Recommended URL:

https://your-ems-server/api/device_offline/

Example: https://your-ems-server/api/device_offline/?sdkey=YOUR_SDKEY&mode=local

Legacy: https://your-ems-server/api/device_offline.php

Method: GET  |  Response: JSON

Parameters

NameRequiredDescription
sdkey Yes API key (or header X-API-Key)
port No 8080 = local / EMS (digital meters). 8081 = central / Link 360. If omitted, uses the site default from EMS configuration.
mode No Alternative to port: local (8080), central (8081), or all (query both services and merge). Aliases: ems, link_360, both.
local No Boolean shortcut: true = 8080 (local/EMS), false = 8081 (central/Link 360). When provided, it overrides mode/port.
hwid No Link 360 only: comma-separated hardware IDs; when set, only matching offline devices are returned

Response shape

  • result — O.K. or ERROR
  • port + source — present when a single service is queried (8080/digital_meter or 8081/link_360)
  • ports + by_source — present when mode=all (each entry has its own port, source, count, data)
  • count — total rows in data
  • data[] — each item: time_stamp, device_id, device_name, …; with mode=all each row also has source and service_port

Example request

curl -G "https://your-ems-server/api/device_offline/" --data-urlencode "sdkey=YOUR_SDKEY" --data-urlencode "port=8080"
https://your-ems-server/api/device_offline/?sdkey=YOUR_SDKEY&mode=local

Example response

{
    "result": "O.K.",
    "source": "digital_meter",
    "count": 1,
    "data": [
        {
            "time_stamp": "20\/05\/2026 14:30:15",
            "device_id": 12,
            "device_name": "Meter-A1",
            "device_address": "1",
            "loop_number": "1",
            "loop_name": "Loop 1",
            "model": "16",
            "converter_ip": "192.168.1.10",
            "status": "Offline"
        }
    ]
}

4) Alarm pending API

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

Both: https://your-ems-server/api/alarm_pending/?sdkey=YOUR_SDKEY&mode=all

Legacy: https://your-ems-server/api/alarm_pending.php

Method: GET  |  Response: JSON

Parameters

NameRequiredDescription
sdkey Yes API key (or header X-API-Key)
port No 8080 = local / EMS. 8081 = central / Link 360. If omitted, uses the site default.
mode No local (8080), central (8081), or all (both). Same aliases as device offline API.
hwid No Link 360 only: comma-separated hardware IDs; when set, only matching alarms are returned

Response shape

  • Same port / mode=all behaviour as the device offline API
  • data[] — time_stamp, source_name, device_id, device_name, point_name, point_description, alarm_message, value, unit, alarm_status, reference_id, point_index, model; optional hwid

Example request

curl -G "https://your-ems-server/api/alarm_pending/" --data-urlencode "sdkey=YOUR_SDKEY" --data-urlencode "port=8080"
https://your-ems-server/api/alarm_pending/?sdkey=YOUR_SDKEY&mode=local

Example response

{
    "result": "O.K.",
    "source": "digital_meter",
    "count": 1,
    "data": [
        {
            "time_stamp": "20\/05\/2026 14:35:22",
            "source_name": "Site A",
            "device_id": 4,
            "device_name": "station1",
            "point_name": "Voltage",
            "point_description": "Line voltage",
            "alarm_message": "High limit exceeded",
            "value": 245.5,
            "unit": "V",
            "alarm_status": "High Alarm",
            "reference_id": 4001,
            "point_index": 1,
            "model": "16"
        }
    ]
}

5) Loop management API

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.

Write (POST create / PUT edit / DELETE remove) — parameters

NameRequiredDescription
sdkeyYesAPI key with write access (or header X-API-Key)
idPUT/DELETELoop id to edit or remove (DELETE also accepts loop_number)
loop_namePOSTDisplay name
loop_numberPOSTUnique loop number
loop_protocolPOSTSee protocol table below
loop_ip, loop_portDepends on protocolRequired for Modbus TCP/BACnet/MBUS/Custom/Link 360/MQTT Device; auto-filled for RTU/Virtual Meter/Software Module
loop_serial_port, loop_baud, loop_parity, loop_stopbits, loop_bytesizeRTU onlySerial config, e.g. /dev/ttyUSB0, 9600, N, 1, 8
loop_enableNotrue/false (default true)

Supported loop_protocol values

ValueProtocolEndpoint fields
0Digital Meterloop_port required, must be 1024–65535 (privileged ports rejected)
1Modbus RTUloop_serial_port required (e.g. /dev/ttyUSB0, COM1); loop_ip/loop_port auto-filled
2Modbus TCPloop_ip + loop_port required
3BACnetloop_ip + loop_port required
4MBUSloop_ip + loop_port required
5Link 360loop_ip + loop_port required
6Customloop_ip + loop_port required
7Virtual Meterloop_ip/loop_port auto-filled (127.0.0.1:9632)
8Software Moduleloop_ip/loop_port auto-filled (127.0.0.1:9633)
9MQTT DeviceBroker hostname/IP in loop_ip and broker port (1–65535) in loop_port. Credentials/TLS are configured in the EMS UI.

On PUT, any field left out keeps its current value — only send the fields you want to change.

Example request (create)

curl -X POST "https://your-ems-server/api/loops/" --data-urlencode "sdkey=YOUR_SDKEY" --data-urlencode "loop_name=Loop 1" --data-urlencode "loop_number=1" --data-urlencode "loop_protocol=2" --data-urlencode "loop_ip=10.0.0.10" --data-urlencode "loop_port=502"

Example response

{"status":"O.K.","code":200,"id":12,"loop_number":1}

6) Device management API

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.

Write (POST create / PUT edit / DELETE remove) — parameters

NameRequiredDescription
sdkeyYesAPI key with write access (or header X-API-Key)
idPUT/DELETEDevice id to edit or remove
namePOSTDisplay name
loopPOSTTarget loop number
addrPOSTDevice address on the loop
modelNoModel id (see Model Library)
enableNotrue/false (default false); enabling is subject to the same device-quota check as the UI
sn, remark, description, ct_pri, ct_sec, retryNoSame fields as the Add/Edit Device dialog

On PUT, any field left out keeps its current value — only send the fields you want to change.

Example request (create)

curl -X POST "https://your-ems-server/api/devices/" --data-urlencode "sdkey=YOUR_SDKEY" --data-urlencode "name=Meter 1" --data-urlencode "loop=1" --data-urlencode "addr=1" --data-urlencode "model=16"

Example response

{"status":"O.K.","code":200,"id":57}

7) Model library API

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

NameRequiredDescription
sdkeyYesAPI key (or header X-API-Key)
idNoReturn 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.

Example request

curl -G "https://your-ems-server/api/models/" --data-urlencode "sdkey=YOUR_SDKEY"

Example response

{"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)

HTTPresultCause
401ERRORInvalid or missing sdkey (loop/device APIs also return 401 when the key is valid but write access is not enabled)
400ERRORMissing or invalid parameters (e.g. live: meter_id; history: begin/end/pointId)
502ERRORService 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.

Latest release

The current release is 2.9.1. See Download > Software for installers.

Upgrading

  1. Back up the database from Administration → Database → Backup.
  2. Apply the upgrade package provided by your vendor or IT team.
  3. Open Administration → Database → Update and confirm all steps complete successfully — especially after restoring an older database backup.
  4. Restart the EMS background service from Administration → System → Services so polling, alarms, and Logic Studio use the new release.
  5. Hard-refresh the browser (Ctrl+F5) on pages you use frequently.

Release notes

Newest releases appear first. Component versions (e.g. Logic Studio) are listed when they differ from the main EMS version.

v2.9.1 Current

November 2026

MCP can create a USB C-Loop Meter loop and a Digital Meter loop that reads C-Loop frames over UDP.

EMS Web: 2.9.1 EMS Service: 2.9.1 EnergyLink360 MCP: 0.1.0 Logic Studio: 0.2.8
  • 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_frame cloop 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.

EMS Web: 2.9.0 EMS Service: 2.9.0 EnergyLink360 MCP: 0.1.0 Logic Studio: 0.2.8
  • 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.

EMS Web: 2.8.10 EMS Service: 2.8.10 Logic Studio: 0.2.8
  • 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).

EMS Web: 2.8.9 EMS Service: 2.8.9 Logic Studio: 0.2.8
  • 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.

EMS Web: 2.8.8 EMS Service: 2.8.8 Logic Studio: 0.2.8
  • MQTT Device — new Modbus-alternative protocol path: loops/devices, subscribe topics, point mapping in Models, and EMS service runtime (mqtt_device_service).
  • MQTT Models — point editor Read / Write tabs: subscribe + JSON path, command topic / payload templates, QoS, retain, and optional readback path.
  • 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.
  • COMTRADE Waveform — opt-in (Administration → Settings → Waveform) for Modbus TCP capable models (e.g. PowerLogic PM8000).
  • 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 Web: 2.8.7 EMS Service: 2.8.7 Logic Studio: 0.2.8
  • 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.

EMS Web: 2.8.6 EMS Service: 2.8.5 Logic Studio: 0.2.8
  • Import History — operator UI and workflow for reviewing meter history imports (preview / commit helpers).
  • Meter history import — CSV / external log merge and import fixes; safer preview and commit paths.
  • IAQ Report — custom report updates, PDF / Excel export improvements, and restore / email merge fixes.
  • Reports — export performance improvements (including OpenSpout for large Excel output where applicable).
  • Sites / Devices — treeview drag-and-drop reliability fixes (reorder / move) and iframe sync polish.
  • Billing / export pages — aligned cache-bust and shared explorer styling with the current release.

v2.8.5

July 2026

Schedule Exception2 and editor UX, Modbus TCP loop timeout, Group edit polish, and EMS service race fixes.

EMS Web: 2.8.5 EMS Service: 2.8.5 Logic Studio: 0.2.8
  • 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.

EMS Web: 2.8.3 EMS Service: 2.8.3 Logic Studio: 0.2.8
  • Schedule — folder tree, templates, copy/remove, point binding, weekly editor, and PDF export integrated with Database Update schema steps.
  • REST API — new / updated devices, loops, and models endpoints with API docs refresh.
  • Digital Meter Log — progress UI, export cache helpers, and Excel / PDF export improvements.
  • Alarms — Alarm Pending and Device Offline operator pages with clear / acknowledge actions.
  • License — improved online token and key handling; backup / restore UI reliability fixes.
  • Model Library — import / pull / publish preview helpers; meter history and kWh file-cache helpers for reports.
  • Menus — role-based menu filtering helpers for administration screens.

v2.8.0

July 2026

Mod Scan 360 user guide, Sites copy/delete, Modbus TCP per-loop reload, and export improvements.

EMS Web: 2.8.0 EMS Service: 2.8.0 Logic Studio: 0.2.8
  • 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.

EMS Web: 2.7.0 EMS Service: 2.7.0 Logic Studio: 0.2.8
  • 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

  1. The EMS service keeps one broker connection per MQTT loop and subscribes to every topic the loop's devices need.
  2. 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.
  3. 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).
  4. 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.

FieldDescription
IP Address / PortBroker host and port. Usually 1883, or 8883 with TLS.
Client IDLeave 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 / PasswordOnly 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.
TLSEncrypted connection to the broker.
Clean sessionStart each connection without broker-side session state.
Keepalive / QoSKeepalive 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

FieldDescription
MQTT MappingRead/write this point over MQTT. Off = the point has no MQTT mapping.
Subscribe TopicTopic 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 PathWhere 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)
Value TypeFloat, Integer, Boolean or String. Boolean accepts true/false, 1/0, on/off, yes/no.
Timestamp PathOptional 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.

FieldDescription
Command TopicTopic to publish to, e.g. cmnd/{device_key}/POWER. Same placeholders as Subscribe Topic.
Command PayloadPayload template. {{value}} (double braces) is replaced with the commanded value: {{value}}, {"setpoint":{{value}}}.
Write ModeState / 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 OptionsState 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 / StepRange mode: a value below Min or above Max is clamped before publishing; Step sets the input increment (e.g. 0.5).
QoSPer-point QoS. Default uses the loop's QoS.
RetainPublish with the retain flag. Use with care: a retained command is replayed to the device every time it reconnects.
Readback TopicOptional 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 PathWhere 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:

FieldDescription
Device KeyReplaces {device_key} in every topic of the Model, e.g. tasmota_A1B2C3. No / or spaces.
Topic VariablesOptional 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 timeoutSeconds 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.

PointSubscribe TopicJSON PathWrite
1 Power (W)tele/{device_key}/SENSORENERGY.Power—
2 Voltage (V)tele/{device_key}/SENSORENERGY.Voltage—
3 Relaystat/{device_key}/POWER$Command Topic cmnd/{device_key}/POWER, Write Mode State, options ON/On/ON and OFF/Off/OFF, Readback Topic stat/{device_key}/POWER, Readback Path blank

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

SymptomWhat to check
Whole loop offlineBroker host/port, TLS on/off, username/password. Another client using the same Client ID. Firewall between EMS and broker.
Device offline, others fineDevice 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 blankJSON 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 numberValue Type (Integer truncates decimals), Factor / Offset / Formula on the Model point.
Command "failed" but device switchedReadback 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 nothingCommand Topic placeholder not filled (Device Key / Topic Variables), point not writable, or no Edit permission.
Device gets the old command after rebootRetain 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

LayerWhat 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 serviceStore 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).

TabUse
OverviewStatus, plus two switches: MCP access (master on/off — when off, every MCP call fails within one second, including open sessions) and Edit mode.
Access TokensCreate 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 ModeOpens 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 SetsEverything 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 ImageStage a PNG/JPEG for 15 minutes so the assistant can attach it to a Model (see Models below).
Audit LogEvery 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

  1. Read and write are separate tokens. A read token can never change anything.
  2. Scopes limit what a write token may touch (table below). A missing scope is reported by name, e.g. forbidden scope=devices:write.
  3. 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.
  4. Edit Mode must be on for any write.
  5. Preview first. A write tool only creates a Change Set and shows what would change. Nothing is saved yet.
  6. 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.
  7. Rollback of an applied Change Set needs its own approval and only works if nobody changed the same item afterwards.
  8. 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.

Token scopes

ScopeAllows
loops:read, devices:read, models:read, points:readReading loops, devices (with live online state), models, points, values and history.
loops:writeLoop create / edit / delete / rename / reorder, BACnet settings, manual BACnet device (with devices:write).
devices:writeDevice create / edit / delete / rename / reorder, BACnet discovery, duplicate Logical Device.
models:writeModel create / edit / copy / delete / image, Library import (with points:write).
points:writeModel points, Logical Device mappings, sites, groups, schedules, point detail, maps, BACnet point import, point commands.

Connecting an AI client

Local (stdio)

For an assistant running on the EMS server itself (Claude Code, Cursor):

{
  "mcpServers": {
    "EnergyLink-P15": {
      "command": "/opt/energylink-mcp/.venv/bin/python",
      "args": ["-m", "energylink_mcp"],
      "env": {
        "ENERGYLINK_API_BASE_URL": "http://127.0.0.1/ems81/api/v1",
        "ENERGYLINK_API_TOKEN": "<read token>",
        "ENERGYLINK_API_WRITE_TOKEN": "<write token>"
      }
    }
  }
}

Remote (Streamable HTTP)

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).

AreaMain tools
Statushealth, get_config_capabilities (field rules, encodings, MQTT rules — the assistant reads this before writing)
Loops & deviceslist_loops, list_devices, list_device_online_status, get_device, list_device_points; preview_loop_config, preview_device_config, renames, reorder
Modelslist_models, get_model_points, preview_model_config, preview_model_points, preview_config_batch (Model + points + devices in one Change Set), get_model_image / preview_model_image / preview_model_image_clear
Cloud Model Librarylist_cloud_models, get_cloud_model, preview_library_model_import (create, create as new name, or replace)
MQTTMQTT Model points and MQTT devices through the Model / Device tools (next section)
BACnetget_bacnet_settings, list_bacnet_devices, list_bacnet_points, start_bacnet_discovery / get_bacnet_discovery_job / cancel_bacnet_discovery, import_bacnet_points, create_bacnet_device, update_bacnet_settings
Logical Devicelist_logical_devices, list_logical_device_mappings, set_logical_device_mapping, clear_logical_device_mapping, bulk_set_logical_device_mappings, duplicate_logical_device
Values & historyread_point_values (up to 200 points, cache or fresh read), get_point_history, site / point live, history, consumption and event reports
Sites & groupslist_sites, create_site_group, move_site_group, add_site_points, attach_device_to_site / detach_device_from_site, groups and group templates
SchedulesFolders, schedules, weekly templates, holidays (incl. Thai holiday import), exceptions, set_point_schedule
Point detailupdate_point_detail, update_point_command, Modbus export mapping
E-MapMaps, pages, layers, shapes, widgets, Widget Library icons, bindings and links
Alarmslist_offline_devices, list_pending_alarms, list_realtime_events, event history
Change Setsget_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).

ObjectKeys
Point mqttmapping_enabled, subscribe_topic_template, json_path, value_type (float|int|bool|string), source_timestamp_path, command_topic_template, command_payload_template, qos, retain, write_type (state|analog), state_options [{value, label, payload}], min_value, max_value, step_value, readback_topic_template, readback_json_path
Device mqttdevice_key, topic_vars (object), freshness_timeout_sec (Offline timeout), enabled
  • 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

ResultMeaning
status=previewed, approval_requiredWaiting for a person in Plug-Ins → MCP or the home-page popup.
status=appliedSaved and read back.
loop_id_reloadThe 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.
warningsSaved 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

MessageWhat to do
MCP access is disabled / every call failsTurn on MCP access in Plug-Ins → MCP → Overview.
edit mode is disabledOpen a window in the Edit Mode tab.
forbidden with scope=…Create a write token with that scope (Access Tokens tab).
forbidden without a scopeThe token owner lacks the menu right or loop/site access.
Write token is not configuredThe MCP server has no write token; reads still work.
stale_previewSomeone changed the item after the preview. Ask the assistant to preview again.
approval_must_be_webExpected — approve in the web UI.
mapping_impactA Model change would drop Logical Device mappings; review the list and confirm.
schema_update_requiredRun Administration → Database → Update.
New tools missing in the AI clientRestart / toggle the MCP server in the client.