Notifications

Notifications can be simple text messages or transport structured data. To distinguish by their purpose and origin, notifications have a type and a subtype.

Notifications are sent by the module via the available communication channels (client/server connections). If a channel is temporarily down (e.g. due to a connection loss), the notifications for that channel will be kept in memory until the channel is available again. (Note: this message queue does not survive a crash or reboot of the module.)

Channels process notifications differently depending on the way they work. For example, a v2 server will forward text notifications as push messages to connected smart phones and email readers, a v3 server will publish them under an MQTT topic, and the webserver will display the message as a modal dialog. See the respective manual sections for details.

Notification types currently defined:

  • info – informational text messages

  • alert – alert text messages

  • error – error code messages

  • data – historical data records, usually CSV formatted

  • stream – live data streaming (high bandwidth), usually JSON formatted

The standard subtypes used are listed below, these can be used to filter messages. Vehicles may introduce custom notifications and replace standard notifications, see the respective user guide section for details.

Subtypes by convention are given in lower case, with dots ‘’.’’ as structural separators.

Notification channels currently defined:

  • ovmsv2 – server v2 connection

  • ovmsv3 – server v3 connection

  • ovmsweb – websocket connections

  • pushover – pushover text messaging service

Channels may have multiple active instances (“readers”), for example you can open multiple websocket connections. Channels may exclude notification types. Currently stream records are only supported on a websocket connection, all other types are supported on all channels.

Use notify status to see the currently registered channels (“readers”). Example:

OVMS# notify status
Notification system has 3 readers registered
  pushover(1): verbosity=1024
  ovmsv2(2): verbosity=1024
  ovmsweb(3): verbosity=65535
Notify types:
  alert: 0 entries
  data: 0 entries
  error: 0 entries
  info: 0 entries
  stream: 0 entries

The channel’s “verbosity” defines the supported maximum length of a textual notification message on that channel. Notification senders should honor this, but not all may do so. If messages exceed this limit, they may be truncated.

Sending notifications

You can send custom notifications from the shell or command scripts by using the notify raise command. The command can send the output of another command, an error code (implies type error), or any text you enter. For example, to send a custom text message, do:

OVMS# notify raise text info usr.anton.welcome "Hello, wonderful person!"

In this case, the type would be info and the subtype usr.anton.welcome. The type must match one of the defined types, the subtype can be chosen arbitrarily. Please use a unique usr. prefix for custom notifications to avoid collisions.

To send a battery status command result, do:

OVMS# notify raise command info battery.status "stat"

To send notifications from Duktape scripts, use the API call OvmsNotify.Raise().

When a text (info/alert) or error notification is sent (i.e. has at least one listening channel, e.g. pushover), an event is raised once when the notification is queued. The event will be named notify.<type>.<subtype>. For example, the second example above would come with an event notify.info.battery.status.

Suppress notifications

You can filter the channels to be used for notifications by their subtypes. By default, no subtypes are filtered on any channel, so all notifications are sent to all clients.

To disable (suppress) notifications, create a config entry based on the respective subtype, that lists the channels to include or exclude:

