Drivetrain Analyzer API¶

Drivetrain Analyzer Cloud allows you to programmatically read the data of your connected motor fleet via Insights Hub Services and Industrial loT APIs.

Getting technical token for accessing Insights Hub APIs¶

You require the Drivetrain Analyzer Cloud API key for your tenant. You can find this in the Settings page.

Here, you can view your API key and the expiration date of your API key. The system sends you an email if the expiration date is to expire within 0 to 7 days or has already expired. You can generate your new API key if it is to expire within 0 to 7 days. If the expiration date is longer than 7 days, then button "Generate" is deactivated. If an API key is not displayed in the dialog after you click on "Generate", then you are notified that you should contact user support.

NOTE:

Security measures

Drivetrain Analyzer Cloud API key must be kept secret.

• Ensure that the transport of the key is secured by technical measures such as encrypted/signed emails, encrypted/signed USB flash drives, etc., specially >in public areas such as the Internet.
• Store the key in the OEM/end customer area in such a way that it is protected from unauthorized access (e.g. on SharePoints, databases, etc. through user >management with access data).

With the Drivetrain Analyzer Cloud key, request your bearer token (access token) using the following

HTTP request:

GET /public/iqtoken/token?key={your Drivetrain Analyzer Cloud API key} HTTP/1 .1

Host:

Region - Europe 1 (Insights Hub on AWS): iqtoken-visualflowcreatorhttp.eul.mindsphere.io

HTTP Response:

{
    "access_token": {Bearer Token},
    "token_type": "bearer",
    "expires_in": 1799,
    "scope": "mdsp:core:Admin3rdPartyTechUser",
    "jti": "9d53d67bb046437d90c309c3a228d942",
    "timestamp": 1613126706928
}

Use the {bearer token} to call the Industrial loT APIs and access your client tenant's data.

More Information:

