EMS dashboard

# BESS Monitor - User Guide

A web dashboard for monitoring Battery Energy Storage Systems (BESS), viewing telemetry, managing maintenance work orders, and interacting with an AI assistant.

URL: bess.paneco.energy

1. Getting Started

Login

Open https://bess.paneco.energy/
Click Login to authenticate via Auth0
After login, the dashboard loads your assigned sites automatically

Access

Your Auth0 account determines which sites you can access:

Admins — see all sites, can switch freely
Users / Viewers — see only sites matching their assigned site codes (e.g., FI006, EE001)
If you have access to multiple sites, a site selector dropdown appears in the left panel

Deep Links

You can share a direct link to a specific site: https://bess.paneco.energy/?id=<site-asset-id>. The link only works if the recipient has that site code in their roles.

2. Dashboard Layout

The dashboard has two main areas:

Area	Content
Left panel	AI chat assistant, site selector, login status
Right panel	Tab bar, site info bar, chart/3D/test/maintenance panels, device list

The divider between left and right panels is draggable to resize.

Tab Bar

Four tabs across the top of the right panel:

Tab	Icon	Description
Charts	show_chart	Time-series line charts with configurable series
3D View	view_in_ar	Interactive 3D visualization of BESS blocks and strings
Test	speed	Raw telemetry cards and chart for node-level monitoring
Maintenance	build	Work orders, availability, notifications

3. Site Selector

Visible when you have access to multiple sites (or are an admin).

Located below the site name in the left panel
Select a site to load its structure, devices, and telemetry
Switching sites resets the chart, device list, and 3D view

4. Site Info Bar

A live summary bar below the tab bar showing key site metrics:

Metric	Source	Description
P (Power)	meterNode	Active power in kW
Q (Reactive)	meterNode	Reactive power in kVAR
Hz (Frequency)	meterNode	Grid frequency
Blocks	site structure	Total BESS block count
Strings	site structure	Total battery string count
SOC	bessNode	State of charge (%)

Values update in real-time via WebSocket subscription.

5. Charts Panel

Interactive time-series line charts powered by ECharts.

Adding Series

Click any telemetry value in the device list to add it as a chart series. Click again to remove. Up to 8 series can be displayed simultaneously.

Each series shows:

Device name + metric label in the legend
Color-coded line with optional dot markers
Tooltip on hover with timestamp, value, and unit

Dual Y-Axis

Left axis (cyan): Power metrics (kW, kVAR)
Right axis (amber): SOC (%), frequency (Hz), voltage (V), temperature (C)

The axis assignment is automatic based on the metric type.

Top Bar Controls

Control	Description
Time window	Displayed in the meta area (e.g., "5h window")
Refresh	Manually re-fetch data for the current time window
Auto toggle	Enable/disable live updates via WebSocket (5s interval)
Dots toggle	Show/hide circle markers on data points
Share	Generate a shareable URL with current chart configuration and snapshot

Interaction

Scroll on chart to zoom in/out on the time axis
Drag the bottom slider to pan through time
Click legend items to show/hide individual series

Sign Convention

Power values (activePower, reactivePower, apparentPower) follow generator convention across the dashboard:

Sign	Meaning	Example
Negative (−)	Charging / importing from grid	−450 kW
Positive (+)	Discharging / exporting to grid	320 kW

This applies to:

Device list — inline telemetry values
Site info bar — P and Q summary
Line chart — plotted data points and tooltips
Attributes popup — live telemetry values
Test panel — widget cards and chart

Exception: The 3D view displays all values as absolute (unsigned magnitude) since bar height represents magnitude only.

The AI assistant can configure charts via natural language (see AI Chat)

6. 3D View Panel

An interactive 3D visualization of the BESS site showing blocks, strings, and transformer.

Metric Selection

Toggle buttons at the top select which metric to visualize:

Metric	Color Scale	Range
Power (kW)	Dark blue → cyan → green → amber	0 to block max
SOC (%)	Red → amber → blue → green	0% to 100%
Temp Max (C)	Cyan → green → amber → red	0 to 45 C
Temp Min (C)	Blue → cyan → green → amber	0 to 45 C
DC Voltage (V)	Red → amber → green → cyan	1000V to 1400V (string-only)

View Modes

Mode	Description
String	Individual bars per battery string (detailed view)
Block	Single aggregated bar per block (overview)

DC Voltage automatically forces String view.

3D Values

All values in the 3D chart are displayed as absolute values (unsigned), regardless of charge/discharge direction.

