Nuvation Energy Battery Stack Emulator

Product Manual
Document ID: NE-PM-014 | Revision: 1.1, 2024-07-16

BSE Software Version: 1.0.0

© 2024 Nuvation Energy
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1. About this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Installation Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Mechanical Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.1. Dimensions and Weight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.2. Installation Location and Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Battery Stack Emulator Electrical Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2.1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2.2. Battery Stack Emulator Network Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2.3. Connect External Network or System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.4. UPS Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3. Battery Stack Emulator First Power-Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3.1. Connect Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3.2. Status LEDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Operating Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. External Computer Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. Network Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.2. Computer OS Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2. Using the Operator Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.1. Download and Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.2. The Dashboard Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.3. The Details Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.2.4. The Status Banner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.3. Using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.3.1. CLI Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.4. Configuring an Emulated Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.5. Using the Battery Stack Emulator Python Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.5.1. Installing Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.5.2. Battery Stack Emulator Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.6. Using the Battery Stack Emulator Modbus TCP Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.6.1. Modbus TCP Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.7. Using the Platform Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.7.1. Launch Platform Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.7.2. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.7.3. Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.7.4. Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.7.5. Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.7.6. Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.8. TCP Ports and Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5. Appendix A: Operating Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.1. Electrical Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
 5.2. Environmental Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.3. Regulatory Compliance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6. Appendix B: List of Supported Equipment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.1. Supported UPS Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
 Nuvation Energy Battery Stack Emulator - Product Manual

1. Introduction
Thank you for choosing Nuvation Energy.

The Battery Stack Emulator accurately emulates many core Nuvation Energy BMS product features
and some of its algorithms.

1.1. About this Manual

This Nuvation Energy Battery Stack Emulator: Product Manual provides the following information:

1. Details of the emulator topology and its operation

2. Installation of client software and its configuration
3. How to use the emulator

This document applies to Battery Stack Emulator 1.0.0 software release (Firmware
 versions Faraday, nPlatform version 2.2.6). Content may be inaccurate or incomplete
for other versions.


We thrive on your feedback and what we build is driven by your input.
Please submit support tickets to [email protected].

Document ID: NE-PM-014 1 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

2. Product Overview
Nuvation Energy Battery Stack Emulator provides the ability to emulate the Nuvation Energy BMS to
allow early engineering development on tasks such as:

▪ Evaluating Battery Management System operation/configuration with a new battery

model/chemistry
▪ Allow third-party integration with the Modbus TCP interface of the Battery Management System
▪ Evaluate external control management of the Battery Management System
▪ Evaluating Battery Management System algorithms and control with emulated system clock for
real-time and faster than real-time emulation
▪ Use the Nuvation Energy BMS Operator Interface with the Battery Stack Emulator
▪ Use the Multi-Stack Controller with the Battery Stack Emulator

Figure 1. Battery Stack Emulator

The Battery Stack Emulator hosts 16 emulator instances providing the following services:

▪ BMS Emulator: An emulator built from the firmware of the BMS that mimics the high-level
application software. Data acquisition is not included and the modelled data of the battery must
be entered into the emulator.
• Emulated BMS port for connecting an Operator Interface. This port can be used to connect the
Operator Interface using a web browser.
• Emulated BMS port for connecting to the Modbus interface of the emulated BMS. Clients can
test the BMS Modbus interface using this port.
▪ CLI: A CLI (Command Line Interface) application to aid in high-level operation to enter emulated
data into the BMS Emulator.
▪ HTTP API: An HTTP interface used by the Nuvation Energy provided Battery Stack Emulator
Python library for controlling the emulated BMS
▪ Modbus TCP: A Modbus TCP interface used to enter emulated data into the BMS Emulator.

To use the Battery Stack Emulator, Nuvation Energy provides:

▪ CLI SSH user credentials

▪ Python library that provides the following capabilities

While executing the emulation, an operator can access and view the Operator Interface in their
browser to observe the emulation in progress.

Document ID: NE-PM-014 2 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

3. Installation Instructions
3.1. Mechanical Installation

3.1.1. Dimensions and Weight

The overall dimensions of the Battery Stack Emulator are 484 mm × 419 mm × 44 mm (19.1 in x
16.5 in x 1.7 in). It has a 1 U height and fits in a standard 48 cm (19 in) size server rack.

The Battery Stack Emulator module weighs 6.5 kg (14.3 lb).

Figure 2. Mechanical Drawing of Battery Stack Emulator

Document ID: NE-PM-014 3 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

3.1.2. Installation Location and Position

The Battery Stack Emulator is rated to operate in the temperature range of 5 °C (41 °F) to 45 °C
(113 °F). It is designed for indoor use.

The Battery Stack Emulator should be installed correctly into its supported size rack with no
additional space required above or below the unit when mounting.

3.1.2.1. Mounting Clearances

A clearance of approximately 762 mm (30 in) in the back of the rack is recommended to allow
sufficient space for airflow, cable connections, and access when servicing.

Document ID: NE-PM-014 4 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

3.2. Battery Stack Emulator Electrical Connections

3.2.1. Getting Started

Before connecting power to the Battery Stack Emulator you need to:

1. Connect external network or system

2. UPS configuration

Below are images of the external interfaces available on the front and back of the Battery Stack
Emulator.

Figure 3. Battery Stack Emulator external interfaces (front)

Figure 4. Battery Stack Emulator external interfaces (back)

3.2.2. Battery Stack Emulator Network Ports

Table 1. Network Port Connection Map
Port Name Function Port Label Port Speed

External Manage network traffic external to the Battery Stack LAN 1 10/100/1000
Emulator. Operator Interface is accessed from this Mbps
port.
LAN 12 1/10 Gbps

Internal Reserved for future use. LAN 2-9 10/100/1000

Mbps
LAN 10, 11 & 13 1/10 Gbps

Figure 5, “Battery Stack Emulator port types” is an image of the Battery Stack Emulator front panel,
pointing out the different types of ports the Battery Stack Emulator supports:

▪ 8x internal Ethernet ports at 10/100/1000 Mbps (LAN 2-9)

Document ID: NE-PM-014 5 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

▪ 2x internal Ethernet port at 1/10 Gbps (LAN 10-11)

▪ 1x internal SFP+ port at 1/10 Gbps (LAN 13)
▪ 1x external Ethernet port at 10/100/1000 Mbps (LAN 1)
▪ 1x external SFP+ port at 1/10 Gbps (LAN 12)

Figure 5. Battery Stack Emulator port types

The external and internal networks of the Battery Stack Emulator should remain


separated and independent for the best operation of the battery pack. Excessive
network traffic on the internal network can interfere with the Battery Stack Emulator
management of devices on the internal network.

3.2.3. Connect External Network or System

The Ethernet RJ45 port labelled 1 or the SFP+ port labelled 12 may be used to connect the Battery
Stack Emulator to an external system, such as:

▪ Energy control systems, such as PCSs and energy controllers

▪ A laptop, to configure operating parameters and observe status
▪ A local area network (LAN) connection, for wired internet access
▪ An Ethernet switch, to access any number of the above devices

The External Ethernet interface is a standard Cat5e-rated RJ45 jack, supporting only 10, 100, and
1000 Megabit speeds. Any Cat5e-rated or higher Ethernet cable of suitable length may be used to
connect to this RJ45 jack.

 Connecting both ports 1 & 12 at the same time will create a loop and will cause
interference with the operation of the external network.

No connection should be made to the IPMI port unless directed by Nuvation Energy.

