The BS120x Client¶

The primary entrypoint from this library is the Bs120xEnet class.

class bs120xenet.Bs120xEnet(lib: str = 'bs120xenet')[source]¶

Client for communicating with a BS120x unit over Ethernet.

Typical usage example:

with Bs120xEnet() as client:
    client.connect("192.168.1.105", "192.168.1.101", 54321)
    client.set_cell_voltage(0, 1.5)
    client.enable_cell(0)
    # Allow time for cell to settle
    time.sleep(0.1)
    print(f"Cell 0 measured voltage: {client.get_cell_voltage(0)} V")
    client.disconnect()

Parameters:: lib (str) – Name of or path to the BS120xEnet DLL. This parameter is optional. if the DLL is in a discoverable location such as C:/Windows/System32 or /usr/lib, or if it was installed to the default path by the Windows MSI installer, it will be found automatically. If it is not automatically found, pass the path to the file to this function.
Raises:: OSError – An error occurred while finding or loading the low-level library.

init()[source]¶

Initialize the client handle.

Warning

Should not be called directly! Use a ‘with’ block instead.

with Bs120xEnet() as client:
    ...

Raises:: Bs120xEnetError – An error occurred during initialization.

cleanup()[source]¶

Clean up the client handle.

Warning

Should not be called directly! Use a ‘with’ block instead.

with Bs120xEnet() as client:
    ...

connect(interface_ip, device_ip, udp_port, udp_timeout=1000, tcp_port=12345)[source]¶

Opens a connection to the BS120x unit.

Parameters:

interface_ip – The IP address of the local NIC to connect on.
device_ip – The IP address of the BS120x unit to connect to.
udp_port – The UDP data port of the BS120x unit.
udp_timeout – The time in milliseconds to wait to receive data from the BS120x unit. A value of -1 will never time out.
tcp_port – The TCP port to send commands to.

Raises:

Bs120xEnetError – An error occurred while attempting to connect.

disconnect()[source]¶: Closes TCP and UDP connections to the BS120x unit.

set_dio_states(output: list[bool], direction: list[bool])[source]¶

Sets the states and directions of the Bs120x DIO.

Parameters:

output (list[bool]) – list of DIO states. Length must be equal to the number of DIO.
direction (list[bool]) – list of DIO directions. Length must be equal to the number of DIO. TRUE configures the DIO as an output and FALSE configures it as an input.

Raises:

Bs120xEnetError – An error occurred while sending the command.

set_analog_outputs(voltages: list[float])[source]¶

Sets the BS120x analog outputs.

Parameters:: voltages (list[float]) – list of analog output voltages. Length must be equal to the number of analog outputs.
Raises:: Bs120xEnetError – An error occurred while sending the command.

set_op_mode_config(config: Bs120xOpModeConfig)[source]¶

Configures the BS120x operational mode options.

Parameters:: config (Bs120xOpModeConfig) – Bs120xOpModeConfig object containing configuration options.
Raises:: Bs120xEnetError – An error occurred while sending the command.

set_all_cell_currents(isrc: float, isnk: float)[source]¶

Sets the sinking and sourcing current limits for all cells.

Parameters:

isrc (float) – Sourcing current limit to set in Amps.
isnk (float) – Sinking current limit to set in Amps.

Raises:

Bs120xEnetError – An error occurred while sending the command.

set_cell_sink_current(cell: int, isnk: float)[source]¶

Sets the sinking current limit for a single cell.

Parameters:

cell (int) – The cell number to set. Cells are 0-indexed.
isnk (float) – Sinking current limit in Amps.

Raises:

Bs120xEnetError – An error occurred while sending the command.

set_cell_source_current(cell: int, isrc: float)[source]¶

Sets the sourcing current limit for a single cell.

Parameters:

cell (int) – The cell number to set. Cells are 0-indexed.
isrc (float) – The sourcing current limit in Amps.

Raises:

Bs120xEnetError – An error occurred while sending the command.

set_all_cell_voltage(voltage: float)[source]¶

Sets the voltage for all cells.

Parameters:: voltage (float) – The voltage to set.
Raises:: Bs120xEnetError – An error occurred while sending the command.

set_cell_voltage(cell: int, voltage: float)[source]¶

Sets the voltage for a single cell.

Parameters:

cell (int) – The cell number to set. Cells are 0-indexed.
voltage (float) – The voltage to set.

Raises:

Bs120xEnetError – An error occurred while sending the command.

enable_all_cells(enable: bool)[source]¶

Enables or disables all cells.

Parameters:: enable (bool) – A value of TRUE will enable all cells. A value of FALSE will disable all cells.
Raises:: Bs120xEnetError – An error occurred while sending the command.

enable_cell(cell: int, enable: bool)[source]¶

Enables or disables a single cell.

Parameters:

cell (int) – The number of the cell to set.
enable (bool) – The enable state for the cell. A value of TRUE will enable the cell and a value of FALSE will disable it.

Raises:

Bs120xEnetError – An error occurred while sending the command.

get_cell_voltage(cell: int) → float[source]¶

Gets the voltage for a single cell.

Parameters:: cell (int) – The number of the cell to read. Cells are 0-indexed.
Returns:: The voltage read at the cell.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: float

get_all_cell_voltage() → list[float][source]¶

Gets the voltages for all cells.

Returns:: A list of all cell voltages.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: list[float]

get_cell_current(cell: int) → float[source]¶

Gets the current for a single cell.

