# editVehicleProfile

Command (Vehicle profiles). updated in 2.1.0 to add userPermission.

Creates or modifies a vehicle profile (updated in 2.1.0 to add userPermission)

Creates or updates a vehicle profile. The profile is what makes BeNav route a 40-tonne articulated
lorry differently from a van: dimensions, weights, trailers, dangerous-goods class and speed limits all
feed the route calculation, so the vehicle is not sent under a low bridge or through a tunnel its load
is barred from.

Sending the command with an id that does not exist creates the profile; sending it with an existing
id updates it. Either way the profile becomes the **currently selected** one, so the next
route is computed for it. A `userPermission` tier decides what the driver can then do with
it on the device, from invisible, through read-only, to fully editable.

**Worth knowing**

- Profiles created over RNC belong to the client application. They are the only ones it can
  select, edit or delete; profiles the driver created by hand are out of reach.
- The `category` decides the transportation mode, overriding the one inside the
  profile if they disagree.
- Editing the profile a journey is already using does not recompute that journey.

**Example: provisioning a fleet from head office**

An operator maintains its vehicle definitions centrally. When a tablet is assigned to a lorry, the
client application pushes that lorry's profile with `editVehicleProfile` (real height,
real weight per axle, real ADR class) and sets `userPermission` so the driver can see the
figures but not change them.

The driver cannot mistype a height and be routed under a bridge, and the operator can correct a
value for the whole fleet without touching a device.