Refer to the network port connection map Table 1, “Network Port Connection Map”.

A typical networking configuration for an Battery Stack Emulator is demonstrated below.

Document ID: NE-PM-014 6 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 6. Typical networking configuration for an Battery Stack Emulator

3.2.4. UPS Configuration

An uninterruptible power supply (UPS) is a device that allows connected equipment to continue
running when incoming power is temporarily interrupted. A UPS also allows for the safe, orderly
shutdown of the connected equipment by providing protection from instantaneous power disruptions.

The Battery Stack Emulator provides support for an external UPS that can be plugged into the USB
3.0 or Ethernet ports. Refer to Figure 3, “Battery Stack Emulator external interfaces (front)” for the
location of USB ports. The list of compatible UPS devices can be found in Appendix B. Only UPS
devices which can connect via USB or Ethernet are supported.

Support for UPS includes the following features:

▪ Auto shutdown : When the UPS is running on battery, and it reaches the critical low battery level,
the UPS will initiate a shutdown procedure. This procedure will trigger the connected Battery
Stack Emulator to gracefully shut down before UPS shuts off power
▪ Timeout : This feature allows the Battery Stack Emulator to operate on battery mode for a
configurable period of time and then automatically power off the connected UPS alongside a
graceful shutdown. This is useful when some UPS capacity should be reserved for a black start of
the system. In a black start scenario, the Battery Stack Emulator UPS should be connected to the
energy storage system to ensure the UPS can maintain continuous operation after black start of
the energy storage system.

Please reach out to [email protected] for support on configuring UPS device with Battery
Stack Emulator. The UPS features cannot be configured directly and will work with default settings as
specified during the ordering process.

Document ID: NE-PM-014 7 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

3.3. Battery Stack Emulator First Power-Up

3.3.1. Connect Power

Identify an appropriate AC power source
An IEC 320-C13 cable is required to connect the AC power source to the back of a unit. In
addition, the AC power source must not be derived from the energy system itself without the
ability to maintain (or turn on) the supply when the energy system is powered off (i.e. black
start).

An external UPS can be used between the energy system-derived AC source and the supply
providing power to the Battery Stack Emulator when an external AC power source is not available.

Powering up the system

Verify that all the mechanical and electrical installation steps are completed. In addition, check if
the Battery Stack Emulator is properly connected to the network, and power.

When ready to power on the Battery Stack Emulator, connect an IEC 320-C13 cable to the unit
and then enable AC power. The Battery Stack Emulator turns on automatically when power is
applied; however, following a shutdown, the power button can be used to manually turn on the
Battery Stack Emulator as an alternative method to simply power-cycling the device.

The Battery Stack Emulator will emit a 4-tone startup chime when low-level software has started.
This will be followed by a 3-tone chime once all software has been initialized. The Nuvation Energy
user interface will be accessible shortly after this chime.

To shutdown the system, momentarily press the power button to initiate a graceful shutdown of
the Battery Stack Emulator. A graceful shutdown is always recommended before unplugging the
power supply.

The Battery Stack Emulator initiates a factory restore after 10 sequential

unsuccessful boot sequences. To avoid this situation, ensure that the unit is fully

 powered up before power cycling.

In the event the unit has initialized a factory restore, please contact
[email protected] to bring the unit back to a functional state.

Document ID: NE-PM-014 8 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

3.3.2. Status LEDs

When the Battery Stack Emulator is powered up, its status LEDs provide indication of the functional
status of the module and its interfaces. The Operator Interface provides additional information.

Figure 7, “Battery Stack Emulator LED Descriptions” and Table 2, “Port LEDs Description” describe the
LEDs present on the Battery Stack Emulator with their corresponding status and descriptions.

Figure 7. Battery Stack Emulator LED Descriptions

Table 2. Port LEDs Description

LED Colour Status

Informational LED Solid Red Battery Stack Emulator Overheating

Flashing Red Battery Stack Emulator: Fan Failure
NIC2 LED Flashing Green LAN2: Active
NIC1 LED Flashing Green LAN1: Active
HDD LED Flashing Orange Battery Stack Emulator: Hard Drive Activity
Power LED Solid Green Battery Stack Emulator: Operational
IPMI Activity (A0) Flashing Orange IPMI Speed: 10/100 Mbps
Flashing Green IPMI Speed: 1 Gbps
IPMI Link (L0) Solid Orange IPMI State: Active
LAN1 Activity (A1) Flashing Orange LAN1 Speed: 10/100 Mbps
Flashing Green LAN1 Speed: 1 Gbps
LAN1 Link (L1) Solid Orange LAN1 State: Active
LAN2 – LAN9 Activity (A2 – A9) Flashing Green LAN# Speed: 10/100 Mbps
Flashing Orange LAN# Speed: 1 Gbps

Document ID: NE-PM-014 9 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

LED Colour Status

LAN2 – LAN9 Link (L2-L9) Solid Orange LAN# State: Active

LAN10 – LAN 13 Activity (A10-A13) Flashing Orange LAN# Speed: 1 Gbps
Flashing Green LAN# Speed: 10 Gbps
LAN10 – LAN13 Link (L10-L13) Solid Orange LAN# State: Active

Document ID: NE-PM-014 10 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4. Operating Instructions
4.1. External Computer Requirements
An external computer, like a laptop or a PC, is required to perform the setup steps. Ensure the
following requirements have been met when selecting a computer.

4.1.1. Network Connection

It is recommended to connect the computer to the same network as the External Ethernet on the
Battery Stack Emulator. The default settings for the External Ethernet are DHCP, and requires the
network to have an active DHCP server. Most corporate networks and routers will have a DHCP
server.

If a DHCP capable network is not available, (i.e. if the computer must be connected directly to the
Battery Stack Emulator via an ethernet cable) it is recommended to initially connect to one of the
Internal Ethernet ports. The Battery Stack Emulator has a static IP default on the Internal Ethernet
network with the following settings:

▪ Static IP: 192.168.1.10

▪ Net mask: 255.255.255.0

Ensure the computer networking is configured with a static IP of 192.168.1.x where x cannot be 0, 10
or 255 to enable communication with the Battery Stack Emulator. It is recommended once the initial
connection has been made, to configure the External Ethernet port to the desired settings and
connect the computer to that network rather than using the Internal Ethernet. See Section 4.7.3,
“Networks” for details on configuring network settings.


An internet connection is not required for the product to function. However it does
use the Network Timing Protocol (NTP) to maintain its clock accuracy.

4.1.2. Computer OS Compatibility

Ensure the Operating System of the laptop/computer supports multi-cast DNS (mDNS).

Table 3. Operating Systems that support mDNS

OS Version Additional Software Required

Windows 10 N/A
Windows 8 and lower Apple Bonjour
MacOS 10.2 and higher N/A
Linux N/A Avahi

 mDNS is also operational when a Static IP is configured.

Document ID: NE-PM-014 11 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Manual IP Discovery
In the event that the computer does not support mDNS, the MAC address for the
external network port is labeled on the exterior of the Battery Stack Emulator.

 Look for this MAC address in the DHCP server to determine which IP address was
assigned to the Battery Stack Emulator and navigate to 'http://<ip-address>'
from a compatible web browser rather than the mDNS URL http://ncontroller-
<serial_number>.local.

4.2. Using the Operator Interface

