The data flow is prone to various fault scenarios, and this section covers how to check and work around some basic scenarios. As described in the overall dataflow section, a key point with the solution is that Vessel Insight sends raw data as-is from the data sources onboard.
In a scenario where no new data is available in the API, the root cause is typically:
- No connectivity: Vessel does not have internet connection, so no new data will be sent to cloud. The data is buffered on edge and queued for sending to cloud once connectivity is back up.
- No data from source systems: The data sources are not sending any data to the edge computer, so there is no data sent to cloud.
- Vessel Insight issues or maintenance: The platform is undergoing maintenance or experiencing an issue.
Check connectivity of vessel
For an API user, the connectivity status of a vessel can be checked by querying the status of the router onboard. For each vessel, there is a path under the Edge Devices folder: Fleet/imoxxx/Edge_Devices/Router/Router_Status.
Note that this is a datatype called state event, and not a timeseries datatype (continuous numeric values).
API request to the get state ID (one time job, the router status node ID will not change):
curl -L 'https://api.kognif.ai/assets/v2/assetmodel/nodes?nodeType=StateEventLog&path=%2FFleet%2FimoXXX%2FEdgeDevices&maxLevelOfEdges=0'
\-H 'Ocp-Apim-Subscription-Key: YOUR KEY'
\-H 'Authorization: ••••••'
Response:
[
{
"id":"109502",
"name":"Router_Status",
"displayName":"Router Status",
"nodeType":"StateEventLog",
"path":"/Fleet/imoXXX/EdgeDevices/Router/Router_Status",
"hasEdges":false,
"edges":[
],
"stateSeriesId":"109502"
}
]
The response contains the ID ("stateSeriesId":"109502") we'll use to the get the data.
Get router status
Now that we have the stateSeriesId, we can query the latest status from the States endpoint.
Request:
curl -L 'https://api.kognif.ai/assets/v2/states/LatestValue/109502'
\-H 'Ocp-Apim-Subscription-Key: YOUR KEY'
\-H 'Authorization: ••••••'
The response contains the latest status along with the latest timestamp.
- state=0 means the router is offline.
- state=1 means the router is online.
- state=2 means the router is recovering - will not stream data.
{
"109502":{
"time":"2024-11-05T02:30:24.28Z",
"state":1,
"manualOverride":true,
"description":"Status of router device",
"author":"GSN Data Polling Serivice",
"previousState":1
}
}
Get when router was last seen
To check when the router was last seen (online), we can use the path /Fleet/imo9686388/EdgeDevices/Router/Last_Seen
We'll query the Last Seen path to see when the router was last online. We'll use the POST Get Latest Value endpoint with path above. Request curl:
curl -L 'https://api.kognif.ai/assets/v2/timeseries/LatestValue/Paths?includeNaN=true&convertToStdUnit=true' \
-H 'Ocp-Apim-Subscription-Key: YOUR KEY' \
-H 'Content-Type: application/json' \
-H 'Authorization: ••••••' \
-d 'body'
With body containing the target Last seen path:
["/Fleet/imoxxx/EdgeDevices/Router/Last_Seen"]
The values item in the response contains the Last Seen timestamp represented as Unix epoch time. More info here:
https://www.epochconverter.com/
. It will not change as long as the router is offline. Once back online, the value will switch back to current timestamp of the latest ping from the router.
{
"/Fleet/imoXXX/EdgeDevices/Router/Last_Seen":{
"timestamp":"2024-11-11T12:00:17.3550000Z",
"values":[
1731030840
],
"vectorElementData":[
{
"name":"Last_Seen",
"displayName":"Last Seen",
"unitId":"1/1",
"displayUnitId":"1/1"
}
]
}
}
Check data rate from data sources
Each of the data sources interfaced to the edge computer can be found under the EdgeDevices folder: /Fleet/imoXXX/EdgeDevices/. This folder contain various system info per data source, one of them is the Average Rate. The Average Rate (AvgRate) measures how much data is ingested into Vessel Insight cloud from that particular source. It can be used to check if Vessel Insight is receiving data in the cloud from the data source.
If no data is recieved in the cloud, the AvgRate will not update. So an AvgRate with an timestamp that has not updated for a while, indicates that data is not flowing.
Different vessels may have different data sources interfaced to the edge with different protocols and setups, such as MQTT, Modbus and NMEA. Each source gets a dedicated folder with relevant metrics. The path syntax is:
/Fleet/imoXXX/EdgeDevices/<iot_device_id>/Generic/Connectors/<Interface>/Sources/<Source_1>/AvgRate
Note that the vessel may have several sources interfaced, and the quickest way to identify them is to search for AvgRate in the response and look at the paths. Some examples are:
NMEA Source
/Fleet/imoxxx/EdgeDevices/<iot_device>/Generic/Connectors/Nmea/Sources/ECDIS_NMEA/AvgRate
Modbus source
/Fleet/imoxxx/EdgeDevices/<iot_device>/Generic/Connectors/Modbus/Sources/rpm/AvgRate
To fetch the relevant nodes, we can use the path filter endpoint with conditions to only return non-empty paths in the Edge Device folder from the Assetmodel Find endpoint.
Curl:
curl -L 'https://api.kognif.ai/assets/v2/assetmodel/nodes'
\-H 'Ocp-Apim-Subscription-Key: your key'
\-H 'Content-Type: application/json'
\-H 'Authorization: ••••••'
\-d 'body'
Body with filters:
{
"path":"/Fleet/imoxxx/EdgeDevices",
"attributeCondition":{
"attributeName":"latestTimestamp",
"operator":"isnotempty"
},
"view":"v1",
"attributeKeys":[
"latestTimestamp"
]
}
The response contains all non empty paths, but we are looking for the paths containing AvgRate. In this example, the vessel only has a MQTT interface to a K-Chief 600 system.
{
"id":298039,
"name":"AvgRate",
"displayName":"AvgRate",
"nodeType":"TimeSeries",
"path":"/Fleet/imoxxx/EdgeDevices/n17878_iot2_001/Generic/Connectors/MQTT/Sources/K_Chief_600/AvgRate",
"hasEdges":false,
"edges":[
],
"attributes":{
"displayName":"AvgRate",
"latestTimestamp":"2024-11-05 10:29:00+00",
}
}
We can use these paths to query the latest average data rate from the sources. From the example response, we'll use the source AvgRate path as input to the Get Latest endpoint.
curl -L 'https://api.kognif.ai/assets/v2/timeseries/LatestValue/Paths?includeNaN=true&convertToStdUnit=true'
\-H 'Ocp-Apim-Subscription-Key: your key'
\-H 'Content-Type: application/json'
\-H 'Authorization: ••••••'
\-d '["/Fleet/imoxxx/EdgeDevices/n17878_iot2_001/Generic/Connectors/MQTT/Sources/K_Chief_600/AvgRate"]'
Response:
{
"/Fleet/imoxxx/EdgeDevices/n17878_iot2_001/Generic/Connectors/MQTT/Sources/K_Chief_600/AvgRate":{
"timestamp":"2024-11-05T15:03:00.0000000Z",
"values":[
22.116666666666667
],
"vectorElementData":[
{
"name":"average ingest rate",
"displayName":"average ingest rate",
"unitId":"Hz",
"displayUnitId":"Hz"
}
]
}
}
For vessels with multiple sources, the paths for each source can be added to the request body.
