e3dc package
Module contents
E3DC Library for Python.
Python class to connect to an E3/DC system. Copyright 2017-2023 Francesco Santini <francesco.santini@gmail.com> and collaborators. See AUTHORS file for full copyright. Licensed under a MIT license. See LICENSE for details.
- exception e3dc.AuthenticationError[source]
Bases:
ExceptionClass for Authentication Error Exception.
- exception e3dc.CommunicationError[source]
Bases:
ExceptionClass for Communication Error Exception.
- class e3dc.E3DC(connectType: int, **kwargs: Any)[source]
Bases:
objectA class describing an E3DC system.
- CONNECT_LOCAL = 1
- CONNECT_WEB = 2
- get_batteries(keepAlive: bool = False)[source]
Scans for installed batteries via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
- List containing the found batteries as follows.:
- [
{‘index’: 0, “dcbs”: 3}
]
- Return type:
list[dict]
- get_batteries_data(batteries: list[dict[str, Any]] | None = None, keepAlive: bool = False)[source]
Polls the batteries data via rscp protocol.
- Parameters:
batteries (dict | None) – batteries dict
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Returns a list of batteries data
- Return type:
list[dict]
- get_battery_data(batIndex: int | None = None, dcbs: list[int] | None = None, keepAlive: bool = False)[source]
Polls the battery data via rscp protocol.
- Parameters:
batIndex (int | None) – battery index
dcbs (list | None) – dcb list
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the battery data structured as follows:
{ "asoc": <absolute state of charge>, "chargeCycles": <charge cycles>, "current": <current>, "dcbCount": <dcb count>, "dcbs": {0: { "current": <current>, "currentAvg30s": <current average 30s>, "cycleCount": <cycle count>, "designCapacity": <design capacity>, "designVoltage": <design voltage>, "deviceName": <device name>, "endOfDischarge": <end of discharge>, "error": <error>, "fullChargeCapacity": <full charge capacity>, "fwVersion": <firmware version>, "manufactureDate": <manufacture date>, "manufactureName": <manufacture name>, "maxChargeCurrent": <max charge current>, "maxChargeTemperature": <max charge temperature>, "maxChargeVoltage": <max charge voltage>, "maxDischargeCurrent": <max discharge current>, "minChargeTemperature": <min charge temperature>, "parallelCellCount": <parallel cell count>, "sensorCount": <sensor countt>, "seriesCellCount": <cells in series count>, "pcbVersion": <pcb version>, "protocolVersion": <protocol version>, "remainingCapacity": <remaining capacity>, "serialCode": <serial code>, "serialNo": <serial no>, "soc": <state of charge>, "soh": <state of health>, "status": <status>, "temperatures": <temperatures>, "voltage": <voltage>, "voltageAvg30s": <voltage average 30s>, "voltages": <voltages>, "warning": <warning> } }, "designCapacity": <design capacity>, "deviceConnected": <device connected>, "deviceInService": <device in service>, "deviceName": <device name>, "deviceWorking": <device working>, "eodVoltage": <eod voltage>, "errorCode": <error code>, "fcc": <full charge capacity>, "index": <batIndex>, "maxBatVoltage": <max battery voltage>, "maxChargeCurrent": <max charge current>, "maxDischargeCurrent": <max discharge current>, "maxDcbCellTemp": <max DCB cell temp>, "minDcbCellTemp": <min DCB cell temp>, "moduleVoltage": <module voltage>, "rc": <rc>, "readyForShutdown": <ready for shutdown>, "rsoc": <relative state of charge>, "rsocReal": <real relative state of charge>, "statusCode": <status code>, "terminalVoltage": <terminal voltage>, "totalUseTime": <total use time>, "totalDischargeTime": <total discharge time>, "trainingMode": <training mode>, "usuableCapacity": <usuable capacity> "usuableRemainingCapacity": <usuable remaining capacity> }
- Return type:
dict
- get_db_data(startDate: date = datetime.date(2025, 12, 1), timespan: Literal['DAY', 'MONTH', 'YEAR'] = 'DAY', keepAlive: bool = False)[source]
Reads DB data and summed up values for the given timespan via rscp protocol.
- Parameters:
startDate (datetime.date) – start date for timespan, default today. Depending on timespan given, the startDate is automatically adjusted to the first of the month or the year
timespan (str) – string specifying the time span [“DAY”, “MONTH”, “YEAR”]
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the stored db information structured as follows:
{ "autarky": <autarky in the period in %>, "bat_power_in": <power entering battery, charging>, "bat_power_out": <power leaving battery, discharging>, "consumed_production": <power directly consumed in %>, "consumption": <self consumed power>, "grid_power_in": <power sent into the grid (production)>, "grid_power_out": <power taken from the grid (consumption)>, "startDate": <date from which db data is fetched of>, "stateOfCharge": <battery charge level in %>, "solarProduction": <power production>, "pm0Production": <power production>, "pm1Production": <power production>, "timespan": <timespan of which db data is collected>, "timespanSeconds": <timespan in seconds of which db data is collected> }
- Return type:
dict
- get_db_data_timestamp(startTimestamp: int, timespanSeconds: int, keepAlive: bool = False)[source]
Reads DB data and summed up values for the given timespan via rscp protocol.
- Parameters:
startTimestamp (int) – UNIX timestampt from where the db data should be collected
timespanSeconds (int) – number of seconds for which the data should be collected
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the stored db information structured as follows:
{ "autarky": <autarky in the period in %>, "bat_power_in": <power entering battery, charging>, "bat_power_out": <power leaving battery, discharging>, "consumed_production": <power directly consumed in %>, "consumption": <self consumed power>, "grid_power_in": <power sent into the grid (production)>, "grid_power_out": <power taken from the grid (consumption)>, "startTimestamp": <timestamp from which db data is fetched of>, "stateOfCharge": <battery charge level in %>, "solarProduction": <power production>, "pm0Production": <power production>, "pm1Production": <power production>, "timespanSeconds": <timespan in seconds of which db data is collected> }
- Return type:
dict
- get_idle_periods(keepAlive: bool = False)[source]
Poll via rscp protocol to get idle periods.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the idle periods structured as follows:
{ "idleCharge": [ { "day": <the week day from 0 to 6>, "start": ( <hour from 0 to 23>, <minute from 0 to 59> ), "end": ( <hour from 0 to 23>, <minute from 0 to 59> ), "active": <boolean of state> } ], "idleDischarge": [ { "day": <the week day from 0 to 6>, "start": ( <hour from 0 to 23>, <minute from 0 to 59> ), "end": ( <hour from 0 to 23>, <minute from 0 to 59> ), "active": <boolean of state> } ] }
- Return type:
dict
- get_power_settings(keepAlive: bool = False)[source]
Polls the power settings via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the power settings structured as follows:
{ "discharge_start_power": <minimum power requested to enable discharge>, "maxChargePower": <maximum charge power dependent on E3DC model>, "maxDischargePower": <maximum discharge power dependent on E3DC model>, "powerSaveEnabled": <status if power save is enabled>, "powerLimitsUsed": <status if power limites are enabled>, "weatherForecastMode": <Weather Forcast Mode>, "weatherRegulatedChargeEnabled": <status if weather regulated charge is enabled> }
- Return type:
dict
- get_powermeter_data(pmIndex: int | None = None, keepAlive: bool = False)[source]
Polls the power meter data via rscp protocol.
- Parameters:
pmIndex (int | None) – power meter index
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the power data structured as follows:
{ "activePhases": <active phases>, "energy": { "L1": <L1 energy>, "L2": <L2 energy>, "L3": <L3 energy> }, "index": <pm index>, "maxPhasePower": <max phase power>, "mode": <mode>, "power": { "L1": <L1 power>, "L2": <L2 power>, "L3": <L3 power> }, "type": <type>, "voltage": { "L1": <L1 voltage>, "L2": <L1 voltage>, "L3": <L1 voltage> } }
- Return type:
dict
- get_powermeters(keepAlive: bool = False)[source]
Scans for installed power meters via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
List containing the found powermeters as follows.:
[ {'index': 0, 'type': 1, 'typeName': 'PM_TYPE_ROOT'}, {'index': 1, 'type': 4, 'typeName': 'PM_TYPE_ADDITIONAL_CONSUMPTION'} ]
- Return type:
list[dict]
- get_powermeters_data(powermeters: list[dict[str, Any]] | None = None, keepAlive: bool = False)[source]
Polls the powermeters data via rscp protocol.
- Parameters:
powermeters (dict | None) – powermeters dict
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Returns a list of powermeters data
- Return type:
list[dict]
- get_pvi_data(pviIndex: int | None = None, strings: list[int] | None = None, phases: list[int] | None = None, keepAlive: bool = False)[source]
Polls the inverter data via rscp protocol.
- Parameters:
pviIndex (int) – pv inverter index
strings (list | None) – string list
phases (list | None) – phase list
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the pvi data structured as follows:
{ "acMaxApparentPower": <max apparent AC power>, "cosPhi": { "active": <active>, "value": <value>, "excited": <excited> }, "deviceState": { "connected": <connected>, "working": <working>, "inService": <in service> }, "frequency": { "under": <frequency under>, "over": <frequency over> }, "index": <pviIndex>, "lastError": <last error>, "maxPhaseCount": <max phase count>, "maxStringCount": <max string count>, "onGrid": <on grid>, "phases": { 0: { "power": <power>, "voltage": <voltage>, "current": <current>, "apparentPower": <apparent power>, "reactivePower": <reactive power>, "energyAll": <energy all>, "energyGridConsumption": <energy grid consumption> } }, "powerMode": <power mode>, "serialNumber": <serial number>, "state": <state>, "strings": { 0: { "power": <power>, "voltage": <voltage>, "current": <current>, "energyAll": <energy all> } }, "systemMode": <system mode>, "temperature": { "max": <max temperature>, "min": <min temperature>, "values": [<value>,<value>], }, "type": <type>, "version": <version>, "voltageMonitoring": { "thresholdTop": <voltage threshold top>, "thresholdBottom": <voltage threshold bottom>, "slopeUp": <voltage slope up>, "slopeDown": <voltage slope down>, } }
- Return type:
dict
- get_pvis(keepAlive: bool = False)[source]
Scans for installed pvis via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
- List containing the found pvis as follows.::
- [
{‘index’: 0, “phases”: 3, “strings”: 2, ‘type’: 3, ‘typeName’: ‘PVI_TYPE_E3DC_E’}
]
- Return type:
list[dict]
- get_pvis_data(pvis: list[dict[str, Any]] | None = None, keepAlive: bool = False)[source]
Polls the inverters data via rscp protocol.
- Parameters:
pvis (dict | None) – pvis dict
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Returns a list of pvi data
- Return type:
list[dict]
- get_system_info(keepAlive: bool = False)[source]
Polls the system info via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the system info structured as follows:
{ "deratePercent": <% of installed peak power the feed in will be derated>, "deratePower": <W at which the feed in will be derated>, "externalSourceAvailable": <wether an additional power meter is installed>, "installedBatteryCapacity": <installed Battery Capacity in W>, "installedPeakPower": <installed peak power in W>, "maxAcPower": <max AC power>, "macAddress": <the mac address>, "maxBatChargePower": <max Battery charge power>, "maxBatDischargePower": <max Battery discharge power>, "model": <model connected to>, "release": <release version>, "serial": <serial number of the system> }
- Return type:
dict
- get_system_info_static(keepAlive: bool = False)[source]
Polls the static system info via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- get_system_status(keepAlive: bool = False)[source]
Polls the system status via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the system status structured as follows:
{ "dcdcAlive": <dcdc alive>, "powerMeterAlive": <power meter alive>, "batteryModuleAlive": <battery module alive>, "pvModuleAlive": <pv module alive>, "pvInverterInited": <pv inverter inited>, "serverConnectionAlive": <server connection alive>, "pvDerated": <pv derated due to deratePower limit reached>, "emsAlive": <emd alive>, "acModeBlocked": <ad mode blocked>, "sysConfChecked": <sys conf checked>, "emergencyPowerStarted": <emergency power started>, "emergencyPowerOverride": <emergency power override>, "wallBoxAlive": <wall box alive>, "powerSaveEnabled": <power save enabled>, "chargeIdlePeriodActive": <charge idle period active>, "dischargeIdlePeriodActive": <discharge idle period active>, "waitForWeatherBreakthrough": <wait for weather breakthrouhgh>, "rescueBatteryEnabled": <rescue battery enabled>, "emergencyReserveReached": <emergencey reserve reached>, "socSyncRequested": <soc sync requested> }
- Return type:
dict
- get_wallbox_data(wbIndex: int = 0, keepAlive: bool = False)[source]
Polls the wallbox status via rscp protocol locally.
- Parameters:
wbIndex (int | None) – Index of the wallbox to poll data for
keepAlive (bool | None) – True to keep connection alive
- Returns:
Dictionary containing the wallbox status structured as follows:
{ "appSoftware": <version of the app>, "batteryToCar": <true if the wallbox may use the battery, otherwise false>, "chargingActive": <true if charging is currently active, otherwise false>, "chargingCanceled": <true if charging was manually canceled, otherwise false>, "consumptionNet": <power currently consumed by the wallbox, provided by the grid in watts>, "consumptionSun": <power currently consumed by the wallbox, provided by the solar panels in watts>, "energyAll": <total consumed energy this month in watthours>, "energyNet": <consumed net energy this month in watthours>, "energySun": <consumed solar energy this month in watthours>, "index": <index of the requested wallbox>, "keyState": <state of the key switch at the wallbox>, "maxChargeCurrent": <configured maximum charge current in A>, "phases": <number of phases used for charging>, "schukoOn": <true if the connected schuko of the wallbox is on, otherwise false>, "soc": <state of charge>, "sunModeOn": <true if sun-only-mode is active, false if mixed mode is active> }
- Return type:
dict
- poll(keepAlive: bool = False)[source]
Polls via rscp protocol.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
Dictionary containing the condensed status information structured as follows:
{ "autarky": <autarky in %>, "consumption": { "battery": <power entering battery (positive: charging, negative: discharging)>, "house": <house consumption>, "wallbox": <wallbox consumption> } "production": { "solar" : <production from solar in W>, "add" : <additional external power in W>, "grid" : <absorption from grid in W> } "stateOfCharge": <battery charge status in %>, "selfConsumption": <self consumed power in %>, "time": <datetime object containing the timestamp> }
- Return type:
dict
- poll_switches(keepAlive: bool = False)[source]
This function uses the RSCP interface to poll the switch status.
- Parameters:
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
list of the switches:
[ { "id": <id>, "type": <type>, "name": <name>, "status": <status> } ]
- Return type:
list[dict]
- sendRequest(request: tuple[str | int | RscpTag, str | int | RscpType, Any], retries: int = 3, keepAlive: bool = False) tuple[str | int | RscpTag, str | int | RscpType, Any][source]
This function uses the RSCP interface to make a request.
Does make retries in case of exceptions like Socket.Error
- Parameters:
request – the request to send
retries (int) – number of retries. Defaults to 3.
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
An object with the received data
- Raises:
e3dc.AuthenticationError – login error
e3dc.SendError – if retries are reached
- sendRequestTag(tag: str | int | RscpTag, retries: int = 3, keepAlive: bool = False)[source]
This function uses the RSCP interface to make a request for a single tag.
Does make retries in case of exceptions like Socket.Error
- Parameters:
tag (str) – the request to send
retries (int) – number of retries. Defaults to 3.
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
An object with the received data
- Raises:
e3dc.AuthenticationError – login error
e3dc.SendError – if retries are reached
- sendWallboxRequest(dataIndex: int, value: int, request: RscpTag = RscpTag.WB_REQ_SET_EXTERN, wbIndex: int = 0, keepAlive: bool = False) tuple[str | int | RscpTag, str | int | RscpType, Any][source]
Sends a low-level request with WB_EXTERN_DATA to the wallbox via rscp protocol locally.
- Parameters:
dataIndex (int) – byte index in the WB_EXTERN_DATA array (values: 0-5)
value (int) – byte value to be set in the WB_EXTERN_DATA array at the given index
request (RscpTag | None) – request identifier (WB_REQ_SET_EXTERN, WB_REQ_SET_PARAM_1 or WB_REQ_SET_PARAM_2),
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
An object with the received data
- sendWallboxSetRequest(dataIndex: int, value: int, request: RscpTag = RscpTag.WB_REQ_SET_EXTERN, wbIndex: int = 0, keepAlive: bool = False) bool[source]
Sends a low-level set request with WB_EXTERN_DATA to the wallbox via rscp protocol locally and evaluates the response.
- Parameters:
dataIndex (int) – byte index in the WB_EXTERN_DATA array (values: 0-5)
value (int) – byte value to be set in the WB_EXTERN_DATA array at the given index
request (RscpTag | None) – request identifier (WB_REQ_SET_EXTERN, WB_REQ_SET_PARAM_1 or WB_REQ_SET_PARAM_2),
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success False if error
- set_battery_to_car_mode(enabled: bool, keepAlive: bool = False)[source]
Sets whether the wallbox may use the battery.
- Parameters:
enabled (bool) – True to enable charging the car using the battery
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success False if error
- set_idle_periods(idlePeriods: dict[str, list[dict[str, Any]]], keepAlive: bool = False)[source]
Set idle periods via rscp protocol.
- Parameters:
idlePeriods (dict) –
Dictionary containing one or many idle periods:
{ "idleCharge": [ { "day": <the week day from 0 to 6>, "start": ( <hour from 0 to 23>, <minute from 0 to 59> ), "end": ( <hour from 0 to 23>, <minute from 0 to 59> ), "active": <boolean of state> } ], "idleDischarge": [ { "day": <the week day from 0 to 6>, "start": ( <hour from 0 to 23>, <minute from 0 to 59> ), "end": ( <hour from 0 to 23>, <minute from 0 to 59> ), "active": <boolean of state> } ] }
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
True if success False if error
- set_power_limits(enable: bool, max_charge: int | None = None, max_discharge: int | None = None, discharge_start: int | None = None, keepAlive: bool = False)[source]
Setting the SmartPower power limits via rscp protocol.
- Parameters:
enable (bool) – True/False
max_charge (int | None) – maximum charge power
max_discharge (int | None) – maximum discharge power
discharge_start (int | None) – power where discharged is started
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
0 if success -1 if error 1 if one value is nonoptimal
- set_powersave(enable: bool, keepAlive: bool = False)[source]
Setting the SmartPower power save via rscp protocol.
- Parameters:
enable (bool) – True/False
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
0 if success -1 if error
- set_switch_onoff(switchID: int, value: Literal['on', 'off'], keepAlive: bool = False)[source]
This function uses the RSCP interface to turn a switch on or off.
- Parameters:
switchID (int) – id of the switch
value (str) – value
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
True/False
- set_wallbox_max_charge_current(max_charge_current: int, wbIndex: int = 0, keepAlive: bool = False) bool[source]
Sets the maximum charge current of the wallbox via rscp protocol locally.
- Parameters:
max_charge_current (int) – maximum allowed charge current in A
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success (wallbox has understood the request, but might have clipped the value) False if error
- set_wallbox_schuko(on: bool, wbIndex: int = 0, keepAlive: bool = False) bool[source]
Sets the Schuko of the wallbox via rscp protocol locally.
- Parameters:
on (bool) – True to activate the Schuko, otherwise false
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success (wallbox has understood the request, but might have ignored an unsupported value) False if error
- set_wallbox_sunmode(enable: bool, wbIndex: int = 0, keepAlive: bool = False) bool[source]
Sets the sun mode of the wallbox via rscp protocol locally.
- Parameters:
enable (bool) – True to enable sun mode, otherwise false,
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success False if error
- set_weather_regulated_charge(enable: bool, keepAlive: bool = False)[source]
Setting the SmartCharge weather regulated charge via rscp protocol.
- Parameters:
enable (bool) – True/False
keepAlive (bool) – True to keep connection alive. Defaults to False.
- Returns:
0 if success -1 if error
- toggle_wallbox_charging(wbIndex: int = 0, keepAlive: bool = False) bool[source]
Toggles charging of the wallbox via rscp protocol locally.
- Parameters:
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success False if error
- toggle_wallbox_phases(wbIndex: int = 0, keepAlive: bool = False) bool[source]
Toggles the number of phases used for charging by the wallbox between 1 and 3 via rscp protocol locally.
- Parameters:
wbIndex (int | None) – index of the requested wallbox,
keepAlive (bool | None) – True to keep connection alive
- Returns:
True if success False if error
- exception e3dc.RSCPAuthenticationError[source]
Bases:
ExceptionClass for RSCP Authentication Error Exception.
- exception e3dc.RSCPKeyError[source]
Bases:
ExceptionClass for RSCP Encryption Key Error Exception.
- exception e3dc.RequestTimeoutError[source]
Bases:
ExceptionClass for Request Timeout Error Exception.
- e3dc.set_rscp_debug(debug: bool)
Turns debug on/off.
- Parameters:
debug (bool) – the status
- Returns:
Nothing