Lektri.co Load Balancing Public RPC list

1. Commands format.

All commands follow the Request/Response JSON-RPC 2.0 format specification: JSON-RPC specs.

2. Revisions.

Version	Date	Comments
1.0	25.02.2025	Initial release.

3. Error codes.

Error code	Error description
0	No error. Everything was successful.
-1	General fail. No details.
-2	JSON request format error. Usually means that a not all keys were found.
-3	Key value length error. Applicable to keys of string type which should be of a fixed length.
-4	Key value range error. The key value is out of range. Applicable to keys of integer type.
-5	Error key format. Example: setting integer value to a boolean key.
-6	Unknown key error.
-7	Prohibited action error.

4. Application configuration keys.

Key name	Key type	Default value	Accepted values	Description
breaker_rating	integer	32	10 - 1000	Breaker rating.
load_balancing_mode	integer	0	0 - 3	Load balancing mode. Values: 0 - Load balancing disabled1 - Power mode (keep charging as long as the breaker rating is not exceeded) 2 - Hybrid mode 3 - Green mode. 4 - Power share mode.
lb_meter_type	string	"Off"
lb_pv_minimum_current	integer	6	1-6	Minimum exported current at which the charging process is still allowed.
reverse_current	boolean	false	true/false	Reverse current sign.
lb_hybrid_current	integer	6	6 - 32	Minimum current in Hybrid mode.
lb_meter_offline_current	integer	6	6 - 32	Charging current when energy meter is offline.
car_minimum_current	integer	6	6 - 10	Car minimum current.
green_forced_single_phase	boolean	false	true/false	Force single phase charging in Green mode.
hybrid_forced_single_phase	boolean	false	true/false	Force single phase charging in Hybrid mode.

5. Energy meter list info.

5.1 Supported energy meter list

5.1.0 Off

Required parameters

No parameters required.

5.1.1 Onboard

Required parameters

Available only for M2W. No parameters required.

5.1.2 Alfa by Sinapsi

Required parameters

{
  "ip": "string",
  "hostname": "string"
}

It is possible to set only ip or hostname, however, it is recommended to set both parameters, so the communication starts as soon as possible.

ip - A string containing IP address. Example: 192.168.0.1

hostname - A string with meter hostname. Example: shellyem-8CAAB505B323

5.1.3 SolarEdge inverter

Required parameters

{
  "ip": "string",
  "hostname": "string",
  "modbus_id": "integer",
  "port": "integer"
}

It is possible to set only ip or hostname, however, it is recommended to set both parameters, so the communication starts as soon as possible.

ip - A string containing IP address. Example: 192.168.0.1

hostname - A string with meter hostname. Example: shellyem-8CAAB505B323

modbus_id - ModBus ID.

port - TCP port for ModBus communication.

5.1.4 Shelly EM

Required parameters

{
  "ip": "string",
  "hostname": "string"
}

It is possible to set only ip or hostname, however, it is recommended to set both parameters, so the communication starts as soon as possible.

ip - A string containing IP address. Example: 192.168.0.1

hostname - A string with meter hostname. Example: shellyem-8CAAB505B323

5.1.5 Shelly 3EM

Required parameters

{
  "ip": "string",
  "hostname": "string"
}

It is possible to set only ip or hostname, however, it is recommended to set both parameters, so the communication starts as soon as possible.

ip - A string containing IP address. Example: 192.168.0.1

hostname - A string with meter hostname. Example: shellyem-8CAAB505B323

5.1.6 Shelly EM PRO

Required parameters

{
  "ip": "string",
  "hostname": "string"
}

It is possible to set only ip or hostname, however, it is recommended to set both parameters, so the communication starts as soon as possible.

ip - A string containing IP address. Example: 192.168.0.1

hostname - A string with meter hostname. Example: shellyem-8CAAB505B323

5.1.7 Shelly 3EM PRO

{
  "ip": "string",
  "hostname": "string"
}

It is possible to set only ip or hostname, however, it is recommended to set both parameters, so the communication starts as soon as possible.

ip - A string containing IP address. Example: 192.168.0.1

hostname - A string with meter hostname. Example: shellyem-8CAAB505B323

6. Commands

6.1 Get load balancing info

Method	Description
Load_balancing_info.Get	Get load balancing info.

Request params format

No parameters.

Response params format

