Vehicle - Devices
The Admin interface handles web service calls from the Admin web gui. The base url for this is at:
/api/vehicle-admin
A JSON file with OpenAPI data about all vehicle-related admin APIs can be downloaded here.
Get Device
Gets details about a specific device:
- GET /v1/devices/{id}
Gets details about a specific device
- Parameters
id (integer) – The id of the device
- Status Codes
200 OK – Success
- DELETE /v1/devices/{id}
Marks a device as deleted
- Parameters
id (integer) – The id of the device to mark as deleted
- Status Codes
200 OK – Success
Returns a Json positive response and the details of the device corresponding to the ID provided in the request:
{
"SerialNumber": "KQKHVXQRGUJBWAV", // String
"CreatedDate": "2020-09-09T12:14:30Z", // DateTime
"CommunityGuid": "1b8cffd5-c94a-40cf-b646-aa95224c3a77", // Guid
"CommunityName": "Community name", // String
"Manufacturer": "Dummy Device Corp.", // String
"ModelMain": "Dummy Box", // String
"ModelSubtype": "Dummy Box", // String (nullable)
"HardwareVersion": "1.0", // String
"PlatformVersion": "1.0", // String
"SoftwareVersion": "a102051b", // String
"HardwareAddress": "3E:8A:19:C0:6F:69", // String
"ReferenceToken": null, // String (nullable)
"ExternalGuid": "90418565-3154-43ef-9559-74bb3edf915f", // Guid
"Guid": "66c9b1a9-e4cf-4ba0-9c2b-5dd03a240c73", // Guid
"InstallationDate": "2020-09-09T12:14:32Z", // DateTime (nullable)
"LastMaintenanceDate": null, // DateTime (nullable)
"LastResetDate:" null, // DateTime (nullable)
"ExternalId": null, // String (nullable)
"LastEventReceived": null, // DateTime (nullable)
"LastHFEventReceived": null, // DateTime (nullable)
"EventPollStartDate": "2020-09-09T12:14:30Z", // DateTime
"LastSynchronization": null, // DateTime (nullable)
"LastNetworkSignalStrengthPct": 72, // Int (nullable)
"LastNetworkInfo": "51", // String (nullable)
"Driver": "00000000-0000-0000-0000-000000000000", // Guid
"IsEnabled": false, // Boolean
"DriverName": "Dummy Device", // String
"CanExecuteCommands": false, // Boolean
"ID": 2 // Int
}
If there is no device corresponding to the ID provided or if there was a problem retrieving the data, a plain Json negative response will be returned.
The CanExecuteCommands fields specified if the device accepts direct commands (i.e. door lock/unlock)
Get Device list
Gets the paged list of devices:
- GET /v1/devices/list
Gets the list of devices
- Query Parameters
driver (string) –
- Status Codes
200 OK – Success
The API accepts an optional query parameter driver set with an on board device driver Guid, and
returns a list of all device records:
[
{
"SerialNumber": "KQKHVXQRGUJBWAV", // String
"CreatedDate": "2020-09-09T12:14:30Z", // DateTime
"CommunityGuid": "1b8cffd5-c94a-40cf-b646-aa95224c3a77", // Guid
"CommunityName": "Community name", // String
"Manufacturer": "Dummy Device Corp.", // String
"ModelMain": "Dummy Box", // String
"ModelSubtype": null, // String
"HardwareVersion": "1.0", // String
"PlatformVersion": "1.0", // String
"SoftwareVersion": "a102051b", // String
"HardwareAddress": "3E:8A:19:C0:6F:69", // String
"ReferenceToken": null, // String
"ExternalGuid": "90418565-3154-43ef-9559-74bb3edf915f", // Guid
"Guid": "66c9b1a9-e4cf-4ba0-9c2b-5dd03a240c73", // Guid
"InstallationDate": "2020-09-09T12:14:32Z", // DateTime (nullable)
"LastMaintenanceDate": null, // DateTime (nullable)
"LastMaintenanceDate": null, // DateTime (nullable)
"ExternalId": null, // String (nullable)
"LastEventReceived": null, // DateTime (nullable)
"LastHFEventReceived": null, // DateTime (nullable)
"EventPollStartDate": "2020-09-09T12:14:30Z", // DateTime
"LastSynchronization": null, // DateTime (nullable)
"LastNetworkSignalStrengthPct": 72, // Int (nullable)
"LastNetworkInfo": "51", // String (nullable)
"Driver": "00000000-0000-0000-0000-000000000000", // Guid
"IsEnabled": false, // Boolean
"DriverName": "Dummy Device", // String
"CanExecuteCommands": false, // Boolean
"ID": 2 // Int
},
...
]
The CanExecuteCommands fields specified if the device accepts direct commands (i.e. door lock/unlock)
Add or edit Device
Persists edits about a new device:
The body of the request is:
{
ID: 4, // Int
SerialNumber: "948973030246021", // String
ExternalGuid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
ExternalId: "...", // String (nullable)
PlatformVersion: "V. 1.0", // String (nullable)
Manufacturer: "Manufacturer name", // String (nullable)
ModelMain: "Main name of the article", // String (nullable)
Driver: "53155c4a-b2a0-412f-ab41-552d9ccdf784" // Guid
}
Returns a plain Json positive response if the record was successfully added, or a plain Json negative response if there was a problem while processing the request.
Possible other error messages are:
err_InvalidElementNo Driver or SerialNumber has been provided in the request body, or no device to edit has been found for the provided
ID
Delete Device
Marks a device as deleted:
- GET /v1/devices/{id}
Gets details about a specific device
- Parameters
id (integer) – The id of the device
- Status Codes
200 OK – Success
- DELETE /v1/devices/{id}
Marks a device as deleted
- Parameters
id (integer) – The id of the device to mark as deleted
- Status Codes
200 OK – Success
Returns a plain Json positive response and marks the corresponding record as deleted.
Possible error messages:
err_ElementDoesNotExistNo record corresponds to the
IDprovidederr_ElementAlreadyDeletedThe corresponding record is already marked as deleted
Get Device events
Gets the list of events for the specified device (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/devices/{id}/device-events
Gets the list of events for the specified device
- Parameters
id (integer) – The id of the device
- Status Codes
200 OK – Success
Returns a list of all the events for device corresponding to the ID provided:
[
{
ID:6789, // Int
DeviceTimestamp: "2001-01-01T01:01:01Z", // DateTime
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
ExtEventId: "...", // String
Type: "Event type", // String
PropertyName: "Name of the event property", // Strine
PropertyValue: "Value of the event property", // String
Source: "softlogic", // String
LastElaborationAttempt: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastElaborationSuccessful: true // Boolean
},
...
]
Type, PropertyName and PropertyValue changes according to the manufacturer and model of the device
Get Device actions
Gets the list of actions commanded on the specified device (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/devices/{id}/device-actions
Gets the list of actions commanded on the specified device
- Parameters
id (integer) – The id of the device
- Status Codes
200 OK – Success
Returns the list of all the actions sent to the specified device:
[
{
ID: 140, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
KeepTryingUntil: "2001-01-01T01:01:01Z", // DateTime (nullable)
Command: "Command identifier", // String
Parameters: "Command parameters" // String
EnteredBy: "Administrator", // String
LastExecutionAttempt: "2001-01-01T01:01:01Z", // DateTime (nullable)
ShouldTryAgain: true, // Boolean
IsSuccessful: false, // Boolean (nullable)
Response: "Response JSON", // String
LastAttemptId: "f18347beb0d84313ab0a6bafebaae27b", // String
EnteredById: "53155c4a-b2a0-412f-ab41-552d9ccdf784" // Guid (nullable)
},
...
]
Command, Parameters and Response changes according to the manufacturer and model of the device
Tests device binding
Tests binding to a device, connecting the serial number to the driver:
- POST /v1/devices/test-bind
Tests binding to a device, connecting the serial number to the driver
- Status Codes
200 OK – Success
The body of the request is:
{
SerialNumber: "948973030246021", // String
Driver: "53155c4a-b2a0-412f-ab41-552d9ccdf784" // Guid
}
Returns a Json positive response and the information of the test binding:
{
result: true, // Boolean
guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
id: "...", // String
mfg: "Manufacturer name", // String
modelMain: "Main name of the article", // String
platfVer: "V. 1.0" // String
}
Returns a plain Json negative response if no driver or serial number has been provided, or if there was an error while testing the binding between the device and the driver.
The fields ExternalGuid and ExternalId are identifier related to the specific vendor platform.
Reset Device
Tries to perform a reset operation on the specified device:
- POST /v1/devices/reset
Tries to perform a reset operation on the specified device
- Status Codes
200 OK – Success
The body is of the request is the following:
{
ID: 123 // Int
ResetType: 0 // Int
}
where ID corresponds to a valid device record to reset.
If the device was successfully reset, it will return a Json positive answer and the result:
{
result: true // Boolean
}
ResetType defines what module of the device has to be reset, and its values type must be one of the ResetType enumeration.
Returns a plain Json negative response if the ID provided does not correspond to any existing device or if there was an errror while executing the command.
Test Device
Performs a device test operation on the specified device:
- POST /v1/devices/test-device
Performs a device test operation on the specified device
- Status Codes
200 OK – Success
The body of the request is:
{
ID: 123, // Int
TestType: 0, // Int
RetryTime: 10 // Int
}
where ID corresponds to a valid device record to test.
TestType defines the type of test that is being performed on the device and its values type must be one of the TestType enumeration.
RetryTime indicates how many minutes the system should attempt to execute the command in the event of a failure
Some tests can only performend by valid administrator accounts with SuperUser priviliges.
If the execution of the command is successful it will return a Json positive response and the result of the test:
{
result: true
}
The request will return a plain Json negative response if the ID provided does not correspond to any existing device, if the the TestType is not a valid value or if the was a problem while testing the device
or a Unauthorized message if you cannot.
Bind Device to Vehicle
Binds a device to a vehicle (Indicates which vehicle the device is mounted on). Must be performed at installation:
- POST /v1/devices/bind-to-vehicle
Binds a device to a vehicle. Must be performed at installation.
- Status Codes
200 OK – Success
The body of the request is:
{
ID: 34, // Int
VehicleID: 12 // Int
}
where ID corresponds to a valid unbound device and VehicleID to a valid vehicle.
Returns a plain Json positive response if the device has been successfully assigned to the vehicle in the platform.
A plain Json negative response is returned if there is no device corresponding to the ID provided in the body
or a Unauthorized message if you cannot.
Possible error messages are:
err_NoVehicleFoundThere is no vehicle corresponding to the ID provided in the request body
err_DeviceAlreadyInstalledThe specified device is already bound to another vehicle
err_MissingVehicleDataThe device’s driver needs some additional vehicle data, and one or more data is missing on the vehicle
Remove Device from Vehicle
Unbinds a device from the vehicle it is on:
- POST /v1/devices/remove-from-vehicle
Unbinds a device from the vehicle it is on.
- Status Codes
200 OK – Success
The request body is:
{
ID: 34 // Int
}
where ID corresponds to a valid device currently bound to a vehicle.
If the device is successfully removed from the vehicle, a plain Json positive response will be returned.
Returns a plain Json negative response if the ID provided in the body does not correspond to an existing device
or a Unauthorized message if you cannot.
Possible error messages are:
err_NoVehicleFoundThe specified device is not currently bound to any vehicle
Get Device Status
Queries the device manufacturer’s API to retrieve the value read from the device.
- GET /v1/devices/{id}/device-status
Get all vehicle info on demand
- Parameters
id (integer) – Vehicle ID
- Status Codes
200 OK – Success
This API returns a positive JSON response with the data read from the device:
{
OdometerKm: 13596, // Int (nullable)
FuelLevelPct: 74, // Int (nullable) (Percentage of fuel level left)
ServiceBatteryVoltageDec: 130, // Int (nullable) (Vehicle battery level in dV)
GPSSatelliteCount: 9, // Int (nullable) (Number of GPS satellites connected to the device)
GPSLatitude: 42.134, // Double (nullable)
GPSLongitude: 12.3467, // Double (nullable)
GPSAltitude: 2.5, // Double (nullable)
GPSSpeedKmh: 30.5, // Double (nullable)
AccelX: 0, // Double (nullable) (Vehicle acceleration on the x axys)
AccelY: 0, // Double (nullable) (Vehicle acceleration on the y axys)
AccelZ: 0, // Double (nullable) (Vehicle acceleration on the z axys)
IsDashboardPowered: true, // Boolean (nullable)
IsEngineRunning: true, // Boolean (nullable)
IsDoorClosed: true, // Boolean (nullable)
IsHandbrakeOn: true, // Boolean (nullable)
IsCharging: true, // Boolean (nullable)
IsChargingComplete: true, // Boolean (nullable)
NetworkSignalStrengthPct: 45, // Int (nullable)
NetworkTechnology: "3G", // String (nullable)
HardwareVersion: "2.0", // String (nullable)
SoftwareVersion: "1.0", // String (nullable)
DeviceTemperatureDegC: 25, // Int (nullable)
ExternalTemperatureDegC: 26, // Int (nullable)
CANBusStatus: true, // Boolean (nullable) (Connection status of the CanBus)
BTStatus: true, // Boolean (nullable) (True if the BlueTooth module is working)
AdditionalData: // Additional Data Array
[
{
Label: "rpm", // String
Value: "15", // String
Type: 1 // Int (enum AdditionalValueType)
},
...
]
}
or an error in case of problems.
The field AdditionalData is an array of data not stored in their specific property: Label refers to a normalized string, to describe
which data is represented in that AdditionalData regardless of the driver manufacturer; Value is the value of the data; Type
can be one of the value defined in the AdditionalValueTypes enumeration.
The enumeration type accepts a list of valid values. Please refer to Device Retrieved Data for a complete list of additional data and their values.