## Command

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "editVehicleProfile",
  "params": {
    "id": "custom_profile_1",
    "name": "Profile 1",
    "userPermission": "LOCKED",
    "majorRoads": true,
    "category": "DELIVERY_TRUCK",
    "profile": {
      "transportationMode": "DELIVERY_TRUCK",
      "height": 4.0,
      "length": 16.0,
      "width": 2.5,
      "weight": 17.0,
      "weightPerAxle": 8.0,
      "nbTrailers": 2,
      "hazmat": "NONE",
      "adr": "NONE",
      "maxSpeed": 90,
      "onlyPhysical": false,
      "drivingProfile": {
        "maxSpeedETA": 0.0,
        "maxSpeedCAL": 0.0
      }
    }
  }
}
```

- `id` Unique identifier of the profile, used only in the RNC commands
- `name` Visible name of the profile in the application
- `userPermission` defines the Permission tier applied to a vehicle profile as seen by the end user in the vehicle selection/edition UI.

  - `HIDDEN` profile is not shown in the selection UI at all. Used for RNC-created profiles that the client app did not ask to expose to the user.
  - `VISIBLE` profile is shown as selectable in the list but has no detail view. This is the default-profile behavior (e.g. PASSENGER\_CAR).
  - `LOCKED` detail view is allowed (form is read-only), no edit, no delete. Used for the 3 code-owned default TRUCK profiles.
  - `EDITABLE` detail view is editable (save/reset buttons shown), no delete.
  - `OPEN` full control including deletion. Used for user-created profiles.
- `userEditionAllowed` Legacy parameter (replaced by `userPermission`) kept for backward compatibility.

  - `false` → `userPermission.VISIBLE`
  - `true ` → `userPermission.EDITABLE` (detail view is editable; deletion is **not** granted)
- `majorRoads` The navigation will favor main road network over small road when computing a route. It is strongly recommended to enable this option when driving trucks  \[`true`\|`false`\] Default `false`.
- `category`String representing the category of the vehicle. Differs from`transportationMode`to allow custom vehicle types that would not be supported by predefined`transportationMode`
- `profile`

  - `transportationMode` transportation mode \[`PEDESTRIAN`\|`PASSENGER_CAR`\|`TAXI`\|`PUBLIC_BUS`\|`DELIVERY_TRUCK`\|`BICYCLE`\|`EMERGENCY`\|`MOTORCYCLE`\|`UNDEFINED`\]  
    There is no `TRUCK` value - use `DELIVERY_TRUCK`. If `category` and `transportationMode` disagree, **the category wins** and the profile's mode is overwritten, so this field can usually be omitted.
  - `height` height of the vehicle (in m)
  - `length` length of the vehicle (in m)
  - `width` width of the vehicle (in m)
  - `weight` total vehicle weight (in metric ton)
  - `weightPerAxle` vehicle weight for each axle (in metric ton)
  - `nbTrailers` amount of trailers (default `-1`, meaning unspecified)
  - `hazmat` hazardous material type, as an enum **name** string (see below). Integers are **not** accepted.
  - `adr` ADR tunnel category (European Agreement concerning the International Carriage of Dangerous Goods by Road), as an enum **name** string (see below). Integers are **not** accepted.
  - `maxSpeed` maximum vehicle speed (in kph)
  - `onlyPhysical` defines if vehicle's weight (weight, weight per axle) and hazmat (hazmat and ADR) should be ignored outside respectively bridges and tunnels (default is false)
  - `drivingProfile` driving profile of the model

    - `maxSpeedETA` defines the maximum speed in kph that is only applied to route ETA (no impact on route calculation)
    - `maxSpeedCAL` defines the maximum speed in kph of the vehicle that is only applied to the route calculation. By default, no maximum speed is applied if no value is specified.

It's possible to dissociate max speed used to compute the route and the ETA.  
By default if you only specify `maxSpeed` it'll be applied to both ETA and calculation.  
If you set the optional values `maxSpeedETA` and `maxSpeedCAL` they will be used for the ETA and calculation

## Possible values for category parameter

```kotlin
"PASSENGER_CAR"  : uses TranspMode.PASSENGER_CAR
"DELIVERY_TRUCK" : uses TranspMode.DELIVERY_TRUCK
"LCV"            : uses TranspMode.PASSENGER_CAR, only available if TranspMode.DELIVERY_TRUCK is available.
"TAXI"           : uses TranspMode.TAXI
"PUBLIC_BUS"     : uses TranspMode.PUBLIC_BUS
"EMERGENCY"      : uses TranspMode.EMERGENCY
"PEDESTRIAN"     : uses TranspMode.PEDESTRIAN
```

The value is matched case-insensitively. `UNDEFINED` is **not** a usable category: it - and any unrecognised name - is rejected with `25 unknown.vehicle.category.error`. A category the licence does not cover is rejected with `26 vehicle.category.unavailable.error`.

## Possible values for hazmat parameter

> **Warning:** Send these as **strings**, e.g. `"hazmat": "EXPLOSIVE"`. A numeric value is read as a position in the list below rather than as the code it looks like, which happens to give the right answer for `0`-`13` and the wrong one, or an outright `-32700 parse.error`, for anything else. Use the names.

```
"NONE"            : No hazardous material
"ALL"             : General hazardous materials
"EXPLOSIVE"       : Trucks with Explosive and Flammable Goods
"WATER"           : Trucks with Goods Harmful for Water
"US_EXPLOSIVES"   : USA only : Explosives (e.g., TNT, ammunition, flares, fireworks)
"US_GAS"          : USA only : Flammable, compressed and poisonous gases (e.g., propane, compressed oxygen, chlorine)
"US_FLAM"         : USA only : Flammable and combustible liquids (e.g., jet fuel, gasoline, fuel oil, alcohols)
"US_FLAM_SOL"     : USA only : Flammable solids, spontaneously combustible materials and water reactive substances
"US_ORGANIC"      : USA only : Oxidizers and organic peroxides (e.g., ammonium nitrate and benzoyl peroxide)
"US_POISON"       : USA only : Poisonous (toxic) and infectious substances (e.g., cyanide, mercury-based compounds, toxins)
"US_RADIO_ACTIVE" : USA only : Radioactive materials (e.g., plutonium-239 and uranium-235)
"US_CORROSIVE"    : USA only : Corrosive materials (e.g., hydrochloric acid, sulfuric acid, sodium hydroxide)
"US_OTHER"        : USA only : Miscellaneous hazardous materials (e.g., asbestos, dry ice, lithium batteries)
"US_PIH"          : USA only : Poisonous inhalation hazards (PIH)
```

## Possible values for adr parameter

> **Warning:** Send these as **strings**, e.g. `"adr": "CAT_B"`. A numeric value is read as a position in the list below, not as the ADR code it looks like: `0` happens to resolve to `NONE`, while the codes 14, 18, 22 and 24 published by earlier revisions of this page are out of range and fail the whole command with `-32700 parse.error`.

```
"NONE"  : No tunnel category restriction (category A)
"CAT_B" : Tunnel Category B
"CAT_C" : Tunnel Category C
"CAT_D" : Tunnel Category D
"CAT_E" : Tunnel Category E
```

## Response

### Success

```
{
  "id": "1",
  "jsonrpc": "2.0",
  "result": {}
}
```

### Error

Incorrect Category

```
{
  "id": "1",
  "jsonrpc": "2.0",
  "error": {
    "code": 26,
    "message": "vehicle.category.unavailable.error"
  }
}
```

Parsing Error

```
{
  "id": "1",
  "jsonrpc": "2.0",
  "error": {
    "code": -32700,
    "message": "parse.error"
  }
}
```

Other errors this command can return:

- `25 unknown.vehicle.category.error` - unknown or unusable `category`.
- `24 add.vehicle.error` - the profile could not be created.
- `23 update.vehicle.error` - the profile exists but could not be updated.