{
  "lib_version": "string",
  "free_heap": "integer",
  "lb_mode": "integer",
  "chargers_number": "integer",
  "compute_mode": "integer",
  "meter_phases": "integer",
  "total_exported_current": "double",
  "phase_exported_current": "double",
  "limit_reason": ["integer", "integer", "integer"],
  "active_chargers": ["integer", "integer", "integer"],
  "active_total": "integer",
  "current": ["double", "double", "double"],
  "available_current": ["double", "double", "double"],
  "total_chargers_current": ["double", "double", "double"],
  "computed_charging_current": ["integer", "integer", "integer"],
  "exported_current": ["double", "double", "double"],
  "pause_requested": ["boolean", "boolean", "boolean"],
  "chargers_list": [
    {
      "id": "string",
      "ip": "string",
      "type": "integer",
      "connected_phase": "integer",
      "em_current": "integer",
      "charger_em_current": "integer",
      "current": ["double", "double", "double"],
      "state": "integer",
      "em_current_updated": "boolean",
      "is_online": "boolean",
      "is_paused": "boolean",
      "voltage": ["double", "double", "double"],
      "instant_power": "double",
      "session_id": "integer",
      "sched_lb_mode": "integer",
      "obc_type": "integer",
      "potential_relay_mode": "integer",
      "charging_mode": "integer",
      "em_relay_mode": "integer"
    },
    //...
    {
      //...
    }
  ]
}

lib_version - LB library version.

free_heap - Available heap memory.

lb_mode - Load balancing mode. Values:

• 0 - Disabled.
• 1 - Power mode.
• 2 - Hybrid mode.
• 3 - Green mode.

chargers_number - Number of chargers in the list.

compute_mode - Algorithm compute mode. Values:

• 0 - Single phase compute mode - algo computed everything in single phase mode, making TRI charging in single phase mode.
• 1 - Auto compute mode - algo keeps track of each type of charger (single/three phase), and distributes accordingly.

meter_phases - Number of phases the energy meter has.

total_exported_current - Total exported current in Amps.

phase_exported_current - Computed distributed exported current per phase in Amps

limit_reason - Limit reason. Values:

• 0 - Limited because there are no active chargers.
• 1 - Limited by the available current under breaker rating.
• 2 - Charger current under resume current.
• 3 - Forbidden to commute from single to auto.
• 4 - When in Hybrid mode exporting less than 6 Amps.
• 5 - In Green and Hybrid mode, limited by export current.
• 6 - The exported current is less than the minimum necessary.
• 7 - Exported current is under 6 Amps, but over LB minimum current.

active_chargers - Active chargers on each phase. [L1, L2, L3]

active_total - Total active charger.

current - Energy meter current value in Amps per phase. [L1, L2, L3]

available_current - Available current on each phase in Amps. [L1, L2, L3]

total_chargers_current - Total current used by the chargers now per phase in Amps. [L1, L2, L3].

computed_charging_current - Computed charging current per phase in Amps. [L1, L2, L3].

exported_current - Exported current per phase in Amps. [L1, L2, L3]

pause_requested - Pause is requested per phase [L1, L2, L3]

chargers_list - Chargers list info object:

• id - Charger ID.

• ip - Charger IP

• type - Charger type. Values:

  • 1 - Single phase charger.
  • 2 - Dual phase charger.
  • 3 - Three phase charger.

• connected_phase - Phase on which the L1 of the charger is connected.

• em_current - Computed current value.

• charger_em_current - EM current currently set on the charger.

• current - Charger current on each phase in Amps. [L1, L2, L3]

• state - Simplified charger state. Values:

  • 0 - State unknown.
  • 1 - Available.
  • 2 - Car connected.
  • 3 - Charging.
  • 4 - Charger error.

• em_current_updated - Flag to note if em_current was updated.

• is_online - Charger is online.

• is_paused - Charger is paused.

• voltage - Charger voltage on each phase in Volts. [L1, L2, L3]

• instant_power - Charger instant power.

• session_id - Charger session ID.

• sched_lb_mode - Schedule load balancing mode.

• obc_type - Car on-board charger type.

• potential_relay_mode - Relay mode without taking into account the em_relay_mode.

• charging_mode - Charger charging mode.

• em_relay_mode - Relay mode set by energy management device.

6.2 Set load balancing mode

Method	Description
Load_balancing_mode.Set	Set load balancing mode.

Request params format

{
  "load_balancing_mode": "integer"
}

load_balancing_mode - Load balancing mode. Values:

• 0 - Disabled.
• 1 - Power mode.
• 2 - Hybrid mode.
• 3 - Green mode.

Response params format

On success:

true

On error: Error message according to RPC-JSON specification and error code number described in Error codes chapter.

6.3 Get load balancing mode

Method	Description
Load_balancing_mode.Get	Get load balancing mode.

Request params format

No parameters.

Response params format

{
  "load_balancing_mode": "integer"
}

load_balancing_mode - Load balancing mode. Values:

• 0 - Disabled.
• 1 - Power mode.
• 2 - Hybrid mode.
• 3 - Green mode.

6.4 Set chargers list.

