Battery Simulation

Simulate battery behavior to test your DUT’s response to various charge levels, voltages, and protection events.

Import

There are two ways to control battery simulation:

# Option 1: Net-based API (recommended)
from lager import Net, NetType

# Option 2: Dispatcher functions (for simple scripts)
from lager.battery.dispatcher import (
    set_to_battery_mode, set_soc, set_voc, set_capacity,
    enable_battery, disable_battery, state, terminal_voltage, current, esr
)

The lager.battery module’s __init__.py is empty. For dispatcher functions, import directly from lager.battery.dispatcher.

Net API Methods

The Net-based API provides methods that can either get or set values. When called without a value parameter, methods read and print the current value. When called with a value, they set it.

Method	Description
`mode(mode_type)`	Set or read simulation mode (‘static’ or ‘dynamic’)
`set_mode_battery()`	Initialize battery simulation mode
`soc(value)`	Set or read state of charge (0-100%)
`voc(value)`	Set or read open-circuit voltage
`voltage_full(value)`	Set or read full charge voltage
`voltage_empty(value)`	Set or read empty battery voltage
`capacity(value)`	Set or read battery capacity (Ah)
`current_limit(value)`	Set or read current limit (A)
`ovp(value)`	Set or read over-voltage protection threshold
`ocp(value)`	Set or read over-current protection threshold
`model(partnumber)`	Set or read battery model
`enable()`	Enable battery simulation output
`disable()`	Disable battery simulation output
`clear_ovp()`	Clear over-voltage protection fault
`clear_ocp()`	Clear over-current protection fault
`state()`	Print comprehensive battery state
`terminal_voltage()`	Read terminal voltage (returns float)
`current()`	Read current (returns float)
`esr()`	Read ESR (returns float)

Method Reference

`Net.get(name, type=NetType.Battery)`

Get a battery simulation net by name.

from lager import Net, NetType

batt = Net.get('BATT', type=NetType.Battery)

Parameters:

Parameter	Type	Description
`name`	`str`	Name of the battery net
`type`	`NetType`	Must be `NetType.Battery`

Returns: Battery simulation Net instance

`set_mode_battery()`

Initialize the instrument for battery simulation mode.

batt.set_mode_battery()

`mode(mode_type=None)`

Set or read the battery simulation mode.

# Set mode
batt.mode('static')   # Fixed parameters
batt.mode('dynamic')  # Parameters evolve based on battery model

# Read mode (prints current mode)
batt.mode()

Parameters:

Parameter	Type	Description
`mode_type`	`str` or `None`	’static’ or ‘dynamic’. If None, reads current mode.

`soc(value=None)`

Set or read the state of charge.

# Set SOC
batt.soc(80)  # Set to 80%

# Read SOC (prints current value)
batt.soc()

Parameters:

Parameter	Type	Description
`value`	`float` or `None`	State of charge (0-100). If None, reads current value.

`voc(value=None)`

Set or read the open-circuit voltage.

# Set VOC
batt.voc(3.7)  # Set to 3.7V

# Read VOC (prints current value)
batt.voc()

Parameters:

Parameter	Type	Description
`value`	`float` or `None`	Voltage in volts. If None, reads current value.

`voltage_full(value=None)` / `voltage_empty(value=None)`

Set or read the full/empty battery voltages.

# Set voltages
batt.voltage_full(4.2)   # Full charge at 4.2V
batt.voltage_empty(3.0)  # Empty at 3.0V

# Read voltages
batt.voltage_full()
batt.voltage_empty()

`capacity(value=None)`

Set or read the battery capacity.

# Set capacity
batt.capacity(2.5)  # 2.5 Ah

# Read capacity
batt.capacity()

`current_limit(value=None)`

Set or read the maximum charge/discharge current.

# Set current limit
batt.current_limit(1.5)  # 1.5A max

# Read current limit
batt.current_limit()

`ovp(value=None)` / `ocp(value=None)`

Set or read protection thresholds.

# Set protection thresholds
batt.ovp(4.4)  # Over-voltage protection at 4.4V
batt.ocp(2.0)  # Over-current protection at 2.0A

# Read thresholds
batt.ovp()
batt.ocp()

`model(partnumber=None)`

Set or read the battery model.

# Set model
batt.model('18650')

# Read current model
batt.model()

