Add event detection with email notifications 

In this section we explain how you can enable event detection in your Amazon/Google/Azure cloud function (e.g. active DTCs, high temperatures, harsh braking, …). Users can be notified via email and the events can be visualized via our Grafana event summary dashboard. This is useful in e.g. predictive maintenance and diagnostics.

Table of Contents

Add event detection with email notifications

Add event detection via JSON file 

To detect custom signal events via your cloud function, follow below steps:

Ensure you are using the latest cloud function
Download our example events.json below and modify it as per your needs
Once ready, upload it to your input bucket root

events.json

How it works 

Adding the events.json to your input bucket will add the following cloud function behavior:

The function will download and validate your events.json file
For each event entry, it loads the trigger message(s) in messages_filtered_list into a data frame
It determines if/when the event occurs in the file based on specified signal thresholds
If events occur, meta info is added to your Parquet data lake (incl. optionally GPS data[1])
Once per file/event, the function will send an email notification to the user[2]

Below is an illustration of the function for identifying high speed events:

custom-lambda-event-trigger-example-speed

JSON syntax 

To illustrate the JSON syntax, consider the default example below:

{
  "general": {
    "include_gps_data": true,
    "signal_latitude": "Latitude",
    "signal_longitude": "Longitude",
    "messages_gps": ["CAN9_GnssPos"],
    "static_body_content": "Review details via <a href='<dashboard-url>'>your event dashboard</a>"
  },
  "events": [
    {
      "event_name": "HighSpeedAlert",
      "messages_match_type": "equals",
      "messages_filtered_list": [["CAN9_GnssSpeed"]],
      "trigger_signals": ["Speed"],
      "lower_threshold": 5,
      "upper_threshold": 10,
      "rising_as_start": true,
      "exact_match": false,
      "raster": "0.2s"
    },
    {
      "event_name": "DM01_DTC_01_Active",
      "messages_match_type": "contains",
      "messages_filtered_list": "_DM01_DTC_01",
      "trigger_signals": ["DM01_OC"],
      "lower_threshold": 0,
      "upper_threshold": 1,
      "rising_as_start": true,
      "exact_match": false,
      "raster": "1s"
    }
  ]
}

The general section lets you specify what CAN message/signals to use for the event GPS position data - as well as a custom message to be included in email notifications.

The events section contains a list of your custom events, each with an event_name.

The messages_filtered_list reflects the CAN messages that contain the event trigger_signals. If messages_match_type equals "exact", the exact list of CAN messages specified is evaluated. If it equals "contains", the messages_filtered_list should equal a string (not a list) and the event then includes all CAN messages which contain this string in their name. The function loops through each event, message and trigger signal combination as part of the evaluation.

The event detection is evaluated based on ‘rising/falling edges’. For example, a ‘rising edge’ start event ("rising_as_start" = true) is defined as an event where trigger_signal >= upper_threshold after trigger_signal <= lower_threshold in the period since the last event within the log file[3].

If exact_match is true, the signal must equal a specific threshold value to be triggered (e.g. for state-type signals). The raster allows optional resampling (e.g. to reduce jittery behavior).

Hysteresis intervals 

For continuous signals (e.g. temperature, speed) we recommend using a hysteresis interval by adding a gap between the values of upper_threshold and lower_threshold. This helps event detection when your trigger signal fluctuates around your upper_threshold.

For boolean signals you can e.g. set lower_threshold = 0 and upper_threshold = 1. For multi-value state signals, you can use "exact_match": true.

Examples 

Example 1: J1939 DM1 DTCs 

A common message of interest for alerts and event identification is the J1939 DM1 message containing Diagnostic Trouble Code (DTC) information. The default events.json example will evaluate all DM01 messages (across all CAN channels and source addresses) to check if the 1st DTC occurrence count goes from 0 to 1 (or higher), reflecting the activation of the 1st DTC.

Example 2: Multiple tire pressures 

You can specify multiple trigger signals per message. For example, you may have a message with 4 tire pressure signals (one per wheel). By adding all of them in the trigger_signals list, the code will evaluate each signal based on the same event settings.

Email notifications 

By default, if the function detects a ‘start event’ in a decoded file, it publishes a message to the email used during the Parquet data lake deployment. To modify/disable this, proceed as follows:

Amazon: Modify the event alert in SNS subscriptions
Google: Modify the event alert in Alerting
Azure: Modify the event alert in your resource group

Warning

We strongly recommend to test your events.json before deployment to production[4]

[1]	GPS data is a ‘nice-to-have’ meta information that helps you better understand and browse events. The example function will attempt to add GPS data (if found), but the GPS data is not ‘required’ to perform the event identification.

[2]	The event email alert functionality differs slightly between Amazon/Google/Azure and you can to some extent control the behavior of when emails are sent (e.g. to cap the number of emails per time period)

[3] Importantly, the function does not have information beyond the trigger MDF log file. As a result, the example function cannot identify transitions that occur between log files. For example, it may be that trigger_signal < lower_threshold near the end of log file 1. Log file 2 may then start with lower_threshold < trigger_signal < upper_threshold and later go to trigger_signal > upper_threshold. In such a scenario, a ‘rising edge’ event occurred - but the function will not detect it. To minimize such ‘false negative’ events we recommend that you avoid using high-frequent file splitting. Alternatively, you can incorporate basic state management by storing the last value of trigger_signal in a object on S3 (unique per device) and fetching this as part of the function.

[4]	If you make errors in your `events.json` or your data exhibits unexpected behavior, you can end up sending an email notification for every log file processed - which can be inconvenient to clean up in your inbox.