Controls

Control	Description
Rotate	Toggle auto-rotation of the 3D scene
Mouse drag	Rotate camera manually
Scroll wheel	Zoom in/out
Click bar	Opens the device attribute popup for that block/string

Visual Features

Container outlines showing physical block enclosures
Transformer block at the top of the layout
Floor texture for spatial reference
Color gradient legend with metric name, unit, and min/max
SSAO (ambient occlusion) for depth perception

7. Test Panel

Raw telemetry monitoring for node-level devices. Designed for commissioning and real-time system verification.

Widget Cards

One card per node device showing live values:

Node Type	Displayed Metrics
meterNode	activePower, reactivePower, frequency
bessNode	activePower, reactivePower, activePowerSetValue
windNode / solarNode	activePower, reactivePower

Each card shows:

Node name and profile label
Live value with unit
Timestamp of last update (HH:MM:SS.mmm precision)
Chart icon if the metric is plotted

Test Chart

5-minute rolling window of raw telemetry data
Plots: activePower (all nodes) and activePowerSetValue (bessNode)
Reactive power is shown in widgets only, not in the chart
Dual Y-axis: Power (left), Frequency (right)

Top Bar Controls

Control	Description
Refresh	Manually re-fetch test data
Auto toggle	Enable/disable 5-second polling
Dots toggle	Show/hide data point markers

Site Switching

When switching sites while on the Test tab, the chart and widget cards automatically reload with the new site's data.

8. Device List

A collapsible tree view of all devices in the current site, displayed below the chart area.

Hierarchy

Site
  meterNode         (grid meter — not expandable)
  bessNode           (BESS controller)
    bessBlock 1      (battery container / block)
      batteryString 1
      batteryString 2
      ...
      hvac
    bessBlock 2
    ...
  windNode           (if present)
  solarNode          (if present)

Telemetry Display

Each device row shows up to 4 live telemetry values:

Profile	Displayed Fields
meterNode	activePower (kW), reactivePower (kVAR), frequency (Hz), powerFactor
bessNode	activePower (kW), stateOfCharge (%), reactivePower (kVAR)
bessBlock	activePower (kW), stateOfCharge (%), reactivePower (kVAR), activePowerSetValue (kW), isOffline
batteryString	activePower (kW), stateOfCharge (%), minCellTemperature (C), maxCellTemperature (C), dcVoltage (V), isOffline
windNode / solarNode	activePower (kW), reactivePower (kVAR)

Interactions

Click expand arrow — drill down into child devices
Click a telemetry value — add/remove it from the chart (highlighted in cyan when active)
Click settings icon (gear) — open the device attributes popup

Scan Functions (Users & Admins)

Available from the device list header:

Scan	Description
Battery String Status	Audits all strings for status register warnings/alarms
Block Status	Audits BESS blocks for status warnings
Missing Data (Strings)	Finds strings with missing telemetry or attributes
Missing Data (Blocks)	Finds blocks with missing telemetry or attributes

Scan results are color-coded: red = alarm, amber = warning, green = OK.

9. Device Attributes Popup

A modal popup showing detailed device information. Opens when clicking a device settings icon or a 3D bar.

Sections

Section	Content
Telemetry	Live values with real-time WebSocket updates
Attributes	Shared scope attributes (configuration values)
Controls	Control attributes (setpoints, commands)
Alarms	Single-value alarm tags with expected state indicators
Status	Bit-field status registers with expandable bit breakdown

Status Bit-Field Decoding

Status registers (e.g., statusContactor, statusString1) expand to show individual bits:

Badge	Meaning
OK (green)	Bit matches expected value
WARNING (amber)	Bit mismatch, warning-level
ALARM (red)	Bit mismatch, alarm-level
— (gray)	No data or no expected value defined

The full register hex value (e.g., 0x003F) is shown alongside the bit breakdown.

Navigation

Use the left/right arrows in the popup header to navigate between sibling devices (e.g., next/previous string in a block).

10. Maintenance Panel

Work order management, team coordination, device status tracking, and availability monitoring.

Key features at a glance:

Summary widgets — work order requests, active WOs, and availability percentage
Work order list — filterable by status, searchable, with color-coded badges
Work order detail — two-column layout with info, rich text description/report, tasks, comments, and file attachments
Status workflow — REQUEST → DRAFT → ACTIVE → IN_PROGRESS → DONE/CLOSED/CANCELLED
Device status tracking — mark devices online/offline with cascade to child strings
Team management — per-site roster with user picker dropdown
Notifications — badge on Maintenance tab, polled every 60 seconds

