Vehicle: added optional automatic trip report generation

Details: https://docs.openvehicles.com/en/latest/userguide/notifications.html

New configs:
  [notify]  report.trip.enable        -- Send trip report on vehicle off (bool, default no)
  [notify]  report.trip.minlength     -- … minimum trip length in km, default 0.2 km

New command:
  stat trip                           -- Output statistics for current/finished trip

Author: dexterbg

docs/source/userguide/notifications.rst

@@ -127,6 +127,7 @@ 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``)
@@ -278,3 +279,32 @@ Already stored log entries will be kept on the server until expiry or manual del
     * 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).

vehicle/OVMS.V3/changes.txt

@@ -1,6 +1,13 @@
 Open Vehicle Monitor System v3 - Change log
 
 ????-??-?? ???  ???????  OTA release
+- Vehicle: added optional automatic trip report generation
+    Details: https://docs.openvehicles.com/en/latest/userguide/notifications.html
+  New configs:
+    [notify]  report.trip.enable        -- Send trip report on vehicle off (bool, default no)
+    [notify]  report.trip.minlength     -- … minimum trip length in km, default 0.2 km
+  New command:
+    stat trip                           -- Output statistics for current/finished trip
 - VW e-Up: added acceleration support; OBD by reading from ECU,
     T26 deriving from speed changes
 

vehicle/OVMS.V3/components/ovms_webserver/src/web_cfg.cpp

@@ -1600,6 +1600,8 @@ void OvmsWebServer::HandleCfgNotifications(PageEntry_t& p, PageContext_t& c)
   std::string error;
   std::string vehicle_minsoc, vehicle_stream;
   std::string log_trip_storetime, log_trip_minlength, log_grid_storetime;
