Smoke Detection API⚓︎
The Smoke Detection API allows you to retrieve a PDF with details about a smoke event that was detected in one of your vehicles.
The Smoke Detection is also part of the INVERS Events API.
It provides events that are delivered to your booking system whenever a smoke event or potential smoke event was detected in one of your vehicles.
Particulate Matter Data (PM2.5)⚓︎
PM2.5 refers to fine particulate matter, 2.5 micrometers or smaller. It’s crucial in smoking detection because tobacco smoke is a major source of PM2.5.
- The additional sensor SDM+ monitors the concentration of PM2.5 in the interior
- The CloudBoxx unit will record detailed PM2.5 data if an internal threshold is crossed
- The recorded data is being sent to our smoke detection service for evaluation
- If the smoke detection service detects a smoke, SmokeDetected and SmokeDataReady events will be triggered (see below for more details).
- Refer to our help page for an installation guide of the SDM+
SmokeDetected and SmokeDataReady⚓︎
When the particulate matter data of a CloudBoxx unit arrives at the Smoke Detection service, it will start an evaluation which might result in sending SmokeDetected and SmokeDataReady events. However, if the conclusion is, that the evaluated particulate matter data does not show patterns of smoke, no event will be sent.
In case the evaluation is that smoke has been detected, two events will be sent.
The SmokeDetected event will be sent as soon as smoke has been detected. Internally, our services gather and interpret data for some time before notifying you to ensure an actual smoke event took place. Therefore, the SmokeDetected event does not mark the first occurrence of particulate matter in the interior.
The SmokeDataReady event will be sent when the internal particulate matter data stream ends and the smoke incident is considered finished. This event will always occur after a SmokeDetected event, but the time between both events may vary dependent on the duration of the smoke incident. This event contains particulate matter metrics of the smoke incident as well as a summary of the vehicle’s state during that time period.
Which Event To Use? / Use Cases⚓︎
SmokeDetected⚓︎
The SmokeDetected event is relevant for being notified about smoke as soon as possible. It offers information about the detected starting point of the smoke.
Excerpt of a SmokeDetected message:
metadata:
type: SmokeDetected
[...]
data:
smoke_detection_id: 01F1FHJ7SHQK5MGF69B8K2346E
[...]
start:
timestamp: '2024-01-01T00:00:00Z'
doors_status:
timestamp: '2024-01-01T00:00:00Z'
value: OPEN
windows_status:
timestamp: '2024-01-01T00:00:00Z'
value: OPEN
ignition:
timestamp: '2024-01-01T00:00:00Z'
value: 'ON'
in_motion:
timestamp: '2024-01-01T00:00:00Z'
value: true
position:
timestamp: '2024-01-01T00:00:00Z'
value:
lat: 50.9096417
lon: 8.0647732
SmokeDataReady⚓︎
The SmokeDataReady event may take several minutes or even longer (depending on the passenger’s smoking behavior) so it is not suitable for notifications. However, it offers the most complete information on the smoke incident for later analysis or reporting.
When multiple smoke issues take place inside the vehicle they will appear as one SmokeDataReady event, as long as they are detected within 2.5-minutes time difference. If this time is exceeded between smoke issues the Smoke Detection will identify a separate occurrence of smoking.
Additional Information⚓︎
For more information on Smoke Detection and how it is displayed in FleetControl, please refer to our Help Page.
Smoke Report PDFs⚓︎
Why Use Smoke Report PDFs⚓︎
The Smoke Report PDF provides a comprehensive overview of the smoke event, including all relevant data. Delivered in a portable format, it enables operator personnel to access the report easily and automatically, without requiring additional authentication or access to internal systems. The report can also be seamlessly transmitted to the responsible party and archived in the operator’s systems for more than 90 days in a structured and automated manner.
How to Retrieve Smoke Report PDFs via API⚓︎
The SmokeDataReady event indicates that the smoke process has been completed and that both the visualization in FleetControl and the PDF are available.
This event contains a smoke_detection_id, which can be used to retrieve the PDF via a GET request from the Smoke Detection API.
Important Note⚓︎
The PDF is not available when a SmokeDetected event is triggered, as the smoke process has not yet been completed. In such cases, the API will respond with a 404 Not Found error.
Visualization⚓︎
Once a SmokeDataReady event is available, it is also available in FleetControl.
There you can see additional details of the smoke incident, like the course of the particulate matter over time as well as changes to door and window status. You can also download Smoke Report PDFs via FleetControl.
You can use that to get a better understanding of the incident, if needed.
For more details regarding the FleetControl Visualization refer to the FleetControl Manual.