Customize the vehicle profile

The CoPilot Native Nav SDK uses a collection of settings called a Vehicle Routing Profile to generate an optimal route based on the size and type of vehicle, as well as your preferences for how that vehicle should be routed.

Using an Account Manager Profile

Routing profiles include default profiles, which are created by Trimble Maps based on the most common types of commercial vehicles, and custom profiles. You can create a custom profile in the Account Manager web tool by changing settings in a default profile based on your fleet’s vehicle types and preferences.

The sample code below shows how to retrieve default profiles from Account Manager and assign the first one to the trip:

private void fetchRoutingProfiles() {
    RetrieveFleetRoutingProfiles fleetRoutingProfiles = RetrieveFleetRoutingProfiles.builder()
            .jsonWebToken(TrimbleMapsAccountManager.getFleetAccessToken())
            .appVersion("1.0.0")
            .build();

    fleetRoutingProfiles.enqueueCall(new Callback<FleetRouteProfileResponse>() {
        @Override
        public void onResponse(Call<FleetRouteProfileResponse> call, Response<FleetRouteProfileResponse> response) {
            List<Profile> profiles = null;
            if (response.body() != null && response.body().results() != null) {
                profiles = fleetRoutingProfiles.convertRoutingProfiles(response.body().results());

            }
            TrimbleMapsTripProvider.retrieve().getOptions().setRoutingProfile(profiles != null ? profiles.get(0) : null);
        }

        @Override
        public void onFailure(Call<FleetRouteProfileResponse> call, Throwable t) {

        }
    });
}

private fun fetchRoutingProfiles() {
    val fleetRoutingProfiles: RetrieveFleetRoutingProfiles = RetrieveFleetRoutingProfiles.builder()
        .jsonWebToken(TrimbleMapsAccountManager.getFleetAccessToken())
        .appVersion("1.0.0")
        .build()

    fleetRoutingProfiles.enqueueCall(object : Callback<FleetRouteProfileResponse>{
        override fun onResponse(call: Call<FleetRouteProfileResponse>, response: Response<FleetRouteProfileResponse>) {
            val profiles = response.body()?.results()?.let {
                fleetRoutingProfiles.convertRoutingProfiles(it)
            }

            TrimbleMapsTripProvider.retrieve().options.routingProfile = profiles?.firstOrNull()
        }

        override fun onFailure(call: Call<FleetRouteProfileResponse>, t: Throwable) {

        }

    })
}

This sample code shows how to retrieve custom profiles and assign the first one to the trip.

private void fetchCustomRoutingProfiles() {
    TrimbleCustomRoutingProfile customProfile = TrimbleCustomRoutingProfile.builder()
            .offset(0)
            .limit(50)
            .build();
    customProfile.enqueueCall(new Callback<CustomRoutingProfileResponse>() {
        @Override
        public void onResponse(Call<CustomRoutingProfileResponse> call, Response<CustomRoutingProfileResponse> response) {
            List<Profile> profiles = null;
            if(response.body() != null && response.body().data() != null) {
                profiles = response.body().data();
            }

            TrimbleMapsTripProvider.retrieve().getOptions().setRoutingProfile(profiles != null ? profiles.get(0) : null);
        }

        @Override
        public void onFailure(Call<CustomRoutingProfileResponse> call, Throwable t) {

        }
    });
}

private fun fetchCustomRoutingProfiles() {
    val customProfile: TrimbleCustomRoutingProfile = TrimbleCustomRoutingProfile.builder()
        .offset(0)
        .limit(50)
        .build()
    customProfile.enqueueCall(object : Callback<CustomRoutingProfileResponse> {
        override fun onResponse(call: Call<CustomRoutingProfileResponse>,
                                response: Response<CustomRoutingProfileResponse>
        ) {
            val profiles = response.body()?.data()
            TrimbleMapsTripProvider.retrieve().options.routingProfile = profiles?.firstOrNull()
        }

        override fun onFailure(
            call: Call<CustomRoutingProfileResponse>,
            t: Throwable
        ) {

        }
    })
}

Setting a custom profile at runtime

Best practice is to create profiles with Trimble Maps Account Manager, as those profiles are linked to your account via API key. However, there may be cases where you need to create and use Routing Profiles on the fly. This can be done using the Profile class and passing that into the navigation prior to routing.