More information on calling up the Industrial loT Endpoints is provided in the Insights Hub documentation (https://documentation.mindsphere.io/MindSphere/howto/howto-selfhosted-api-access.html#caIling-mindsphere-endpoints).

Reading assets and asset properties for the EU1 region (Insights Hub running on AWS)¶

The following provides an overview of the data that you can access as a user of your client tenant.

Drivetrain Analyzer Cloud assets¶

Asset variables¶

Drivetrain Analyzer Cloud assets are of the type "Simotics" (core.basicdevice -> tenant_name."Simotics").

• AgentSerialNumer: serial number of the Connection Module IOT device
• Application: motor application Possible values are: Pump, fan, compressor, other
• AssetTypeVersion: asset type version number
• BatteryRuntimeLeft: estimate of the remaining battery time in months
• BatteryStatus: battery status as a percentage (%)
• BearingCondition: Motor bearing condition Possible values are: {0 = calibration/missing data, 1 = OK , 2 = low/medium probability of failure, 3 = high probability of failure}
• Conditionstate: asset status that is derived from the open reports in the logbook. Possible values are: {0 = OK, 1 = info, 2 = warning, 3 = error, 4 = unknown}
• Connected At: date and time of the last data that Connection Module IOT transferred to SI IQ Fleet
• Connectionstate: Connection Module IOT connection status. Possible values: {0 = connected, 1 = temporarily interrupted, 2 = disconnected}
• CreateDate: date and time that the asset was created
• DigitalTwinVersion: (internal) motor digital twin version, which is used during the onboarding
• ElectricalDatalndex: selected motor operating point index
• FirmwareVersion: installed firmware version of Connection Module IOT
• GenericVibrationMonitoring: true, if Connection Module IOT was onboarded as sensor for generic vibration monitoring.
• ManufacturerProductNumber: manufacturer's product article number (MLFB) of the motor
• OperatingMode: Motor operating mode Possible values are: {1 = DOL, 2 = VSD}
• PoleNumber: number of motor poles
• Relubricationinterval: motor relubrication interval in hours
• ScanCycle: Connection Module IOT sensor measurement interval in the "duration" format defined in standard ISO 8601
• SerialNumber: motor serial number
• TransmitCycle: Connection Module IOT data transfer interval in the "duration" format defined in standard ISO 8601
• VoltageDropResets: number of Connection Module IOT brownout resets

You can call up the list of assets integrated in the application and the variables of each asset using the "Asset Management Service" of Insights Hub.

The documentation and the API specification can be found at the following link (https://documentation.mindsphere.io/MindSphere/apis/advanced-assetmanagement/api-assetmanagement-overview.html)

Example:

GET https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets

Header:

Content-Type: application/json
Authorization: Bearer <Bearer Token>

Signals¶

All Time Series data of the IQFIeet signaIs are available in the aspects of the "Simotics" asset type:

In order to read out the SIDRIVE IQ Fleet signals, all data points within a time period are provided by the "IOT Time Series Service" of Insights Hub. The description and the API specification can be found at the following link: (https://documentation.mindsphere.io/MindSphere/apis/iot-iottimeseries/api-iottimeseries-overview.html)

As an alternative to individual data points, you can also use the "Aggregates Service" of Insights Hub. The description is provided at the following link: (https://documentation.mindsphere.io/MindSphere/apis/iot-iottsaggregates/api-iottsaggregates-overview-v4.html)

Example - IOT Time Series Service:

GET https://gateway.eu1.mindsphere.io/api/iottimeseries/v3/timeseries/789ffa1f911f4cc08e5a8021208d9476/LowFrequency?to=2020-07-11T07:00:00.00Z&sort=desc

Header:

Content-Type: application/json
Authorization: Bearer <Bearer Token>

Example - Aggregates Service:

GET https://gateway.eu1.mindsphere.io/api/iottsaggregates/v3/aggregates/daa80a036ad74578b49c72e76ded3a24/LowFrequency?select=ElectricalEnergy&intervalUnit=hour&from=2020-05-01T00:00:00.000Z&to=2020-06-23T08:00:00.00Z&intervalValue=8

Header:

Content-Type: application/json
Authorization: Bearer <Bearer Token>

Notifications¶

Logs¶

Event type: IQFIeetEvent
Event Type Id: 015578eb-c77a-4f85-8ac7-8fbbd6e1d181

You can access all protocols that were created for the assets of the tenant via the "Event Management Service" of Insights Hub. The documentation and the API specification can be found at the following link: (https://documentation.mindsphere.io/MindSphere/apis/advanced-eventmanagement/api-eventmanagement-overview.html)

Example:

GET https://gateway.eu1.mindsphere.io/api/eventmanagement/v3/events?filter={%22and%22:{%22timestamp%22:{%22after%22:%222019-04-26T21:00:00.000Z%22},%22typeId%22:%22015578eb-c77a-4f85-8ac7-8fbbd6e1d181%22}}

Header:

Content-Type: application/json
Authorization: Bearer <Bearer Token>

Example response model:

{
    "id": "7d7f518f-5962-40e6-bbdd-6d82a48f977d",
    "typeld": "015578eb-c77a-4f85-8ac7-8fbbd6eldl81",
    "correlationld": "63884d7db29503c577262efa351192b3",
    "timestamp": "2022-12-01T00:45:45Z",
    "entityld": "b3cf3b0191d64fb5a5clebedl91d2506",
    "etag": 0,
    "_links": {
        "self": {
        "href": "https://gateway.eul.mindsphere.io/api/eventmanagement/v3/events/7d7f518f-5962-40e6-bbdd-6d82a48f977d"
        }
    },
    "logType": "multiplethresholdviolation",
    "severity": 20,
    "kpiValue": "14.0674",
    "acknowledged": false,
    "kpiName": "RMSVelY",
    "description": "Error Threshold Connect Vibration Tangential(y)",
    "thresholdvalue": "10",
    "date2": "2022-12-01T06:44:39.000Z",
    "datel": "2022-12-01T00:45:45.000Z",
    "title": "Error Threshold Connect Vibration Tangential (y)",
    "serviceTag": false,
    "comment": "",
    "detail": "Between 12/1/2022 12:45:45 AM and 12/1/2022 6:44:39 AM, the Connect Vibration Tangential (y) error threshold value 10 mm/s has been exceeded by 46 data point(s) with the maximum value of 14.067 mm/s.",
    "category": "",
    "parameterl": "46"
}

Comments¶

Event Type: IQFIeetCommentEvent
EventTypeld: 953b41 43-fc09-4ebe-a05d-eeb0a5c6af34

Example response model:

{
    "id": "3cc0f416-7f7a-41a8-b005-390c6d9def0d",
    "typeld": "953b4143-fcO 9-4ebe-a05d-eeb0a5c6af34",
    "correlationld": "638864a59080059201c35254c34fdc21",
    "timestamp": "2022-12-01T08:24:05.114Z",
    "entityld": "b3cf3b0191d64fb5a5clebedl91d2506",
    "etag": 0,
    "_links": {
        "self": {
        "href": "https://gateway.eul.mindsphere.io/api/eventmanagement/v3/events/3cc0f416-7f7a-41a8-b005-390c6d9def0d"
        }
    },
    "severity": 0,
    "parentLogld": "7d7f518f-5962-40e6-bbdd-6d82a48f977d",
    "acknowledged": false,
    "serviceTag": false,
    "userEmail": "user@email.com",
    "commentText": "This is a comment"
}