Vehicles

The ev module allows configuring vehicle profiles. Vehicles are identified by their MAC address, which they transmit e.g. when connecting via ISO 15118 (Autocharge) or which can be spoofed via the API using ev/inject_ev. Based on the matched profile, charging sessions can be assigned to a user (Autocharge) and the state of charge (SoC) of the vehicle can be estimated from battery capacity and charging efficiency.

warp1

Not supported on this hardware!

warp2

Not supported on this hardware!

warp3

Not supported on this hardware!

warp4

ev/state

The state of the currently connected vehicle.

Example

HTTP (curl)

# $HOST e.g. warp4-AbCd

Read

curl http://$HOST/ev/state

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp4/AbCd

Read

mosquitto_sub -v -C 1 -h $BROKER -t $PREFIX/ev/state

{
    "active_ev_index": 0,
    "name": "ID.4",
    "mac": "0A:1B:2C:D3:E4:F5",
    "soc": 42.5,
    "capacity": 77.0,
    "charging_efficiency": 0.92
}

A vehicle is connected and was matched to the first vehicle profile. The estimated state of charge is 42.5 %.

Name	Description
active_ev_index int	Index of the matched vehicle profile in ev/config. -1 if no vehicle is connected or the vehicle could not be matched to a profile.
name string	Name of the matched vehicle profile. Empty if no vehicle is connected or the vehicle could not be matched to a profile.
mac string	MAC address of the connected vehicle in the format AA:BB:CC:DD:EE:FF. Empty if no vehicle is connected.
soc float (%)	Current state of charge (SoC) of the vehicle in percent. Either transmitted by the vehicle (ISO 15118-20), set via ev/inject_soc or estimated from the charged energy, the battery capacity and the charging efficiency. null if unknown.
capacity float (kWh)	Battery capacity of the connected vehicle in kWh. Taken from the matched vehicle profile or transmitted by the vehicle (ISO 15118-20). null if no vehicle is connected.
charging_efficiency float	Charging efficiency of the connected vehicle: ratio of stored to consumed energy. Taken from the matched vehicle profile. 0.92 if no profile is matched.

ev/seen_macs

The MAC addresses of the most recently connected vehicles (up to 8). Helpful for determining the MAC address of a vehicle to be configured in ev/config.

Example

HTTP (curl)

# $HOST e.g. warp4-AbCd

Read

curl http://$HOST/ev/seen_macs

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp4/AbCd

Read

mosquitto_sub -v -C 1 -h $BROKER -t $PREFIX/ev/seen_macs

[
    { "mac": "0A:1B:2C:D3:E4:F5", "seen_at": 1234567 },
    { "mac": "5C:AF:06:12:34:56", "seen_at": 42000 }
]

Index	Description
[..] object	A seen MAC address Name Description mac string MAC address of the vehicle in the format AA:BB:CC:DD:EE:FF. seen_at int (ms) Time at which the MAC address was last seen, in milliseconds since boot.

ev/inject_soc

Sets the state of charge (SoC) of the currently connected vehicle via the API. Starting from this value, the SoC is further estimated from the charged energy, the battery capacity and the charging efficiency.

http

mqtt

Triggers a one-time action. Messages retained via the broker are ignored.

Example

HTTP (curl)

# $HOST e.g. warp4-AbCd

Write

curl http://$HOST/ev/inject_soc -d '{ "soc": 42.5 }'

or abbreviated:

curl http://$HOST/ev/inject_soc -d '42.5'

Sets the state of charge of the connected vehicle to 42.5 %.

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp4/AbCd

Write

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_soc -m '{ "soc": 42.5 }'

or abbreviated:

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_soc -m '42.5'

Sets the state of charge of the connected vehicle to 42.5 %.

Name	Description
soc float (%)	State of charge in percent. Must be between 0 and 100.

ev/inject_ev

Pretends that a vehicle with the given MAC address has connected. This allows identifying a vehicle via the API that does not transmit its MAC address itself (via ISO 15118). If the MAC address can be matched to a vehicle profile from ev/config, its settings are applied and (if Autocharge is active) the charging session is assigned to the configured user.

http

mqtt

Triggers a one-time action. Messages retained via the broker are ignored.

Example

HTTP (curl)

# $HOST e.g. warp4-AbCd

Write

curl http://$HOST/ev/inject_ev -d '{ "mac": "0A:1B:2C:D3:E4:F5" }'

or abbreviated:

curl http://$HOST/ev/inject_ev -d '"0A:1B:2C:D3:E4:F5"'