OVMS# config set notify <subtype> <channels>
<channels> options are:
  1. explicit inclusion: e.g. ovmsv2,pushover (only enable these)

  2. explicit exclusion: e.g. *,-ovmsv3,-ovmsweb (only disable these)

  3. - (dash) to disable all

  4. empty/* to enable all

Example: to disable the OTA update notifications on all channels, do:

OVMS# config set notify ota.update -

Standard notifications

Type

Subtype

Purpose / Content

alert

alarm.sounding

Vehicle alarm is sounding

alert

alarm.stopped

Vehicle alarm has stopped

alert

batt.12v.alert

12V Battery critical

alert

batt.12v.recovered

12V Battery restored

alert

batt.12v.shutdown

System shutdown (deep sleep) due to low 12V battery level

alert

batt.bms.alert

Battery pack/cell alert (critical voltage/temperature deviation)

alert

batt.soc.alert

Battery SOC critical

info

charge.done

stat on charge finished

info

charge.started

stat on start of charge

info

charge.toppingoff

stat on start of topping off charge/phase

info

charge.stopped

stat on planned charge stop

alert

charge.stopped

stat on unplanned charge stop

data

debug.crash

Transmit crash backtraces (→ *-OVM-DebugCrash)

data

debug.tasks

Transmit task statistics (→ *-OVM-DebugTasks)

info

drive.trip.report

Trip driving statistics (see Trip report)

alert

flatbed.moved

Vehicle is being transported while parked - possible theft/flatbed

info

heating.started

stat on start of heating (battery)

data

log.grid

Grid (charge/generator) history log (see below) (→ *-LOG-Grid)

data

log.trip

Trip history log (see below) (→ *-LOG-Trip)

alert

modem.no_pincode

No PIN code for SIM card configured

alert

modem.wrongpincode

Wrong pin code

info

ota.update

New firmware available/downloaded/installed

info

pushover

Connection failure / message delivery response

stream

retools.list.update

RE toolkit CAN frame list update

stream

retools.status

RE toolkit general status update

info

valet.disabled

Valet mode disabled

info

valet.enabled

Valet mode enabled

alert

valet.hood

Vehicle hood opened while in valet mode

alert

valet.trunk

Vehicle trunk opened while in valet mode

alert

vehicle.idle

Vehicle is idling / stopped turned on

Grid history log

The grid history log can be used as a source for long term statistics on your charges and typical energy usages and to calculate your vehicle energy costs.

Log entries are created on each change of the charge or generator state (v.c.state / v.g.state).

You need to enable this log explicitly by configuring a storage time via config param notify log.grid.storetime (in days) or via the web configuration page. Set to 0/empty to disable the log. Already stored log entries will be kept on the server until expiry or manual deletion.

Note: the stability of the total energy counters included in this log depends on their source and persistence on the vehicle and/or module. If they are kept on the module, they may lose their values on a power outage.

  • Notification subtype: log.grid

  • History record type: *-LOG-Grid

  • Format: CSV

  • Archive time: config notify log.grid.storetime (days)

  • Fields/columns:

    • pos_gpslock

    • pos_latitude

    • pos_longitude

    • pos_altitude

    • pos_location

    • charge_type

    • charge_state

    • charge_substate

    • charge_mode

    • charge_climit

    • charge_limit_range

    • charge_limit_soc

    • gen_type

    • gen_state

    • gen_substate

    • gen_mode

    • gen_climit

    • gen_limit_range

    • gen_limit_soc

    • charge_time

    • charge_kwh

    • charge_kwh_grid

    • charge_kwh_grid_total

    • gen_time

    • gen_kwh

    • gen_kwh_grid

    • gen_kwh_grid_total

    • bat_soc

    • bat_range_est

    • bat_range_ideal

    • bat_range_full

    • bat_voltage

    • bat_temp

    • charge_temp

    • charge_12v_temp

    • env_temp

    • env_cabintemp

    • bat_soh

    • bat_health

    • bat_cac

    • bat_energy_used_total

    • bat_energy_recd_total

    • bat_coulomb_used_total

    • bat_coulomb_recd_total

Trip history log

The trip history log can be used as a source for long term statistics on your trips and typical trip power usages, as well as your battery performance in different environmental conditions and degradation over time.

Entries are created at the beginning and end of each “ignition” cycle (v.e.on change). Configure a minimum trip length for logging by the config variable notify log.trip.minlength or via the web UI. If your vehicle does not support the v.p.trip metric, set the minimum trip length to 0.

The log entry at the beginning of a trip is created to track non-driving SOC changes, vampire drains and BMS SOC corrections that occurred in between. If you’re just interested in the actual drive results, filter the records e.g. by pos_trip > 0.1 or env_drivetime > 10 (by default log entries will be created 3 seconds after the v.e.on state change).

You need to enable this log explicitly by configuring a storage time via config param notify log.trip.storetime (in days) or via the web configuration page. Set to 0/empty to disable the log. Already stored log entries will be kept on the server until expiry or manual deletion.

  • Notification subtype: log.trip

  • History record type: *-LOG-Trip

  • Format: CSV

  • Archive time: config notify log.trip.storetime (days)

  • Fields/columns:

    • pos_gpslock

    • pos_latitude

    • pos_longitude

    • pos_altitude

    • pos_location

    • pos_odometer

    • pos_trip

    • env_drivetime

    • env_drivemode

    • bat_soc

    • bat_range_est

    • bat_range_ideal

    • bat_range_full

    • bat_energy_used

    • bat_energy_recd

    • bat_coulomb_used

    • bat_coulomb_recd

    • bat_soh

    • bat_health

    • bat_cac

    • bat_energy_used_total

    • bat_energy_recd_total

    • bat_coulomb_used_total

    • bat_coulomb_recd_total

    • env_temp

    • env_cabintemp

    • bat_temp

    • inv_temp

    • mot_temp

    • charge_12v_temp

    • tpms_temp_min

    • tpms_temp_max

    • tpms_pressure_min

    • tpms_pressure_max

    • tpms_health_min

    • tpms_health_max

Trip report

The trip report outputs some core statistics of the current or most recent trip (drive cycle). It can be queried any time using the stat trip command, or be configured to be sent automatically on turning the vehicle off:

Use the web UI (Config → Notifications) or set config variable notify report.trip.enable to yes and optionally a minimum trip length in notify log.trip.minlength (defaults to 0.2 km). If your vehicle does not support the v.p.trip metric, set the minimum trip length to 0.

The statistics available depend on your vehicle type (i.e. metrics support of that vehicle adaption). Vehicles also may override the report to provide custom statistics. By default, a full trip report will contain:

  • Trip length

  • Average driving speed

  • Overall altitude difference (start to end point)

  • Energy consumption in Wh per km/Mi

  • Recuperation percentage (in relation to energy used)

  • SOC difference & new SOC

  • Estimated range difference & new range

  • Average acceleration & deceleration

The average driving speed is calculated only from speeds above 5 kph (3 mph) (to exclude slow speed rolling), and the acceleration & deceleration averages exclude values below 2.5 kph/s (1.6 mph/s) (constant speed cruising).