The Battery Stack Emulator Operator Interface provides an interface to the stack as it would for the
real Stack Switchgear hardware. To connect the Operator Interface to the first emulated BMS, use the
connection information: http://<ip_address>:8000, where the <ip_address> is the IP address of the
Battery Stack Emulator or the mDNS hostname ncontroller-<serial_number>.local. Some specific
examples of the connection information to be used in the Operator Interface are listed below for the
first emulated BMS at port 8000 (see Table 8, “Battery Stack Emulator TCP Ports and Services for
Stack 'n'” for Operator Interface ports on emulated BMSs other than the first):

▪ Using IP 192.168.1.10: http://192.168.1.10:8000

▪ Using mDNS for product serial number 12345678: http://ncontroller-12345678.local:8000

Not all operations are supported when using the Operator Interface to access the Battery Stack
Emulator. The unsupported features and operations are defined in the list below.


Firmware upgrades are not supported through the Operator Interface. To upgrade
the Battery Stack Emulator, please refer to Section 4.7.5.1.


Networking can not be updated through the Operator Interface. To update the
network information, please refer to Section 4.7.3.

Entering Service Lockout through the Operator Interface is not supported. If Service
 Lockout is entered, it can not be exited again without re-uploading the stack
configuration or restarting the Battery Stack Emulator.


Open wire detection is not supported through the Operator Interface on the Battery
Stack Emulator.

Configuration files cannot be uploaded through the Battery Stack Emulator Operator
 Interface. Battery Stack Emulator configuration must be done using the web
endpoint http://<ip_address>:53000/upload-config as described in Section 4.4

4.2.1. Download and Install

The Operator Interface is used to access the Battery Stack Emulator. It must be installed on a local

Document ID: NE-PM-014 12 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

PC and will accesses the BMS over a network connection.

Download
Visit https://www.nuvationenergy.com/technical-resources to download the latest version of the
Operator Interface.

Install
Extract the contents of bms-oi-<version>.zip to a suitable location on your computer. To avoid
overwriting other releases or files present in the same directory it is recommended to extracting
the package to a folder with the same name as the package.

Document ID: NE-PM-014 13 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.2.2. The Dashboard Tab

The default tab of the Operator Interface is the Dashboard. The Dashboard contains a high-level
overview on the state of the battery stack. This is the only page required for daily monitoring of the
battery stack.

Figure 8. Nuvation Energy BMS Operator Interface Dashboard screenshot

4.2.2.1. Warnings and Faults

Before going into the details of the gauges and information presented in the dashboard, it is
important to understand what a fault and a warning Nuvation Energy BMS status means.

An ALL OK indicates that there are no faults or warning. This is the normal state for Nuvation
Energy BMS.

A Warning indicates the state of the battery system has been detected outside of its normal
operational range. The cause of the warning should be identified and a corrective action
should be performed. For instance, if the warning is a thermistor temperature measurement
has become too hot, the battery system should be cooled to bring the measurement back
into the normal operational range.
A Fault indicates the state of the battery system has been detected outside of its safe
operational range. The cause of the fault must be identified and a corrective action must be
performed. For instance, if the fault is a cell voltage measurement has become too low, the
cell maintenance manual must be reviewed to identify what remedial actions are required.

A Fault is more severe than a Warning and the source of the fault must be discovered and
resolved before attempting to clear and continue operating the battery system.

4.2.2.2. Stack Voltage

The stack voltage radial meter shows the total battery stack voltage.

Document ID: NE-PM-014 14 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.2.2.3. Stack Current

The stack current radial gauge shows the battery stack current as well as the maximum charge
current limit and the maximum discharge current limit. The acceptable current range is visualized on
the gauge by the blue arc. An absence of the blue arc indicates the battery stack cannot be charged
or discharged in its present condition.

A negative current value indicates the battery stack is charging. A positive current value indicates the
battery stack is discharging.

4.2.2.4. State-of-Charge
The State-of-Charge radial gauge shows the battery stack’s State-of-Charge. The battery stack is
empty when the State-of-Charge value is 0% and full when the State-of-Charge value is 100%.

4.2.2.5. Depth-of-Discharge

Document ID: NE-PM-014 15 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

The Depth-of-Discharge radial gauge shows how much energy has been taken out of the battery
stack. In an ideal Energy Storage System, defined as a system with no power losses, the amount of
energy shown in this gauge needs to be added back into the battery stack to fill it back up to 100%
State-of-Charge.

4.2.2.6. Cell Voltage

The cell voltage bar gauge shows the maximum, minimum, and average cell voltage measurements
within the stack.

The high cell voltage and low cell voltage warning and fault threshold is visualized on the gauge with
yellow and red segments. The blue segment depicts the acceptable cell voltage range.

If a triangle enters the yellow segment, a warning has occurred. If a triangle enters the red segment,
a fault has occurred.

The maximum and minimum cell location in the stack and their voltage values are shown below the
gauge, along with the average cell voltage value.

Document ID: NE-PM-014 16 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.2.2.7. Temperature
The temperature bar gauge shows the maximum, minimum, and average cell temperature
measurements within the stack.

The high cell temperature and low cell temperature warning and fault threshold is visualized on the
gauge with yellow and red segments. The blue segment depicts the acceptable cell temperature
range.

If a triangle enters the yellow segment, a warning has occurred. If a triangle enters the red segment,
a fault has occurred.

The maximum and minimum cell location in the stack and their temperature values are shown below
the gauge, along with the average cell temperature value.

Document ID: NE-PM-014 17 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.2.2.8. Nuvation Energy BMS Status

Nuvation Energy BMS status information contains information on the overall safety status of the
battery stacks, the battery stack connection state, number of cells balancing, maximum charge
current limit, maximum discharge current, and the time and date of the last update of the
Dashboard.

4.2.2.8.1. Operation Status

Nuvation Energy BMS operation state is shown in the big status circular indicator.

Document ID: NE-PM-014 18 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 9. Three possible Nuvation Energy BMS operation states

The normal state is All OK and the color of the indicator will be green. The warning state is Warning
and the color of the indicator will be orange. The fault state is Fault and the color of the indicator will
be red.

Clicking on the indicator will jump to a comprehensive status list of warnings and faults active in the
battery stack.

Clicking on the Clear button below the state will cancel any warnings and faults that are not self-
clearing.

4.2.2.8.2. Connection State

The battery stack connection state is shown in the oval indicator.

Figure 10. Three possible connection states

Stack Disconnected in a red oval indicates the SSG contactors are open, and the battery stack is
unavailable to be charged or discharged.

Stack Pre-charging in an orange oval indicates the battery stack has connected its pre-charge circuit
and is attempting to equalize the battery stack voltage to the system DC bus voltage.

Stack Connected in a green oval indicates the battery stack is available to be charged or discharged.

Clicking the Connect button initiates the stack connection sequence of events. Nuvation Energy BMS
must be in the All OK state for the Connect button to be available.

Clicking the Disconnect button will disconnect the battery stack from the system DC bus.

4.2.2.8.3. Information Table

The information table shows the number of cells that are having excess energy bled off to maintain a
balanced battery stack.

Document ID: NE-PM-014 19 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

The Charge Limit shows the maximum charge current limit value. The Discharge Limit shows the
maximum discharge current limit value.

The Charge Limit and Discharge Limit values are visualized on the Stack Current radial gauge as the
limits of the blue arc.

4.2.2.8.4. Last Update