Pretends that a vehicle with the MAC address 0A:1B:2C:D3:E4:F5 has connected.

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp4/AbCd

Write

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_ev -m '{ "mac": "0A:1B:2C:D3:E4:F5" }'

or abbreviated:

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_ev -m '"0A:1B:2C:D3:E4:F5"'

Pretends that a vehicle with the MAC address 0A:1B:2C:D3:E4:F5 has connected.

Name	Description
mac string	MAC address of the vehicle in the format AA:BB:CC:DD:EE:FF.

ev/config

The configured vehicle profiles.

Example

HTTP (curl)

# $HOST e.g. warp4-AbCd

Read

curl http://$HOST/ev/config

{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

Write

curl http://$HOST/ev/config -d '{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}'

or abbreviated:

curl http://$HOST/ev/config -d '[
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]'

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp4/AbCd

Read

mosquitto_sub -v -C 1 -h $BROKER -t $PREFIX/ev/config

{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

Write

With MQTT on $PREFIX/ev/config_update

mosquitto_pub -h $BROKER -t $PREFIX/ev/config_update -m '{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}'

or abbreviated:

mosquitto_pub -h $BROKER -t $PREFIX/ev/config_update -m '[
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]'

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

Name

Description

evs object[..]

List of vehicle profiles (up to 16). [0] - A vehicle profile Name Description name string Name to identify this vehicle. Up to 16 characters. mac string MAC address of the vehicle in the format AA:BB:CC:DD:EE:FF. If the vehicle changes part of its address between charging sessions (e.g. VW ID models), the changing bytes can be marked with xx as wildcard, e.g. AA:BB:CC:xx:xx:xx. capacity float (kWh) Battery capacity of the vehicle in kWh. Used to estimate the state of charge. 0 if unknown (then 60 kWh are assumed). charging_efficiency float Charging efficiency of the vehicle: ratio of stored to consumed energy. Used to estimate the state of charge. Typically 0.92. user_id int ID of the user this vehicle is assigned to, or 0 if it is not assigned to any user. If the vehicle is detected and Autocharge is active, the charging session is assigned to this user.

wem

Not supported on this hardware!

wem2

Not supported on this hardware!

any

ev/state

The state of the currently connected vehicle.

Example

HTTP (curl)

# $HOST e.g. warp-AbCd

Read

curl http://$HOST/ev/state

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp/AbCd

Read

mosquitto_sub -v -C 1 -h $BROKER -t $PREFIX/ev/state

{
    "active_ev_index": 0,
    "name": "ID.4",
    "mac": "0A:1B:2C:D3:E4:F5",
    "soc": 42.5,
    "capacity": 77.0,
    "charging_efficiency": 0.92
}

A vehicle is connected and was matched to the first vehicle profile. The estimated state of charge is 42.5 %.

Name	Description
active_ev_index int	Index of the matched vehicle profile in ev/config. -1 if no vehicle is connected or the vehicle could not be matched to a profile.
name string	Name of the matched vehicle profile. Empty if no vehicle is connected or the vehicle could not be matched to a profile.
mac string	MAC address of the connected vehicle in the format AA:BB:CC:DD:EE:FF. Empty if no vehicle is connected.
soc float (%)	Current state of charge (SoC) of the vehicle in percent. Either transmitted by the vehicle (ISO 15118-20), set via ev/inject_soc or estimated from the charged energy, the battery capacity and the charging efficiency. null if unknown.
capacity float (kWh)	Battery capacity of the connected vehicle in kWh. Taken from the matched vehicle profile or transmitted by the vehicle (ISO 15118-20). null if no vehicle is connected.
charging_efficiency float	Charging efficiency of the connected vehicle: ratio of stored to consumed energy. Taken from the matched vehicle profile. 0.92 if no profile is matched.

ev/seen_macs

The MAC addresses of the most recently connected vehicles (up to 8). Helpful for determining the MAC address of a vehicle to be configured in ev/config.

Example

HTTP (curl)

# $HOST e.g. warp-AbCd

Read

curl http://$HOST/ev/seen_macs

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp/AbCd

Read

mosquitto_sub -v -C 1 -h $BROKER -t $PREFIX/ev/seen_macs

[
    { "mac": "0A:1B:2C:D3:E4:F5", "seen_at": 1234567 },
    { "mac": "5C:AF:06:12:34:56", "seen_at": 42000 }
]

Index	Description
[..] object	A seen MAC address Name Description mac string MAC address of the vehicle in the format AA:BB:CC:DD:EE:FF. seen_at int (ms) Time at which the MAC address was last seen, in milliseconds since boot.

