# Pythia Technologies — DM Series Guide For the DM, SPDM, SPIGM and SPAC4 · Revision DRAFT 2026-09-30 · pythiatech.com/pythia-dm --- # [USE] How to use this guide **This guide is written to be read by an AI assistant for you.** You don't need to read it cover to cover. Give it to an AI assistant and ask your question in plain words. The assistant answers from these pages and can walk you through each step. ## [USE-1] Quick start 1. **Get the guide** from **pythiatech.com/pythia-dm**. The text-file version ("DM Series Guide for AI Assistants") works best with AI assistants; the PDF is for reading. 2. **Open an AI assistant**, such as Claude, ChatGPT, Microsoft Copilot or Google Gemini. 3. **Give it the guide.** Attach the text file to a new conversation (look for a paperclip, **+** or **Attach**). Or, if your assistant can browse the web, ask it to read the "DM Series Guide for AI Assistants" from pythiatech.com/pythia-dm. 4. **Ask your question**, and ask follow-up questions as you would with a knowledgeable colleague. The **Help** button in the DM console points to the same page ([GS-7]). ## [USE-2] Questions you can ask - "How do I add a new location, group and unit?" - "What does the red COMMUNICATIONS status on a unit mean, and what should I check?" - "Set me up to email the on-call team, but only for critical alarms, and not overnight." - "How do I bring a Smart Panel leak sensor into an alarm?" - "Why didn't I get an email for this alarm?" - "How do I give a coworker View-only access?" - "How do I connect Claude to my DM with the AI Connector?" - "Give me the Modbus register list for our BMS integrator." - "What does this message mean: (paste the message)?" ## [USE-3] Tips - **Be specific:** name the page, unit or message you're looking at. - **Ask for step-by-step instructions** when you want to follow along. - **Say which product you have** (DM, SPDM, SPIGM or SPAC4) if it isn't a plain DM. - **Paste the exact message** you see on screen. > **Important:** Don't paste passwords, tokens, SNMP communities, customer names or IP addresses into a public AI tool unless your organization allows it. You don't need them to get help: this guide contains no site secrets. If your question isn't answered here, contact Pythia Technologies: **support@pythiatech.com**. --- # [AIX] Instructions for AI assistants You are helping a user of a Pythia Technologies DM-family product. Follow these rules. 1. **Answer from this document.** Cite the section ID in brackets, e.g. "(see [ALM-3])", so the user can find it. If the document doesn't cover something, say so and suggest contacting Pythia Technologies (support@pythiatech.com). Don't guess at menu names, defaults or behavior. 2. **Identify the product.** Part 1 applies to every product. SPDM/SPIGM add [SPD]; SPAC4 is covered in [SPA]. If the user hasn't said which product they have and it matters, ask. 3. **Use the exact labels.** Bold text is exactly what appears on screen. Quoted text is exactly what the DM displays. Navigation is written as **A › B › C** following the console's tree. 4. **Respect roles.** Many actions are Admin only ([APX-B]). If the user is a View user, tell them to ask an Administrator. 5. **Repeat every Caution** for irreversible or equipment-affecting actions before giving the steps: commands to equipment, deletions, Trend Off (it deletes history), updates, network changes. 6. **Never ask for secrets.** Don't ask the user to share passwords, API tokens or SNMP community strings. 7. **Start with the task index.** For "how do I…" questions, look up [MAP]; for problems, [APX-D]; for on-screen messages, [APX-A]. 8. **If you are connected to a live DM** through the AI Connector, the live DM wins: call `get_info` first ([AIC-7]). 9. **Keep answers short and practical.** Give steps, then offer to explain further. --- # [MAP] Task index | I want to… | Section | |---|---| | Sign in / sign out | [GS-3], [GS-6] | | Understand the screen layout | [GS-4] | | Find something by name | [GS-5] | | See active alarms | [ALM-2] | | Put alarms on a wall screen | [GS-2] | | Acknowledge an alarm | [ALM-3.1] | | Clear a stuck alarm | [ALM-3.2] | | Test an alarm and its notifications | [ALM-7] | | Review past alarms | [ALM-6] | | Add a location / group / unit | [MON-2.1], [MON-3.1], [MON-4.2] | | Rename or delete something | [CON-3.3], [CON-5] | | Add a picture banner to a location or group | [MON-5] | | Change the site picture or list refresh rate | [CON-2.1] | | Show temperature/humidity gauges for a group | [MON-4.1] | | See a unit's live readings | [UNIT-1] | | Add data points, controls or alarm settings to a unit | [UNIT-1.4], [UNIT-2.2], [UNIT-3.3], [UNIT-4.2] | | Change an alarm threshold or severity | [UNIT-4.3], [UNIT-4.4] | | Send a command or change a setpoint | [UNIT-3.2] | | Understand an equipment dashboard | [EQP] | | Choose the right driver for my equipment | [DRV] | | Identify a Liebert IGM unit | [APX-E.1] | | Set up a cooling-unit manager (lead/standby, failover) | [DRV-3.1] | | Email people when alarms happen | [AUT-2.1], [AUT-3] | | Only notify for some alarms | [AUT-1] | | Stop notifications at certain times | [AUT-5] | | Send SNMP traps to a management system | [AUT-4], [INTG-4.2] | | Send daily "still alive" emails | [AUT-6] | | Set up the outgoing mail server | [SET-7] | | Record and chart history | [TRD-2], [TRD-3] | | Export a chart or list | [TRD-4], [CON-9] | | Add a user / give View-only access | [USR-2] | | Change my password | [USR-4] | | Disable or remove someone's access | [USR-1], [USR-3] | | Restrict which computers can reach the DM | [SET-2] | | Back up the configuration | [SET-3] | | Apply a software update | [SET-9] | | Change the DM's IP address | [SET-5] | | Set the time zone or NTP | [SET-8] | | Restart the DM | [SET-1.1] | | Look at logs / who signed in | [SET-10], [USR-6] | | Connect a BMS or SCADA (Modbus, BACnet) | [INTG-3], [INTG-5] | | Connect a network-management system (SNMP) | [INTG-4] | | Allow an external system to write setpoints | [INTG-2.2] | | Export the register / OID / object list | [INTG-2.1] | | Set up ALC WebCTRL points | [INTG-7] | | Connect an AI assistant to the DM | [AIC-2], [AIC-5] | | Control what AI assistants may change | [AIC-3] | | Build my own dashboard page | [CUS-2], [CUS-3] | | Map a Smart Panel input and alarm on it | [SPD-1.2], [SPD-2] | | Use SPAC4 | [SPA] | | Demonstrate the DM without equipment | [APX-E.2] | | Understand a message on screen | [APX-A] | | Fix a problem | [APX-D] | | Look up a term | [APX-C] | --- # [INT] Introduction ## [INT-1] What a DM does A Pythia Technologies **DM** (Data Monitoring appliance) watches the equipment that keeps a site running: UPS systems, generators, power distribution and meters, cooling units, leak and environmental sensors, servers and switches. It then tells people when something needs attention. It: - **polls** each piece of equipment over its own protocol (SNMP, Modbus, BACnet, Liebert IGM and others) every few seconds; - shows everything live in a **web console** and on an **Alarm View** wall display; - raises **alarms** when conditions are met, and sends **email** and **SNMP traps**; - records **history** (alarm history and trends); - lets authorized people **command** equipment (for example start a unit or change a setpoint); - **publishes** all of its data to building-management and network-management systems over SNMP, Modbus/TCP and BACnet/IP; - lets **AI assistants** read the site, and act on it only where an administrator allows ([AIC]). The DM is delivered preconfigured on Pythia hardware. ## [INT-2] The product family | Product | What it is | Covered in | |---|---|---| | **DM** | The core monitoring appliance | Part 1 | | **SPDM** / **SPIGM** | A DM with a built-in Smart Panel input module (SPIGM is a different physical build of the same software) | Part 1 + [SPD] | | **SPAC4** | A Smart Panel that controls a team of air-conditioning units | [SPA] (and Part 1 where it applies) | ## [INT-3] How the DM organizes a site ``` Site (the DM) └── Locations e.g. Powell Office └── Groups e.g. Power Rack 1, Environmentals └── Units e.g. UPS-21A, Office TH1 ├── Data readings (Temperature, Output Load…) ├── Controls writable points (Unit On, Temperature Setpoint…) └── Alarms alarm settings (High Temperature…) ``` - A **unit** is one piece of equipment, polled by a **driver** for its make and model ([DRV]). - **Alarm settings** on a unit define *when* an alarm fires. The resulting **alarm events** appear under **Alarms** ([ALM]). - **Status rolls up:** a unit in alarm turns its group, location and the tree red. **Disabled** items are gray and raise no alarms. ## [INT-4] What happens when something goes wrong 1. The unit's driver polls the equipment. A reading crosses a threshold, a status switches on, or the equipment stops answering. 2. After the alarm's **Fail Count** of polls in a row, the alarm fires. It appears in **Alarms › Active**, turns the tree red, and shows on the Alarm View. 3. Every **automation** whose categories include the alarm's category sends email and/or SNMP traps, unless it's in a quiet time ([AUT]). 4. Someone **acknowledges** it to show it's being handled ([ALM-3]). 5. When the condition ends, the alarm clears by itself, a CLEAR notification goes out, and the occurrence is kept in **History**. ## [INT-5] Who can do what - **Admin:** everything. - **View:** see everything, change nothing (except their own password). - **API:** AI assistants through the AI Connector, with limits the Admin sets. Details: [USR] and [APX-B]. ## [INT-6] How this guide is organized - **Part 1 — Core Platform** (every product): [GS] Getting started · [CON] Working with the console · [MON] Monitoring your site · [UNIT] Units in detail · [EQP] Equipment dashboards · [ALM] Alarms · [AUT] Automations and notifications · [TRD] Trends · [USR] Users and accounts · [SET] System settings · [INTG] Integrations · [CUS] Custom pages - **Part 2 — DM AI Connector:** [AIC] - **Part 3 — SPDM and SPIGM:** [SPD] - **Part 4 — SPAC4:** [SPA] - **Part 5 — Equipment catalog:** [DRV] - **Appendices:** [APX-A] Messages · [APX-B] Access rights · [APX-C] Glossary · [APX-D] Troubleshooting · [APX-E] Tools and demo driver · [APX-F] What changed · [APX-G] About this document --- ===================================================================== # PART 1 — CORE PLATFORM (all DM-family products) ===================================================================== # [GS] Getting Started Applies to: all DM-family products · all users This chapter covers what you see when you first open the DM, how to sign in, how the console is laid out, and how to find your way around. Everything later in this guide assumes you know the parts named here. --- ## [GS-1] Opening the DM Type your DM's address into a web browser, for example `https://dm.example.com/`. Your administrator or Pythia Technologies gives you the address. - On a **DM, SPDM or SPIGM**, the address opens the **Alarm View** ([GS-2]), a live alarm board that needs no sign-in. - On an **SPAC4**, the address opens the panel display instead ([SPA]). To reach the full console, click **Launch DM** on the Alarm View, or go to `https:///default.asp`. Either way you arrive at the sign-in page ([GS-3]). **Browser requirements:** any current browser (Chrome, Edge, Firefox or Safari) with JavaScript turned on. The console uses a dark theme only. The Alarm View also works on phones and tablets. --- ## [GS-2] The Alarm View Applies to: DM, SPDM, SPIGM · no sign-in required The Alarm View is a single page built for wall screens and quick checks. It shows the DM's active alarms and updates every 2 seconds. > **Note:** Anyone who can reach the DM's address can open the Alarm View without signing in. It shows active alarms, alarm history, and who acknowledged an alarm, including their note. It cannot change anything. **Top of the page:** | Control | What it does | |---|---| | **Launch DM** | Opens the console sign-in page in a separate browser tab. | | **Active** / **History** | Switches between current alarms and past alarms. | | **Flash** | When on (the default), the browser tab flashes when a new unacknowledged alarm arrives. Your choice is remembered on this browser. | | **Refresh** | Reloads the list immediately. | | Status dot and **Updated:** | Green when the page is receiving data; shows the time of the last update. | **Active mode** (title **Active Alarms**): - Columns: **Severity**, **Time**, **Location**, **Group**, **Unit**, **Type**, **Text**. A legend shows the four severities: **CRT** Critical, **MAJ** Major, **MIN** Minor, **WAR** Warning ([ALM-1]). - An alarm someone has acknowledged shows a green **ACK** badge next to its severity and appears dimmed ([ALM-3]). - The subtitle counts active alarms, and unacknowledged ones when some are acknowledged: "3 Active Alarms · 1 unacknowledged". - With nothing active: "No active alarms — all systems normal." - The browser tab's icon turns the color of the worst **unacknowledged** alarm. When every active alarm is acknowledged, the normal icon returns, even though alarms are still active. - Tab flashing stops when you look at the tab, after 30 seconds, or when no unacknowledged alarms remain. The first load never flashes. **History mode** (title **Alarm History**): - Columns: **Time Start**, **Time Stop**, **Location**, **Group**, **Unit**, **Type**, **Text**. - **Show:** **Last 4h** (default), **Last 8h**, **Last 12h**, **Last 24h**, **All**. - History does not refresh by itself. Click **Refresh**. In both modes you can search the list, sort by clicking a column heading, and export the list with **PDF** or **Excel**. Exports do not include acknowledgment details. The Alarm View is read-only. To acknowledge or clear alarms, sign in to the console ([ALM]). --- ## [GS-3] Signing in 1. Open the sign-in page (**Launch DM**, or `https:///default.asp`). 2. In **User:**, type your sign-in name. This is usually your email address; capital letters don't matter. 3. In **Password:**, type your password. Click **Show** to see what you typed (**Hide** hides it again). "Caps Lock is on." appears if it is. 4. Press **Enter** or click **Sign On**. The button reads **Signing in...** for a second or two while your browser prepares a secure sign-in. Your password itself is never sent to the DM. 5. The console opens ([GS-4]). If sign-in fails, the page shows the reason, clears the password box and lets you try again: | Message | Meaning | What to do | |---|---|---| | "Invalid credentials" | Wrong sign-in name or password, or the account is disabled. The DM deliberately does not say which. | Check both; ask an administrator to check the account. | | "Nonce expired" | Too much time passed between starting the sign-in and completing it. | Try again. | | "JavaScript is required to sign in to this system." | JavaScript is turned off in your browser. | Turn it on and reload the page. | > **Note:** AI accounts (Access **API**) cannot sign in to the console. They connect through the AI Connector ([AIC]). ### [GS-3.1] First sign-in with an older login name Applies to: accounts whose sign-in name is not an email address Sign-in names must now be email addresses. If yours isn't, the DM shows **Update Your Login** after you sign in: "Please update your account to use an email address as your login. This is required before you can continue." 1. Enter your email address in **New email** and click **Change Email**. 2. When **Email Updated** appears, click **OK, Sign In** and sign in with the new email address and your existing password. **Cancel** signs you out; you will see this page again next time. The built-in **Admin** account is exempt. --- ## [GS-4] The console layout The console has four areas: ``` ┌──────────────────────────── Top bar ────────────────────────────┐ │ Search… [pills] Help Sign Out │ ├──────────────┬──────────────────────────────────────────────────┤ │ Navigation │ │ │ tree │ Content area │ │ │ │ ├──────────────┴──────────────────────────────────────────────────┤ │ DIRECTORY: / Locations / … All normal 12:49:23 admin │ └─────────────────────────── Status bar ──────────────────────────┘ ``` ### [GS-4.1] Navigation tree (left) The tree is how you move around the DM. The top row shows the logo and your site's or product's name; click it to return to the **Site Overview**. Below it are the main areas: | Tree item | What it holds | Chapter | |---|---|---| | **Alarms** | Active alarms, information events, alarm history | [ALM] | | **Automations** | Email and SNMP-trap notifications, heartbeats | [AUT] | | **Locations** | Your sites: locations › groups › units | [MON], [UNIT] | | **Logs** | Service logs and the Logins log | [SET] | | **Settings** | System settings, policies, mappings, network, time, updates | [SET], [INTG] | | **Smart Panel** | The Smart Panel (SPDM/SPIGM only) | [SPD] | | **Trends** | Trend buckets and history | [TRD] | | **Users** | User and API accounts | [USR] | | **Views** | Fleet views such as sensors and branch circuits | [INTG] | Your DM may show fewer or more items depending on its product and installed features. - Click an item's **name** to open its page (and expand it). Click the **chevron** (›) to expand or collapse it without opening it. - Icons and names change color with status: **red** = in alarm, **dimmed gray** = disabled. - The tree remembers which branches you expanded while the browser tab stays open. - View users see only their own account under **Users**. > **Note:** Always move around the console with the tree, the status bar, or the rows in a page. If you open a console page by typing its address, it opens on its own without the tree and navigation. ### [GS-4.2] Top bar | Item | What it does | |---|---| | **Search** box | Finds units, locations, groups and points by name ([GS-5]). | | **Reset to default page** | Appears only while a custom page is showing ([CUS-4]). | | **Update available — Refresh** | Appears when the DM's software or custom pages have changed. Click it to reload all four areas ([CON]). | | **Help** | Opens the console help document in a new tab. | | **Sign Out** | Signs you out immediately, with no confirmation. | ### [GS-4.3] Status bar (bottom) - **DIRECTORY:** where you are, for example `/ Locations / Powell Office / Power Rack 1`. Click any part to go there, or **/** for the Site Overview. A colored dot shows the current item's status. - **Alarm badge:** "All normal" (green) or "N active alarms" (red). Click it to open **Alarms › Active** ([ALM]). - **Connection warnings:** "Disconnected – retrying" when the DM has not answered for 12 seconds; "Session expired" when you have been signed out ([GS-6]). - **Clock:** time and date from **your computer's** clock, not the DM's. - **You:** your sign-in name and role badge (**Admin** in blue, **View** in gray). ### [GS-4.4] Content area Everything else appears here: lists, unit pages, dashboards, settings. The common controls used on every page (Cards/Table, refresh indicators, Properties dialogs, Add and Delete) are in [CON]. --- ## [GS-5] Searching 1. Click the search box in the top bar ("Search units, groups, points, alarm settings… (press Enter)"). 2. Type at least 2 characters, then press **Enter** or click the arrow button at the right end of the box. With fewer than 2 characters, nothing happens. 3. The **Search** page opens in the content area. It lists matches grouped as **Units**, **Locations**, **Groups**, **Alarms**, **Controls** and **Data Points**, each with a status dot, its location path, and a type badge. 4. Refine the search in the box at the top of the results; the list updates as you type. Click a result (or press **Enter** for the first one) to open it. Search looks at the names and descriptions of locations, groups and units, and at each unit's alarm settings, controls and data points. Under **Alarms** it finds a unit's **alarm settings**, not alarms that are currently active; use **Alarms › Active** for those ([ALM]). It shows at most 40 results: "Showing the first 40 of N matches — refine your search." --- ## [GS-6] Sessions, connection loss and signing out **Session expired.** If you are signed out after **20 minutes** without activity, or because the DM restarted, the page shows **Session expired**: "Your session ended after a period of inactivity." (or "The server was restarted or unreachable, and your session has ended."). Click **Sign in now**, or wait 5 seconds, to go to the sign-in page. After you sign in again, the console reopens the page you were on. **Connection lost.** If the DM stops answering (network problem, DM rebooting), pages show a yellow "Connection lost — reconnecting…" pill and keep trying. They recover on their own when the connection returns; you do not need to sign in again unless your session also ended. **Signing out.** Click **Sign Out** in the top bar. You return to the sign-in page. Closing the browser tab without signing out leaves your session open until it times out. --- ## [GS-7] Help Click **Help** in the top bar. The **Help and Documentation** window opens over the current page: - "The DM Series Guide is on the Pythia Technologies website, as a PDF for humans and a text file for AI assistants:" followed by the address **pythiatech.com/pythia-dm**. Click it to open the page in a new tab, or click **Copy** to copy the address. - "If this computer cannot reach the internet, type that address on another device." - "Tip: ask your AI assistant to read the "DM Series Guide for AI Assistants" from that page, or download the text file and attach it to your chat." ([USE]) - "Questions? Contact Pythia Technologies support at support@pythiatech.com." Close it with **×**, the **Esc** key, or a click outside the window. If your browser blocks copying, the button reads **Select and copy**; select the address and copy it yourself. --- # [CON] Working with the Console Applies to: all DM-family products · all users (editing is Admin only) Every console page is built from the same small set of controls: a Cards/Table switch, an auto-refreshing data area, a **Properties** dialog for editing, an **Add** dialog for creating, and a confirmation for deleting. This chapter describes each one once. Later chapters say "open **Properties**" or "use the rename pencil" and only list the fields each page offers. --- ## [CON-1] Cards and Table views Most list pages (locations, groups, units, settings and other containers) can show their contents two ways: - **Cards:** a grid of tiles. Each shows the item's icon, name and, when there is one, its description. Click a card to open the item. - **Table:** one row per item, with columns specific to the page. Click a row to open the item. Switch with the **Cards** and **Table** buttons at the right of the section header. The active one is solid blue. Your choice is remembered on this browser and applies to **every** list page until you switch back. An empty page shows "No items in this container." --- ## [CON-2] Auto-refresh and the status dot Pages keep themselves up to date. You never need the browser's reload button. - **Live pages** (equipment dashboards, alarm lists) refresh every **2 seconds**. - **List pages** refresh at the site's **list-view refresh rate**. An Admin sets it under **Site Properties** ([CON-2.1]). The page footer shows the current rate, for example "auto-refresh every 5 seconds", or "No auto-refresh" when it is 0. - Some pages load once and don't refresh, such as property pages, alarm history and log viewers. They say so in their footer. At the top right of each page: - **Status dot:** green and pulsing = healthy; amber = loading; red = the last update failed; gray = the item is disabled. - **Updated: HH:MM:SS** (or **Last Update:**): the time of the last successful update. If it keeps advancing, the data is live. - **Refresh** button (on many pages): update now. ### [CON-2.1] Site Properties Applies to: Admin On the **Site Overview** (click the site name at the top of the tree), click **Properties**: | Field | Meaning | |---|---| | **Site Identifier** | The DM's site code. | | **List View Refresh Rate in Seconds. 0 = No Refresh** | How often list pages refresh: 0, 2, 5, 10, 15, 30, 60 or 120 seconds. Default 10. | | **Site Image** | The picture on the Site Overview. **Change image…** replaces it immediately, without Save ([MON]). | --- ## [CON-3] The Properties dialog Applies to: Admin (View users see the same values read-only) **Properties** is the console's single way of editing. A location, a unit, a data point, an email recipient or a system setting is always edited in a dialog with the same layout. Open it with: 1. the blue **Properties** button in a page's header, which edits the item whose page you are on; or 2. on some pages, an item's name or row, which edits that item without leaving the list. Simple items (a single email recipient, an allowed address) have their own page with a **Property | Value | Description** table and a **Properties** button above it. The dialog is the same. ### [CON-3.1] Fields you will see | You see | It means | |---|---| | Text or number box | Type a value. Number boxes accept whole numbers or decimals as the field requires. | | Toggle switch | Yes/No. Green and to the right = Yes. Tables show **Yes** / **No**. | | Dropdown | Pick one value. A blank first entry clears the value. | | Checkbox list | Tick every option that applies (for example several alarm categories). | | Password box | Always empty, with "Leave blank to keep current". Leave blank to keep the stored value; type to replace it. The stored value is never shown. | | Image or page field | A box with **×** (clear) and **Choose…** (pick or upload a file) ([CUS-3]). | | Small table | Read-only information made of several name/value pairs. | Grayed fields are read-only (live readings, system-assigned values); empty read-only fields are hidden. "Property type N not yet editable in this dialog" marks a value you can see but not change here. ### [CON-3.2] Saving - **Save** stays disabled until you change something. - Click **Save** to write all changes at once. On success the dialog closes and the page shows the new values. - **Close** (or **×**) leaves without saving. - If the DM rejects a value, the reason appears in red at the bottom of the dialog and nothing is changed. Common reasons: - " must be a number" - " is below the minimum of " / " is above the maximum of " - " value "" is not one of the allowed options" - Field "" cannot contain a pipe character (|). No value anywhere may contain `|`. ### [CON-3.3] Renaming with the pencil Where a name can be changed, the dialog shows it at the top with a **pencil**. Renaming takes effect on its own, separately from **Save**. 1. Click the pencil. The name becomes an edit box with a green **✓** and a gray **✕**. **Enter** confirms and **Esc** cancels. 2. Type the new name and click **✓**. The name changes at once in the dialog, the tree and the page address. Everything under the item keeps working. If the name is refused, a red message appears next to the box: - "Name is required" / "Name must be 1-100 characters" - "Invalid characters: \ & % # ? " ," - "That name already exists" - For items named by an address: "Must be a valid IPv4 address (e.g. 192.168.1.10)" or "Must be a valid email (e.g. user@example.com)" Names that cannot change appear grayed with no pencil. > **Note:** Whether a unit, data point, control or alarm can be renamed depends on the unit's driver. Units using a **generic** driver allow renaming. Most equipment-specific drivers use fixed point names, which you cannot rename, because the driver and its dashboard identify each point by its name ([EQP]). > **Note:** Renaming a unit, data point or alarm keeps its trend history, but systems outside the DM that refer to it by name (for example a BMS reading its SNMP/Modbus/BACnet mapping, or an AI assistant) may need updating ([INTG]). --- ## [CON-4] Adding items Applies to: Admin Pages that accept new items have a blue **Add** button. It opens **Add to **, with the same field types as Properties. - Required fields are marked **\***. - Problems are shown in red under the field before anything is sent, for example: "IP Address" must be a valid IPv4 address (e.g. 10.251.0.0) -- check for an extra dot or space. - Click **Save**. After a brief **Saving...** overlay ([CON-6]), the console opens the new item so you can continue setting it up. --- ## [CON-5] Deleting items Applies to: Admin **Delete** is never a toolbar button. It is the red **Delete** button at the bottom left of the **Properties** dialog. 1. Open **Properties** and click **Delete**. 2. A confirmation names exactly what will be removed and says "This action cannot be undone." 3. Click the red **Delete** to proceed, or **Cancel**. > **Caution:** Deleting is permanent: there is no undo or recycle bin. When the confirmation says "and everything inside it", everything under the item is deleted too, including its settings and history. Some items must be emptied first. The DM refuses and says what is still inside, for example: > The location "Powell Office" contains 6 group(s). > Delete all group(s) before deleting this location. After a delete, the console shows **Saving...** briefly and opens the parent page. --- ## [CON-6] The "Saving..." overlay After you add, rename or delete something, the screen dims under **Saving...** while the DM finishes the change. It usually clears in a second or two, then the console opens the right page by itself. There is nothing to click. --- ## [CON-7] Working alongside other users Several people can use the console at once. - **Someone deletes what you are viewing:** your page shows "Redirecting to in 3 second(s)..." and then opens the parent page. Click **Go now** to go immediately. - **Update available — Refresh:** a pill in the top bar tells you the console has changed since you opened it. This happens when new DM software is installed, a custom page or image is uploaded, or a page is reset to its default. Your pages keep working; click the pill when convenient to reload all four areas of the console. --- ## [CON-8] Connection problems - **"Connection lost — reconnecting…"** (yellow pill at the bottom of the page): the DM stopped answering. The page keeps retrying and clears the pill by itself when the DM answers again. A page first opened during an outage shows "Connection lost — attempting to reconnect…" and "This page will refresh on its own once the connection is back." - **"Disconnected – retrying"** in the status bar: no answer for about 12 seconds. - **"Session expired":** you have been signed out ([GS-6]). - **Rebooting Gateway:** after an Admin restarts the DM ([SET]), the console waits and returns to the sign-in page when the DM is ready. If a connection warning does not clear, check the DM's power and network connection. --- ## [CON-9] Exports Pages with reportable data (alarm lists, readings, mappings, logs) have export buttons, usually **PDF** and **Excel**; some offer more formats. Exports are created in your browser from the data on screen and download directly. No internet connection is needed. The chapter for each page says what its export contains. --- ## [CON-10] What View users see View users see all information the same way: views, refresh, status, property tables, connection indicators, the update pill and exports. They do not get **Add**, **Delete** or the rename pencil; property dialogs, where shown, are read-only. Where an Admin's footer reads "Use Properties to edit or delete this item.", a View user's reads "Property values shown in read-only mode." --- # [MON] Monitoring Your Site Applies to: DM, SPDM, SPIGM (SPAC4 has its own overview — [SPA]) · adding, changing and deleting is Admin only The DM organizes everything it monitors in three levels: - **Locations:** a site or building, for example **Powell Office**. - **Groups:** a set of related equipment within a location, for example **Power Rack 1** or **Environmentals**. - **Units:** one piece of monitored equipment, for example **UPS-21A** or **Office TH1**. Each unit has data points, alarm settings and, for some equipment, controls ([UNIT]). Status rolls upward. A unit in alarm puts its group and its location in alarm, and the tree, lists and status badges all show it. Items can be **Normal** (green), **Alarm** (red) or **Disabled** (gray; not being monitored). This chapter covers the pages for each level and how to add, change and remove locations, groups and units. --- ## [MON-1] Site Overview Click the site name at the top of the tree. The **Site Overview** is the console's home page. - **Top half:** the site image. The standard image is the Pythia "Data Monitoring Application" graphic. An Admin can replace it with a site photo or plan ([MON-1.1]). - **Bottom half:** **Locations**, one row or card per location with its **Status** and **Description**. Click a location to open it. - **Last Update:** the page refreshes every 30 seconds. The location list here can't be searched or filtered. For that, use the **Locations** page ([MON-2]). ### [MON-1.1] Change the site image Applies to: Admin 1. On the Site Overview, click **Properties** (**Site Properties** opens). 2. Under **Site Image**, click **Change image…**. 3. Pick an image already on the DM, or **Upload new image…** (PNG, JPG or GIF). The new image appears at once for everyone, with no Save needed. The same dialog holds the site identifier and the list refresh rate ([CON-2.1]). --- ## [MON-2] Locations Click **Locations** in the tree. - **Summary:** **Total Locations**, **Normal**, **Alarms** ("N location(s) in alarm" or "All locations normal"). - **Search locations…** matches name, code and description. - **Table columns:** **Location**, **Status**, **Code**, **Enabled**, **Description**. Cards show the same, with the code as a small badge. Disabled locations appear faded. ### [MON-2.1] Add a location Applies to: Admin 1. On the **Locations** page, click **Add**. 2. Enter **Location Name** (required, up to 100 characters; not `\ & % # ? " ,`). 3. Leave **Enable for monitoring** ticked, unless you want to set the location up before monitoring starts. 4. Optionally enter a **Code** (a short site code, e.g. `SITECODE`) and a **Description** (up to 200 characters). 5. Click **Save**. The console opens the new, empty location. "A location with that name already exists." means the name is taken. ### [MON-2.2] Change or delete a location Applies to: Admin Open the location and click **Properties** (**Location Properties**): | Field | Meaning | |---|---| | **Location Name** | Use the pencil to rename ([CON-3.3]). | | **Enable Location for Monitoring** | Off = the location and everything in it show **Disabled** and raise no alarms. | | **Location Code** | Optional site code. | | **Location Description** | Shown in lists and under the name on the banner. | | **Overview Image** | Optional banner picture for this location's page ([MON-5]). | | **Page URL** | Which page opens for this location: the standard Groups page, or a custom page ([CUS]). | To delete: **Delete** › confirm. A location that still has groups can't be deleted: "The location "" contains N group(s). Delete all group(s) before deleting this location." --- ## [MON-3] Groups (a location's page) Click a location in the tree or in a list. - **Summary:** **Total Groups**, **Normal**, **Alarms**. - **Overview banner** (if the location has an **Overview Image**) ([MON-5]). - **All Groups:** **Group**, **Status**, **Enabled**, **Description**. **Search groups…** matches name, status and description. - Buttons: **Add** (Admin), **Properties** (edits the location), **Cards** / **Table**. A location can instead open a custom page ([CUS]). ### [MON-3.1] Add a group Applies to: Admin 1. Open the location and click **Add**. 2. Enter **Group Name** (required; same character rules as locations) and an optional **Description**. 3. **Type** is **Generic**. 4. Leave **Enable for monitoring** ticked. 5. Click **Save**. The console opens the new group. ### [MON-3.2] Change or delete a group Applies to: Admin Open the group and click **Properties** (**Group Properties**): | Field | Meaning | |---|---| | **Group Name** | Rename with the pencil. | | **Enable Group for Monitoring** | Off = the group and its units show **Disabled** and raise no alarms. | | **Group Type** | Read-only. | | **Column Header 1** … **Column Header 5** | Up to five extra columns on the group's Units list. Enter the name of a data point (for example `Temperature`, `Humidity`) and the list shows each unit's current value in that column. | | **Group Description** | Shown in lists and on the banner. | | **Overview Image** | Optional banner picture ([MON-5]). | | **Page URL** | Standard Units list, the environmental gauge view ([MON-4.1]), or a custom page ([CUS]). | To delete: **Delete** › confirm. A group that still has units can't be deleted: "The group "" contains N unit(s). Delete all unit(s) before deleting this group." --- ## [MON-4] Units (a group's page) Click a group. - **Summary:** **Total Units**, **Normal**, **Alarms** ("N unit(s) in alarm" or "All units normal"). - **Overview banner** (if the group has an **Overview Image**). - **All Units:** **Unit**, **Status**, then the group's custom columns (for example **Temperature**, **Humidity**), then **Description**. **Search units…** also matches the custom column values. - Buttons: **Add** (Admin), **Properties** (edits the group), **Cards** / **Table**. Click a unit to open its page ([UNIT]) or its equipment dashboard ([EQP]). ### [MON-4.1] Environmental gauge view A group of temperature/humidity sensors can show its units as gauges instead of a list. The page is the same as the Units page, but in **Cards** view each unit shows a red thermometer gauge for temperature and a blue droplet gauge for humidity. The values come from the group's first column headers containing "temp" and "humid". To switch a group to this view (Admin): **Group Properties** › **Page URL** › type `PTJ_units_environmentals.html` › **Save**. To switch back, set **Page URL** to `PTJ_units.html`. > **Caution:** In the gauge view's own Properties dialog, don't clear **Page URL** to return to the standard list; type `PTJ_units.html` instead. Clearing it can leave the group unreachable from the tree. This view has no overview banner. ### [MON-4.2] Add a unit Applies to: Admin 1. Open the group and click **Add** (**Add New Unit**). 2. Enter **Unit Name** (required; not `\`, `/` or `|`). 3. Choose the **Network** the equipment is reached on, for example **LAN (NET)**. 4. Choose the **Driver** for the equipment. Its description appears under the list. The list shows every driver installed on your DM; see [DRV] for what each supports. 5. Click **Save**. The console opens the new unit. The driver must suit the network: an Ethernet driver (NET) needs an Ethernet network, and a serial driver (COM) needs a serial port. Otherwise the DM refuses: "Driver type () does not match Network type ()". **Next steps:** open the unit's **Properties** to enter its address (IP address, port, community and so on) and to turn on its **Data**, **Alarms** and **Controls** ([UNIT]). Drivers that come with an equipment dashboard open it automatically for new units and fill in the unit's description. Other units open the standard unit page ([EQP]). --- ## [MON-5] Overview banners Applies to: setting a banner is Admin only · everyone sees it A location or group can show a picture across the top of its page, such as a building photo, rack elevation or floor plan. Its name and description appear in the corner. 1. Open the location's or group's **Properties**. 2. In **Overview Image**, click **Choose…** and pick an image, or **Upload new image…** (PNG, JPG or GIF). 3. Click **Save**. To remove it, click **×** in **Overview Image** and **Save**. Banners appear on the standard Groups and Units pages only, not on the gauge view or custom pages. --- ## [MON-6] Enabling, disabling and status - **Disable** a location, group or unit to stop monitoring it, for maintenance or while it is being set up. It shows **Disabled** (gray), raises no alarms, and does not count toward its parent's alarm status. - **Status colors** everywhere: green **Normal**, red **Alarm** (pulsing on cards), gray **Disabled**. - A **location with no groups** shows **Normal**, but nothing there is actually being monitored yet. - **Service alarms** come from the DM itself, not from your equipment. One example is "Polling Failed", when a unit's driver cannot run. They appear in **Alarms › Active** and on the Alarm View with **Location** = the site identifier, **Group** = **PTI Service**, and **Unit** = the DM's computer name. They count in the status bar's alarm badge but do **not** change any location's, group's or unit's status. So the status bar can show "1 active alarm" while every location shows **Normal** ([ALM]). --- # [UNIT] Units in Detail Applies to: all DM-family products · viewing: all users · configuring and commanding: Admin A unit is one piece of monitored equipment. It has up to three kinds of points: - **Data points:** readings the DM polls from the equipment, such as temperature, load or voltage. - **Controls:** values the DM can write to the equipment, such as an on/off command or a setpoint. - **Alarm settings:** the conditions the DM watches, such as "temperature above 90". > **Note:** Alarm settings on a unit are **configuration**: they define what to watch. When a condition trips, the resulting **alarm event** appears site-wide under **Alarms**, where it is acknowledged and cleared ([ALM]). This chapter covers setting the rules. Many units open an **equipment dashboard** (a picture of the equipment with live values) instead of the standard unit page described here. See [EQP]. The Data, Controls and Alarms pages below work the same for every unit. --- ## [UNIT-1] The unit page Click a unit in the tree or in its group's list. ### [UNIT-1.1] Status The page title is the unit's name, with its description underneath. At the top right, one status block summarizes the unit: | Status | Meaning | |---|---| | **ALARM ACTIVE** + "N Active" (red) | At least one of the unit's alarms is active. | | **COMMUNICATIONS** (red) | No alarm is active, but at least one data point or control failed to update on the last poll. | | **ALL NORMAL** + "0 Active" (green) | Running, no alarms, every poll succeeding. | | **DISABLED** (gray) | The unit is not being monitored (its Enable is off). | An active alarm takes precedence over a communications problem. A disabled unit shows no counts. ### [UNIT-1.2] What's on the page - **Live Data** (left): every data point with its value and description. Click a point for its detail page, or the **Live Data** title for the full list. A point name in red means its last poll failed; a value in red means the point reports a problem. - **Alarm Status** (right): one card per alarm setting with an **ACTIVE**, **NORMAL** or **DISABLED** pill, active ones first. Click a card for that alarm's page. - **Controls** (below, only on units that have controls): **Setpoint** (what was commanded), **Value** (what the equipment reports) and **Description**. A yellow **OVR** badge means the control is in override. - **Open Device** button: opens the equipment's own web page in a new tab. It appears only if the unit's **URL to Open Unit in Browser** is set. The page refreshes every 2 seconds. ### [UNIT-1.3] Unit Properties Applies to: Admin Click **Properties** (**Unit Properties**). Fields depend on the driver; typical ones: | Field | Meaning | |---|---| | **Unit Name** | Rename with the pencil, if the driver allows ([CON-3.3]). | | **Enable Unit for Monitoring** | Off = not polled, shows **Disabled**, raises no alarms. | | **Virtual Monitoring Network** | The network the unit is reached on. | | **Unit Interface Driver** | The driver (read-only). | | **Unit IP Address** | The equipment's address. | | Protocol fields | For example SNMP community and port, or Modbus unit address. Blank fields are filled with the driver's defaults when you save. | | **Unit Code** | Optional code. | | **Add Data Container** / **Add Alarms Container** / **Add Controls Container** | Tick and **Save** to add that section to the unit ([UNIT-1.4]). | | **Unit Description** | Shown under the name and in lists. | | **URL to Open Unit in Browser** | Address for the **Open Device** button. | | **Universal Identifier** | A unique ID the DM assigns automatically. Other systems (mappings, AI assistants) use it to recognize the unit even after a rename. | **Delete** removes the unit and everything under it: "This action cannot be undone. All data points, alarms, and controls under this unit will also be removed." ### [UNIT-1.4] Adding the Data, Alarms and Controls sections A new unit starts with no points. To add them: 1. Open **Unit Properties**. 2. Tick **Add Data Container**, **Add Alarms Container** and/or **Add Controls Container**. 3. Click **Save**. The DM creates each section. For equipment-specific drivers, it also adds the driver's standard points. Doing this again later puts back any standard points you deleted, without duplicating the rest. The boxes appear unticked the next time you open the dialog. > **Note:** Unticking a box does **not** remove a section. To remove a whole section, use **Delete** at the bottom of that section's **Properties** grid ([UNIT-2.3], [UNIT-3.3], [UNIT-4.3]). --- ## [UNIT-2] Data points ### [UNIT-2.1] The Live Data list Click the unit's **Data** node in the tree, or the **Live Data** title on the unit page. - Columns: **Data**, **Enable**, **Value**, **Description**, in the driver's order. - Gray name = point disabled; red name = last poll failed. - A red banner appears when points are failing: "Communications issue — N data points failed to update on the last poll". It is hidden while the unit is disabled. - Refreshes at the site's list rate ([CON-2]). ### [UNIT-2.2] Add a data point Applies to: Admin Click **Add** (**Add New Data Point**). Fill in the name, **Description**, **Enable**, **Format**, the scaling values (Gain, Offset, Addend), and the driver's address fields (for example a Modbus register or an SNMP OID). Click **Save**. A duplicate name is refused: "A data point with that name already exists". Names cannot contain `\`, `/` or `|`. > **Tip:** End a description with the unit of measure in parentheses, such as `Supply Air Temperature (F)`. The console, exports and AI assistants all use it as the unit of measure. ### [UNIT-2.3] The Data Point Properties grid Applies to: Admin **Properties** on the Live Data list opens a grid of every point: **Description**, **Enable**, **Value Format**, **Trend Data**. - **Every change saves immediately.** There is no Save button. A green "✓ Saved" flashes after each change; on failure the grid names the field and point, for example 'Could not update Enable for "Temperature".', and puts the old value back. - **Set all →** at the top applies one value to a whole column (not Description). - **Trend Data** assigns the point to a trend bucket so its history is recorded ([TRD]). > **Caution:** Setting **Trend Data** to **— Off —** stops trending the point and **deletes its recorded trend history**. Moving it to a different bucket keeps the history. - **Delete** (bottom left, when the driver allows) removes the whole Data section and all its points. ### [UNIT-2.4] The data point page Click a data point's name. - **Live value:** large, with the unit of measure from the description. `--` means no reading. A red value and a **⚠ COMM ISSUE** badge mean the last poll failed. - **Live chart:** starts empty ("Collecting data...") and fills while the page is open, sampling every 2 seconds. It shows this viewing session only. For stored history, use trends ([TRD]). - **Chart:** **Line** (default), **Bar**, **Gauge**, or **Step** (on/off-type points only). - **Window:** **Last 1 minute**, **Last 5 minutes** (default), **Last 15 minutes**. - Hover over the chart to see the exact value and time. - Your chart type and window are remembered for each point on this browser. - **Gauge zones:** in Gauge mode, **Min**, **Max**, **Warn Low** and **Warn High** color the dial. > **Caution:** Gauge **Min / Max / Warn Low / Warn High** only color the dial on your screen. They are stored in your browser, are not sent to the DM, and do **not** raise alarms or send notifications. Real alarm thresholds are set in the unit's alarm settings ([UNIT-4]). - **Trend:** (Admin) assigns the point to a trend bucket, the same setting as in the grid. The same caution about **Off** applies. - **Export:** **PDF** (a snapshot of the chart) and **Excel** (the samples collected so far). - **Properties** (Admin): all the point's settings. Cleared Gain, Offset, Addend or Description are reset to 1, 0, 0 and the point's name. **Delete** removes the point. --- ## [UNIT-3] Controls A control writes to the equipment: an on/off command, a mode, or a setpoint. > **Caution:** **Commands are sent to the equipment without asking for confirmation.** Clicking **On** or **Off**, clicking **Apply** on a setpoint, pressing **Enter** in a setpoint box, or changing a setpoint cell in the Control Properties grid acts at once. The DM sends the value on its next poll and keeps re-sending it whenever the equipment's actual value differs. ### [UNIT-3.1] The Controls list Click the unit's **Controls** node, or the **Controls** title on the unit page. | Column | Shows | |---|---| | **Control** | Name (red if its last poll failed). | | **Enable** | **Yes** / **No**. A control must be enabled before anyone, including an AI assistant, can command it. | | **Status** | **Normal**, **Fault** (enabled but the last poll failed), or **Disabled**. | | **Setpoint** | The commanded value (— when none). | | **Value** | The value read back from the equipment. | | **Description** | Free text. | A red banner appears when controls are failing to update. ### [UNIT-3.2] Command a control Applies to: Admin 1. Click the control's name. 2. The **COMMAND** panel shows **Commanded** → **Actual**. 3. Send the command: - **On/off controls:** click **On** or **Off**. One click sends the command. - **Numeric controls:** type a value and click **Apply** (or press **Enter**). - Controls with an **Override** row: use it to force the output independently of the normal setpoint. 4. A message confirms: "Setpoint → ON sent." (or shows the error). 5. **Commanded** changes at once. **Actual** follows within a poll or two. If it never does, check the control's **Status** and the unit's communications. View users see the **Commanded → Actual** readout but no command buttons. ### [UNIT-3.3] Add controls and the Control Properties grid Applies to: Admin - **Add** (**Add New Control**): enter a name, choose the **Type** the driver offers (for example **Control**, **Control On/Off** or **Control On/Off Override**), then fill in that type's fields. **Save** is available once a Type is chosen. - **Properties** opens the **Control Properties** grid (**Enable**, **Setpoint**, **Value**, **Description**). Every change saves immediately, and a setpoint change **commands the equipment**. - **Clear Setpoints** (in the grid's top row) asks "Clear the setpoint on all N control(s)? Each is re-read fresh from the unit on the next poll." It clears every stored setpoint, so the DM stops pushing old values and adopts what the equipment actually reports. - **Delete** (bottom left, when the driver allows) removes the whole Controls section. --- ## [UNIT-4] Alarm settings Each alarm setting defines a condition, how serious it is, and how long it must last before it fires. ### [UNIT-4.1] The alarm list Click the unit's **Alarms** node, or the **Alarm Status** title on the unit page. The list shows **Alarm**, **Enable**, **State** (**ACTIVE** / **NORMAL** / **UNKNOWN**), **Category** and **Description**, active ones first. ### [UNIT-4.2] Add an alarm setting Applies to: Admin Click **Add** (**Add New Alarm**). The form comes from the driver. Typically: - the alarm's name, **Severity**, **Count**, **Category**, **Description**; - the condition: what to read (for example a register or OID), a **Comparison Operator** and an **Alarm Threshold**. For some drivers (for example DIRS and the SNMP families) the **Add New Alarm** dialog asks only for the **Alarm Identifier** and **Alarm Type**: **ALARM** (follow an on/off status), **LOGIC** (combine several conditions) or **VALUE** (compare a reading to a threshold). The type decides which fields the alarm's **Properties** then offers ([SPD-2.3]). Set the threshold and other details afterwards in the alarm's **Properties** if the Add form doesn't show them. ### [UNIT-4.3] The Alarm Properties grid (all alarms at once) Applies to: Admin **Properties** on the alarm list opens a grid of every alarm setting: - **Global Alarm Test** (top): turns on a test alarm for **every** alarm on the unit, to check the whole notification chain without waiting for a real event. Turn it off afterwards. - **Category:** **— None —** or **Category 01**–**Category 25** (or the driver's own list). Automations use categories to decide who is notified ([AUT]). - **Severity:** **INFORMATION**, **WARNING**, **MINOR**, **MAJOR**, **CRITICAL** ([ALM-1]). - **Fail Count** (1–5): how many polls in a row the condition must hold before the alarm fires. Raise it to ignore brief blips. - **Enable:** off = the alarm is not evaluated (**UNKNOWN**). Every change saves immediately. **Set all…** changes a whole column after asking to confirm, for example "Are you sure you want to set severity to 'CRITICAL' for all 8 alarms?". **Delete** (bottom left) removes the whole Alarms section. ### [UNIT-4.4] One alarm's page Click an alarm setting's name. - **State:** **NORMAL** (green), **UNKNOWN** (gray), or, while firing, the severity word (**CRITICAL**, **MAJOR**, **MINOR**, **WARNING**, **INFORMATION**) in its color. It updates every 2 seconds. - **History:** **Time Start**, **Time Stop**, **Duration**, **Text**, newest first. A firing alarm has a live row whose duration counts up. - **Export:** **PDF** / **Excel** of the history. - **Properties** (Admin): all fields, including the condition. Typical fields: - **Enable Alarm for Monitoring** - **Alarm Severity** - **Count Before Generating Alarm** (1–5) - **Alarm Category** - **Latch Alarm** (on some drivers): **Latch** keeps the alarm active after its condition clears, until someone sets it to **Unlatch** - **Gain Value**, **Offset Value**, **Gain-Offset Calculation Order**, **Additional Value to Add** - **Comparison Operator** (AND, NAND, >, <, =, !=), **Alarm Threshold** - **Alarm Description** - **Generate Software Alarm Test** This is where real alarm thresholds live. - **Delete** removes the alarm setting. Its recorded history stays until cleared. - **Clear History** (Admin): "Permanently delete N record(s) for this alarm?". It cannot be undone, and the records also disappear from the site-wide history. Export first if you need them. > **Note:** An Admin who sees **⚠ Not editable — re-add this alarm** instead of **Properties** is looking at an older alarm setting that can no longer be evaluated. Delete it and add it again. --- ## [UNIT-5] What View users see View users see every page in this chapter: the unit page, the Live Data list, data point pages with charts, gauges and exports, the Controls list and **Commanded → Actual** readouts, and alarm settings with their history and exports. They do not see **Add**, **Properties**, the bulk grids, **Trend** selectors, **Clear History**, or any command buttons, and the DM refuses any change they attempt. --- # [EQP] Equipment Dashboards Applies to: all DM-family products · viewing: all users · properties: Admin Many units open an **equipment dashboard** instead of the standard unit page ([UNIT-1]): a live drawing of the equipment, such as a UPS power path, a cooling unit or a server faceplate, with its readings placed where they belong. Dashboards come with the unit's driver. Which ones you see depends on your equipment. [DRV] lists the standard drivers and whether each has a dashboard. Dashboards are for **watching**. Except for the cooling units noted in [EQP-4], you change settings and send commands on the unit's **Controls** page ([UNIT-3]). --- ## [EQP-1] What every dashboard has - **Header:** the unit name, its description, and a status pill: - **ALARM ACTIVE** + "N Active" (red) - **COMMUNICATIONS** (red): readings failed on the last poll. Not shown on IGM-driver dashboards. - **ALL NORMAL** + "0 Active" (green) - **DISABLED** (gray) - **Updated:** time and status dot. Dashboards refresh every 2 seconds (sensor dashboards every 2.5 seconds). - **Open Device:** opens the equipment's own web page, if the unit has one configured ([UNIT-1.3]). - **Properties** (Admin): the unit's Properties dialog. Its **Delete Unit** button removes the unit and everything under it. Refresh pauses while the dialog is open. - **The drawing:** the equipment with live values, an operating-mode badge (for example **ONLINE**, **ON BATTERY**), and animated power or air flow. - **Live Data** and **Alarm Status** lists below the drawing. Click a reading for its data point page, or an alarm for its alarm page. The section titles open the full Data and Alarms lists. ### [EQP-1.1] When the equipment stops answering - Most dashboards freeze the drawing in gray and show a **NO COMMS** mode badge, keeping the last values on screen. - Some show a red banner instead: "N data point(s) did not respond on the last poll." - Values that have never been read show `--`. > **Note:** Status and mode text on dashboards is shown exactly as the equipment reports it, including the manufacturer's spelling. --- ## [EQP-2] Which units open a dashboard - **Opens automatically for new units:** - the SNMP drivers for CyberPower UPS, Liebert GXT4 UPS, Liebert CRAC (ENV1), Supermicro X12 server and Cisco Business 250 switch; - the Liebert IGM drivers L00, LAM, MM2, MM4, PMP, PMP2, SC4, SM4, ST2, STS, WDU, WDU2 and XDC. These drivers also fill in the unit's description. - **Other drivers with a dashboard** (for example the Vertiv GXT5 and EXM UPS, the Liebert battery monitor, the generic UPS driver, and the temperature/humidity sensor page): Pythia assigns the dashboard to the unit during the DM's initial configuration. Pythia is updating more drivers to assign their dashboards automatically. A unit that opens the standard unit page is working normally. If you'd like an equipment dashboard for a unit that doesn't have one, let Pythia Technologies know. - **Units without a dashboard** always use the standard unit page ([UNIT-1]). ### [EQP-2.1] Setting up a unit with a manifest driver The CyberPower UPS, Liebert GXT4, Liebert CRAC (ENV1), Supermicro X12 and Cisco CBS250 drivers carry their own standard list of points. After adding the unit ([MON-4.2]): 1. Enter the unit's IP address and SNMP settings in **Properties**. 2. Tick **Add Data Container**, **Add Alarms Container** and **Add Controls Container**, then **Save**. The button shows **Seeding points…** while the DM adds the standard points. "Seeding: N added, N already existed, N FAILED. Save again to retry the failed points." means some points failed; **Save** again. The equipment's SNMP access list must allow the DM's IP address. --- ## [EQP-3] Dashboard gallery ### [EQP-3.1] UPS | Dashboard | Shows | Mode badge | |---|---|---| | **Vertiv GXT5 / Liebert GXT4** | Power path: AC in › rectifier › DC bus › inverter › static switch › load, with static bypass; **Input**, **Battery**, **Output** panels; battery status | **ONLINE**, **ON BATTERY**, **BYPASS**, **DISABLED**, **NO COMMS** | | **Vertiv EXM** (three-phase) | As GXT5, with per-phase values and a generator input | adds **MAINT BYP** | | **CyberPower UPS** | Power path and battery | **ONLINE**, **ON BATTERY**, **ON BOOST**, **ON BUCK**, **OVERLOAD**, **OUTPUT OFF** | | **Generic UPS** (any UPS with the standard UPS MIB) | One-line diagram with gauges | **● NORMAL**, **● ON BATTERY**, **● ON BYPASS**, **● OUTPUT OFF**, **● COMMS LOST** | | **Liebert Multi-Module / Single-Module UPS** (IGM MM4, SM4) | UPS module with battery | **ONLINE**, **ON BATTERY**, **OUTPUT OFF** (SM4 adds **ON BYPASS**); battery **CHARGED**, **CHARGING**, **DISCHARGING**, **LOW** | | **Liebert System Control Cabinet** (IGM SC4) | Up to six parallel UPS modules | System **ONLINE**, **ON BYPASS**, **OUTPUT OFF**; module tiles **ONLINE**, **ALARM**, **OFFLINE**, **N/A** | ### [EQP-3.2] Batteries **Liebert battery monitor** (two strings): per-string state **FLOAT**, **DISCHARGING**, **EQUALIZING**, **STR OFFLINE**, **RUNAWAY**, with an alarm count per string. ### [EQP-3.3] Cooling | Dashboard | Shows | |---|---| | **Liebert CRAC** (SNMP) | Unit with fans, coils and air flow; overlays such as **SMOKE DETECTED**, **LOSS OF POWER**, **UNIT SHUTDOWN**, **FIRE DETECT**, **FIRE ALARM**, **REMOTE SHUTDOWN**; editable setpoints ([EQP-4]). | | **Liebert Deluxe System/3, Mini-Mate2, Level 0 controller** (IGM LAM, MM2, L00) | Unit drawing, readings, and a read-only setpoint table: "Setpoints (read-only — change on the Controls page)". | | **Liebert XD chiller** (IGM XDC) | Mode **ON**, **OFF**, **DISABLED**, with its setpoints read-only. | ### [EQP-3.4] Power distribution and switching | Dashboard | Shows | |---|---| | **Liebert Precision Power Center** (IGM PMP, PMP2) | One-line power distribution; PMP2 adds power-quality values (THD, K-factor, crest factor). | | **Liebert static transfer switch** (IGM STS, ST2) | Two sources feeding the load, tagged **PREFERRED** and **ON LOAD**. | | **CyberPower ATS** | **SOURCE A**, **SOURCE B** or **NO SOURCE**; "Active: Source A", "Source A Failed", **Redundant** / **Not Redundant**. | ### [EQP-3.5] Leak detection **Liebert leak detection** (IGM WDU single cable, WDU2 dual cable): cable state **OK**, **LEAK** or **CABLE FAULT**, and leak distance in feet or meters. ### [EQP-3.6] Generators **Generac generator (H100 controller):** engine, alternator and fuel base, with a transfer switch showing **UTILITY** or **GENERATOR** feeding the load. Mode **STANDBY**, **CRANKING**, **WARMING UP**, **RUNNING**, **EXERCISING**, **COOL DOWN**, **SHUTDOWN** (emergency stop), **POWER LOSS** (" ● ON GEN" is added while the generator carries the load). A yellow strip warns "Generator is NOT IN AUTO — automatic start on power loss is disabled". ### [EQP-3.7] IT equipment | Dashboard | Shows | |---|---| | **Supermicro X12 server** | Front faceplate (power, drive, network and ID LEDs, drive bays) and an inside view with fan speeds and component temperatures. Mode **ONLINE**, **ALARM**, **POWERED OFF**, **NO COMMS**, **DISABLED**. The server's power controls are installed **disabled** because they can power-cycle the server. | | **Cisco Business 250 switch** | Faceplate with a link light per port, and a health strip (CPU, temperature, power supply, uptime, firmware). Mode **ONLINE**, **ALARM**, **NO COMMS**, **DISABLED**. "Port n Link Down" alarms are installed disabled; enable the ones for ports you care about. | ### [EQP-3.8] Sensors **Temperature / humidity sensor:** semicircular gauges for **Temperature** (°F, default 32–120) and **Humidity** (%, 0–100). The colored zones come from the unit's **Low**/**High Temperature** and **Humidity** alarm thresholds. Status word **NORMAL**, **HIGH TEMP**, **LOW TEMP**, **HIGH HUMIDITY** or **LOW HUMIDITY**. ### [EQP-3.9] Equipment managers Pythia's manager units coordinate a team of cooling units: lead/standby rotation, failover and staging. See [DRV-3]. | Dashboard | Shows | |---|---| | **Unit Team Manager** (two units, lead/standby) | Roles **LEAD** / **STANDBY** / **DISABLED**, **FAILOVER ARMED** / **FAILOVER OFF**, "SWITCHING — Ns" during a changeover, last changeover time. | | **CRAC Manager** (three units, two running) | Mode **NORMAL · 2 RUN**, **STAGING · 3 RUN**, **FAILOVER · N RUN**, **OVERRIDE · N RUN**, **DEGRADED · 1 RUN**, **ALL RUNNING**, **ALL OFF**; roles **LEAD** / **DUTY** / **STANDBY**; notes such as "fewer than 2 units running — check overrides / unit enables". | Manager dashboards only display commands. Operate the manager from its **Controls** page. Deleting a manager unit does not delete the units it manages. --- ## [EQP-4] Dashboards that change settings Applies to: Admin The **Liebert CRAC** dashboards (SNMP) have a **Controls** table where an Admin can type a new setpoint directly. The change is sent **as soon as you leave the box**, and the result shows ✓ or ✗. > **Caution:** Setpoints typed on these dashboards go to the equipment **immediately, with no confirmation**, just like the Controls page ([UNIT-3]). A few dashboards built for particular installations also have editable controls; they carry the same caution. All other dashboards are read-only. --- ## [EQP-5] Group dashboards A group can also open a dashboard showing all its units together. For example: | Group dashboard | Shows | |---|---| | **UPS Systems** | A small UPS panel per unit (**NORMAL**, **ON BATTERY**, **ON BYPASS**, **OUTPUT OFF**), with runtime under 15 minutes in amber. | | **Branch Circuits** | Per-panel phase currents, total, imbalance and highest breaker. | | **Alarm Panels** / **Generator Systems** | A wall of status panels with one light per alarm. | Group dashboards have the group's **Properties** and often **Add Unit**. They are set up through the group's **Page URL** ([MON-3.2]). Custom dashboards for your own layout are covered in [CUS]. --- # [ALM] Alarms Applies to: all DM-family products · viewing: all users · acknowledging and clearing: Admin An **alarm** is an event: a condition on a unit that is true right now, or was true in the past. Alarms come from the unit alarm settings described in [UNIT-4]. This chapter covers working alarms site-wide: seeing what is active, acknowledging and clearing, and reviewing history. For a wall display that needs no sign-in, see the **Alarm View** ([GS-2]). --- ## [ALM-1] Buckets and severities **Alarms** in the tree has three buckets: | Bucket | Holds | Refresh | Removed when | |---|---|---|---| | **Active** | Alarms that are firing now | every 2 seconds | the condition ends, an Admin clears it, or it has not been refreshed for 24 hours | | **Information** | Notices that aren't faults (severity INFORMATION) | every 2 seconds | an Admin clears them | | **History** | Every past alarm, with start and stop time | when you click **Refresh** | an Admin deletes records | **Severities** (set in each alarm setting, [UNIT-4.3]): | Badge | Severity | Color | |---|---|---| | **CRT** | Critical | red; the row pulses | | **MAJ** | Major | orange | | **MIN** | Minor | yellow | | **WAR** | Warning | teal | | INFO | Information | blue (Information bucket) | Active alarms turn their unit, group and location red in the tree and lists, and the status bar shows "N active alarms" ([GS-4.3]). ### [ALM-1.1] Service alarms Some alarms come from the DM itself rather than your equipment, for example "Polling Failed" when a unit's driver cannot run. They show **Location** = the site identifier, **Group** = **PTI Service**, **Unit** = the DM's computer name. They count in the status bar but don't change any location's status. --- ## [ALM-2] The Active list Click **Alarms › Active** (or the red alarm badge in the status bar). - **Title and counts:** "5 Active Alarms", plus "· 3 unacknowledged" when some are acknowledged. - **Filters:** click **CRT**, **MAJ**, **MIN** or **WAR** to show only those severities, or **ACK Unacknowledged only** to hide acknowledged alarms. **Search alarms...** matches any text, including who acknowledged it. - **Columns** (click to sort): **Severity** (worst first by default), **Ack**, **Time**, **Location**, **Group**, **Unit**, **Type**, **Text**. Location, group, unit and type are links. - **Acknowledged alarms** show a green **ACK** badge and appear dimmed; a Critical one stops pulsing. Hover the badge for who acknowledged it, when, and their note. - **Details:** click an alarm's **Time** to open **Alarm Details**: time, location, group, unit, type, message, and the acknowledgment if any, with **Open full page ↗**. - **Export:** **PDF** or **Excel** of the rows shown, including the acknowledgment text. - With nothing active: "No active alarms — all systems normal." --- ## [ALM-3] Acknowledging and clearing Applies to: Admin **Acknowledge** means "someone has seen this and is handling it." **Clear** removes the alarm. | | Acknowledge | Clear | |---|---|---| | Alarm stays active? | **Yes**, still red, still counted | **No**, removed from Active | | Written to History? | No | Yes, with the clear time as its stop time | | Sends notifications? | No | Yes: automations send a **CLEAR** message ([AUT]) | | Can be undone? | Yes (**Un-acknowledge**) | No. If the condition still exists, the equipment raises it again as a new alarm on the next poll. | | Logged in **Logins** log | Yes | No | ### [ALM-3.1] Acknowledge - **One alarm:** open **Alarm Details** (click its time) › **Acknowledge** › optionally type a note › **OK**. - **Several:** tick their checkboxes › **Acknowledge Selected** › optional note (applies to all) › **OK**. - **On the full alarm page:** **Acknowledge** ("Acknowledge this alarm? It stays active; the acknowledgment records who took it and when."). The note can be up to 255 characters. Acknowledging again replaces the previous note. To remove an acknowledgment, use **Un-acknowledge** on the full alarm page ("Remove the acknowledgment from this alarm?"). > **Note:** An acknowledgment lasts only while the alarm is active. When the alarm clears, the acknowledgment is not kept in History. If the alarm's severity changes, it stays acknowledged. Acknowledging does not stop repeated SNMP traps. > **Note:** Only Admins can acknowledge in the console. AI assistants can acknowledge or clear only if an Admin allows it ([AIC-3]). ### [ALM-3.2] Clear - **Several:** tick them › **Clear Selected** › confirm "Clear N selected active alarm(s)? This cannot be undone." - **On the full alarm page:** **Clear** › confirm. - **In Alarm Details:** **Clear Alarm**. > **Caution:** **Clear Alarm** in the **Alarm Details** window clears the alarm **immediately, without asking for confirmation**. Use Clear for alarms that are stuck (the condition is gone but the alarm remains) or no longer relevant. Clearing an alarm whose condition still exists only makes it come back on the next poll. --- ## [ALM-4] The full alarm page Click an alarm's timestamp in the tree, or **Open full page ↗**. The title is the severity (for example **Critical Alarm**). It shows **Severity**, **Started**, **Location**, **Group**, **Unit**, **Type**, **Description**, **Category** and **Acknowledged** ("No", or who and when with their note). Admins get **Acknowledge** / **Un-acknowledge** and **Clear**. The page doesn't refresh on its own. --- ## [ALM-5] Information Click **Alarms › Information**. Information events are notices rather than faults. The list shows **Time**, **Location**, **Group**, **Unit**, **Type**, **Text**, with **Search events...**, details, exports, and (Admin) **Clear Selected** or **Clear Event**. They cannot be acknowledged. > **Caution:** **Clear Event** in the details window acts immediately, without confirmation. --- ## [ALM-6] History Click **Alarms › History**. It shows the newest 1000 records: **Time Start**, **Time Stop**, **Location**, **Group**, **Unit**, **Type**, **Text**. Click a row for details. **Search history...** filters the list. It doesn't refresh on its own. Applies to: Admin - **Keep last [30] days — Delete Older Records:** deletes history older than the number of days you enter, after confirmation. - **Clear All History:** "Delete ALL alarm history? This deletes every record from the ALARMS table and cannot be undone." > **Caution:** Deleted history cannot be recovered. Export first if you need it. One alarm setting's own history, with durations, is on its alarm page under the unit ([UNIT-4.4]). --- ## [ALM-7] Testing an alarm Applies to: Admin To check that an alarm and its notifications work without waiting for a real event: 1. Open the alarm setting under the unit (** › Alarms › **) and click **Properties**. 2. Turn on **Generate Software Alarm Test** and **Save**. The alarm fires within a poll or two and appears in **Active**. Automations for its category send **real** notifications to their recipients. That is the point of the test: it proves the whole chain from alarm to email or trap ([AUT]). Warn recipients first if needed. 3. When finished, turn **Generate Software Alarm Test** off and **Save**. The alarm clears by itself and is recorded in History. To test every alarm on a unit at once, use **Global Alarm Test** in the unit's Alarm Properties grid ([UNIT-4.3]). > **Note:** While a test is on, clearing the alarm only makes it come back on the next poll. Turn the test off instead. --- ## [ALM-8] What View users see View users see all three buckets, filters, details, the full alarm page, exports and acknowledgment badges. They cannot acknowledge, clear or delete anything. --- # [AUT] Automations and Notifications Applies to: all DM-family products · viewing: all users · changing: Admin **Automations** send news out of the DM. An **Alarm** automation sends email and SNMP traps when alarms fire and clear. A **Heartbeat** automation sends scheduled "still alive" emails, so that silence from the DM is never mistaken for health. All DM email goes out through the DM's built-in **SMTP Relay**. The sender (**From**) address and outgoing mail server are set there ([SET]), not on the automations. --- ## [AUT-1] How an alarm notification is decided For every alarm that fires or clears, the DM checks each **Alarm** automation in turn. It notifies that automation's recipients only if **all** of these are true: 1. The automation is **enabled**. 2. The automation's **Alarm Category** includes the alarm's category. Alarm settings use **Category 01**–**Category 25** ([UNIT-4.3]). The DM's own alarms use three system categories: **Service** (DM service alarms such as "Polling Failed", [ALM-1.1]), **Communications** (a unit stopped answering) and **Disabled** (monitoring was turned off). Tick these too if you want to be told about them. 3. The current time is **not** inside one of the automation's time exceptions for today ([AUT-5]). Then: - **Email** goes to each **enabled** recipient, once when the alarm fires and once when it clears (subject ending "- CLEAR"). - **SNMP traps** go to each **enabled** destination, once when the alarm fires and once when it clears. **Persistent** destinations also get the trap again on every poll while the alarm stays active. - Information events are notified the same way. > **For AI assistants:** When a user says "I'm not getting alarm emails", check in this order: the automation is enabled; its Category includes the alarm's category; no time exception covers the current time; the recipient is enabled; the SMTP Relay shows the message as sent ([SET]). --- ## [AUT-2] The Automations list Click **Automations** in the tree. The list shows **Name**, **Type** (**Alarm** or **Heartbeat**), **Enabled**, **Category** and **Description**. It loads once and has no search. - **Enable or disable** (Admin): in **Table** view, click the **Enabled** switch. Disabling stops an Alarm automation from sending, but keeps everything configured. Heartbeat rows show a dash instead of a switch ("Heartbeats have no Enable setting: they send for as long as they exist") ([AUT-6]). - Disabled automations appear faded. ### [AUT-2.1] Add an automation Applies to: Admin 1. Click **Add**. 2. Enter an **Automation Name** (required, up to 100 characters, e.g. `CRITICAL ONLY`). 3. Choose **Type**: **Alarm** (default) or **Heartbeat**. You cannot change it later. 4. Optionally enter a **Description**, then click **Add**. The DM creates the automation's fixed lists: **Email**, **SNMP Trap** and **Time** for Alarm; **Interval** and **Period** for Heartbeat. It then opens the new automation. > **Caution:** A new Alarm automation starts **disabled and with no categories**, so it sends nothing yet. Open its **Properties**, tick the **Alarm Category** values it should notify for, turn on **Enable Automation**, and **Save**. Messages: "Automation name is required.", "Name and description cannot contain the pipe character (|).", "An automation with that name already exists". ### [AUT-2.2] Change or delete an automation Applies to: Admin Open the automation and click **Properties** (**Automation Properties**): | Field | Meaning | |---|---| | **Automation Name** | Rename with the pencil. | | **Enable Automation** | On = sends notifications. | | **Alarm Category** | Tick every category this automation notifies for: **Category 01**–**Category 25**, **Service**, **Disabled**, **Communications**. | | **Type of Automation** | **Alarm** or **Heartbeat** (read-only). | | **Automation Description** | Free text. | The dialog also has **Delete**, **Cancel** and **Save**. A heartbeat's **Heartbeat Properties** has only Name, Type and Description. Deleting removes the automation and everything in it: "Are you sure you want to delete the automation "" and everything inside it (all recipients, trap destinations, and time exceptions)? This action cannot be undone." To stop an Alarm automation temporarily, disable it instead. --- ## [AUT-3] Email recipients Open an Alarm automation and click **Email**. The list shows each recipient's **Email**, **Enabled**, **Short Format**, **Test** and **Description**, with search. | Flag | Meaning | |---|---| | **Enabled** | Receives notifications. Off = paused. | | **Short Format** (badge **Text**) | A compact message for SMS or pager gateways: the subject is just the alarm type, and the body is one line. | | **Test** | Sends **one** test email ("DM Console Test") within a few seconds of saving, then turns itself off. It does not limit what the recipient receives: a test recipient still gets real alarm emails. | **Add a recipient** (Admin): **Add** › **Email Address** (required) › optional **Description** › flags (**Enabled** is ticked) › **Add**. Messages: "Email address is required.", "Must be a valid email (e.g. user@example.com).", "A recipient with that email already exists". **Change or remove:** click the recipient › **Properties** (flags, description, **Delete**). The address is the recipient's name; change it with the pencil. ### [AUT-3.1] What the emails look like - **Subject:** ` - - - - `, for example `Powell Office - Environmentals - Office TH1 - Low Humidity - CRITICAL`. When the alarm clears, the last part is `CLEAR`. - **Body:** Time, Location, Location Code, Group, Unit, Unit Code, Type, Category and Severity, then the alarm text, ending "Message from Pythia Technologies DM Console." - **Short Format:** subject = the alarm type; body = the full subject line above. - **From:** the SMTP Relay's **From Address** ([SET]). --- ## [AUT-4] SNMP trap destinations Open an Alarm automation and click **SNMP Trap**. The list shows **IP Address**, **Enabled**, **Port**, **Persistent**, **SNMP v2**, **Test** and **Description**. | Setting | Meaning | |---|---| | **Port** | **162** (standard) or **8162**. | | **Persistent** | Re-send the trap on **every poll while the alarm is active**, not only when it fires. Acknowledging the alarm does not stop this. | | **SNMP v2** | Send SNMPv2c traps; otherwise SNMPv1. Match the receiving system. | | **Test** | Sends **one** test trap, then turns itself off. | **Add** (Admin): **Add** › **IP Address** (required, e.g. `192.0.2.10`) › **Port** › **Description** › flags › **Add**. Messages: "IP address is required.", "Must be a valid IPv4 address (e.g. 192.168.1.10).", "A destination with that IP already exists". Trap contents (OIDs and variables) for integrators: [INTG]. --- ## [AUT-5] Time exceptions (quiet times) Open an Alarm automation and click **Time**. Time exceptions are **quiet times**: while the current time is inside one of today's ranges, this automation sends **nothing**. Outside them, and on days with no entry, it sends as normal. With no time entries at all, the automation sends at all times. **Example:** a daytime-only pager automation. Add quiet ranges for the hours you don't want pages, such as 00:00–08:00 and 17:00–24:00 on weekdays, plus full-day ranges on weekend days. 1. **Add a day:** **Add** › choose `1 - SUNDAY` … `7 - SATURDAY` › **Add**. Each day can be added once ("That day is already added to this automation"). 2. **Add a range:** open the day › **Add** › **Start Time** (00:00–23:00) and **Stop Time** (01:00–24:00, on the hour) › optional **Description** › **Add**. - "Stop time must be after start time." - Ranges in one day can't overlap: "This time range overlaps the existing range 08:00 - 12:00". - Two ranges can't start at the same time. 3. **Change or delete:** a day's **Properties** moves it to another day or deletes it with its ranges. A range's **Properties** changes its stop time or deletes it. Times are the DM's local time. --- ## [AUT-6] Heartbeat automations A heartbeat sends "system is alive" emails on a schedule. If they stop arriving, the DM, its network or its mail path has a problem. > **Note:** A heartbeat automation cannot be disabled. As long as it exists, its schedules send. To stop heartbeats, remove the recipients, delete the period, or delete the heartbeat automation. Open a Heartbeat automation. It has two schedule types: | Schedule | Sends | Managed how | |---|---|---| | **Interval** | Around the clock: **01 (5-Minutes)**, **02 (15-Minutes)**, **03 (1-Hour)**, on the clock's even marks (e.g. :00, :05, :10…) | Fixed; they can't be added, renamed or deleted | | **Period** | Once a day at a chosen hour, `00:00`–`23:00` | **Add** any hours you need ("That period is already added to this automation") | Each interval and period has **its own recipient list**. Click it and add recipients as in [AUT-3]. A slot with no recipients sends nothing. > **Caution:** A heartbeat recipient's **Enabled** switch is currently **not** honored; the recipient still receives heartbeats. To stop heartbeats going to someone, remove them from the list. **Test** works as for alarm recipients. **The emails:** - **Subject:** `DM Console Heartbeat - - .` - **Body:** `Heartbeat message from DM Console - - ` - **Short Format:** subject `Heartbeat`, body = the full subject. - **From:** the SMTP Relay's **From Address**. Heartbeats also stop if the DM's license check fails. **Delete:** heartbeat **Properties** › **Delete**: "Are you sure you want to delete the heartbeat automation "" and everything inside it (all interval and period schedules)? This action cannot be undone." Before deleting a heartbeat or a period, tell whoever watches for it, or the silence will look like an outage. --- ## [AUT-7] Testing notifications - **One recipient:** tick **Test** on it and **Save**. One test email or trap goes out within a few seconds. - **The whole chain from alarm to message:** raise a test alarm ([ALM-7]). It follows the same rules as a real alarm. - **The mail path itself:** use **Send Test** on **Settings › SMTP Relay**, and check its Recent Activity for delivery ([SET]). --- ## [AUT-8] What View users see View users can browse all automations, recipients, trap destinations, time exceptions and heartbeat schedules. **Enabled** appears as "✓ Yes" / "— No". They see no **Add**, **Properties** or **Delete**. --- # [TRD] Trends Applies to: all DM-family products · viewing: all users · choosing what to trend and deleting: Admin **Trends** record a data point's value over time so you can chart it later: days of UPS load, a week of room temperature, a month of power use. The live chart on a data point's page ([UNIT-2.4]) shows only the time you've had the page open. Trends are stored on the DM. --- ## [TRD-1] How trending works - **Five buckets**, each with its own recording rate: | Bucket | Records every | Chart window choices | |---|---|---| | **01 (5-MINUTES)** | 5 minutes | 24, 48, 72, 120 (default) or 168 hours | | **02 (15-MINUTES)** | 15 minutes | 24, 48, 72, 120 (default) or 168 hours | | **03 (30-MINUTES)** | 30 minutes | 30, 60, 90, 120 (default) or 180 days | | **04 (1-HOUR)** | 1 hour | 30, 60, 90, 120 (default) or 180 days | | **05 (1-DAY)** | 1 day | 30, 60, 90, 120 (default) or 180 days | - **A point is in one bucket at a time.** Assigning a point to a bucket starts recording; its trend appears in that bucket shortly afterwards. - **History is kept for 6 months.** Older records are removed automatically. - **Renaming** a location, group or unit keeps the history. - **Moving a point to another bucket** keeps its history, which continues in the new bucket. > **Caution:** **Turning trending Off for a point deletes all of its recorded history** within a few seconds. There is no "pause". If you may want the history later, export it first ([TRD-4]) or leave the point trending. --- ## [TRD-2] Choosing what to trend Applies to: Admin **For one point:** on the point's page, use **Trend:** ([UNIT-2.4]), or set **Trend Data** in the unit's Data Point Properties grid ([UNIT-2.3]). **For many points:** **Trends** › **Configure Points** opens **Configure Trended Points**. It lists every trendable point under **Locations**, grouped by location › group › unit. - The subtitle counts them: "N trendable points · M trended". - **Search:** "Filter by point, unit, group, or location…". Tick **Trending only** to see just the trended points. - **Trend bucket** column: pick **Off** or a bucket. The change saves immediately ("✓ Saved"). - **Bulk:** tick points (or the header box for everything matching the filter), choose a bucket at the bottom left, and click **Apply**. The DM asks to confirm when you turn points **Off** ("Turn OFF trending for N point(s)?"), or when you set more than 20 points. The result reads "Saved N point(s)." or lists the failures, which stay ticked. > **Caution:** The confirmation for **Off** does not mention it, but turning points off **deletes their history** ([TRD-1]). Smart Panel points are trended from their own properties, not from this list ([SPD], [SPA]). **Configure Points** is shown to Admins only. --- ## [TRD-3] Reading a trend 1. Click **Trends**, then a bucket. The bucket lists its trends, named `___Data_`, for example `Powell Office_Environmentals_Office TH1_Data_Temperature`. 2. Click a trend to open its chart. The subtitle shows the bucket, the window and the number of plotted values, for example "Trend in 01 (5-MINUTES) — 120 Hours — 1416 buckets". When a window has more values than fit, the DM combines them: the line shows the average and a shaded band shows the minimum and maximum ("with min/max band"). | Control | What it does | |---|---| | **Refresh** | Reload the data (the chart doesn't refresh on its own). | | **Chart:** | **Line**, **Area**, **Bar** or **Step**. | | **Window:** | How far back to show ([TRD-1]). | | **Y-Min:** / **Y-Max:** | Fix the vertical scale, or leave on **auto**. | | **Theme:** | Line color: Blue, Cyan, Green, Amber, Magenta, Mono. | | **Zoom** | Drag across the chart to zoom in; **Reset Zoom** returns to the full window. | | Hover | Shows the exact time and value. | Your chart choices are remembered per trend on this browser. Times are the DM's local time. "No trend data in this window" means nothing was recorded in that period. --- ## [TRD-4] Exporting **Export:** on the chart page: - **CSV** and **Excel:** the time and average value for each plotted point. - **PNG** and **PDF:** a picture of the chart as shown. The file is named after the trend and bucket. --- ## [TRD-5] Deleting a trend Applies to: Admin On the chart page: **Properties** (shows the trend's name and ID) › **Delete Trend** › confirm: > "All historical data values collected for this trend will be permanently deleted. The data point will also stop being trended (you can re-enable it from the data point properties). This action cannot be undone." The chart's **Properties** button is shown to Admins only. --- ## [TRD-6] Trends and AI assistants An AI assistant connected through the AI Connector can list trended points and read trend history for charts and summaries ([AIC-7.2]). If the administrator allows it, it can also assign or remove a point's trend bucket. The caution in [TRD-1] applies there too. --- # [USR] Users and Accounts Applies to: all DM-family products · managing accounts: Admin Everyone who signs in has an account under **Users**. There are three kinds: | Access level | Can sign in to the console | Can do | |---|---|---| | **Admin** | Yes | Everything: view, configure, command equipment, manage users. | | **View** | Yes | Look at everything they are allowed to see; change their own name, sign-in email and password. No changes to the DM. | | **API** | **No** | Used only by AI assistants through the AI Connector, with a token instead of a password ([AIC-2]). | What each level can do, page by page, is in [APX-B]. --- ## [USR-1] The Users list Click **Users** in the tree. The list shows **ID** (the sign-in email, or the AI system's name for API accounts), **Enable**, **First Name**, **Last Name** and **Access**. - **Admins** see every account and can switch **Enable** on or off directly in the list. A disabled account cannot sign in, and a disabled API account's token stops working. - **View users** see only their own account: "You can edit your own account. Other accounts are managed by an administrator." > **Note:** Disabling or deleting an account takes effect immediately. Someone already signed in with it is signed out the next time they click anything. --- ## [USR-2] Add a user Applies to: Admin 1. **Users** › **Add User**. 2. Fill in: - **User Identifier (Email Address)**: their email address, used to sign in. - **User's First Name** and **User's Last Name** (required). - **User's Password** and **User's Password Confirmation**. - **Access Level**: **Admin** or **View** (for an AI assistant choose **API**, see [AIC-2.1]). - **Enable User Account** (ticked). 3. Click **Add User**. Messages: "User Identifier must be a valid email address.", "Passwords do not match.", "A user with that ID already exists". > **Tip:** Give each person their own account. Use **View** for anyone who only needs to watch. Shared accounts make the **Logins** log useless for knowing who did what. --- ## [USR-3] An account's page and Properties Click an account. The page lists its properties. An Admin can click **Properties** to: | Item | Notes | |---|---| | **ID** + pencil | Change the sign-in email ([CON-3.3]). From then on the user signs in with the new address. | | **Enable User Account** | Allow or block sign-in. | | **User's First Name** / **User's Last Name** | | | **Access Level** | **Admin** or **View**. An API account's level can't be changed. | | **Change Password** | Set a new password for the user: **Reset Password for ** › **New** / **Confirm** › **Set Password**. | | **Delete** | Delete the account. There is no undo. | ### [USR-3.1] The built-in Admin account Every DM has a built-in **Admin** account for recovery. Nobody can delete, rename, disable or demote it, and it has no **Delete** button. Keep its password safe, and don't use it for everyday work. **Deleting your own account:** an Admin may delete their own account. The confirmation warns "This is your own account. You will be signed out immediately", and you are then returned to the sign-in page. View users can't delete accounts. Account deletions, renames, and enabling or disabling an account are recorded in the **Logins** log. --- ## [USR-4] Your own account Applies to: everyone Every user can change their own **first name**, **last name**, **sign-in email** and **password**. Click your account under **Users**, then **Properties**. - **Name:** edit **User's First Name** / **User's Last Name** and **Save**. - **Sign-in email:** use the pencil next to your ID ([CON-3.3]). You are then signed out; sign in again with the new address. - **Password:** **Change Password** › **Current password**, **New password**, **Confirm new password** › **Change Password**. "Password changed. Use your new password the next time you sign in." "Current password is incorrect." means the current password didn't match. The new password must be different from the current one. --- ## [USR-5] Passwords - Passwords are checked in your browser in a way that never sends the password itself to the DM ([GS-3]). - **Settings › Policies › Passwords** holds password rules (minimum length, maximum age, history, lockout), but they are **not currently enforced** ([SET-6.1]). Choose long passwords, change them when people leave, and review the **Logins** log for failed sign-ins ([SET-10]). - Forgotten password: an Admin sets a new one ([USR-3]). A forgotten **Admin** password with no other Admin account needs Pythia Technologies. --- ## [USR-6] What is recorded The **Logins** log ([SET-10]) records: - sign-ins and failed sign-ins (including attempts to sign in with an API account); - password changes and sign-in email changes; - new accounts; - alarm acknowledgments; - policy changes; - AI Connector account events: token viewed or regenerated, API Access and Allowed IPs changes. It keeps 7 days. --- # [SET] System Settings Applies to: all DM-family products · viewing: all users · changing: Admin **Settings** in the tree holds the DM's system configuration. Your DM shows the areas installed on it; a typical DM has: | Settings area | Covered in | |---|---| | **Access Control** (Access Control List) | [SET-2] | | **Backups** (Listing of System Backups) | [SET-3] | | **Communication Ports** (Listing of Communication Ports) | [SET-4] | | **Mappings** (Listing of Protocol Mappings) | [INTG] | | **Monitoring** (Listing of Monitoring Settings) | [SET-4] | | **Network Interfaces** (Listing of Network Interfaces) | [SET-5] | | **Policies** (System Policies) | [SET-6] | | **SMTP Relay** (SMTP Relay Settings) | [SET-7] | | **SNMP Settings** (Listing of SNMP System Settings) | [INTG] | | **Time** (Time Settings) | [SET-8] | | **Updates** (Listing of System Updates) | [SET-9] | **Logs**, a separate branch of the tree, is in [SET-10]. Site-wide options (site identifier, list refresh rate, site image) are in **Site Properties** ([CON-2.1]). --- ## [SET-1] System information and restarting Applies to: Admin Click **Settings**, then **Properties**. The dialog shows read-only system information: **Service Status**, **System Serial Number**, **System Version**, **System Installation Date**, **Security Key Status**, **Console IP Addresses**, **Console Gateway IP Addresses**, **Operating System**. ### [SET-1.1] Restart the DM 1. In the same dialog, tick **Reboot Gateway** and click **Save**. 2. Confirm: "Reboot the gateway now? This restarts the system. You will lose this connection — the page will wait while it restarts and return you to the sign-in screen automatically once the gateway is back online." Click **Reboot Now**. 3. The page shows "Waiting for the gateway to come back online… (this can take a few minutes on some hardware)" and opens the sign-in page when the DM is back. Monitoring, alarms and notifications pause while the DM restarts. If it isn't back after 5 minutes, the page says so; refresh after another minute, and contact Pythia Technologies if it still doesn't answer. --- ## [SET-2] Access Control (allowed addresses) Applies to: Admin **Access Control** lists the computers and networks allowed to reach the DM. **While the list is empty, every address is allowed.** | What it restricts | Which entries count | |---|---| | Modbus/TCP and BACnet/IP clients (BMS, SCADA) reading or writing the DM's mappings | **Every** entry | | The web console, the Alarm View and the AI Connector | Only entries with **Apply ACL to DM Console** turned on. If no entry has it on, the console is open to every address. | Add an entry: **Add** › - **Allowed IP Address or Network Address** (e.g. `192.0.2.0`); - **Network Subnet in Slash Notation** (32 = one address; 24 = the whole 192.0.2.x network); - **Apply ACL to DM Console**; - **Description of IP Address or Network Address**; then **Save**. The DM itself (127.0.0.1 and the DM's own addresses) is always allowed. > **Caution:** Before turning on **Apply ACL to DM Console** for any entry, add an entry, also with the switch on, that covers **your own computer**. Otherwise your next request is refused and you are locked out of the console. Refused console requests show "0001 - IP Address not allowed:
". SNMP access has its own list under **SNMP Settings** ([INTG]). --- ## [SET-3] Backups Applies to: viewing: all users · creating, downloading, deleting and scheduling: Admin A backup saves the DM's **configuration only**: locations, groups, units and their points, automations, users, mappings and settings. It does **not** include trend history, alarm history or logs. - **Backup Now:** "Create a backup now? This will save the current configuration." › **Backup Now**. Wait for "Backing up..." to finish. - **Scheduled backups:** **Properties** › **Enable Daily Backup Schedule** and **Time of Backup** › **Save**. - **File names:** manual backups are `DT_Backup_.bk` and scheduled ones `_.bk`, where `` is the weekday (0 = Sunday … 6 = Saturday). So the DM keeps one of each per weekday, and **each file is overwritten a week later**. - **Download** (keep a copy off the DM): open a backup › **Download**. - **Delete:** tick backups › **Delete Selected** › confirm "This action cannot be undone. The files are removed immediately." > **Note:** The console has no restore button. To restore a backup, contact Pythia Technologies with the `.bk` file. > **Tip:** Download a backup after any significant configuration change and keep it somewhere safe. The DM keeps only the last seven days of scheduled backups. --- ## [SET-4] Communication Ports and Monitoring Applies to: viewing: all users · changing: Admin - **Communication Ports:** the DM's serial ports (for example **COM5**, "FTDI - USB Serial Port (COM5)") with **Baud Rate** and **Parity**. Serial (COM) drivers use these ([DRV]). - **Monitoring › Drivers:** the drivers installed on this DM ([DRV]). - **Monitoring › Networks:** the **virtual monitoring networks**. Each is a polling process that reads its units in turn. The list shows **Network**, **Type** (NET or COM), last **Start Time** / **Stop Time**, **Total Time** (seconds per polling pass), **Process ID** and **Description**. Open one to see each device address it polls and how long each took. - **Properties:** **Network Type**, **Poll Rate in seconds** (how often it polls, e.g. 15) and **Network Description**. - **Add** creates another network. Spreading units across networks lets slow equipment be polled separately from fast equipment. Choose a unit's network in its **Virtual Monitoring Network** property ([UNIT-1.3]). > **Note:** A unit is polled at its network's **Poll Rate**. Alarm **Fail Count** ([UNIT-4.3]) counts these polls. With a 15-second poll rate and a Fail Count of 3, a condition must last about 45 seconds before the alarm fires. --- ## [SET-5] Network Interfaces Applies to: viewing: all users · changing: Admin **Settings › Network Interfaces › 0, 1, …**. Each interface shows its **Name**, **MAC**, **Status**, **Link Speed** and **Current IP**, and lets an Admin set: - **Obtain an IP address automatically (DHCP)** (interface 0 only), or - one or more static **IP Address** / **Subnet Mask** / **Gateway (optional)** rows (**+ Add IP**, up to 16), and - **DNS Server**. Nothing changes until you click **Apply & Restart**: "Apply the network configuration and restart the system? … If you changed the IP of the interface you're connected through, you will lose this connection and must reconnect at the new address." The DM restarts. For a static address, the page takes you to the new address when the DM is back. **Cancel** discards your edits. > **Caution:** A wrong address, mask or gateway can make the DM unreachable over the network. Check the values with your network team before applying. If the DM is also reached by a DNS name (for HTTPS or the AI Connector), update the DNS record too. --- ## [SET-6] Policies Applies to: viewing: all users · changing: Admin **Settings › Policies** groups system-wide rules into categories. Open a category to see its policies. Toggle **Enable** in the list, or click a policy to change its value and **Save**. Every policy change is recorded in the **Logins** log. ### [SET-6.1] Passwords | Policy | Default value | Allowed range | Default state | |---|---|---|---| | **Admin Maximum Age** — Maximum age of Admin password in days | 60 | 0–3650 | Disabled | | **History** — Block reuse of the last number of previous passwords | 5 | 0–100 | Disabled | | **Lockout** — Lock account after number of consecutive failed sign-ins | 5 | 1–100 | Disabled | | **Minimum Length** — Minimum password length in characters | 8 | 1–128 | Disabled | | **User Maximum Age** — Maximum age of user password in days | 90 | 0–3650 | Disabled | > **Note:** The password policies are **not currently enforced**, even when enabled. Until they are, set strong passwords by hand and remove accounts that are no longer needed ([USR]). ### [SET-6.2] AI Connector Present only on DMs with the AI Connector. Six policies decide what AI assistants may change. All install **Disabled** except **Redacted Properties**. Full table: [AIC-3]. --- ## [SET-7] SMTP Relay (outgoing email) Applies to: viewing: all users · settings and tests: Admin Every email the DM sends (alarm notifications, heartbeats, tests) goes through its built-in **SMTP Relay**. The relay queues each message and delivers it, retrying if needed. ### [SET-7.1] The relay page **Settings › SMTP Relay** refreshes every 5 seconds. It shows: - **Status:** "Listening" / "Not Listening", the delivery mode ("Direct MX", or "Smart Host : …") and the HELO name. - Counters, the last error, the **Message Queue** (messages waiting or retrying) and **Recent Activity** (**QUE** queued, **OK** delivered, **FAIL** failed, **EXP** expired). "Queue is empty — delivery is normally immediate; messages appear here only while delivery is pending or retrying." ### [SET-7.2] Settings **Properties** (**SMTP Relay Properties**): | Field | Meaning | |---|---| | **Smart Host** | Your organization's mail server (e.g. `smtp.example.com`). Blank = deliver directly to each recipient's mail server ("Direct MX"). | | **Smart Host Port** | 25 when blank; 587 for STARTTLS or 465 for SMTPS is typical. | | **Smart Host TLS** | **Default — auto when a user is set**, **None — plaintext**, **STARTTLS (typically port 587)**, **SMTPS — implicit TLS (port 465)**, **Auto — STARTTLS when offered**. | | **Smart Host Certificate** | **Validate (default)** or **Accept self-signed**. | | **Smart Host User** / **Smart Host Password** | Sign-in for the mail server. The password is stored encrypted and never shown. Leave it blank to keep it; `-` clears it. Clearing **Smart Host User** also deletes the password. | | **From Address** | Sender for all DM email. `noreplies@pythiatech.com` when blank. | | **HELO Name**, **Message Limit MB** (25), **Queue Alarm Depth** (50; 0 = off), **Queue Limit** (5000), **Queue Limit MB** (500), **Expire Days** (1), **Keep Undeliverable (Badmail)**, **Badmail Keep Days** (1) | Queue and delivery limits; the defaults suit most sites. | | **Bind Address(es)** / **Listen Ports** | Which of the DM's addresses and ports the relay accepts mail on (default port 25). Remove 25 only if you know nothing on the DM needs it. | Click **Save Settings**. Changes apply within about 5 seconds. **Connection Allow List:** other computers allowed to send mail through the relay. "No entries — only 127.0.0.1 may connect." is normal: the DM only relays its own mail. > **Tip:** Microsoft 365, Google and similar services only accept mail whose **From Address** is the signed-in account or an alias of it. Otherwise messages fail (a 553 error in **Recent Activity**). ### [SET-7.3] Test email Type an address in **Send test email to...** and click **Send Test**. "Queued." means the relay accepted it; watch **Recent Activity** for **OK** (delivered) or **FAIL**. The test email's subject is "PTI SMTP Relay Test". **Reset** clears the counters and recent activity immediately, without asking for confirmation. --- ## [SET-8] Time Applies to: viewing: all users · changing: Admin **Settings › Time** shows **Enable** (Enable Time Management), **Timezone**, **DST** (Enable Daylight Savings Time), **NTP** (Synchronize with Network Time Server), **NTP Server**, and the current **Date** and **Time**. To change them: **Properties** › **Enable Time Management** › **Timezone Setting** › **Enable Daylight Savings Time** › **Synchronize with Network Time Server** and **Network Time Server**, or set **Date** and **Time** by hand when NTP is off › **Save**. With **Synchronize with Network Time Server** on, the DM keeps Windows' time service running and synchronizes with the NTP server regularly. The DM must be able to reach that server. The timezone list covers the Americas, the Atlantic, UTC and GMT. All times the DM records (alarms, history, trends, logs) use the DM's time and timezone. --- ## [SET-9] Software updates Applies to: viewing: all users · uploading and applying: Admin Pythia Technologies supplies DM updates as `.upd` files. 1. **Settings › Updates**: drag the `.upd` file onto "Drag .upd files here", or click **Choose Files** (up to 100 MB each). The update is listed as **PENDING**. 2. Tick it and click **Apply Selected**, or open it and click **Apply Now**. 3. Confirm: "The update will modify the existing configuration. This action cannot be undone - there is no rollback." 4. The status becomes **APPLIED** (with an Applied time and the update's own description) or **FAILED** (with its **Last Error**; **Re-Apply** retries). > **Caution:** Updates cannot be rolled back. Take and download a backup first ([SET-3]), and apply updates only as instructed by Pythia Technologies. Deleting an update from the list removes the file; "This does NOT roll back the effects of any previously-applied update." When an update changes the console, every user sees the **Update available — Refresh** pill ([CON-7]). --- ## [SET-10] Logs Applies to: viewing: all users · enabling and clearing: Admin **Logs** in the tree lists the DM's logs with **Log Name**, **Enabled** and **Description**: | Log | Records | |---|---| | **Logins** (Console Login Log) | Sign-ins, failed sign-ins, account and password changes, alarm acknowledgments, policy changes, AI Connector account and token events. **Enabled by default.** | | **AI Connector** | AI Connector refusals and writes ([AIC-4]) | | **Alarms**, **Automations**, **DM**, **DT**, **DTC DM**, **Smart Panel**, **SMTP Relay**, **Trends**, **Update**, **Views** | Service diagnostics, mainly for Pythia support | Open a log to see its newest 500 entries (**Time**, **Text**), newest first, with **Search log...**, **Refresh**, and **PDF** / **Excel** export. Logs don't refresh on their own. - **Logging Enabled / Logging Disabled** (Admin) turns a log on or off. View users see only the log's state. - **Clear Log** (Admin): "Delete all entries from the log? This cannot be undone." > **Note:** The **Logins** log keeps entries for 7 days. The service logs keep only the **last 15 minutes**; they are live diagnostic windows. Turn one on only when Pythia support asks, and export it promptly if you need to keep it. --- # [INTG] Integrations: SNMP, Modbus/TCP and BACnet/IP Applies to: all DM-family products · viewing and exporting: all users · settings and write permissions: Admin · audience: integrators connecting a BMS, SCADA or network-management system The DM publishes everything it monitors on three standard protocols at once, so other systems can read it and, where you allow, write setpoints: | Protocol | The DM acts as | Default port | |---|---|---| | **SNMP** v1/v2c | SNMP agent | UDP 161 (traps sent to 162) | | **Modbus/TCP** | Modbus server (slave) | TCP 502 | | **BACnet/IP** | one BACnet device | UDP 47808 | You don't build these maps by hand. The DM builds and updates them from your locations, groups and units every 60 seconds. **Settings › Mappings** shows the result and lets you export it. > **Note:** SNMPv3 and BACnet/SC are not available on the DM today. There is no BACnet PICS document or BTL listing. --- ## [INTG-1] How the mapping numbers work Every unit and point gets a **mapping ID** automatically. All three protocol addresses come from the same IDs: | Item | Mapping ID | |---|---| | Unit | 1–254, lowest free number across the DM | | Alarm point | 2–999 within its unit (1 = the unit's communications status) | | Data point | 2–999 within its unit (1 = the unit's status) | | Control | odd numbers 1–999 within its unit (the next even number is its read-back value) | | Item (unit ID **U**, point ID **p**) | SNMP OID (base `1.3.6.1.4.1.38801.4`) | Modbus/TCP (unit ID = U) | BACnet/IP Analog Value instance | |---|---|---|---| | Unit communications (0 = normal, 1 = lost) | `.U.1.1` | coil 00001 | U×10000 + 1001 | | Alarm p (0 = normal, 1 = alarm) | `.U.1.p` | coil p | U×10000 + 1000 + p | | Unit status (0 = disabled, 1 = normal, 2 = alarm) | `.U.2.1` | input register 30001 | U×10000 + 3001 | | Data point p | `.U.2.p` | Integer: 30000+p · Float: 30000+2p−1 and 30000+2p | U×10000 + 3000 + p | | Control p (odd): setpoint, read/write | `.U.3.p.1` | holding register 40000+p | U×10000 + 4000 + p | | Control p: current value, read-only | `.U.3.p.2` | holding register 40000+p+1 | U×10000 + 4000 + p + 1 | **Consequences for integrators:** - A unit's IDs stay the same while it exists, and renaming keeps them. - New units and points appear on the protocols within about 1–2 minutes. - **Deleting a unit or point frees its number, and the next one added reuses it.** After deleting and adding equipment, re-export the map and check your client's configuration. - Only the first 254 units are published. Each unit can publish up to 998 alarms, 998 data points and about 500 controls. --- ## [INTG-2] The Mappings pages **Settings › Mappings** lists **BACnet/IP**, **Modbus/TCP** and **SNMP**. Each protocol page lists the mapped units, and you can drill down to every register, OID or object. The protocol pages do not refresh on their own; click **Refresh**. | Page | Columns | |---|---| | **Modbus/TCP** | **Device Id** (the Modbus unit ID), **Mapped Unit** (`Location\Group\Unit`), **Points** | | **SNMP** | **OID**, **Unit Id**, **Mapped Unit** | | **BACnet/IP** | **Device Id** (the unit's instance prefix, **not** a separate BACnet device), **Mapped Unit**, **Objects** | Drill-down pages list each item with **Enable** (writable items only), **Type** (**Readonly** / **Read/Write**) and **Description**. ### [INTG-2.1] Exports Every protocol page has **Export:** **CSV**, **PDF**, **Excel**, **HTML** and **JSON**. The SNMP page adds **MIB** and the BACnet page adds **EDE**. The files are generated in your browser and named, for example, `Modbus_TCP_Mapping_YYYYMMDD_HHMM.csv`. - **Modbus** exports in a Float format show each value's register pair as one row (e.g. `30001-30002`) and state the word order. - **MIB:** an SNMPv2 module `PYTHIA-DM-MIB`. Object names are numbered in export order, so re-export the MIB after adding or removing points. - **EDE:** the standard BACnet engineering-data exchange CSV for BMS import. **ALC URL** opens the ALC / WebCTRL integration list ([INTG-7]). ### [INTG-2.2] Allowing writes Applies to: Admin External systems can write **control setpoints only**. Readings, alarms and statuses are always read-only. A write is accepted only when: 1. the unit is enabled, **and** 2. that setpoint's mapping entry is enabled for writing: **Enable Register for Write** (Modbus), **Enable Object Identifier for Write** (SNMP) or **Enable Instance for Write** (BACnet). **New setpoint mappings are not writable** until you enable them. Enable one on its properties page (drill down, click it, **Properties**), or all of a protocol's setpoints at once with **Enable All R/W** ("Enable ALL read/write (setpoint) points for this protocol?"). There is no "disable all"; disable individual points on their properties pages. > **Caution:** A setpoint written by an external system acts on the equipment just like a command from the console ([UNIT-3]). Enable only the setpoints the external system actually needs. On/off controls accept only 0 (off) and 1 (on). --- ## [INTG-3] Modbus/TCP **Settings › Mappings › Modbus/TCP › Properties:** | Field | Meaning | |---|---| | **Format for Data Point Values** | **Float LoHi** (default), **Float HiLo** or **Integer** | | **Modbus Port** | TCP port (default 502) | "Changing the format rebuilds the Modbus register map. After saving, allow 1-2 minutes for the service to update the registers before exporting." **Formats** (for data points and unit status; alarms are always coils and controls always single 16-bit registers): - **Float LoHi:** a 32-bit IEEE-754 float in two consecutive input registers, **low word first** (CDAB, "word-swapped"). - **Float HiLo:** the same, **high word first** (ABCD). - **Integer:** one 16-bit register per point, the value × 10 (one implied decimal). Negative values are not supported. - Bytes within each word are big-endian in all formats. If values look like nonsense, the client's word order doesn't match the Format; switch one of them. **Wire details:** - The **unit identifier** in each request = the **Device Id**. - Register numbers are 1-based: coil 00001 = FC01 address 0; input register 30001 = FC04 address 0; holding register 40001 = FC03 address 0. - Function codes: **01** read coils (alarms, communications), **04** read input registers (status, data), **03** read holding registers (odd = setpoint, even = current value), **06** write single register (setpoints only), **16** write multiple registers (one register only). Coils can't be written. - Exceptions: **01** unsupported function; **02** unmapped address or unknown unit, no value yet (for example a disabled unit), or write not allowed; **03** malformed request. - Several clients can connect at once. Idle connections are closed after 15 minutes. - Only clients allowed by **Settings › Access Control** can connect ([SET-2]). - A changed **Modbus Port** takes effect when the DM's Modbus service restarts; restarting the DM ([SET-1.1]) does this. --- ## [INTG-4] SNMP **Settings › Mappings › SNMP › Properties › Format for Data Point Values:** - **String** (default): the value as the console shows it, as text. On/Yes/Closed values are sent as INTEGER 1, and Off/No/Open as 0. - **Integer:** a whole number (the value, scaled by the point's scale factor). Alarms, unit status and controls are always INTEGER. **Agent:** SNMP **v1 and v2c** on UDP 161, enterprise **38801** (Pythia Technologies), data under `1.3.6.1.4.1.38801.4`. It supports GET, GETNEXT (walks) and SET. SET works only on control setpoints (`.3.