Method	Description
Chargers_list.Set	Set chargers list.

Request params format

{
  "chargers_list": [
    {
      "ip": "string",
      "id": "string"
      // ...
    },
    {
      //...
    }
  ]
}

At leas on parameter is needed. The other parameter will be updated through mDNS.!

ip - Charger IP.

id - Charger ID.

Response params format

On success:

true

On error: Error message according to RPC-JSON specification and error code number described in Error codes chapter.

6.5 Get chargers list.

Method	Description
Chargers_list.Get	Get chargers list.

Request params format

No parameters.

Response params format

{
  "chargers_list": [
    {
      "id": "string",
      "ip": "string",
      "phase_type": "integer",
      "connected_phase": "integer"
      // ...
    },
    {
      //...
    }
  ]
}

ip - Charger IP.

id - Charger ID.

phase_type - Charger type. Values:

• 1 - Single phase charger.
• 2 - Dual phase charger.
• 3 - Three phase charger.

connected_phase - Phase on which the L1 of the charger is connected.

6.6 Get load balancing meter info.

Method	Description
Lb_meter_info.Get	Description.

Request params format

No parameters.

Response params format

{
  "type": "integer",
  "phases": "integer",
  "meter_status": "integer",
  "custom_code": "integer",
  "voltage": ["double", "double", "double"],
  "current": ["double", "double", "double"],
  "active_current": ["double", "double", "double"],
  "exported_active_energy": ["double", "double", "double"],
  "imported_active_energy": ["double", "double", "double"],
  "total_exported_energy": "double",
  "total_imported_energy": "double",
  "power_factor": ["double", "double", "double"],
  "angle": ["double", "double", "double"],
  "active_p": ["double", "double", "double"],
  "apparent_p": ["double", "double", "double"],
  "reactive_p": ["double", "double", "double"],
  "inverter": {
    "lifetime_energy": "double",
    "ac_power": "double"
  }
}

type – Meter type. Values:

• 0 - Unknown
• 1 - No onboard meter.
• 2 - ADE753 onboard meter
• 3 - ADE7880 onboard meter
• 4 - Chain2Gate by MAC meter
• 5 - Alfa by Sinapsi meter
• 6 - Sunspec SolarEdge inverter
• 7 - Shelly EM meter
• 8 - Shelly 3EM meter
• 9 - Shelly EM PRO meter
• 10 - Shelly 3EM PRO meter
• 11 - Internal meter

phases – Meter number of phases. Range: 1-3.

meter_status – Meter communication status. Values:

• 0 – Communication is working.
• -1 – General communication error.
• -2 – Meter not initialized.
• -3 – Meter communication timeout.

custom_code – Meter dependent error status. Check source code for explanations.

voltage – Measured voltage per phase. [L1, L2, L3]

current – Measured current per phase. [L1, L2, L3]

active_current – Measured active current per phase. [L1, L2, L3]

angle – Measured angle per phase. [L1, L2, L3]

active_p – Measured active power per phase. [L1, L2, L3]

apparent_p – Measured apparent power per phase. [L1, L2, L3]

reactive_p – Measured reactive power per phase. [L1, L2, L3]

6.7 Get meter list.

Method	Description
Lb_meter_list.Get	A list of supported meters.

Request params format

No parameters.

Response params format

{
  "meter_list": [
    "string",
    "string"
    //...
  ]
}

meter_list - A list of supported energy meters, according to Supported meter list.

6.8 Set energy meter configuration.

Method	Description
Lb_meter_config.Set	Set energy meter configuration.

Request params format

{
  "name": "string",
  "ip": "string",
  "hostname": "string",
  "port": "integer",
  "modbus_id": "integer",
  "baudrate": "integer"
}

name - Meter name according to Supported meter list.

ip - A string containing IP address. Example: "192.168.0.1"

hostname - A string with meter hostname. Example: "shellyem-8CAAB505B323"

port - TCP port number.

modbus_id - ModBus ID.

baudrate - Baudrate for RS485 energy meters.

Response params format

On success:

true

On error: Error message according to RPC-JSON specification and error code number described in Error codes chapter.

6.9 Get energy meter configuration

Method	Description
Lb_meter_config.Get	Get energy meter configuration.

Request params format

No parameters.

Response params format

{
  "name": "string",
  "ip": "string",
  "hostname": "string",
  "port": "integer",
  "modbus_id": "integer",
  "baudrate": "integer"
}

name - Meter name according to Supported meter list.

ip - A string containing IP address. Example: "192.168.0.1"

hostname - A string with meter hostname. Example: "shellyem-8CAAB505B323"

port - TCP port number.

modbus_id - ModBus ID.

baudrate - Baudrate for RS485 energy meters.