The Updated time and date shows the last time the Operator Interface had successfully communicated
with Nuvation Energy BMS and updated all items in the Dashboard with values from Nuvation Energy
BMS. The time and date is based on the local computer/tablet; it does not come from Nuvation
Energy BMS.

If the communication with a Nuvation Energy BMS is lost, a notification banner appears at the top of
the display screen. The information shown on the Dashboard represents the last data received and is
no longer recent.

Document ID: NE-PM-014 20 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.2.3. The Details Tab

The Details tab contains a much more detailed view into the status of Nuvation Energy BMS. The data
values shown in this tab can be easily copied into a spreadsheet as a means of capturing the current
state of Nuvation Energy BMS for manual data recording purposes.

The Details tab has multiple sub-sections called accordions that can be expanded to reveal more
information. You can have multiple accordions expanded at the same time.

Figure 11. Nuvation Energy BMS Operator Interface Details tab screenshot

Figure 12. Operator Interface Support Button

 The SUPPORT button can be used to direct the operator to the Nuvation Energy website
to contact Support.

4.2.3.1. Battery
The Battery accordion contains values on the overall battery stack and the maximum charge current
limit, the maximum discharge current limit, and the number of cells balancing in the battery stack.
This information is identical to the values shown in the radial gauges, the bar gauges and the

Document ID: NE-PM-014 21 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Information Table on the Dashboard.

Figure 13. Battery accordion in Details Tab

4.2.3.2. Contactor Life

The Contactor Life accordion contains values that track the life of contactors. See Contactor Life
Tracking for further information.

Figure 14. Contactor Life accordion in Details Tab

4.2.3.3. SoC Calibration

The State of Charge Calibration accordion allows for calibration of SoC and reset of the measured
capacity estimate. This accordion is only visible if the OCV is enabled (stack_soc.ocv_enabled). Both
of these operations are only enabled when the battery is operational (not in service lockout) but
disconnected (stack_control.actual_state == 0).

Document ID: NE-PM-014 22 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 15. SoC Calibration accordion in Details Tab

4.2.3.3.1. Charge Calibration

SoC charge calibration resets the SoC based on the open-circuit voltage curve. More specifically, it
uses the measured voltage in the cell and the OCV curve to calculate a cell level SoC estimate. The
SoC estimates are aggregated to determine the stack level SoC that is seen on the dashboard. Since
the SoC calibration uses the OCV, the curve needs to be enabled.

A user can reset the SoC only if the stack is disconnected. For chemistries like LFP, it is also beneficial
to wait 1 hour after disconnection before resetting the SoC. This will allow the battery to relax and
reach equilibrium before a reset calculation is conducted. Although it is recommended to wait 1 hour,
the period is not enforced on the Operator Interface.

The SoC reset is used to provide a rough initial estimate of SoC before a calibration can occur. This is
usually when the BMS is initially connected and setup up. It should not be used as a replacement for
SoC calibration, which can be done by charging the battery to FULL.

4.2.3.3.2. Capacity Reset

Capacity calibration resets the SoC to the nominal capacity. Note that if the stack is imbalanced, it
will update the nominal capacity to account for this imbalance. This is done by calculating the SoC for
each cell.

The recommendations for SoC calibration described above can be followed here as well for
determining when to do a capacity reset.

The user should reset the capacity if the measured capacity value is significantly different from the
nominal capacity and the battery degradation is known. Once again, the reset provides a rough
capacity estimate. The ideal approach for determining measured capacity is to conduct a charge to
FULL and a discharge to EMPTY calibration cycle.

4.2.3.4. Safety
The Safety accordion contains a comprehensive list of all possible Nuvation Energy BMS faults,

Document ID: NE-PM-014 23 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

warnings and user triggers as well as the overall status of the battery stack. An active fault is shown
as Tripped. An active warning or user trigger is shown as Triggered. A fault, warning or user trigger
that has not completed its Self Check is shown as Checking. In normal operation, all user triggers,
warnings and faults should be Clear.

Figure 16. Safety accordion in Details Tab

Clicking on the Clear Faults and Warnings button at the bottom of this accordion will clear any faults
and warnings that are not self-clearing. The Clear button on the Dashboard can also be used.

Figure 17. Bottom of Safety accordion in Details Tab

Clicking on the Generate Report button at the bottom of this accordion will generate a safety report
JSON file with a list of the Nuvation Energy BMS faults and warnings and their current state as well as
the current firmware versions.

4.2.3.5. Cell Voltages

Document ID: NE-PM-014 24 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

The Cell Voltages accordion lists voltage measurements for all Cells configured in the Configuration
file. Cells that are not configured are displayed as a - (hyphen). Voltages in red indicate
measurements which have triggered a Nuvation Energy BMS fault. Voltages that are highlighted in
yellow are open wires. There is no differentiation between cells that are in the normal operating
voltage range and cells that have triggered a Nuvation Energy BMS warning. There is also no
indication of which particular cells are currently being balanced by the BMS.

Figure 18. Cell Voltages accordion in Details Tab

Figure 19. Cell Voltages with open wires accordion in Details Tab

4.2.3.5.1. Filtering
You can filter the display to highlight cells with voltages above or below a value you specify. The
values that match the criteria will be bolded and all other values will be faded.

4.2.3.6. Thermistor Temperatures

The Thermistor Temperatures accordion lists temperature measurements for all Thermistors
configured in the Configuration file. Thermistors that are not configured are displayed as a dash.
Temperatures in red indicate measurements which have triggered a Nuvation Energy BMS fault.
There is no differentiation between thermistors that are in the normal operating temperature range
and thermistors that have triggered a Nuvation Energy BMS warning.

Document ID: NE-PM-014 25 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 20. Thermistor accordion in Details Tab

4.2.3.6.1. Filtering
You can filter the display to highlight cells with temperatures above or below a value you specify. The
values that match the criteria will be bolded and all other values will be faded.

4.2.3.7. Open Wire

Open wire detection is not supported through the Operator Interface on the Battery
 Stack Emulator. The following section describes the section as it pertains to the G5
High-Voltage BMS.

The Open Wire accordion lists open wire diagnostics for all Cells configured in the Configuration file.
Cells that are not configured are displayed as a - (hyphen). Diagnostic data that is highlighted in
yellow indicates an open wire.

Figure 21. Open Wire accordion in Details Tab

To trigger diagnostics on all cells, click the "Acquire Open Wire Ratios" button. Once clicked, the open
wire scanning process begins.

Figure 22. Open Wire acquiring accordion in Details Tab

Document ID: NE-PM-014 26 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Once the open wire scanning has completed and all diagnostics data is collected it is displayed in a
tabular format with open wires highlighted in yellow.

Figure 23. Open Wire diagnostics accordion in Details Tab

The diagnostic values displayed are ratios of Voltage. Values very close to one ( > 0.97) indicate a
short condition. Values approaching zero (0.0 to 0.4) indicate an open wire connection.

4.2.3.7.1. Filtering
Use the filter to highlight ratios of Voltage that are above or below the specified value. The values
that match the criteria will be bolded and all other values will be faded.

4.2.3.8. Resistance
Resistance accordion in Details Tab
The Resistance accordion contains cell resistance estimate values of every installed cell. This
accordion is only visible if the cell model estimator is enabled (stack_cell_model_estimator.enabled).
See Cell Resistance Estimation for further information.

