cariflex/tools/EVerest-main/modules/API/API

API module documentation

This module is responsible for providing a simple MQTT based API to EVerest internals

Periodically published variables for each connected EvseManager

This module periodically publishes the following variables for each connected EvseManager.

everest_api/connectors

This variable is published every second and contains an array of the connectors for which the api is available:

["evse_manager"]

The following documentation assumes that the only connector available is called "evse_manager".

everest_api/evse_manager/var/datetime

This variable is published every second and contains a string representation of the current UTC datetime in RFC3339 format:

2022-10-11T16:18:57.746Z

everest_api/evse_manager/var/hardware_capabilities

This variable is published every second and contains the hardware capabilities in the following format:

    {
        "max_current_A_export":16.0,
        "max_current_A_import":32.0,
        "max_phase_count_export":3,
        "max_phase_count_import":3,
        "min_current_A_export":0.0,
        "min_current_A_import":6.0,
        "min_phase_count_export":1,
        "min_phase_count_import":1,
        "supports_changing_phases_during_charging":true
    }

everest_api/evse_manager/var/session_info

This variable is published every second and contains a json object with information relating to the current charging session in the following format:

{
    "charged_energy_wh": 0,
    "charging_duration_s": 84,
    "datetime": "2022-10-11T16:48:35.747Z",
    "discharged_energy_wh": 0,
    "latest_total_w": 0.0,
    "permanent_fault": false,
    "state": "Unplugged",
    "active_enable_disable_source": {
        "source": "Unspecified",
        "state": "Enable",
        "priority": 5000
    },
    "uk_random_delay": {
        "remaining_s": 34,
        "current_limit_after_delay_A": 16.0,
        "current_limit_during_delay_A": 0.0,
        "start_time": "2024-02-28T14:11:11.129Z"
    },
    "last_enable_disable_source": "Unspecified"
}

• charged_energy_wh contains the charged energy in Wh
• charging_duration_s contains the duration of the current charging session in seconds
• datetime contains a string representation of the current UTC datetime in RFC3339 format
• discharged_energy_wh contains the energy fed into the power grid by the EV in Wh
• latest_total_w contains the latest total power reading over all phases in Watt
• uk_random_delay_remaining_s Remaining time of a currently active random delay according to UK smart charging regulations. Not set if no delay is active.
• state contains the current state of the charging session, from a list of the following possible states:
  • Unplugged
  • Disabled
  • Preparing
  • Reserved
  • AuthRequired
  • Charging
  • ChargingPausedEV
  • ChargingPausedEVSE
  • Finished
  • FinishedEV
  • FinishedEVSE
  • AuthTimeout

everest_api/evse_manager/var/limits

This variable is published every second and contains a json object with information relating to the current limits of this EVSE.

    {
        "max_current": 16.0,
        "nr_of_phases_available": 1,
        "uuid": "evse_manager"
    }

everest_api/evse_manager/var/telemetry

This variable is published every second and contains telemetry of the EVSE.

    {
        "fan_rpm": 0.0,
        "rcd_current": 0.0991784930229187,
        "relais_on": false,
        "supply_voltage_12V": 11.950915336608887,
        "supply_voltage_minus_12V": -11.94166374206543,
        "temperature": 30.729248046875
    }

everest_api/evse_manager/var/powermeter

This variable is published every second and contains powermeter information of the EVSE.

    {
        "current_A": {
            "L1": 16.113445281982422,
            "L2": 16.113445281982422,
            "L3": 16.113445281982422,
            "N": 0.20141807198524475
        },
        "energy_Wh_import": {
            "L1": 1537.3179931640625,
            "L2": 1537.3179931640625,
            "L3": 1537.3179931640625,
            "total": 4611.9541015625
        },
        "frequency_Hz": {
            "L1": 50.03734588623047,
            "L2": 50.03734588623047,
            "L3": 50.03734588623047
        },
        "meter_id": "YETI_POWERMETER",
        "phase_seq_error": false,
        "power_W": {
            "L1": 3602.54833984375,
            "L2": 3602.54833984375,
            "L3": 3602.54833984375,
            "total": 10807.64453125
        },
        "timestamp": 1665509120.0,
        "voltage_V": {
            "L1": 223.5740509033203,
            "L2": 223.5740509033203,
            "L3": 223.5740509033203
        }
    }

Periodically published variables for OCPP

everest_api/ocpp/var/connection_status

This variable is published every second and contains the connection status of the OCPP module. If the OCPP module has not yet published its "is_connected" status or no OCPP module is configured "unknown" is published. Otherwise "connected" or "disconnected" are published.

Commands and variables published in response

everest_api/evse_manager/cmd/enable_disable