.1`), with a Read-Write community and the write permission from [INTG-2.2]; otherwise it returns readOnly or badValue. ### [INTG-4.1] SNMP Settings (communities and managers) Applies to: Admin **Settings › SNMP Settings**: - **Community Strings:** add each community (**SNMP Community String**) with **Access Right** **Read-Only** or **Read-Write**. A Read-Write community is needed for SET. - **IP Addresses:** the management stations allowed to query the DM (**IP Address Allowed**, **IP Address Description**). This is separate from **Access Control**, which covers Modbus, BACnet and the console. - **Properties:** **SNMP System Contact** and **SNMP System Location**. > **Caution:** Treat community strings like passwords. Don't use `public` for a Read-Write community. ### [INTG-4.2] SNMP traps Traps are sent by Alarm automations to their **SNMP Trap** destinations ([AUT-4]), as SNMPv1 or SNMPv2c (per destination), with community `public`. | | SNMPv1 | SNMPv2c | |---|---|---| | Trap identity | enterprise `1.3.6.1.4.1.38801.1.1.1`, generic 6, specific 1 | `1.3.6.1.4.1.38801.1.2.1.` | | Variables | `…38801.1.1.2.1` – `.10` | `…38801.1.2.2.1` – `.10` | The 10 variables, in order: Location, Location Code, Group, Unit, Unit Code, Type, Text, Severity (text), Severity (number: 1 Information, 2 Warning, 3 Minor, 4 Major, 5 Critical), Category. SNMPv3 traps and INFORMs are not available. --- ## [INTG-5] BACnet/IP **The DM is one BACnet device.** Every mapped point, from every unit, is an **Analog Value** object in that one device. **Settings › Mappings › BACnet/IP › Properties:** | Field | Meaning | |---|---| | **BACnet Device Instance** | The DM's device instance (default 1). Must be unique on the BACnet network. | | **BACnet Port** | UDP port (default 47808). Takes effect when the DM's BACnet service restarts. | **Device:** Vendor **Pythia Technologies** (ID 617), Model "DT09", Description "Pythia Technologies BACnet Gateway", Protocol Revision 14, no segmentation. **Services:** ReadProperty, ReadPropertyMultiple, WriteProperty, Who-Is/I-Am. There is **no COV, no segmentation, and no alarm/event services**, so poll the values instead. Large object lists must be read by index (index 0 = count). **Objects:** - Object_Name `Location\Group\Unit\Point`. - Units "no-units"; the unit of measure is in the point's description. - A point with no value (for example a disabled unit) reads **−32768** with the FAULT flag set. **Writes:** - Present_Value of setpoint objects only (odd 4xxx), subject to [INTG-2.2]. - Priority is ignored (there is no priority array). - Refused writes return write-access-denied. **Discovery:** - Replies go straight to the requester. - The DM does not act as a BBMD or register as a foreign device. A BMS on another subnet must reach the DM directly (for example with a static device binding). Only clients allowed by **Settings › Access Control** get answers ([SET-2]). --- ## [INTG-6] Views **Views** in the tree shows data collectors that feed fleet dashboards such as **Sensors** and **Branch Circuits**. The page refreshes every 5 seconds and shows "Views: N Running: N Stopped: N Errors: N" and a card per view: **Normal** / **Error** / **Disabled**, collector running or stopped, **Poll Rate**, and start and stop times. Click a view for its data or dashboard. Views are set up by Pythia Technologies. A DM without views shows "No views configured." --- ## [INTG-7] ALC / WebCTRL integration URLs On any protocol page, **ALC URL** opens a window listing a ready-made ALC WebCTRL point address for every mapped point: | Protocol | Address pattern | Example | |---|---|---| | SNMP | `snmp://1/s/` | `snmp://1/s5/.4.1.1.1` | | BACnet | `bacnet://0:/2:` | `bacnet://0:192.0.2.10/2:13001` | | Modbus/TCP | `mtcpip://///` | `mtcpip://FLOAT/30001/7/192.0.2.10` | - **SNMP:** choose the **SNMP OID Table Index** (**S1**–**S80**) and enter `1.3.6.1.4.1.38801` into that index of WebCTRL's SNMP OID Table. - **BACnet / Modbus:** choose the **Server IP Address** (the DM address WebCTRL uses). - **Modbus Float:** set WebCTRL's "Reverse order of High and Low Words for FLOAT Data Type" to match the Modbus Format ([INTG-3]). - **Copy** copies one address; **Copy All URLs** copies all addresses shown. Search with "Filter URL, unit, type, or description…". **Export:** CSV, PDF, Excel. --- ## [INTG-8] AI assistants and the mappings An AI assistant connected through the AI Connector can read the same maps (without communities or other credentials) and produce register lists or EDE-style tables on request ([AIC-7.2]). --- # [CUS] Custom Pages Applies to: DM, SPDM, SPIGM and SPAC4 · attaching and uploading pages is Admin only A custom page is your own dashboard inside the DM console, such as a UPS redundancy view, a rack elevation, a one-line diagram or a floor plan. It is a single HTML file that you upload to the DM and attach to a **Location** or a **Group**. When anyone clicks that location or group in the tree, the custom page opens in the content area instead of the standard list. The tree, top bar and status bar stay the same. You do not need to be a web developer. An AI assistant can write the page for you ([CUS-2]). > **Note:** Equipment dashboards for individual units are not custom pages. They come with the unit's driver ([EQP]) and cannot be replaced by upload. --- ## [CUS-1] How custom pages work - **Where a page can go:** on a Location or a Group. Each Location or Group shows either its standard page or one custom page. - **Where files are kept:** uploaded pages and images are stored in the DM's site folder and served by the DM itself. A custom page needs nothing from the internet. - **What the page can show:** anything the console can read: unit status, live data points, alarms and controls, from any location on the DM. The page shows data with the permissions of the person viewing it, so a View user sees nothing through a custom page that they could not see in the console. - **What the DM passes to the page:** the path of the Location or Group it is attached to, so one page file can be attached to several groups and show each group's own units. - **Everyone sees the change:** when a page is uploaded, replaced or attached, other signed-in users get the **Update available — Refresh** pill in their top bar ([CON]). --- ## [CUS-2] Getting a page written The DM publishes an authoring guide that tells any AI assistant exactly how to write a page that works the moment it is uploaded. ### [CUS-2.1] With any AI assistant Applies to: DMs with the DM AI Connector installed 1. In a browser, open `https:///ai_pages.asp`. 2. Copy the entire page and paste it into your AI assistant. 3. In the same message, describe the page you want. For example: "A page for the Power Rack 1 group showing each UPS's load, with a warning if either UPS in a pair could not carry the other's load." 4. Save the HTML file the assistant produces, with a simple file name: letters, digits, `_`, `-` and `.` only, no spaces. 5. Upload and attach it ([CUS-3]). An assistant connected through the AI Connector can read the same guide itself with its `get_page_guide` tool ([AIC-7.2]). > **Tip:** Give the assistant the exact names of the units and data points you want shown. Point names differ between equipment drivers, even for the same measurement. You can see them on each unit's **Live Data** page ([UNIT]). ### [CUS-2.2] Without the AI Connector If `ai_pages.asp` is not available on your DM, give your AI assistant [CUS-6] of this guide as its instructions. --- ## [CUS-3] Uploading and attaching a page Applies to: Admin 1. In the tree, open the Location or Group that should show the page, and click **Properties**. 2. Find the **Page URL** field and click **Choose…** next to it. The **Choose a page** window lists every page already uploaded to the DM. 3. Do one of the following: - Click an existing page to select it. - Click **Upload new page…** and choose your `.html` or `.htm` file. If a file with the same name already exists, the DM asks: "“” already exists. Replace the existing file with this new version?" - Use **Replace** on an existing page's tile to upload a new version under the same name. This does not ask for confirmation. 4. **Page URL** now shows `site/.html`. Click **Save**. 5. Click the Location or Group in the tree. Your page appears. Uploading alone does not attach a page: you must **Save** the Properties dialog. Replacing a file that is already attached takes effect for everyone at once, with no Save needed. > **Note:** The DM's web server caches pages aggressively. After replacing a page, press **Ctrl+Shift+R** to see the new version. ### [CUS-3.1] Images for your pages Images such as floor plans or photos are uploaded the same way, through any **Choose…** button on an image field (for example **Overview Image**). Supported types are **.png**, **.jpg**/**.jpeg** and **.gif**; SVG is not accepted. A page refers to an uploaded image as `/Custom/site/`. ### [CUS-3.2] Other page choices **Page URL** also accepts the DM's standard pages: | Page URL | Shows | |---|---| | `PTJ_groups.html` | A Location's standard Groups list (the default for a location) | | `PTJ_units.html` | A Group's standard Units list (the default for a group) | | `PTJ_units_environmentals.html` | A Group's units as temperature/humidity gauges ([MON]) | Only `.html` pages are accepted. Anything else gives "URL must point at an .html page, or be cleared to use the default view." --- ## [CUS-4] Returning to the standard page, and changing properties Applies to: Admin While a Location or Group shows a custom page, its standard page — and the **Properties** button on it — is not shown, unless the custom page itself includes a **Properties** button. To return to the standard page: 1. Open the Location or Group in the tree so its custom page is showing. 2. Click **Reset to default page** in the top bar. 3. Confirm "Reset this container to its standard view ()?". The standard page opens. The uploaded file stays on the DM. To change the Location's or Group's properties (name, description, column headers, and so on) and keep the custom page: reset it as above, make your changes in **Properties**, then attach the page again with **Page URL › Choose…** and **Save** ([CUS-3]). > **Caution:** For a group using the environmental gauge view, do not clear **Page URL** from that view's Properties. Set it to `PTJ_units.html` instead. [Pending fix — BUGS #9] --- ## [CUS-5] Limits and troubleshooting - **No delete:** the console has no way to delete an uploaded file. Replace it with a new version, or ask Pythia Technologies to remove it. - **One file per page:** CSS and JavaScript must be inside the HTML file. No separate `.js` or `.css` uploads, no external scripts, fonts or images. - **Locations and Groups only.** Units show their driver's dashboard. | Symptom | Likely cause | Fix | |---|---|---| | Page shows but no live data, or "POLL FAILED" | The page asks the AI Connector (`ai.asp`) or uses a token, or has a host name written into it | Have it rewritten to follow [CUS-6] | | Some units show as dead or blank | The page uses a point name that unit's driver doesn't have | Check the unit's **Live Data** names; have the page try the alternatives | | Page returns to the sign-in screen | Your console session expired | Sign in again; the page is working correctly | | Old version still showing | Browser or server cache | **Ctrl+Shift+R** | | "Upload failed: Only .html pages allowed" | Wrong file type | Save the file as `.html` | | "Upload failed: Invalid filename" | Name contains `\ / .. :` | Rename the file | | "Upload failed: Admin access required" | Signed in as View | Sign in as an Admin | --- ## [CUS-6] Rules a custom page must follow > **For AI assistants:** Use these rules when writing a page for a Pythia DM. On DMs with the AI Connector, `ai_pages.asp` / `get_page_guide` has the complete guide with a working template. When the two differ, that guide wins. 1. **One self-contained file.** Inline CSS and JavaScript. `` first in ``. No CDN scripts, web fonts, analytics or internet images, because DMs are usually on isolated networks. Use system fonts. The console's own `/Custom/ptj-pythia-base.css` and `.js` may be included by those exact paths (optional). 2. **Read data from the console API with the viewer's session:** `fetch('/json.asp?CMD=&DIR=' + encodeURIComponent(path), { credentials: 'same-origin', cache: 'no-store' })` Use a relative URL: **no host name, no token, no API key, no password.** Never call `ai.asp` or `mcp.asp`. 3. **Commands:** | Command | DIR | Returns | |---|---|---| | `GETGRPUNITS` | `\Locations\\` | the group's units (use to discover them) | | `GETUNIT` | `\Locations\\\` | everything about one unit: `status`, `data[]`, `alarms[]`, `controls` (preferred) | | `GETUNITDATAS` | `…\\Data` | data points only | | `GETUNITALMS` | `…\\Alarms` | alarms only | | `GETTREE` | any container path | one level of the tree | 4. **Read the page's own location from `?dir=`** in its URL, which the DM appends. Normalize doubled backslashes; treat paths as case-insensitive. 5. **Interpret values correctly:** every `value` is a **string** (parse numbers and check they are finite). A blank value means no successful poll yet. `cstate "2"` means the last poll failed: show the value as **stale**, not current. Unit `status` 1 = normal, 2 = alarm, anything else = disabled. 6. **Use exact point names** from the real unit. Where drivers differ, try a list of candidates (for example `Output Watts X`, then `Watts`, then `Output KW X` × 1000). 7. **Poll every 5 seconds** (never faster than 2). Request all units in parallel, never start a poll while one is still running, and abort any request after 8 seconds. On failure, keep the last good value on screen marked STALE. 8. **Session expiry:** on HTTP 401, stop polling and send the whole window to `/PTJ_logon.html`. 9. **Safety:** escape every server string before inserting it as HTML. Put no secrets in the page. Pages display data; changes belong in the console's own screens. 10. **Offline test switch:** support `?demo=1` with simulated values so the page can be previewed without a DM. --- ===================================================================== # PART 2 — DM AI CONNECTOR ===================================================================== # [AIC] The DM AI Connector Applies to: DM, SPDM, SPIGM and SPAC4 with the DM AI Connector installed · setup is Admin only The DM AI Connector lets an AI assistant — Claude, ChatGPT, Copilot, or any tool that speaks MCP or plain HTTPS — read your DM's live data and, only if an administrator allows it, make a small set of carefully limited changes. You ask questions in plain language ("Is anything in alarm right now?", "Chart the UPS load for the last week") and the assistant answers from the live site. This chapter is written for three readers: administrators who set up access, people who connect an assistant, and the AI assistant itself, which can use [AIC-7] as its reference. > **For AI assistants:** If you are connected to a DM through this connector, call `get_info` first. It reports this account's actual permissions and the DM's conventions, and it outranks anything in this guide if the two differ. Never ask a person to read you a password, community string or token. --- ## [AIC-1] What the AI Connector does ### [AIC-1.1] Reads and writes The connector offers 15 functions. Eleven only **read**; four can **change** something. | Kind | What the assistant can do | |---|---| | Read | Describe the site, list locations/groups/units with their status, read a unit's live data, alarms and controls, read configuration properties, list active/information/history alarms, read one alarm's history, list trended points and read trend history, read the SNMP/Modbus/BACnet mappings, and read the custom-page authoring guide. | | Write | Change a control's setpoint · assign or remove a data point's trend bucket · acknowledge an active alarm · clear one stuck active alarm. | The assistant **cannot**: see or change user accounts, passwords, tokens, SNMP communities or other credentials; change system settings, policies, network, time, backups or updates; add, rename or delete locations, groups, units or points; create automations; or reach anything outside the DM. ### [AIC-1.2] How a write is allowed Every write must pass **all** of these checks. If any one fails, the DM refuses and says which one: 1. The assistant's **API account** is enabled and its token is valid. 2. The request comes from an address the account allows (**Allowed IPs**, if set). 3. The account's **API Access** is **Read-Write** (new accounts are **Read Only**). 4. The matching **AI Connector policy** is enabled on the DM (every write policy is **Disabled** by default — see [AIC-3]). 5. For a control setpoint: that control's own **Enable** is on. An operator must enable a control before any assistant can write it. 6. The value passes the control's own limits or option list. Reads need only checks 1 and 2 (plus the rate limit, if enabled). ### [AIC-1.3] What you need - The DM AI Connector installed on your DM. If **Settings › Policies** has no **AI Connector** category, it is not installed — contact Pythia Technologies. - The DM reachable by **HTTPS using its DNS name** (for example `https://dm.example.com`), with a trusted certificate. Pythia configures this when the DM is delivered. The connector refuses plain HTTP, and AI clients reject untrusted certificates and bare IP addresses. For certificate options — your own certificate authority, a public certificate, or a self-signed certificate — and for making AI clients trust a private certificate, ask Pythia Technologies for the **DM TLS Certificates** guide. - An AI client running on a computer that can reach the DM. Most DMs sit on a private network, so **cloud-hosted AI websites cannot reach them**; use a desktop or command-line assistant on a computer on that network. --- ## [AIC-2] Giving an assistant access: API accounts Applies to: Admin Each AI system gets its own **API account**. It has no password and **cannot sign in to the console**; it authenticates with a **token**, a 64-character secret the DM generates. ### [AIC-2.1] Create an API account 1. In the tree, click **Users**, then **Add User**. 2. Set **Access Level** to **API**. The password fields disappear and the name field becomes **API Account Name (the AI system it serves)**. 3. Enter a name for the AI system (for example `Claude`). First and last name are optional. 4. Click **Save**. The dialog changes to show the token: "API account created. Copy the bearer token now. An administrator can also retrieve it later from the account's page." 5. Click **Copy Token** and give the token to the person connecting the assistant (see [AIC-5]). The new account starts **Read Only** with no address restriction. Creating it is recorded in the **Logins** log. > **Note:** The token is shown once in this dialog, but an Admin can copy it again at any time from the account's Properties ([AIC-2.2]). ### [AIC-2.2] Manage an API account Open **Users › ** and click **Properties**. The **ID Properties** dialog has: | Control | What it does | |---|---| | **Enable User Account** | Off = the token stops working on the next request. The quickest way to cut an assistant off. Saved with **Save**. | | **Access Level** | Shows **API**. It cannot be changed; to make a human account, delete this one and create a new one. | | **API Access** | **Read Only** or **Read-Write**. Takes effect **immediately** when changed (no Save needed). Choosing Read-Write asks you to confirm: "Allow this AI account to WRITE?" — the dialog lists what Read-Write allows. Below it: "Token last used: (DM time)" or "Token never used." | | **Allowed IPs** | Addresses allowed to use this token. Blank = any address. Accepts IPv4 addresses (`10.0.0.5`), IPv4 ranges (`192.0.2.0/24`) and exact IPv6 addresses, comma-separated. The hint shows your own browser's address. Saved with **Save**, after a confirmation. | | **Copy Token** | Copies the current token to the clipboard ("API token copied to the clipboard."). | | **Regenerate Token** | Asks "Regenerate this account's API token? The current token stops working immediately." then copies the new token. Every assistant using the old token must be reconfigured. | | **Delete** | Deletes the account; its token stops working. | Tokens never expire. To rotate a token, use **Regenerate Token**. Viewing a token, regenerating it, and changing API Access or Allowed IPs are all recorded in the **Logins** log. > **Caution:** Read-Write unlocks **all four** kinds of write for this account — control setpoints, trend-bucket assignment, alarm acknowledgment and alarm clearing — each still subject to its own AI Connector policy ([AIC-3]). A control setpoint also needs that control's own Enable. > **Note:** An assistant that is already connected may need to **reconnect** before a newly allowed write tool appears in its tool list. ### [AIC-2.3] Cut off an assistant Each of these takes effect on the assistant's next request: | To stop… | Do this | |---|---| | everything this assistant does | turn off **Enable User Account**, or **Regenerate Token**, or delete the account | | only its writes | set **API Access** to **Read Only** | | one kind of write for **every** assistant | turn off that policy ([AIC-3]) | | use from other computers | set **Allowed IPs** | --- ## [AIC-3] AI Connector policies Applies to: Admin · **Settings › Policies › AI Connector** These DM-wide switches decide which kinds of write any assistant may make, plus two protections. **All install Disabled except Redacted Properties**, which is a protection rather than a permission and installs Enabled. Click a policy name to open it; toggle **Enable** inline in the list, or on the policy's page (**Save**). | Policy | Default | What it controls | |---|---|---| | **Alarm Acknowledgment** | Disabled | Lets assistants acknowledge active alarms. The alarm stays active; the acknowledgment records who owns it. | | **Alarm Clearing** | Disabled | Lets assistants clear (remove) one active alarm at a time. Irreversible — intended for stuck alarms. | | **Configuration Writes** | Disabled | Master switch for point-configuration changes. Each kind of change is an item under it; today there is one item, **Trend Bucket** (assign or clear a data point's trend bucket). Both the master and the item must be enabled. | | **Control Writes** | Disabled | Lets assistants write control setpoints. Each control still needs its own Enable. | | **Rate Limit** | Disabled; value 600 | Maximum requests per minute per AI account (allowed range 10–100000). Extra requests are refused, not queued. | | **Redacted Properties** | **Enabled**; empty list | Extra property names to hide from assistants, comma-separated, `*` as a wildcard (e.g. `PIN, *Access Code*`). | Credentials are **always** hidden from assistants, whatever this policy says: any property named Community, Read/Write/Trap Community, Password, Passphrase, Auth/Priv Password, Auth/Priv Passphrase, Secret, Shared Secret, API Key or Token, or whose name contains "password", "passphrase" or "secret". Hidden values appear to the assistant as `********`. --- ## [AIC-4] Records and audit - **Logins log** (always on): failed tokens, refusals because of Allowed IPs, attempts to sign in to the console with an API account, account creation, token viewed or regenerated, API Access and Allowed IPs changes. - **AI Connector log** (**Logs › AI Connector**, disabled by default): every refused request and every successful write — setpoint changes (old → new value), trend-bucket changes, acknowledgments and clears (with the note). Successful reads are never logged. > **Note:** Logs other than **Logins** keep entries for 15 minutes. The AI Connector log is a live diagnostic window, not a long-term audit trail. Acknowledgments made by an assistant show in the console's alarm pages exactly like an operator's, with the API account's name. --- ## [AIC-5] Connecting an assistant All methods use the same token. None of the DM's download pages contain your token; you enter it yourself. The two facts every AI client needs: - **Endpoint (MCP):** `https:///mcp.asp` — Streamable HTTP, JSON-RPC 2.0, stateless. - **Header:** `Authorization: Bearer ` on every request. There is no OAuth sign-in. ### [AIC-5.1] Any AI assistant — the guided way 1. In a browser, open `https:///ai_setup.asp`. 2. Copy the entire page and paste it into your AI assistant, then ask it to connect you to your DM. 3. The assistant walks you through: getting the token, testing the connection before changing anything, configuring your particular client, and a final test. ### [AIC-5.2] Claude Desktop on Windows — the scripted way 1. Open `https:///ai_connect.asp`. It downloads a PowerShell script with your DM's address already filled in. 2. Run the script. It checks that Claude Desktop and Node.js are installed (and offers to install Node.js), asks for your token, tests the connection, backs up your Claude Desktop configuration, and adds an entry named `dm-ai-connector` without disturbing other servers. 3. Fully quit Claude Desktop from the system tray and start it again. 4. Ask: "What equipment is being monitored, and is anything in alarm?" > **Caution:** The script stores the token in Claude Desktop's configuration file on that computer, as Claude Desktop does for every connector. Treat the file like the token itself. > **Note:** If the script reports a certificate-trust failure, your DM uses a certificate from a private certificate authority or a self-signed certificate. Ask your administrator for the CA certificate file and run the script again with `-CaFile `. > **Note:** Install Claude Desktop from Anthropic's website (claude.ai/download), not from the Microsoft Store. The Store version keeps its settings in a different place, so the script may not find them. If Claude Desktop doesn't show the DM connector after running the script, set it up manually ([AIC-5.3]) or contact Pythia Technologies. ### [AIC-5.3] Claude Code and other MCP clients - **Claude Code:** `claude mcp add dm-ai-connector https:///mcp.asp --transport http --header "Authorization: Bearer "` - **Claude Desktop on macOS or manual setup:** Claude Desktop cannot send headers itself, so use the `mcp-remote` bridge (Node.js 18 or later). The exact configuration block is on `ai_setup.asp`. - **Other MCP clients:** point them at the endpoint with the header. Clients that only support local (stdio) servers can use the same `mcp-remote` bridge. ### [AIC-5.4] Scripts and other tools (REST) The same functions are available as plain HTTPS GET requests: `GET https:///ai.asp?CMD=&DIR=` with the `Authorization: Bearer ` header. Commands and paths are listed in [AIC-7]. ### [AIC-5.5] If the connection fails | What you see | Meaning | Fix | |---|---|---| | HTTP 401, or "Invalid token" | Token wrong, regenerated, or account disabled | Get the current token from your administrator | | Code 21009 "Source address not allowed for this account" (also HTTP 401) | Token is fine; this computer's address is not in **Allowed IPs** | Administrator adds the address | | HTTP 403 "HTTPS required" | Connected with `http://` | Use `https://` | | HTTP 403 "IP Address not allowed" | The DM's own address restrictions block this computer | Contact your DM administrator | | HTTP 404 on `/mcp.asp` | The AI Connector is not installed on this DM | Contact Pythia Technologies | | Certificate error | Connected by IP address, or the certificate is not trusted | Use the DM's DNS name; if it persists, contact Pythia | | Timeout / cannot reach | This computer cannot reach the DM's network | Run the AI client on a computer on the DM's network | | "AI interface not licensed" | The DM's system license is missing | Contact Pythia Technologies | --- ## [AIC-6] Using it: what you can ask Once connected, ask in your own words. Examples: - "Give me an overview of this site. Is anything in alarm?" - "What alarms fired last night, and have they cleared?" - "Show the live readings for UPS-21A." - "Chart the UPS load for the past week." - "Which data points are being trended, and which bucket is each in?" - "Export the Modbus register map as a CSV for our BMS integrator." - "Write me a custom dashboard page for the Power Rack 1 group." (see [CUS]) - "Acknowledge the high-temperature alarm on CRAC-01 and note that facilities is on it." (needs Read-Write and **Alarm Acknowledgment**) - "Set the supply-air setpoint on AHU-11 to 68." (needs Read-Write, **Control Writes**, and that control enabled) > **For AI assistants:** Before any write, tell the user exactly what you will change and wait for their confirmation. For `clear_alarm`, confirm first and put the reason in the note — clearing cannot be undone. If a write tool you expect is missing from your tool list, the account or policy does not allow it; tell the user to ask their DM administrator, then reconnect. --- ## [AIC-7] Reference for AI assistants and integrators ### [AIC-7.1] Reading the data correctly 1. Values are delivered exactly as stored, already scaled. The unit of measure is the parenthetical in the point's description, e.g. `(F)`, `(kW)`. Trust it even when a value looks surprising. 2. All timestamps are DM-local time. `get_site` reports the DM's time zone and current UTC offset. 3. Point, alarm and control names are the exact registered names, typos included. Use them byte-for-byte. 4. Many alarms are status annunciations (for example "Load On Battery"), not faults. 5. A location with no groups is not configured yet; its "Normal" does not mean "monitored and healthy". 6. For a control, `setpoint` is what was commanded and `value` is what the equipment reports. After a write, `value` catches up on the unit's next poll. 7. `commsOk: false` means some points did not answer the last poll; treat their values as stale. A **Disabled** unit is not a communications problem. 8. `capped: true` means more than 1000 rows exist; the list is not complete. 9. Hidden (redacted) properties show `********` with `"redacted": true`. Do not ask anyone to read them to you. 10. In `get_info`, trust `configurationWriteItems` rather than `configurationWrites` (the latter reports the master switch only). ### [AIC-7.2] Functions MCP tool names are shown with their REST command. `DIR` paths use single backslashes; optional arguments follow a `|`. | MCP tool | REST command | Kind | DIR / arguments | Returns | |---|---|---|---|---| | `get_info` | AIGETINFO | read | — | This account's permissions, conventions, command list | | `get_site` | AIGETSITE | read | — | Site name, counts of locations/groups/units, active alarm count, time zone, UTC offset, connector version | | `get_tree` | AIGETTREE | read | none, `\Locations\` or `\Locations\\` | Locations › groups › units with status, description, and the group's summary values | | `get_unit` | AIGETUNIT | read | `\Locations\\\` | Status, comms health, data points, alarms (active/normal/disabled), controls (setpoint and value) | | `get_props` | AIGETPROPS | read | a node under `\Locations`, `\Trends` or `\Alarms` | Configuration properties (credentials hidden) | | `get_alarms` | AIGETALARMS | read | none, or `\Alarms\Active`, `\Alarms\Information`, `\Alarms\History` | Bucket counts, or the bucket's alarms (History: newest first, up to 1000) | | `get_alarm_history` | AIGETALARMHISTORY | read | `\Locations\\\\Alarms\` `|window=` | Past occurrences; if currently firing, an `active.dir` to use with acknowledge/clear | | `get_trends` | AIGETTRENDS | read | none, or a location/group/unit path | Trend buckets and trendable points; `historyDir` for trended points | | `get_trend_history` | AIGETTRENDHISTORY | read | a point's `historyDir` `|window=` | Up to 2000 time buckets with min/max band. Window: days (1–3650) or hours (1–87600) depending on the bucket; default 120 | | `get_mappings` | AIGETMAPPINGS | read | none, or `\Settings\Mappings\Modbus/TCP`, `…\BACnet/IP`, `…\SNMP` | Register / object / OID map for integrators (no credentials) | | `get_page_guide` | AIGETPAGEGUIDE | read | — | The custom-page authoring guide ([CUS]) | | `set_control` | AISETCONTROL | write | `\Locations\\\\Controls\` `|value=` (empty value clears) | Previous and new setpoint | | `set_trend_bucket` | AISETTRENDBUCKET | write | `\Locations\\\\Data\` `|value=` (empty stops trending) | Previous and new bucket | | `acknowledge_alarm` | AIACKALARM | write | `\Alarms\Active\