2hBoard Specific Behaviour

The scope of this document is to describe the specific behaviours of the 2hire device (2hBoard) in the 2hire as adapter (2aa) service.

To understand the standard behaviours of 2aa please refer to the developer portal

Installation

In order to install a 2hBoard you'll need to implement the following process:

• Retrieve the profile id for your vehicle's brand and model using the list profiles endpoint

• Register the 2hBoard by providing the qrCode printed on the device and the profileId via the register endpoint

  • If the Vehicle has already been registered with another profile the endpoint will return a CONFLICT_ERROR that provides the id for the already registered vehicle

    JSON

    {
      "code": "CONFLICT_ERROR",
      "errorId": "52410965-9d0b-4dca-861c-aba09f803c10",
      "details": {
        "cause": "PAYLOAD_CONFLICT",
        "raw": {
          "messages": [
          	"Vehicle already registered with another profile"
          ],
          "vehicleId": "b6bb6966-4597-48d1-8115-37243063ef0f"
        }
      }
    }

    • Change the 2hBoard configuration by providing the vehicle id and the profile id via calling the set profile endpoint

  • Please refer to the developer portal's error page for more info on other errors that might be returned

• Wait for the device to be asynchronously configured by polling the profile status endpoint or by subscribing to the vehicle:*:specific:profile_status topic

• Once the 2hBoard has been configured you can test the installation by calling the start and stop endpoints

• Turn on the engine and test if the 2hBoard can correctly gather data from the vehicle by forcing the data extraction and checking the vehicle's signals

Data patterns

The 2hBoard generates position data every 30s while the vehicle is not moving (low_speed) and sends 5 positions every 5s whenever the vehicle is detected moving (high_speed).

Trip detection is performed via GPS, the status of the trip can be queried by calling the trip_detected get signal endpoint, when a trip is detected data extraction from the vehicle is triggered for the configured signals.

Data from the vehicle is extracted every 30s while being in trip and keeps being extracted until the engine is detected being turned off for about 5s.

2hBoards can also be configured to extract data during the execution of a command

Specific Commands

These commands are always available on 2hBoard vehicles, regardless of the profile that is currently associated with the vehicle.

Set profile

Schedules a profile update on a device, the update is asyncronous, watch the profile_status signal to check when the profile finished applying

[POST]/vehicle/{uuid}/command/specific/set_profile

{
  "profileId": "683a6519-1e40-46f9-a27d-06c7d06d9a1a"
}

Response

Success 200

{
  "success": true
}

Error

Please refer to the developer portal's error page

Extract Data

Forces the data extraction to start, if the vehicle's engine is currently off only one data request will be performed, if not the device will continue extracting data until the vehicle is turned off

[POST]/vehicle/{uuid}/command/specific/extract_data

{}

Response

Success 200

{
  "success": true
}

Error

Please refer to the developer portal's error page

Immobilizer on

Immobilizes the vehicle without locking the doors

[POST]/vehicle/{uuid}/command/specific/immobilizer_on

{}

Response

Success 200

{
  "success": true
}

Error

Please refer to the developer portal's error page

Immobilizer off

Removes the vehicle immobilization without unlocking the doors

[POST]/vehicle/{uuid}/command/specific/immobilizer_off

{}

Response

Success 200

{
  "success": true
}

Error

Please refer to the developer portal's error page

Specific Signals

These signals are always available on 2hBoard vehicles, regardless of the profile that is currently associated with the vehicle.

Profile Status

Gets the status of the last scheduled profile update

[GET]/vehicle/{uuid}/signal/specific/profile_status

Response

Success 200

{
	"data": {
    "current": {
      "profileId": "02f9ccc1-6a9a-4be8-b8ef-271c2cdd0031",
      "version": {
        "boxFamily": "2hireBoxV1.0",
        "revision": 1
      }
		}
  },
  "timestamp": 1664396046803
}

 
{
  "data": {
    "pending": {
      "profile": {
        "profileId": "05a34a27-f928-4a63-a1f8-623bf4378753",
        "version": {
          "boxFamily": "2hireBoxV1.5",
          "revision": 1
        },
      },
      "requestTime": 1664396046803,
      "status": "WAITING",
    }
  },
  "timestamp": 1664396046803
}

Error

Please refer to the developer portal's error page

Trip Detected

Gets the last updated status of the trip detection algorithm, which determines if a vehicle is moving or not based on gps position

[GET]/vehicle/{uuid}/signal/specific/trip_detected

Response

Success 200

{
  "data": {
    "value": false
  },
  "timestamp": 1684050846238
}

External Voltage

Gets the last value of the input voltage read by the device.
The value is sent by the device every 30 seconds. During server-side processing, a filter is applied so that the data is forwarded only if there is a voltage variation of at least 0.07 V or if one hour has passed since the last update.

[GET]/vehicle/{uuid}/signal/specific/external_voltage

Response

Success 200

{
  "data": {
    "voltage": 12.686
  },
  "timestamp": 1684252813045
}

Position

Gets the last updated unfiltered position and its related properties

[GET]/vehicle/{uuid}/signal/specific/position

Response

Success 200

{
  "data": {
    "type": "low_speed",
    "fixed": true,
    "latitude": 41.92004395,
    "longitude": 12.52167797,
    "externalVoltage": 13.686,
    "internalVoltage": 4.212
  },
  "timestamp": 1684255585280
}