Filtering is available for resistance values. Use the filter to highlight resistance values that are above
or below the specified value. The values that match the criteria will be bolded and all other values will
be faded.

Document ID: NE-PM-014 27 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 24. Resistance accordion in Details Tab

Document ID: NE-PM-014 28 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.2.4. The Status Banner

The banner at the top of the screen is used to indicate high level changes in system status. During
typical operation nothing is displayed and this indicates the Operator Interface is communicating with
the BMS and the BMS is fully operational with no major diagnostics problems.

4.2.4.1. Service Lockout Indication

The Battery Stack Emulator should never be in service lockout. If service lockout is
 entered through the Operator Interface, it can only be exited with by re-uploading
the stack configuration.

When the system is either entering or is in service lockout, a banner is displayed indicating this to the
user.

Figure 25. Operator Interface Service Lockout indicator

Figure 26. Operator Interface Entering Service Lockout indicator

4.2.4.2. Self Check Indication

When the system is either exiting service lockout or has just booted, the system will execute a Self
Check to verify a safe operation. A banner is displayed indicating the Self Check execution to the
user.

Figure 27. Operator Interface Self Check indicator

4.2.4.3. Communication Loss

When the Operator Interface can no longer communicate with the Battery Management System, a
communication lost banner is displayed at the top of the display. It will provide the amount of time
since disconnected and updates each second.

Figure 28. Operator Interface Communication lost indicator

Document ID: NE-PM-014 29 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.3. Using the CLI

To connect to the first instance (i.e. the first stack) of the Battery Stack Emulator CLI, run ssh -p
50022 sim@<ip-address> from a command shell (CMD, PowerShell, or bash, depending upon which
approach you are using). The SSH username is sim and the password is provided by Nuvation. You
should see the following:

Figure 29. Battery Stack Emulator CLI

The Battery Stack Emulator prompt can be used to initialize the emulator and perform basic
operations. For connecting with other emulated BMS instances, see Table 8, “Battery Stack Emulator
TCP Ports and Services for Stack 'n'” for CLI SSH ports on emulated BMSs other than the first.

4.3.1. CLI Commands

The Battery Stack Emulator CLI (Command Line Interface) can be used to perform basic operations
such as setting voltages, temperatures and current as well as connecting/disconnecting the battery
stack. Below is a summary of the commands available for use:

▪ run: free-running clock mode

▪ stop: stopped/stepped clock mode
▪ step: step clock
▪ set cell: set cell voltages
▪ set therm: set thermistor temperatures
▪ set dc: set current
▪ batt clear: clear faults
▪ batt connect: connect contactors
▪ batt disconnect: disconnect contactors

4.3.1.1. Clocking Commands

The Battery Stack Emulator relies on a clock signal to execute processing for a single time-step and
update outputs based on battery measurement inputs. Emulation time may be clocked in a
continuous, free-running fashion. On startup, the Battery Stack Emulator will initially run in free-
running mode. In this mode, the resulting behavior closely resembles a running BMS.

The Battery Stack Emulator may be stopped at any time with the stop command:

Document ID: NE-PM-014 30 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

BSE> stop

When emulation has been stopped with the above command, emulation time may also be clocked one
cycle at a time. In this mode, the resulting behavior is more like a single-step debugger where inputs
can be changed and outputs examined at each individual time step:

BSE> step <timestep>

where <timestep> is the optional time step size in seconds, which defaults to 1 second.

The run command is used to resume the free-running mode:

BSE> run

4.3.1.2. Set Commands

Cell voltages, thermistor temperatures, and stack current may be set to arbitrary values using the set
command. If the emulator is not in free-running mode, simply setting a measurement does not cause
the Battery Stack Emulator to use the new value(s) immediately. The emulator clock must first be
advanced as described in Section 4.3.1.1.

To set installed cell voltages between 3.2 and 3.3 V:

BSE> set cell 3.2 3.3

To set installed thermistor temperatures between 28 and 29 °C:

BSE> set therm 28 29

Note when the two arguments are given following cell or therm, the Battery Stack Emulator assigns
random values between the two points. If only a single value is given, it sets all inputs to the same
value.

To set DC current to a constant current of 5 A:

BSE> set dc cc 5

4.3.1.3. Battery Commands

The usual battery commands to connect, disconnect, and clear faults are available through the batt
command. These operations can also be initiated from the Operator Interface.

To clear latched faults:

BSE> batt clear

Document ID: NE-PM-014 31 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

To connect the battery stack:

BSE> batt connect

To disconnect the battery stack:

BSE> batt disconnect

4.3.1.4. Exiting the CLI

The CLI can be exited using the CTRL + C and CTRL + D key combinations after a simulation session is
finished. When exited in this manner, the Battery Stack Emulator instance will be terminated and
restarted.

If using an openssh client, the CLI can be exited using the following escape sequence from the
emulator prompt.

BSE> *ENTER*
~.

This sequence will leave the emulator running but terminate the SSH connection. Due to the nature of
the PuTTY client, this sequence will not terminate connection from sessions using that client.

4.4. Configuring an Emulated Stack

The Battery Stack Emulator is provided with a default configuration. In the case another configuration
file is required, it can be uploaded to the Battery Stack Emulator using the following command:

curl --location 'http://<ip_address>:53000/upload-config' --form 'file=@<file_location>'

where ip_address is the address of the Battery Stack Emulator and file_location refers to the location
of the desired configuration.

For more details about the configuration format and customizations, please refer to the relevant
sections of the Stack Switchgear Product Manual.

4.5. Using the Battery Stack Emulator Python Library

The provided python library and playback script may be used to communicate with the Battery Stack
Emulator. This python library and supporting files are provided by Nuvation Energy in a 'zip' file. The
following diagram shows the entire emulator process of the Battery Stack Emulator with the Python
library:

Document ID: NE-PM-014 32 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 30. Python Library Overview

This playback script requires an external PC on the same network as the Battery Stack Emulator with
Python installed. The summary of how the library is intended to be used is:

1. Connect to the emulated BMS instance to a python application

2. At each emulated clock cycle, data for the battery is input into the Battery Stack Emulator.
Simulated battery data is provided by the client.
3. After the clock update, a list of BMS registers is read from the BSE. The list of registers is
configurable by the client.
4. The output data is provided using a python key/value map where the key is the BMS register
name.

Users of the emulator would develop software that at each emulated clock cycle would do the
following:

1. Translate the output BMS registers into their proprietary data structures.
2. Input these data structures into their proprietary algorithm software.

These software components are shown in Figure 30, “Python Library Overview” as the Proprietary
Software blocks.

4.5.1. Installing Python

The Battery Stack Emulator has been tested on python3 version 3.8, though other python versions
might also work. If python3 is not already installed, it can be downloaded from the link:
https://www.python.org/downloads/

In addition to Python3, the following python libraries are required:

Document ID: NE-PM-014 33 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

▪ requests==2.28.1
▪ pandas==1.4.0
▪ numpy==1.24.4

The libraries can be installed using the package manager pip with the commands below:

▪ python3 -m pip install requests==2.28.1

▪ python3 -m pip install pandas==1.4.0
▪ python3 -m pip install numpy==1.24.4

Once python and the libraries are installed, unpack the provided 'zip' file from Nuvation Energy with
the python library for the Battery Stack Emulator in a folder on the external PC.

4.5.2. Battery Stack Emulator Playback