Keithley 2281S supported model aliases: ‘18650’, ‘liion’, ‘nimh’, ‘nicd’, ‘lead-acid’

`enable()` / `disable()`

Enable or disable battery simulation output.

batt.enable()   # Enable output
batt.disable()  # Disable output

`clear_ovp()` / `clear_ocp()`

Clear protection faults.

batt.clear_ovp()  # Clear over-voltage fault
batt.clear_ocp()  # Clear over-current fault

`state()`

Print comprehensive battery simulator state.

batt.state()
# Prints: terminal voltage, current, ESR, SOC, VOC, capacity, protection status

`terminal_voltage()` / `current()` / `esr()`

Read measurements (return values, don’t print).

v = batt.terminal_voltage()  # Returns terminal voltage in volts
i = batt.current()           # Returns current in amps
r = batt.esr()               # Returns ESR in ohms

print(f"Voltage: {v}V, Current: {i}A, ESR: {r} ohms")

Returns: float - Measurement value

Examples

Basic Battery Simulation

from lager import Net, NetType

# Get battery net
batt = Net.get('BATT', type=NetType.Battery)

# Initialize and configure
batt.set_mode_battery()
batt.mode('static')
batt.voc(3.7)
batt.capacity(2.5)

# Enable output
batt.enable()

# Read state
batt.state()
print(f"Terminal voltage: {batt.terminal_voltage()}V")

# Disable when done
batt.disable()

Simulate Battery Discharge

from lager import Net, NetType
import time

batt = Net.get('BATT', type=NetType.Battery)
batt.set_mode_battery()

# Configure battery parameters
batt.mode('static')
batt.voc(4.2)
batt.voltage_full(4.2)
batt.voltage_empty(3.0)
batt.capacity(3.0)
batt.soc(100)  # Start fully charged

batt.enable()

# Simulate discharge by stepping SOC
for soc_level in [100, 75, 50, 25, 10]:
    batt.soc(soc_level)
    time.sleep(0.5)
    v = batt.terminal_voltage()
    print(f"SOC: {soc_level}%, Terminal: {v:.2f}V")

batt.disable()

With Protection Monitoring

from lager import Net, NetType

batt = Net.get('BATT', type=NetType.Battery)
batt.set_mode_battery()

# Configure with protection
batt.voc(3.7)
batt.capacity(2.0)
batt.ovp(4.3)  # Over-voltage at 4.3V
batt.ocp(2.0)  # Over-current at 2.0A

batt.enable()

# Monitor
print(f"Voltage: {batt.terminal_voltage():.2f}V")
print(f"Current: {batt.current():.3f}A")

# Clear any faults if needed
batt.clear_ovp()
batt.clear_ocp()

batt.disable()

Supported Hardware

Manufacturer	Model	Features
Keithley	2281S	Battery simulation, dynamic modeling

Dispatcher Functions

For simple scripts, you can use dispatcher functions that take net names directly:

Configuration Functions

from lager.battery.dispatcher import (
    set_to_battery_mode, set_soc, set_voc, set_volt_full, set_volt_empty,
    set_capacity, set_current_limit, set_ovp, set_ocp, set_model
)

# Initialize battery mode
set_to_battery_mode('BATT')

# Set battery parameters
set_soc('BATT', 80)            # 80% state of charge
set_voc('BATT', 3.7)           # 3.7V open-circuit voltage
set_volt_full('BATT', 4.2)     # Full charge voltage
set_volt_empty('BATT', 3.0)    # Empty voltage
set_capacity('BATT', 2.5)      # 2.5Ah capacity
set_current_limit('BATT', 1.5) # 1.5A current limit

# Protection thresholds
set_ovp('BATT', 4.3)           # Over-voltage protection at 4.3V
set_ocp('BATT', 2.0)           # Over-current protection at 2.0A

# Set battery model (if supported by hardware)
set_model('BATT', '18650')

Enable/Disable Functions

from lager.battery.dispatcher import enable_battery, disable_battery

enable_battery('BATT')   # Enable battery output
disable_battery('BATT')  # Disable battery output

State and Measurement Functions

from lager.battery.dispatcher import state, terminal_voltage, current, esr

# Print comprehensive state
state('BATT')

# Read individual measurements
v = terminal_voltage('BATT')  # Returns terminal voltage
i = current('BATT')           # Returns current draw
r = esr('BATT')               # Returns equivalent series resistance