ev/inject_soc

Sets the state of charge (SoC) of the currently connected vehicle via the API. Starting from this value, the SoC is further estimated from the charged energy, the battery capacity and the charging efficiency.

http

mqtt

Triggers a one-time action. Messages retained via the broker are ignored.

Example

HTTP (curl)

# $HOST e.g. warp-AbCd

Write

curl http://$HOST/ev/inject_soc -d '{ "soc": 42.5 }'

or abbreviated:

curl http://$HOST/ev/inject_soc -d '42.5'

Sets the state of charge of the connected vehicle to 42.5 %.

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp/AbCd

Write

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_soc -m '{ "soc": 42.5 }'

or abbreviated:

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_soc -m '42.5'

Sets the state of charge of the connected vehicle to 42.5 %.

Name	Description
soc float (%)	State of charge in percent. Must be between 0 and 100.

ev/inject_ev

Pretends that a vehicle with the given MAC address has connected. This allows identifying a vehicle via the API that does not transmit its MAC address itself (via ISO 15118). If the MAC address can be matched to a vehicle profile from ev/config, its settings are applied and (if Autocharge is active) the charging session is assigned to the configured user.

http

mqtt

Triggers a one-time action. Messages retained via the broker are ignored.

Example

HTTP (curl)

# $HOST e.g. warp-AbCd

Write

curl http://$HOST/ev/inject_ev -d '{ "mac": "0A:1B:2C:D3:E4:F5" }'

or abbreviated:

curl http://$HOST/ev/inject_ev -d '"0A:1B:2C:D3:E4:F5"'

Pretends that a vehicle with the MAC address 0A:1B:2C:D3:E4:F5 has connected.

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp/AbCd

Write

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_ev -m '{ "mac": "0A:1B:2C:D3:E4:F5" }'

or abbreviated:

mosquitto_pub -h $BROKER -t $PREFIX/ev/inject_ev -m '"0A:1B:2C:D3:E4:F5"'

Pretends that a vehicle with the MAC address 0A:1B:2C:D3:E4:F5 has connected.

Name	Description
mac string	MAC address of the vehicle in the format AA:BB:CC:DD:EE:FF.

ev/config

The configured vehicle profiles.

Example

HTTP (curl)

# $HOST e.g. warp-AbCd

Read

curl http://$HOST/ev/config

{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

Write

curl http://$HOST/ev/config -d '{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}'

or abbreviated:

curl http://$HOST/ev/config -d '[
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]'

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

MQTT (mosquitto)

# $BROKER e.g. my_mosquitto.localdomain
# $PREFIX e.g. warp/AbCd

Read

mosquitto_sub -v -C 1 -h $BROKER -t $PREFIX/ev/config

{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

Write

With MQTT on $PREFIX/ev/config_update

mosquitto_pub -h $BROKER -t $PREFIX/ev/config_update -m '{
    "evs": [
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]
}'

or abbreviated:

mosquitto_pub -h $BROKER -t $PREFIX/ev/config_update -m '[
        {
            "name": "ID.4",
            "mac": "0A:1B:2C:xx:xx:xx",
            "capacity": 77.0,
            "charging_efficiency": 0.92,
            "user_id": 2
        },
        {
            "name": "Zoe",
            "mac": "5C:AF:06:12:34:56",
            "capacity": 52.0,
            "charging_efficiency": 0.9,
            "user_id": 0
        }
    ]'

Configures two vehicle profiles: One vehicle with a rotating MAC address (only the first three bytes are used for identification) whose charging sessions are assigned to the user with ID 2, and one vehicle with a fixed MAC address without user assignment.

Name

Description

evs object[..]

List of vehicle profiles (up to 16). [0] - A vehicle profile Name Description name string Name to identify this vehicle. Up to 16 characters. mac string MAC address of the vehicle in the format AA:BB:CC:DD:EE:FF. If the vehicle changes part of its address between charging sessions (e.g. VW ID models), the changing bytes can be marked with xx as wildcard, e.g. AA:BB:CC:xx:xx:xx. capacity float (kWh) Battery capacity of the vehicle in kWh. Used to estimate the state of charge. 0 if unknown (then 60 kWh are assumed). charging_efficiency float Charging efficiency of the vehicle: ratio of stored to consumed energy. Used to estimate the state of charge. Typically 0.92. user_id int ID of the user this vehicle is assigned to, or 0 if it is not assigned to any user. If the vehicle is detected and Autocharge is active, the charging session is assigned to this user.