In your given package, you will find the python library for interacting with an emulator instance. This
library is used for reading time series data from a text file and writing the data into the Battery Stack
Emulator. The emulation will always start from 1 second for initialization. Specific BMS registers can
be read from the BMS after inputting the data.

The Battery Stack Emulator does not emulate the exact data acquisition of the
 Nuvation Energy BMS. Any artifacts attributed to acquisition need to be included with
the input data.

While executing the emulation, an operator can access and view the BMS OI in their browser to
observe the emulation in progress. The following sections will describe the different files in the folder
and how to use the playback function. Before using the playback library, emulation should be stopped
using the stop command as defined in Section 4.3.1, “CLI Commands”.


Currently, the time resolution on the Battery Stack Emulator is limited to integer
seconds.

4.5.2.1. Battery Input Data

The battery input data is in the form of a CSV file that contains time series data for the battery
measurements. Each row in the CSV file represents a discrete point in time. All columns are described
in the table below. The columns have the same syntax as the registers in the BMS. The following
table (Table 4, “Columns of the battery input data file”) describes the required columns of the battery
input data file in greater detail.

Table 4. Columns of the battery input data file

Measurement Column name Units Description

The elapsed time when the battery

Time sc_clock[0].seconds s measurements were recorded, starting from
zero.

Document ID: NE-PM-014 34 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Measurement Column name Units Description

Current stack_power[0].current A The applied current to the stack.

The measured voltage of cell 'n' in the
Voltage cell[n].voltage V stack, with multiple columns allowed, one
for each cell index.
The measured temperature of thermistor
Temperature therm[m].temperature °C 'm' in the stack, with multiple columns
allowed, one per thermistor index.
The measured capacity of the battery stack
Capacity stack_soc[0].measured_capacity Ah which is only required for the first time
period, not every time step.
The minimum voltage of a single cell in the
Voltage stack_cell_stat[0].min V
stack.
The maximum voltage of a single cell in the
Voltage stack_cell_stat[0].max V
stack.
Temperature stack_therm_stat[0].min °C The minimum temperature in the stack.
Temperature stack_therm_stat[0].max °C The maximum temperature in the stack.

In the folder sim_data of the Battery Stack Emulator package, there will be an initial CSV file called
battery_input_data.csv. The data provided in this file contains sample measurements that can be used
to better understand what the input into the Battery Stack Emulator should be. The file should be
updated with your unique battery measurement data, keeping in mind the format of the input file.

4.5.2.2. BMS Output Registers

The BMS output register file contains the list of registers that are to be read from the Battery Stack
Emulator. Each row contains the name of a specific register that is to be read. It should be noted that
for components with multiple instances, different register expressions can be used to read multiple
values simultaneously. More information of the BMS register syntax can be found in the stack-level
Product Manual. Similar to the battery input data, the BMS output register file initially found in the
emulator package contains a few default registers. The file can be updated with the specific registers
that you would like to read from the BMS at the end of every emulated clock cycle.

4.5.2.3. Playback Object

The playback object can be built in python by calling the build build_playback() function. The function
has four arguments:

▪ input_data_file: The path to the battery input data, as type string.

▪ output_reg_file: The path to the output register, as type string.
▪ ini_soc: The initial state-of-charge of the battery at the beginning of the test, as type int.
▪ ip: The IP address of the emulator, as defined in Section 4.8, “TCP Ports and Services”.
▪ port: The emulation API HTTP port of the emulated BMS in the Battery Stack Emulator, as defined
in Section 4.8, “TCP Ports and Services”.

After the playback object has been built, there are two methods and one attribute that can be

Document ID: NE-PM-014 35 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

accessed to run the playback script.

step(): At each emulation clock cycle, the step function can be called to input the latest measurement
data into the Battery Stack Emulator.

get_bms_output(): After the clock update, the get_bms_output() function can be called to read the list
of BMS registers defined in the bms output register file. The output data is in the form of a python
key/value map where the key is the BMS register name.

finished: A boolean value indicating whether all the data in the CSV file has been inputted into the
Battery Stack Emulator and the emulation has finished.

4.5.2.4. Run Playback

The emulator package will contain a demo python file called run_playback.py, that can be used as an
example of how the playback function works. The run_playback.py python file can be run using the
following command (in Windows WSL, Linux, or OS X shell):

python3 run_playback.py --ip 10.202.11.106 --port 53000 input_file.csv bms_out_regs.csv

The function will take the measurement data from the input data file, read the registers listed in the
Battery Management System output register file, output the specified output register as a CSV format
by default.

The run_playback.py script supports the following arguments:

Table 5. Command Line Arguments for run_playback.py

Argument Description Default Value

in_file The name of the input playback trace file N/A (Required)
The name of the csv file with bms
bms_out_regs N/A (Required)
registers names for output
The IP address of the Battery Stack
--ip localhost
Emulator
The port of the Battery Stack Emulator
--port PORT 53000
instance HTTP interface
--ini_soc INI_SOC The initial SOC of the battery stack 100
The name of the output playback trace
--out_file OUT_FILE playback_trace.csv
file
--delimiter DELIMITER The delimiter of the playback trace file ,

The run_playback.py script supports a single emulated BMS playback at the specific port (see Table 8,
“Battery Stack Emulator TCP Ports and Services for Stack 'n'” for emulation API ports on emulated
BMSs other than the first). To run playback on multiple stacks, multiple script instances must be run
together in parallel.

4.6. Using the Battery Stack Emulator Modbus TCP Port

Document ID: NE-PM-014 36 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

To connect to the first instance (i.e. the first stack) of the Battery Stack Emulator Modbus TCP,
connect to port 33000 at your nController’s IP address. The Modbus TCP writes/reads can be used to
set/get Battery Stack Emulator values. See Table 8, “Battery Stack Emulator TCP Ports and Services
for Stack 'n'” for connecting to the Modbus TCP server on the other emulated BMS instances.

4.6.1. Modbus TCP Addresses

The Battery Stack Emulator Modbus TCP can be used to set voltages, temperatures, and current.
Below is a table summary of implemented Modbus addresses:

Table 6. Battery Stack Emulator Modbus TCP Addresses

Modbus
Direction Name Base Length Data Size Units Notes
Address

800 points matched to the real

Input Cell Voltage 0 800 16 bits mV Cell Interface and cell wiring
layout
400 points matched to the real
Cell Interface and thermistor
Input Thermistor Voltage 800 400 16 bits mV
wiring layout, expressed as
thermistor voltage
Stack current input. Word order
Input Stack Current 1200 2 32 bits mA
is little-endian
Stack voltage input. Set to 0 to
Input Stack Voltage 1202 2 32 bits mV use cell voltages instead. Word
order is little-endian
Input Padding/Reserved 1204 395 16 bits N/A
Transfers holding register inputs
Input Latch Trigger 1599 1 16 bits N/A to simulator and populates
holding register outputs
Input Padding/Reserved 1600 800 16 bits N/A
Contactor coil status bits (3
Contactor Coil
Output 2400 1 16 bits Bitfield LSbs), matched to contactor
Outputs
wiring harness. Read only

4.7. Using the Platform Interface

4.7.1. Launch Platform Interface

The Platform Interface accessible by navigating to http://ncontroller-<serial_number>.local/platform
and enables configuration and management of the Nuvation Energy Battery Stack Emulator.

This URL can be accessed via a compatible computer.