Clear Functions

from lager.battery.dispatcher import clear, clear_ovp, clear_ocp

clear('BATT')      # Clear all protection faults
clear_ovp('BATT')  # Clear over-voltage protection fault
clear_ocp('BATT')  # Clear over-current protection fault

Dispatcher Functions Reference

Function	Description
`set_to_battery_mode(netname)`	Initialize battery simulation mode
`set_soc(netname, value)`	Set state of charge (0-100%)
`set_voc(netname, value)`	Set open-circuit voltage (V)
`set_volt_full(netname, value)`	Set full charge voltage (V)
`set_volt_empty(netname, value)`	Set empty voltage (V)
`set_capacity(netname, value)`	Set capacity (Ah)
`set_current_limit(netname, value)`	Set current limit (A)
`set_ovp(netname, value)`	Set over-voltage protection (V)
`set_ocp(netname, value)`	Set over-current protection (A)
`set_model(netname, partnumber)`	Set battery model
`enable_battery(netname)`	Enable battery output
`disable_battery(netname)`	Disable battery output
`state(netname)`	Print comprehensive state
`terminal_voltage(netname)`	Read terminal voltage
`current(netname)`	Read current
`esr(netname)`	Read ESR
`clear(netname)`	Clear all protection faults
`clear_ovp(netname)`	Clear OVP fault
`clear_ocp(netname)`	Clear OCP fault

Notes

Call set_mode_battery() before using other battery methods
Methods like soc(), voc(), etc. can get or set values depending on whether a value is passed
Use mode('static') for fixed parameters, mode('dynamic') for evolving behavior
Always call disable() when finished
terminal_voltage(), current(), and esr() return values (for use in code)
state() prints values (for debugging)
Protection thresholds help prevent damage to your DUT

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Import

Net API Methods

Method Reference

`Net.get(name, type=NetType.Battery)`

`set_mode_battery()`

`mode(mode_type=None)`

`soc(value=None)`

`voc(value=None)`

`voltage_full(value=None)` / `voltage_empty(value=None)`

`capacity(value=None)`

`current_limit(value=None)`

`ovp(value=None)` / `ocp(value=None)`

`model(partnumber=None)`

`enable()` / `disable()`

`clear_ovp()` / `clear_ocp()`

`state()`

`terminal_voltage()` / `current()` / `esr()`

Examples

Basic Battery Simulation

Simulate Battery Discharge

With Protection Monitoring

Supported Hardware

Dispatcher Functions

Configuration Functions

Enable/Disable Functions

State and Measurement Functions

Clear Functions

Dispatcher Functions Reference

Notes

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

​Import

​Net API Methods

​Method Reference

​Net.get(name, type=NetType.Battery)

​set_mode_battery()

​mode(mode_type=None)

​soc(value=None)

​voc(value=None)

​voltage_full(value=None) / voltage_empty(value=None)

​capacity(value=None)

​current_limit(value=None)

​ovp(value=None) / ocp(value=None)

​model(partnumber=None)

​enable() / disable()

​clear_ovp() / clear_ocp()

​state()

​terminal_voltage() / current() / esr()

​Examples

​Basic Battery Simulation

​Simulate Battery Discharge

​With Protection Monitoring

​Supported Hardware

​Dispatcher Functions

​Configuration Functions

​Enable/Disable Functions

​State and Measurement Functions

​Clear Functions

​Dispatcher Functions Reference

​Notes

Import

Net API Methods

Method Reference

`Net.get(name, type=NetType.Battery)`

`set_mode_battery()`

`mode(mode_type=None)`

`soc(value=None)`

`voc(value=None)`

`voltage_full(value=None)` / `voltage_empty(value=None)`

`capacity(value=None)`

`current_limit(value=None)`

`ovp(value=None)` / `ocp(value=None)`

`model(partnumber=None)`

`enable()` / `disable()`

`clear_ovp()` / `clear_ocp()`

`state()`

`terminal_voltage()` / `current()` / `esr()`

Examples

Basic Battery Simulation

Simulate Battery Discharge

With Protection Monitoring

Supported Hardware

Dispatcher Functions

Configuration Functions

Enable/Disable Functions

State and Measurement Functions

Clear Functions

Dispatcher Functions Reference

Notes