For the complete maintenance app guide, see Maintenance app.

11. AI Chat Assistant

A Claude-powered AI assistant in the left panel that understands your site structure and telemetry.

Usage

Type a natural language query and press Enter (or click Send). Examples:

Query	Action
"Show power and SOC for block 1 last 2 hours"	Configures chart with specified series and time window
"Last 12 hours"	Changes the time window to 12 hours
"Show all blocks"	Expands all blocks in the device list
"Scan battery strings"	Runs battery string status audit
"Open attributes for FI006ES1BK1BS3"	Opens the attribute popup for a specific device

Suggested Prompts

Quick-start suggestion buttons appear below the input when the chat is empty.

Voice Input

Click the microphone button or press Ctrl+Shift+M to dictate your query. Click again to stop recording.

What the AI Can Do

Configure chart series (device + metric combinations)
Set time windows (hours, or specific date ranges)
Navigate the device tree (expand blocks, drill to devices)
Run diagnostic scans
Open device attribute popups
Answer questions about displayed data

12. Theme & Mobile

Dark / Light Theme

Toggle via the sun/moon icon in the top-left corner. Charts, 3D view, and all panels adapt to the selected theme. The 3D view uses a consistent dark navy background in both themes.

Mobile Layout

On screens narrower than 768px:

The left panel becomes a slide-out drawer
Toggle it with the chat icon in the mobile header
Tap the backdrop to close the drawer
The site name appears in the mobile header bar

13. Role Permissions Summary

Dashboard Access

Feature	Viewer	User	Admin
View charts	Y	Y	Y
View 3D visualization	Y	Y	Y
View test panel	Y	Y	Y
View device list + telemetry	Y	Y	Y
View device attributes popup	Y	Y	Y
Add series to chart	Y	Y	Y
Share chart link	Y	Y	Y
Use AI chat	Y	Y	Y
Use voice input	Y	Y	Y
Run diagnostic scans	Y	Y	Y
Switch between assigned sites	Y	Y	Y
Access all sites	—	—	Y
Enable admin mode	—	—	Y

Maintenance Access

Action	Viewer	Partner	User	Admin
View work orders	Y	Y	Y	Y
Create WO (as REQUEST)	Y	—	—	—
Create WO (as DRAFT)	—	Y	Y	Y
Edit work order fields	—	Y	Y	Y
Add comments	—	Y	Y	Y
Upload/delete files	—	Y (own)	Y (own)	Y (any)
Manage task checklists	—	Y	Y	Y
Assign team members	—	—	—	Y
Manage team list	—	—	—	Y
Rename categories	—	—	—	Y
View notifications	Y	Y	Y	Y

Partner-Maintenance Role

External maintenance partners have a dedicated partner-maintenance role:

Site access: determined by team membership in the site_team_members table (not Auth0 site codes)
UI: only the Maintenance tab is visible — no Charts, 3D View, Test, or device list
Permissions: equivalent to dashboard-user for maintenance features (create drafts, edit, comment, upload, manage tasks)
Cannot: assign team members, manage team list, rename categories, or access telemetry panels

Site Access

Users/Viewers: Auth0 roles include site codes (e.g., FI006, EE001) — you can only access matching sites
Partners: site access is based on team membership — your administrator adds you as a team member for specific sites
Admins: access to all sites without needing site codes
The site selector shows only your allowed sites

EMS dashboard

Table of Contents

1. Getting Started

Login

Access

Deep Links

2. Dashboard Layout

Tab Bar

3. Site Selector

4. Site Info Bar

5. Charts Panel

Adding Series

Dual Y-Axis

Top Bar Controls

Interaction

Sign Convention

6. 3D View Panel

Metric Selection

View Modes

3D Values

Controls

Visual Features

7. Test Panel

Widget Cards

Test Chart

Top Bar Controls

Site Switching

8. Device List

Hierarchy

Telemetry Display

Interactions

Scan Functions (Users & Admins)

9. Device Attributes Popup

Sections

Status Bit-Field Decoding

Navigation

10. Maintenance Panel

11. AI Chat Assistant

Usage

Suggested Prompts

Voice Input

What the AI Can Do

12. Theme & Mobile

Dark / Light Theme

Mobile Layout

13. Role Permissions Summary

Dashboard Access

Maintenance Access

Partner-Maintenance Role

Site Access