+  bool report_trip_enable;
+  std::string report_trip_minlength;
 
   if (c.method == "POST") {
     // process form submission:
@@ -1608,6 +1610,8 @@ void OvmsWebServer::HandleCfgNotifications(PageEntry_t& p, PageContext_t& c)
     log_trip_storetime = c.getvar("log_trip_storetime");
     log_trip_minlength = c.getvar("log_trip_minlength");
     log_grid_storetime = c.getvar("log_grid_storetime");
+    report_trip_enable = (c.getvar("report_trip_enable") == "yes");
+    report_trip_minlength = c.getvar("report_trip_minlength");
 
     if (vehicle_minsoc != "") {
       if (atoi(vehicle_minsoc.c_str()) < 0 || atoi(vehicle_minsoc.c_str()) > 100) {
@@ -1636,6 +1640,12 @@ void OvmsWebServer::HandleCfgNotifications(PageEntry_t& p, PageContext_t& c)
       }
     }
 
+    if (report_trip_minlength != "") {
+      if (atoi(report_trip_minlength.c_str()) < 0) {
+        error += "<li data-input=\"report_trip_minlength\">Trip report min length must not be negative</li>";
+      }
+    }
+
     if (error == "") {
       // success:
       if (vehicle_minsoc == "")
@@ -1660,6 +1670,12 @@ void OvmsWebServer::HandleCfgNotifications(PageEntry_t& p, PageContext_t& c)
       else
         MyConfig.SetParamValue("notify", "log.grid.storetime", log_grid_storetime);
 
+      MyConfig.SetParamValueBool("notify", "report.trip.enable", report_trip_enable);
+      if (report_trip_minlength == "")
+        MyConfig.DeleteInstance("notify", "report.trip.minlength");
+      else
+        MyConfig.SetParamValue("notify", "report.trip.minlength", report_trip_minlength);
+
       c.head(200);
       c.alert("success", "<p class=\"lead\">Notifications configured.</p>");
       OutputHome(p, c);
@@ -1680,6 +1696,8 @@ void OvmsWebServer::HandleCfgNotifications(PageEntry_t& p, PageContext_t& c)
     log_trip_storetime = MyConfig.GetParamValue("notify", "log.trip.storetime");
     log_trip_minlength = MyConfig.GetParamValue("notify", "log.trip.minlength");
     log_grid_storetime = MyConfig.GetParamValue("notify", "log.grid.storetime");
+    report_trip_enable = MyConfig.GetParamValueBool("notify", "report.trip.enable");
+    report_trip_minlength = MyConfig.GetParamValue("notify", "report.trip.minlength");
 
     // generate form:
     c.head(200);
@@ -1701,6 +1719,17 @@ void OvmsWebServer::HandleCfgNotifications(PageEntry_t& p, PageContext_t& c)
 
   c.fieldset_end();
 
+  c.fieldset_start("Vehicle Reports");
+
+  c.input_checkbox("Enable trip report", "report_trip_enable", report_trip_enable,
+    "<p>This will send a textual report on driving statistics after each trip.</p>");
+  c.input("number", "Report min trip length", "report_trip_minlength", report_trip_minlength.c_str(), "Default: 0.2 km",
+    "<p>Only trips over at least this distance will produce a report. If your vehicle does not support the "
+    "<code>v.p.trip</code> metric, set this to 0.</p>",
+    "min=\"0\" step=\"0.1\"", "km");
+
+  c.fieldset_end();
+
   c.fieldset_start("Data Log Storage Times");
 
   c.input("number", "Trip history log", "log_trip_storetime", log_trip_storetime.c_str(), "Default: empty/0 = disabled",

vehicle/OVMS.V3/components/vehicle/vehicle.cpp

@@ -85,7 +85,8 @@ OvmsVehicleFactory::OvmsVehicleFactory()
   cmd_charge->RegisterCommand("current","Limit charge current",vehicle_charge_current,"<amps>",1,1);
   cmd_charge->RegisterCommand("cooldown","Start a vehicle cooldown",vehicle_charge_cooldown);
 
-  MyCommandApp.RegisterCommand("stat","Show vehicle status",vehicle_stat);
+  OvmsCommand* cmd_stat = MyCommandApp.RegisterCommand("stat","Show vehicle status",vehicle_stat);
+  cmd_stat->RegisterCommand("trip","Show trip status",vehicle_stat_trip);
 
   OvmsCommand* cmd_bms = MyCommandApp.RegisterCommand("bms","BMS framework");
   cmd_bms->RegisterCommand("status","Show BMS status",bms_status);
@@ -248,6 +249,16 @@ OvmsVehicle::OvmsVehicle()
   m_last_gentime = 0;
   m_last_parktime = 0;
 
+  m_drive_startsoc = StdMetrics.ms_v_bat_soc->AsFloat();
+  m_drive_startrange = StdMetrics.ms_v_bat_range_est->AsFloat();
+  m_drive_startaltitude = StdMetrics.ms_v_pos_altitude->AsFloat();
+  m_drive_speedcnt = 0;
+  m_drive_speedsum = 0;
+  m_drive_accelcnt = 0;
+  m_drive_accelsum = 0;
+  m_drive_decelcnt = 0;
+  m_drive_decelsum = 0;
+
   m_ticker = 0;
   m_12v_ticker = 0;
   m_chargestate_ticker = 0;
@@ -1083,6 +1094,96 @@ OvmsVehicle::vehicle_command_t OvmsVehicle::CommandStat(int verbosity, OvmsWrite
   return Success;
   }
 
+/**
+ * CommandStatTrip: default implementation of vehicle trip status report
+ */
+OvmsVehicle::vehicle_command_t OvmsVehicle::CommandStatTrip(int verbosity, OvmsWriter* writer)
+  {
+  metric_unit_t rangeUnit = (MyConfig.GetParamValue("vehicle", "units.distance") == "M") ? Miles : Kilometers;
+  metric_unit_t speedUnit = (rangeUnit == Miles) ? Mph : Kph;
+  metric_unit_t accelUnit = (rangeUnit == Miles) ? MphPS : KphPS;
+  metric_unit_t energyUnit = (rangeUnit == Miles) ? WattHoursPM : WattHoursPK;
+  metric_unit_t altitudeUnit = (rangeUnit == Miles) ? Feet : Meters;
+  const char* rangeUnitLabel = OvmsMetricUnitLabel(rangeUnit);
+  const char* speedUnitLabel = OvmsMetricUnitLabel(speedUnit);
+  const char* accelUnitLabel = OvmsMetricUnitLabel(accelUnit);
+  const char* energyUnitLabel = OvmsMetricUnitLabel(energyUnit);
+  const char* altitudeUnitLabel = OvmsMetricUnitLabel(altitudeUnit);
+
+  float trip_length = StdMetrics.ms_v_pos_trip->AsFloat(0, rangeUnit);
+
+  float speed_avg = (m_drive_speedcnt > 0)
+    ? UnitConvert(Kph, speedUnit, (float)(m_drive_speedsum / m_drive_speedcnt))
+    : 0;
+  float accel_avg = (m_drive_accelcnt > 0)
+    ? UnitConvert(MetersPSS, accelUnit, (float)(m_drive_accelsum / m_drive_accelcnt))
+    : 0;
+  float decel_avg = (m_drive_decelcnt > 0)
+    ? UnitConvert(MetersPSS, accelUnit, (float)(m_drive_decelsum / m_drive_decelcnt))
+    : 0;
+
+  float energy_used = StdMetrics.ms_v_bat_energy_used->AsFloat();
+  float energy_recd = StdMetrics.ms_v_bat_energy_recd->AsFloat();
+  float energy_recd_perc = (energy_used > 0) ? energy_recd / energy_used * 100 : 0;
+  float wh_per_rangeunit = (trip_length > 0) ? (energy_used - energy_recd) * 1000 / trip_length : 0;
+
+  float soc = StdMetrics.ms_v_bat_soc->AsFloat();
+  float soc_diff = soc - m_drive_startsoc;
+  float range = StdMetrics.ms_v_bat_range_est->AsFloat();
+  float range_diff = range - m_drive_startrange;
+  float alt = StdMetrics.ms_v_pos_altitude->AsFloat();
+  float alt_diff = UnitConvert(Meters, altitudeUnit, alt - m_drive_startaltitude);
+
+  std::ostringstream buf;
+  buf
+    << "Trip "
+    << std::fixed
+    << std::setprecision(1)
+    << trip_length << rangeUnitLabel
+    << " Avg "
+    << std::setprecision(0)
+    << speed_avg << speedUnitLabel
+    << " Alt "
+    << ((alt_diff >= 0) ? "+" : "")
+    << alt_diff << altitudeUnitLabel
+    ;
+  if (wh_per_rangeunit != 0)
+    {
+    buf
+      << "\nEnergy "
+      << wh_per_rangeunit << energyUnitLabel
+      << ", "
+      << energy_recd_perc << "% recd"
+      ;
+    }
+  buf
+    << std::setprecision(1)
+    << "\nSOC "
+    << ((soc_diff >= 0) ? "+" : "")
+    << soc_diff << "%"
+    << " = "
+    << soc << "%"
+    << "\nRange "
+    << ((range_diff >= 0) ? "+" : "")
+    << range_diff << rangeUnitLabel
+    << " = "
+    << range << rangeUnitLabel
+    ;
+  if (accel_avg > 0)
+    {
+    buf
+      << "\nAccel +"
+      << accel_avg
+      << " / "
+      << decel_avg << accelUnitLabel
+      ;
+    }
+
+  writer->puts(buf.str().c_str());
+
+  return Success;
+  }
+
 void OvmsVehicle::VehicleConfigChanged(std::string event, void* data)
   {
   OvmsConfigParam* param = (OvmsConfigParam*) data;
@@ -1125,6 +1226,15 @@ void OvmsVehicle::MetricModified(OvmsMetric* metric)
     {
     if (StandardMetrics.ms_v_env_on->AsBool())
       {
+      m_drive_startsoc = StdMetrics.ms_v_bat_soc->AsFloat();
+      m_drive_startrange = StdMetrics.ms_v_bat_range_est->AsFloat();
+      m_drive_startaltitude = StdMetrics.ms_v_pos_altitude->AsFloat();
+      m_drive_speedcnt = 0;
+      m_drive_speedsum = 0;
+      m_drive_accelcnt = 0;
+      m_drive_accelsum = 0;
+      m_drive_decelcnt = 0;
+      m_drive_decelsum = 0;
       MyEvents.SignalEvent("vehicle.on",NULL);
       if (m_autonotifications)
         {
@@ -1364,10 +1474,35 @@ void OvmsVehicle::MetricModified(OvmsMetric* metric)
     if (m_autonotifications)
       NotifyGenState();
     }
+  else if (metric == StandardMetrics.ms_v_pos_speed)
+    {
+    // Collect data for trip speed average:
+    const float min_speed = 5.0;          // slow speed exclusion [kph]
+    float speed = StandardMetrics.ms_v_pos_speed->AsFloat();
+    if (speed > min_speed)
+      {
+      m_drive_speedcnt++;
+      m_drive_speedsum += speed;
+      }
+    }
   else if (metric == StandardMetrics.ms_v_pos_acceleration)
     {
     if (m_brakelight_enable)
       CheckBrakelight();
+
+    // Collect data for trip acceleration/deceleration average:
+    const float min_accel = 2.5 / 3.6;    // cruising range exclusion [m/s²]
+    float accel = StandardMetrics.ms_v_pos_acceleration->AsFloat();
+    if (accel > min_accel)
+      {
+      m_drive_accelcnt++;
+      m_drive_accelsum += accel;
+      }
+    else if (accel < -min_accel)
+      {
+      m_drive_decelcnt++;
+      m_drive_decelsum += accel;
+      }
     }
   else if (metric == StandardMetrics.ms_v_bat_power)
     {
@@ -1628,9 +1763,11 @@ void OvmsVehicle::NotifyVehicleOn()
 
 void OvmsVehicle::NotifyVehicleOff()
   {
-  float min_trip_length = MyConfig.GetParamValueFloat("notify", "log.trip.minlength", 0.2);
-  if (StdMetrics.ms_v_pos_trip->AsFloat() >= min_trip_length)
+  float trip = StdMetrics.ms_v_pos_trip->AsFloat();
+  if (trip >= MyConfig.GetParamValueFloat("notify", "log.trip.minlength", 0.2))
     NotifyTripLog();
+  if (trip >= MyConfig.GetParamValueFloat("notify", "report.trip.minlength", 0.2))
+    NotifyTripReport();
   NotifiedVehicleOff();
   }
 
@@ -1719,6 +1856,19 @@ void OvmsVehicle::NotifyTripLog()
   MyNotify.NotifyString("data", "log.trip", buf.str().c_str());
   }
 
+void OvmsVehicle::NotifyTripReport()
+  {
+  // Send trip report notification
+  //  Notification type "info", subtype "drive.trip.report" 
+  bool send_report = MyConfig.GetParamValueBool("notify", "report.trip.enable", false);
+  if (send_report)
+    {
+    StringWriter buf(200);
+    CommandStatTrip(COMMAND_RESULT_NORMAL, &buf);
+    MyNotify.NotifyString("info", "drive.trip.report", buf.c_str());
+    }
+  }
+
 OvmsVehicle::vehicle_mode_t OvmsVehicle::VehicleModeKey(const std::string code)
   {
   vehicle_mode_t key;

vehicle/OVMS.V3/components/vehicle/vehicle.h

@@ -348,6 +348,16 @@ class OvmsVehicle : public InternalRamAllocated
     int m_last_chargetime;                  // duration of current/most recent charge [s]
     int m_last_gentime;                     // duration of current/most recent generator run [s]
 
+    float m_drive_startsoc;                 // SOC at drive start (vehicle.on)
+    float m_drive_startrange;               // Range estimation at drive start (vehicle.on)
+    float m_drive_startaltitude;            // Altitude at drive start (vehicle.on)
+    uint32_t m_drive_speedcnt;              // Driving speed average data
+    double m_drive_speedsum;                // Driving speed average data
+    uint32_t m_drive_accelcnt;              // Driving acceleration average data
+    double m_drive_accelsum;                // Driving acceleration average data
+    uint32_t m_drive_decelcnt;              // Driving deceleration average data
+    double m_drive_decelsum;                // Driving deceleration average data
+
   protected:
     uint32_t m_ticker;
     int m_12v_ticker;
@@ -388,6 +398,7 @@ class OvmsVehicle : public InternalRamAllocated
   protected:
     virtual void NotifyGridLog();
     virtual void NotifyTripLog();
+    virtual void NotifyTripReport();
 
   protected:
     virtual int GetNotifyVehicleStateDelay(const std::string& state) { return 3; }
@@ -493,6 +504,7 @@ class OvmsVehicle : public InternalRamAllocated
 
   public:
     virtual vehicle_command_t CommandStat(int verbosity, OvmsWriter* writer);
+    virtual vehicle_command_t CommandStatTrip(int verbosity, OvmsWriter* writer);
     virtual vehicle_command_t ProcessMsgCommand(std::string &result, int command, const char* args);
 
   public:
@@ -736,6 +748,7 @@ class OvmsVehicleFactory
     static void vehicle_charge_stop(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);
     static void vehicle_charge_cooldown(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);
     static void vehicle_stat(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);
+    static void vehicle_stat_trip(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);
     static void bms_status(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);
     static void bms_reset(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);
     static void bms_alerts(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv);

vehicle/OVMS.V3/components/vehicle/vehicle_shell.cpp

@@ -417,6 +417,20 @@ void OvmsVehicleFactory::vehicle_stat(int verbosity, OvmsWriter* writer, OvmsCom
     }
   }
 
+void OvmsVehicleFactory::vehicle_stat_trip(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv)
+  {
+  if (MyVehicleFactory.m_currentvehicle==NULL)
+    {
+    writer->puts("Error: No vehicle module selected");
+    return;
+    }
+
+  if (MyVehicleFactory.m_currentvehicle->CommandStatTrip(verbosity, writer) == OvmsVehicle::NotImplemented)
+    {
+    writer->puts("Error: Functionality not available");
+    }
+  }
+
 void OvmsVehicleFactory::bms_status(int verbosity, OvmsWriter* writer, OvmsCommand* cmd, int argc, const char* const* argv)
   {
   if (MyVehicleFactory.m_currentvehicle != NULL)