The code below demonstrates how to create a Heavy Duty Truck profile, hauling flammable hazardous material with custom vehicle dimensions.

Profile routingProfile = Profile.builder()
	.units(DirectionsCriteria.Units.ENGLISH)
	.vehicleType(DirectionsCriteria.VehicleType.TRUCK)
	.vehicleOptions(VehicleOptions.builder()
        	.vehicleConfig(VehicleConfigurations.builder()
                	.height(129)
                	.length(480)
                	.weight(35000)
                	.width(96)
                	.maxWeightPerAxleGroup(23000.0)
                	.build())
        	.hazmatType(DirectionsCriteria.Hazmat.FLAMMABLE)
        	.build())
	.build();

var routingProfile: Profile? = Profile.builder()
    .units(DirectionsCriteria.Units.ENGLISH)
    .vehicleType(DirectionsCriteria.VehicleType.TRUCK)
    .vehicleOptions(VehicleOptions.builder()
            .vehicleConfig(VehicleConfigurations.builder()
                    .height(129.0)
                    .length(480.0)
                    .weight(35000.0)
                    .width(96.0)
                    .maxWeightPerAxleGroup(23000.0)
                    .build()
            )
            .hazmatType(DirectionsCriteria.Hazmat.FLAMMABLE)
            .build()
    )
    .build()

Once you have created your profile, you can apply it to your trip:

trimbleMapsTrip.getOptions().setRoutingProfile(routingProfile);

See the Quick Navigation tutorial for more information on how to create a trip.

Profile settings

Units of measurement

The Profile builder supports the ability to configure the units of measurement for the profile being created. This is set using units().

English/Imperial and Metric are both supported. The value set here, will determine how the dimensions values you provide are interpreted. The constants for this can be found in DirectionsCriteria.Units.

If set to Metric, dimensions are entered in centimeters and weights are entered in kilos. If set to English, dimensions are entered in inches and weights are entered in pounds.

Vehicle Type

The type of vehicle that is being driven/routed can be set using vehicleType() and passing in one of the constants from DirectionsCriteria.VehicleType. The CoPilot Native Nav SDK supports a variety of vehicle types, including TRUCK for heavy duty or HGV vehicles; MIDSIZE_TRUCK for medium duty vehicles; LIGHT_TRUCK for light duty / LCV vehicles; and AUTO for automobiles/cars. Depending on the vehicle type selected, the routing can change quite significantly. Learn more about how Trimble Maps handles truck routing here.

Vehicle Options

Vehicle options allow you to provide more details about the vehicle itself. It’s important to be accurate as the configurations here determine the route that is calculated. The more accurate your configs, the more accurate the ETA, distance and route calculated. Vehicle options covers items such as:

• The vehicle’s dimensions
• HazMat hauling
• ADR tunnel codes in the EU.

This can all be set with a series of builders as as well, as illustrated with the sample code below:

.vehicleOptions(
   	VehicleOptions.builder()
        .tunnelCategory(DirectionsCriteria.TunnelCategory.BCDE) // EU Tunnel Code
        .vehicleConfig(
            VehicleConfigurations.builder()
                .maxWeightPerAxleGroup(25000.0) // Dimensions of the vehicle
                .width(102)
                .length(420)
                .weight(50000)
                .height(129)
                .build()
        )
        .hazmatType(DirectionsCriteria.Hazmat.FLAMMABLE) // HazMat settings
        .build()
)

.vehicleOptions(
    VehicleOptions.builder()
        .tunnelCategory(DirectionsCriteria.TunnelCategory.BCDE) // EU Tunnel Code
        .vehicleConfig(
            VehicleConfigurations.builder()
                .maxWeightPerAxleGroup(25000.0) // Dimensions of the vehicle
                .width(102.0)
                .length(420.0)
                .weight(50000.0)
                .height(129.0)
                .build()
        )
        .hazmatType(DirectionsCriteria.Hazmat.FLAMMABLE) // HazMat settings
        .build()
)

• TunnelCategory() sets the ADR tunnel code for Europe, should it be applicable.
• VehicleConfig() covers the dimensions and weight of the vehicle being used.
• HazmatType() is for when hazardous materials are being hauled. The DirectionsCriteria constants can be used for providing some of the parameters required.

DirectionsCriteria Constants

Throughout the Profile builder, a lot of the parameters are expecting one of the constants set in the DirectionsCriteria class. These are broken down into a series of subclasses.