Command to enable or disable a connector on the EVSE. The payload should be the following json:

    {
        "connector_id": 0,
        "source": "LocalAPI",
        "state": "Enable",
        "priority": 42
    }

connector_id is a positive integer identifying the connector that should be enabled. If the connector_id is 0 the whole EVSE is enabled.

The source is an enum of the following source types :

- Unspecified
- LocalAPI
- LocalKeyLock
- ServiceTechnician
- RemoteKeyLock
- MobileApp
- FirmwareUpdate
- CSMS

The state can be either "enable", "disable", or "unassigned".

"enable" and "disable" enforce the state to be enable/disable, while unassigned means that the source does not care about the state and other sources may decide.

Each call to this command will update an internal table that looks like this:

Source	State	Priority
Unspecified	unassigned	10000
LocalAPI	disable	42
LocalKeyLock	enable	0

Evaluation will be done based on priorities. 0 is the highest priority, 10000 the lowest, so in this example the connector will be enabled regardless of what other sources say. Imagine LocalKeyLock sends a "unassigned, prio 0", the table will then look like this:

Source	State	Priority
Unspecified	unassigned	10000
LocalAPI	disable	42
LocalKeyLock	unassigned	0

So now the connector will be disabled, because the second highest priority (42) sets it to disabled.

If all sources are unassigned, the connector is enabled. If two sources have the same priority, "disabled" has priority over "enabled".

everest_api/evse_manager/cmd/enable

Legacy command to enable a connector on the EVSE kept for compatibility reasons. They payload should be a positive integer identifying the connector that should be enabled. If the payload is 0 the whole EVSE is enabled. It will actually call the following command on everest_api/evse_manager/cmd/enable_enable:

    {
        "connector_id": 1,
        "source": "LocalAPI",
        "state": "Enable",
        "priority": 100
    }

everest_api/evse_manager/cmd/disable

Legacy command to enable a connector on the EVSE kept for compatibility reasons. Command to disable a connector on the EVSE. They payload should be a positive integer identifying the connector that should be disabled. If the payload is 0 the whole EVSE is disabled. It will actually call the following command on everest_api/evse_manager/cmd/enable_disable:

    {
        "connector_id": 1,
        "source": "LocalAPI",
        "state": "Disable",
        "priority": 100
    }

everest_api/evse_manager/cmd/pause_charging

If any arbitrary payload is published to this topic charging will be paused by the EVSE.

everest_api/evse_manager/cmd/resume_charging

If any arbitrary payload is published to this topic charging will be resumed by the EVSE.

everest_api/evse_manager/cmd/stop_charging

If any arbitrary payload is published to this topic charging will be stopped by the EVSE.

everest_api/evse_manager/cmd/set_limit_amps

Command to set an amps limit for this EVSE that will be considered within the EnergyManager. This does not automatically imply that this limit will be set by the EVSE because the energymanagement might consider limitations from other sources, too. The payload can be a positive or negative number.

📌 Note: You have to configure one evse_energy_sink connection per EVSE within the configuration file in order to use this topic!

everest_api/evse_manager/cmd/set_limit_watts

Command to set a watt limit for this EVSE that will be considered within the EnergyManager. This does not automatically imply that this limit will be set by the EVSE because the energymanagement might consider limitations from other sources, too. The payload can be a positive or negative number.

📌 Note: You have to configure one evse_energy_sink connection per EVSE within the configuration file in order to use this topic!

everest_api/evse_manager/cmd/set_limit_amps_phases

Command to set a current (amps) and a phase limit for this EVSE, which will be considered by the energy management. The payload should be in the following json format:

    {
        "amps": 8.0,
        "phases": 3
    }

Setting these limits does not automatically imply that they will be set by the EVSE because the energy management might consider limitations from other sources, too. The "amps" value can be a positive or negative number. The "phases" value must be either 1 or 3. Please consider that switching between AC single-phase (1ph) and three-phase (3ph) charging does only work if 1ph/3ph switching is activated in the EVerest configuration. For more information please look in the EVerest documentation.

📌 Note: You have to configure one evse_energy_sink connection per EVSE within the configuration file in order to use this topic!

everest_api/evse_manager/cmd/force_unlock

Command to force unlock a connector on the EVSE. The payload should be a positive integer identifying the connector that should be unlocked. If the payload is empty or cannot be converted to an integer connector 1 is assumed.

everest_api/evse_manager/cmd/uk_random_delay

Command to control the UK Smart Charging random delay feature. The payload can be the following enum: "enable" and "disable" to enable/disable the feature entirely or "cancel" to cancel an ongoing delay.

everest_api/evse_manager/cmd/uk_random_delay_set_max_duration_s

Command to set the UK Smart Charging random delay maximum duration. Payload is an integer in seconds.

everest_api/errors/var/active_errors

Publishes an array of all active errors of the charging station