Replace <serial number> with the Battery Stack Emulator serial number - this can be found on a label
on the exterior of the product. Below is an example of a product label, with the relevant serial
number listed beside the field "SN".

Document ID: NE-PM-014 37 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Figure 31. Sample product label

 The above product label is an example, and the actual label will be different.


The Platform Interface currently supports the most recent versions of Mozilla Firefox
and Google Chrome. Other browsers such as Internet Explorer are not supported.

Five main pages can be accessed by using the menu on the left side of the page:

▪ Functions
▪ Networks
▪ Backups
▪ Settings
▪ Logs

Document ID: NE-PM-014 38 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.7.2. Functions
The Functions page is responsible for installing and upgrading application software.

It is highly recommended to only install/upgrade software under guidance from

 Nuvation Energy. Incorrectly installing/upgrading software could render the Battery
Stack Emulator inoperable.

Figure 32. Nuvation Energy Platform Interface Function

The Functions card displays a list of all functions currently installed along with their respective
versions.

 It is normal for functions of type Standalone to display the Stopped status if one or
more functions of type Bundle are present.

4.7.2.1. Installing a Function

1. Use the Choose File button to select a file with the extension .fn, .fns, or .fnz.
2. Click Install to install the function.

4.7.2.2. Upgrading a Function

1. Software may be upgraded in place by installing a newer version without uninstalling the older
version.

Document ID: NE-PM-014 39 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.7.3. Networks
The networks page shows the current network status of the Battery Stack Emulator and allows for
configuration of the network interfaces.

Figure 33. Nuvation Energy Platform Interface Networks

4.7.3.1. Networking
There are two configuration cards on this page:

▪ External Network: Controls the External Ethernet network on the Battery Stack Emulator
▪ Bridge: Controls the Internal Ethernet network on the Battery Stack Emulator

Each card shows the following information:

▪ IP Address: The current IP of the Battery Stack Emulator on that network. Displays Unknown if no
address is assigned
▪ Netmask: The current netmask of the connected network. Displays Unknown if no address is assigned
▪ DHCP: Whether DHCP will be used to acquire an address. Displays On for yes, and Off for no.
▪ Required: Whether the network interface is required to be up for proper operation. The Battery
Stack Emulator will wait for up to 2 minutes during power-up for interfaces marked 'required' to
come up before continuing with system startup
▪ STP: Spanning Tree Protocol. STP protects inadvertent loops within the network between grouped
ports of the Battery Stack Emulator. When enabled, a delay of 30 seconds occurs between a
network interface gaining carrier and beginning to forward traffic.
▪ MAC Address: The MAC address of the Battery Stack Emulator on the network. This address is not
modifiable
▪ Arrow in the header: A green up-arrow indicates the network interface has a carrier. A red down-
arrow indicates no carrier

Document ID: NE-PM-014 40 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

If DHCP is disabled on the External Network, the following options will become available:

▪ DNS: The nameserver address to use for hostname lookups. If no DNS is available, set to 0.0.0.0 to
disable
▪ Gateway: The gateway address to access the Internet from this network. If no gateway is available,
set to 0.0.0.0 to disable


To communicate with the Battery Stack Emulator while the gateway is set to 0.0.0.0,
the Battery Stack Emulator must be on the same subnet as the gateway.

Clicking the Edit Configuration button switches from showing the current status to showing the
configured values. Values can be edited in the fields directly. The field will change from green to red if
an invalid value is entered. Click Apply to apply and save the configuration.


The Platform Interface only supports configuring IPv4 networks. Operation of the
Battery Stack Emulator on IPv6-only networks is not supported.

The DNS server will receive queries for Internet addresses (for example NTP server
 addresses), so the DNS server should forward queries to root nameservers for proper
operation.


If 2 or more networks overlap with each other, the message "Error: Conflicting
Networks" will appear. This may cause undesirable operation.

When applying External network settings involving DHCP, the old IP address will not


be released, and this may be reflected by the status IP address not matching the
configured value. This ensures that the device will always be reachable. A reboot of
the device will release the old address.

4.7.3.2. Configuration
For the External network settings, the IP address and other corresponding information are
automatically assigned by the DHCP server. For the Internal network settings, it is recommended to
keep the default parameters which are listed as follows:

▪ IP Address: 192.168.1.10
▪ Netmask: 255.255.255.0

Document ID: NE-PM-014 41 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.7.4. Backups
The Backups page is responsible for creating and restoring a state for the Battery Stack Emulator.
That state includes configured settings, installed functions, and all logged data at the time of the
backup creation.

Figure 34. Nuvation Energy Platform Interface Backups

4.7.4.1. Create a System Backup

To create a backup of the current state of the system, click on Create. After a few minutes, a new
backup file will be displayed under Backups with a name, creation date and size. To rename the file,
click on Rename and input the name when prompted.

Figure 35. Nuvation Energy Platform Interface Backup file

A copy of the backup file can be downloaded on a compatible computer by clicking the Download
button. At any time, a backup file can be deleted by clicking the Delete button.

4.7.4.2. Upload a Backup File

To upload an existing backup file, click on Choose file and select a .nbk file, then click the Upload
button.


These files are relatively large and might take time to upload and download to the
system.

Document ID: NE-PM-014 42 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.7.4.3. Backup Restore

To restore the Battery Stack Emulator to a previous state, click the Restore button that corresponds to
the .nbk file with the desired state.


Restoring will delete all current data on the device. Other backups will not be
deleted.


If restoring a backup that contains different network settings, you may have to
navigate your browser to the new address if this does not happen automatically.

Document ID: NE-PM-014 43 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.7.5. Settings
The settings page is responsible for the following:

▪ Upgrading the Battery Stack Emulator

▪ Factory Resetting the Battery Stack Emulator
▪ Rebooting and Powering off the Battery Stack Emulator
▪ Setting Date, Time, and Timezone
▪ Importing and Exporting System Configuration Files

Figure 36. Nuvation Energy Platform Interface Settings


The above screenshot of the settings page is an example, the actual page will be
different.

4.7.5.1. Upgrading the Battery Stack Emulator

It is strongly recommended to only upgrade software under guidance from Nuvation
 Energy. Incorrectly upgrading software could render the Battery Stack Emulator
inoperable.

To upgrade the Battery Stack Emulator, click the Choose File button to select a file with an extension
of .nup or .nosp. Then, click Upgrade to upgrade the unit.

Document ID: NE-PM-014 44 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

 It is always recommended to create a backup before upgrading.

The upgrade process may take a couple minutes, so please wait for the upgrade
 process to complete. The page will automatically refresh once the upgrade is
complete.

Downgrading the Battery Stack Emulator is not an accessible feature. To revert to a

 previous version, please use the backup/restore feature. Please contact
[email protected] for assistance with downgrading.

4.7.5.2. Factory Reset the System

It is strongly recommended to only factory reset the unit under guidance from
 Nuvation Energy. This action is not reversible and will reset the unit to the same
state as it was shipped from the factory.

To reset the Battery Stack Emulator, click the Factory Reset button.

The reset process may take a few minutes, so please wait for it to complete. The


page will automatically refresh once the reset is complete. However, the process will
reset all network settings, so the Battery Stack Emulator may no longer be reachable
without adjusting the computer’s network settings.

4.7.5.3. Rebooting the System

To reboot the Battery Stack Emulator, click on the Reboot button and wait until the unit has been
rebooted.


The Platform Interface will not be functional while the Battery Stack Emulator is
rebooting.