Parameters:: cell (int) – The number of the cell to read. Cells are 0-indexed.
Returns:: The cell current in Amps.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: float

get_all_cell_current() → list[float][source]¶

Gets the currents for all cells.

Returns:: A list of all cell currents in Amps.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: list[float]

get_analog_input(analog_input: int) → float[source]¶

Gets the voltage of an analog input.

Parameters:: analog_input (int) – The index of the analog input to read. Analog inputs are 0-indexed.
Returns:: The analog input voltage.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: float

get_all_analog_input() → list[float][source]¶

Gets the voltages of all analog inputs.

Returns:: A list of all analog input voltages.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: list[float]

get_dio_state(dio: int) → bool[source]¶

Gets the state of a DIO.

Parameters:: dio (int) – The index of the DIO to read. DIO are 0-indexed.
Returns:: A Boolean value representing the state of the DIO.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: bool

get_all_dio_state() → list[bool][source]¶

Gets the states of all DIO.

Returns:: A list of all DIO states.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: list[bool]

get_status() → Bs120xStatus[source]¶

Gets status information for the unit.

Returns:: A Bs120xStatus object containing health and status information.
Raises:: Bs120xEnetError – An error occurred during readback.
Return type:: Bs120xStatus

get_unit_config() → Bs120xUnitConfig[source]¶

Retrieves unit configuration information.

Note

query_config must be called prior to calling this method.

Returns:: Bs120xUnitConfig object containing unit configuration values.
Raises:: Bs120xEnetError – An error occured while getting configuration.
Return type:: Bs120xUnitConfig

reset()[source]¶

Resets the BS120x unit. disconnect and connect must be called to re-establish a connection with the unit.

Raises:: Bs120xEnetError – An error occurred while sending the command.

set_ip_address(ip: str)[source]¶

Sets the unit’s IP address. The unit must be restarted for changes to take effect.

Parameters:: ip (str) – The new IP address for the unit. The final octet may not be equal to 1 or 255.
Raises:: Bs120xEnetError – An error occurred while sending the command.

query_config()[source]¶

Queries the unit’s configuration information.

Raises:: Bs120xEnetError – An error occurred while sending the command.

set_config_option(opt: str, value)[source]¶

Sets a configuration option by name. Unit must be restarted for changes to take effect.

Parameters:

opt (str) – The option to set.
value – The value to set the option to. Values may be Boolean, integer, float, or string.

Raises:

Bs120xEnetError – An error occurred while setting the configuration option.

enable_udp_data(enable: bool)[source]¶

Enables or disables the UDP data broadcast. Unit must be restarted for changes to take effect.

Parameters:: enable (bool) – A value of TRUE will enable the UDP data broadcast and a value of FALSE will disable it.
Raises:: Bs120xEnetError – An error occurred while setting the configuration option.

set_udp_data_port(port: int)[source]¶

Sets the port for the unit to broadcast data on. Unit must be restarted for changes to take effect

Parameters:: port (int) – The UDP port to broadcast on.
Raises:: Bs120xEnetError – An error occurred while setting the configuration option.

set_udp_data_period(period: int)[source]¶

Sets the interval at which the unit broadcasts data over UDP. Unit must be restarted for changes to take effect.

Parameters:: period (int) – The period in milliseconds at which to broadcast.
Raises:: Bs120xEnetError – An error occurred while setting the configuration option.

set_box_id(id: int)[source]¶

Sets the unit’s Box ID. Unit must be restarted for changes to take effect.

Parameters:: id (int) – The new Box ID for the unit. Valid values are 0-15.
Raises:: Bs120xEnetError – An error occurred while setting the configuration option.

set_can_period(period: int)[source]¶

Sets the interval at which the unit transmits data over CAN. Unit must be restarted for changes to take effect.

Parameters:: period (int) – The period in milliseconds at which to transmit data.
Raises:: Bs120xEnetError – An error occurred while setting the configuration option.

enable_cell_inhibit(enable: bool)[source]¶

Enables or disables the cell inhibit lines.

Parameters:

enables – A value of TRUE will enable cell inhibit lines and a value of FALSE will disable them.
enable (bool)

Raises:

Bs120xEnetError – An error occurred while setting the configuration option.

get_config_value_bool(opt: str) → bool[source]¶

Gets a Boolean configuration option value by name.

Note

query_config must be called prior to calling this method.

Parameters:: opt (str) – The configuration option to read.
Returns:: The configuration option value.
Raises:: Bs120xEnetError – An error occurred while reading the configuration option.
Return type:: bool

get_config_value_int(opt: str) → int[source]¶

Gets an integer configuration option value by name.

Note

query_config must be called prior to calling this method.

Parameters:: opt (str) – The configuration option to read.
Returns:: The configuration option value.
Raises:: Bs120xEnetError – An error occurred while reading the configuration option.
Return type:: int

get_config_value_float(opt: str) → float[source]¶

Getes a floating point configuration option by name.

Note

query_config must be called prior to calling this method.

Parameters:: opt (str) – The configuration option to read.
Returns:: The configuration option value.
Raises:: Bs120xEnetError – An error occurred while reading the configuration option.
Return type:: float

get_config_value_string(opt: str) → str[source]¶

Gets a string configuration option by name.

Note

query_config must be called prior to calling this method.

Parameters:: opt (str) – The configuration option to read.
Returns:: The configuration option value.
Raises:: Bs120xEnetError – An error occurred while reading the configuration option.
Return type:: str