4.7.5.4. Powering off the System

To power off the Battery Stack Emulator, click on the Power off button. Alternatively, pressing the
physical power button on the unit will have the same effect. Following a shutdown, the physical power
button can be pressed to restart the unit.

Before removing power from the Battery Stack Emulator, ensure that the unit has


been powered off either through the Platform Interface or the physical power button.
Abruptly removing power while the unit is still on may lead to internal file corruption
or damage causing the unit to become inoperable.

4.7.5.5. Setting the Date, Time, and Timezone

Document ID: NE-PM-014 45 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

The Timezone and Date/Time are individually configurable.

Setting the Date and Time

1. Click the blue edit-button to the right of the Time label.
2. Select the date and time by clicking on the field that is shown.
3. Click Apply to save the changes or Cancel to discard the changes.
Setting the Timezone
1. Click on the blue edit-button to the right of the Timezone label
2. Select the desired timezone from the dropdown list.
3. Click Apply to save the changes or Cancel to discard the changes.

4.7.5.6. Configuration Import and Export

Configuration files are YAML files that contain settings to be uploaded to the system.


Please contact [email protected] for more information on configuration
files.

To upload a configuration file:

1. Click the Choose File button.

2. Select a YAML configuration file.
3. Click the Import button. A notification box will appear indicating the configuration was uploaded.

 To get the configuration file currently uploaded on the system. Click the Export
button.

Document ID: NE-PM-014 46 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

4.7.6. Logs
The logs page allows debugging information to be downloaded from the Battery Stack Emulator.
These logs can allow Nuvation Energy to more easily assist with support.

Figure 37. Nuvation Energy Platform Interface Logs

4.7.6.1. Downloading Logs

Set the Priority, Search, Since, and Until options as requested by Nuvation Energy support and click
Download. Save the resulting .logx file to your computer so it can be relayed to Nuvation Energy
support.

4.8. TCP Ports and Services

By default, the following port mapping is used for HTTP and Modbus TCP access for the first instance
of an emulated BMS:

Table 7. Battery Stack Emulator TCP Ports and Services for Stack '0'
Port Service Name Protocol Description

The emulated BMS HTTP interface of the emulated

8000 BMS HTTP HTTP Battery Management System which can be used to
connect with the OI.
The emulated BMS Modbus interface for accessing the
503 BMS Modbus Modbus TCP
SunSpec Energy Storage Models.
The interface to be used for configuration upload and
53000 Emulation API HTTP
playback script execution.
The interface to be used for setting Battery Stack
33000 Emulation Modbus Modbus TCP
Emulator values over Modbus.
The interface for CLI emulator access. Username and
50022 Emulation CLI SSH
password will be provided by Nuvation Energy.

The Battery Stack Emulator has up to 16 instances of emulated stacks, with the port number
incremented for each subsequent stack. The table below shows the ports for stack 'n', where the first
stack has 'n = 0', the second stack as 'n = 1' etc.

Table 8. Battery Stack Emulator TCP Ports and Services for Stack 'n'
Port Service Name

8000 + n BMS HTTP

Document ID: NE-PM-014 47 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

Port Service Name

503 + n BMS Modbus

53000 + n Emulation API
33000 + n Emulation Modbus
50022 + n Emulation CLI

For example, the fourth instance with index 'n = 3' will have port 8003 for BMS HTTP, 53003 for
emulator HTTP, port 506 for Modbus TCP, port 33003 for emulator Modbus, and port 50025 for SSH.

In some cases, the SSH client may emit error messages similar to the following immediately at start-
up:

channel 5: open failed: connect failed: Connection refused

This is usually the result of having the Operator Interface or some other program actively trying to
connect to the emulator before it is running.

Document ID: NE-PM-014 48 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

5. Appendix A: Operating Limits

 Exceeding the maximum ratings will damage the module.

5.1. Electrical Characteristics

Symbol Parameter Conditions Min Typ Max Units

Power Specifications
Input Voltage - 100 - 240 V AC
Input Frequency - 50 - 60 Hz
+Vin
Vin = 120 V AC - - 5 A AC
Input Current
Vin = 240 V AC - - 2.5 A AC
Ethernet Specifications
10BASE-T
Connection Speed 100BASE-TX 10 - 1000 Mb/s
RJ45 1000BASE-T
Port 1-9
Twisted-pair cable rating - Cat 5e - Cat 6
Ethernet jack rating - - Cat6 -
1GBASE-T
Connection Speed 1 - 10 Gb/s
10GBASE-T
RJ45
Port 10-11 Twisted-paid cable rating - Cat 6 - -
Ethernet jack rating - - Cat6 -
SFP+
SFP+ Port Speed - 1 - 10 Gb/s
Port 12-13

Systems involving more than 10 Ethernet connected ports for equipment will require
an external network Ethernet switch to be connected to the nController EMS.
 This external switch is not provided. An industrial grade, un-managed switch is
recommended.

5.2. Environmental Conditions

Symbol Parameter Conditions Min Max Units

Thermal Specifications
Operating Temperature - 5 45 °C
Ta
Storage Temperature - -40 70 °C
Humidity Specifications
Operational Relative Humidity Non-Condensing 8 90 %
RH
Storage Relative Humidity Non-Condensing 5 95 %

Document ID: NE-PM-014 49 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

If the Battery Stack Emulator is stored at temperatures below 5 °C, it must be

warmed up in a 20 °C or warmer environment for 45 minutes before applying power.
 Powering the unit below 5 °C may impact data logging or cause other unexpected
behaviour.

 The Battery Stack Emulator unit should not be shipped while installed in a rack.

5.3. Regulatory Compliance

Standard Name

Electromagnetic Emissions
FCC Class B US Federal electromagnetic radiation limits
EN 55032 Class B European Electromagnetic compliance testing of multimedia equipment
EN 61000-3-2/3-3 European Electromagnetic limits for harmonic current emissions
CISPR 32 Class B International Electromagnetic compatibility of multimedia equipment
Electromagnetic Immunity
EN 55024/CISPR 24 European information technology equipment immunity characteristics
Safety
CSA/EN/IEC/UL 60950-1
Information technology equipment safety general requirements
Compliant
CE Marking Compliant with European Union (EU) directives and regulations

Document ID: NE-PM-014 50 Rev 1.1, 2024-07-16

1.0.0
 Nuvation Energy Battery Stack Emulator - Product Manual

6. Appendix B: List of Supported Equipment

6.1. Supported UPS Devices
The following UPS devices have been tested and are supported with Nuvation Energy products:

▪ APC SRT3000RMXLA
▪ APC BR1000MS
▪ CPS CP1500PFCLCD
▪ CPS CP1350PFCLCD

 Nuvation Energy guarantees product compatability with the above family models.

Excluding the UPS devices mentioned above, following family models are likely to be compatible,
however have not been thoroughly tested by Nuvation Energy:

▪ APC Smart-UPS family models

▪ Other APC Back-UPS family models
▪ CPS CP*PFCLCD family models
▪ CPS OR*PFCRT* family models
▪ CPS BRG*AVRLCD family models
▪ CPS CP*AVRLCD family models
▪ CPS CP*AVR* family models


Nuvation Energy does not guarantee product compatability with the above family
models.

 The Battery Stack Emulator can communicate with UPSes via USB and Ethernet.

Document ID: NE-PM-014 51 Rev 1.1, 2024-07-16

1.0.0