Policy Tables Overview

Policies are rules enforced by SDL core that configure how the system can and/or will behave. For example, a policy could prohibit the use of an application (e.g. Flappy Bird) in a specific type of vehicle. In general, policies are configured by an OEM (e.g. Ford, Toyota, Suzuki) and stored in their SDL Policy Server. Once configured, all policies for a specific vehicle can be requested in the form a JSON document called a Policy Table. Policy Tables are downloaded to a vehicle's head unit where it can be enforced by SDL Core.

Example Policy Table

An example Policy Table is available in the SDL Core repository.

Application Policies

An application's permissions and settings are stored in the app_policies property in a Policy Table. The application policies are used to grant applications access to a specific set of features, such as vehicle data and/or running in the background. Any other application related data, such as user-consents, can also be stored in application policies as well.

Application ID

Settings for a specific application are stored in the app_policies object as a property named after the application's unique ID (e.g. "663645645" or any string of at most 100 characters). The value of this property can be either an object containing properties listed below or a reference to another sibling property (e.g. "default" or "device"). In addition, a special value of "null" can be used to indicate that the application has been revoked.

Application HMI Types

An application can be categorized by an HMI type allowing the SDL-enabled head unit to understand how to appropriately handle the application. There are several HMI types listed below.

Application HMI Levels

An HMI Level describes the state of an application. Resources are granted to an application based on its current state. While some resources are granted automatically to an application in a specific HMI Level, many can be controlled by the Policy Table.

Request Types

Default

A default application configuration can be stored in the app_policies object as a property named default. This property's value is an object containing any valid application property excluding certificate and nicknames.

Device

Permissions granted to the user's device post-DataConsent.

Example

An example of how the Application Policy portion of a Policy Table might look.

"app_policies": {
    "default": {
        "keep_context": true,
        "steal_focus": true,
        "priority": "NONE",
        "default_hmi": "NONE",
        "groups": [ "Base-1" ],
        "preconsented_groups": [],
        "RequestType": [],
        "memory_kb": 5,
        "watchdog_timer_ms": 55
    },
    "device": {
        "keep_context": true,
        "steal_focus": true,
        "priority": "NONE",
        "default_hmi": "NONE",
        "groups": [ "Base-2" ],
        "preconsented_groups": []
    },
    "pre_DataConsent": {
        "keep_context": true,
        "steal_focus": true,
        "priority": "NONE",
        "default_hmi": "NONE",
        "groups": [ "BaseBeforeDataConsent" ],
        "preconsented_groups": [],
        "memory_kb": 5,
        "watchdog_timer_ms": 55
    },
    "[App ID 1]": "null",
    "[App ID 2]": "default",
    "[App ID 3]": {
        "nicknames": [ "Awesome Music App" ],
        "keep_context": true,
        "steal_focus": true,
        "priority": "NONE",
        "default_hmi": "NONE",
        "groups": [ "Base-1", "VehicleInfo-1" ],
        "preconsented_groups": [],
        "RequestType": [],
        "RequestSubType": [ "Sub Type" ],
        "AppHMIType": [ "MEDIA" ],
        "memory_kb": 5,
        "watchdog_timer_ms": 55,
        "certificate": "[Your Certificate]"
    }
}

Consumer Friendly Messages

There are certain scenarios when SDL Core needs to display a message to the user. Some examples are when an error occurs or an application is unauthorized. These messages can include spoken text and text displayed to a user in multiple languages. All of this information is stored in the consumer_friendly_messages property.

Messages

All messages are given a unique name (e.g. "AppUnauthorized" or "DataConsent") and stored as an object in the consumer_friendly_messages object's messages property.

Language

Since each message should support multiple languages, each message object will contain a property named languages. Language properties are named by combining the ISO 639-1 language code and the ISO 3166 alpha-2 country code. For example, messages for English speaking citizens of the United States would be under the key en-us.

Message Text

Inside each language object is the data to be displayed or spoken by the module. The data is organized in the following properties.

Version

The version property in the consumer_friendly_messages object defines the current version of all the messages. It is used during a Policy Table update to determine whether or not the consumer friendly messages need to be updated. The version must be in the format ###.###.###.

Example

An example of how the Consumer Friendly Messages portion of a Policy Table might look.

"consumer_friendly_messages": {
    "version": "001.001.015",
    "messages": {
        "AppUnauthorized": {
            "languages": {
                "de-de": {
                    "tts": "Diese Version von %appName% ist nicht autorisiert und wird nicht mit SDL funktionieren.",
                    "line1": "nicht autorisiert"
                },
                "en-ie": {
                    "tts": "This version of %appName% is not authorized and will not work with SDL.",
                    "line1": "not authorized"
                },
                "en-us": {
                    "tts": "This version of %appName% is not authorized and will not work with SDL.",
                    "line1": "Not Authorized"
                }
            }
        },
        "DataConsent": {
            "languages": {
                "en-us": {
                    "tts": "To use mobile apps with SDL, SDL may use your mobile device's data plan....",
                    "line1": "Enable Mobile Apps",
                    "line2": "on SDL? (Uses Data)"
                }
            }
        }
    }
}

Device Data

Information about each device that connects to SDL Core is recorded in the Policy Table. This information is used to persist configurations for the head unit based on the device connected.

Device Specific Information

Devices are identified in the Policy Table using a unique identifier. Device unique identifier(s) are either a bluetooth mac address or USB serial address irreversibly encrypted/hashed using SHA-256. Information about a specific device is stored using its unique identifier as a key. The following properties describe the information stored.

User Consents

Whether or not an SDL user has given permission for a feature can be stored for each device and application connected to a vehicle's head unit. For example, a user may consent to allowing SDL to use their phone's cellular data to download Policy Table updates. These consent records are stored in the user_consent_records property.

Device

User consent(s) for a device are stored in a property named device in the user_consent_records object. The value of this property is an object with the following properies:

Application

User consent(s) can also be saved per application on a device under a property named after its Application ID. The value of this property is an object with the same user consent record properties as device above.

Example

An example of how the Device Data portion of a Policy Table might look.

"device_data": {
    "[ID VALUE HERE]": {
        "hardware": "iPhone 4S",
        "max_number_rfcom_ports": 25,
        "firmware_rev": null,
        "os": "iOS",
        "os_version": "5",
        "carrier": "AT&T",
        "user_consent_records": {
            "device": {
                "consent_groups": {
                    "DataConsent-1": true
                },
                "input": "VUI",
                "time_stamp": "4/24/2012 12:30:00 PM"
            },
            "[APP ID HERE]": {
                "consent_groups": {
                    "Location-1": true,
                    "DrivingData-1": false
                },
                "input": "VUI",
                "time_stamp": "3/26/2012 10:41:00 AM "
            }
        }
    }
}

Functional Groupings

Before an application can use each feature offered by SDL it must first be granted permission to do so in the Policy Table. Each feature may require several RPCs with specific HMI level permission, as well as allowed parameters and other information. In order to avoid duplicating this data for each application, SDL instead uses functional groupings. A functional grouping is simply a group of RPC messages and parameters with specific HMI permissions and allowed parameters. So for example, if an application named Torque wanted access to vehicle data you would simply add the VehicleData functional group to Torque's allowed policies.

Functional Group

Each functional group is given a unique name (e.g. BasicVehicleData) that is used to reference that group from anywhere within the Policy Table. Each functional group may contain the following properties.

RPCS

Each RPC in the rpcs property has a unique name that represents an existing RPC (e.g. AddSubMenu). In each RPC object there may be the following properties.

Example

An example of how the Functional Groupings portion of a Policy Table might look.

"functional_groupings": {
    "Base-1": {
        "rpcs": {
            "AddCommand": {
                "hmi_levels": [
                    "BACKGROUND",
                    "FULL",
                    "LIMITED"
                ]
            },
            "AddSubMenu": {
                "hmi_levels": [
                    "BACKGROUND",
                    "FULL",
                    "LIMITED"
                ]
            },
            "Alert": {
                "hmi_levels": [
                    "FULL",
                    "LIMITED"
                ]
            },
        }
    },
    "VehicleInfo-1": {
        "user_consent_prompt": "VehicleInfo",
        "rpcs": {
            "GetVehicleData": {
                "hmi_levels": [
                    "BACKGROUND",
                    "FULL",
                    "LIMITED"
                ],
                "parameters": [
                    "engineTorque",
                    "externalTemperature",
                    "fuelLevel",
                    "fuelLevel_State",
                    "headLampStatus",
                    "instantFuelConsumption",
                    "odometer",
                    "tirePressure",
                    "vin",
                    "wiperStatus"
                ]
            },
        }
    }
}

Module Config

The module configuration property contains information used to configure SDL Core for use on the current vehicle.

Notifications

There is a limit for the number of notifications that can be displayed per priority level. The limit is instead based on notifications per minute. You can configure these in the notifications_per_minute_by_priority property. The following are the available priority levels.

Policy Table Update Configurations

Periodically changes will be made to a Policy Table, either by the Policy Server or SDL Core. This means SDL Core should check for and perform a Policy Table update, which synchronizes the local and Policy Server Policy Tables. You can configure when SDL Core will check using the following configurations.

Preloaded Policy Tables

SDL Core can use a predefined Policy Table located locally on the vehicle's head unit. This is present to initially configure SDL Core as well as to enable the storage of vehicle data before a Policy Table update has occurred.

Policy Table Structure Configurations

The policy table's structure is determined by the following configurations.

Server Requests

All requests made directly by SDL Core or by proxy can be configured using the following attributes.

Endpoints

This section is a list of URLs that are used throughout the SDL lifecycle, such as Policy Table updates, module software updates, and lock screen imagery.

Vehicle Information

Vehicle identification information is stored in the module configuration portion of the Policy Table.

Example

An example of how the Module Config portion of a Policy Table might look.

"module_config": {
    "endpoints": {
        "0x07": {
        "default": [ "http://localhost:3000/api/1/policies/proprietary" ],
      }
    },
    "exchange_after_x_ignition_cycles": 100,
    "exchange_after_x_kilometers": 1800,
    "exchange_after_x_days": 30,
    "full_app_id_supported": true,
    "notifications_per_minute_by_priority": {
        "EMERGENCY": 60,
        "NAVIGATION": 15,
        "voiceCommunication": 10,
        "COMMUNICATION": 6,
        "NORMAL": 4,
        "NONE": 0
    },
    "seconds_between_retries": [ 1, 5, 25, 125, 625 ],
    "timeout_after_x_seconds": 60,
    "vehicle_make": "Ford",
    "vehicle_model": "F-150",
    "vehicle_year": "2015"
}

Module Meta

Language and Country

The current language and regional settings can be configured using the following properties.

Module Version

The current version of the vehicle's module should be stored in the following property.

Policy Table Update

Information about when a Policy Table update has last taken place is stored in the following properties.

Vehicle Data

Additional vehicle information is stored in the module meta property.

Example

An example of how the Module Meta portion of a Policy Table might look.

"module_meta": {
    "ccpu_version": "4.1.2.B_EB355B",
    "language": "en-us",
    "pt_exchanged_at_odometer_x": 1903,
    "pt_exchanged_x_days_after_epoch": 46684,
    "ignition_cycles_since_last_exchange": 50,
    "vin": "1FAPP4442VH100001"
}

Usage and Errors

Errors and usage statistics that occur while an application is in use or are related to an application are record. The information does not contain user information and is very small as to use as little mobile data as possible. This data is sent to the Policy Server when performing a Policy Table update.

Application Errors

Errors and usage statistic that occur while an application is in use or are related to an application are recorded. The following properties are tracked in a property named after the application's ID.

General Errors

Some basic usage and error counts are stored in the following properties.

Example

An example of how the Usage and Error portion of a Policy Table might look.

"usage_and_error_counts": {
    "count_of_iap_buffer_full": 1,
    "app_level": {
        "[App ID Here]": {
          "app_registration_language_gui": "en-us",
          "app_registration_language_vui": "en-us",
          "count_of_rejected_rpcs_calls": 9,
          "count_of_rejections_duplicate_name": 2,
          "count_of_rejections_nickname_mismatch": 1,
          "count_of_removals_for_bad_behavior": 6,
          "count_of_rfcom_limit_reached": 1,
          "count_of_rpcs_sent_in_hmi_none": 7,
          "count_of_run_attempts_while_revoked": 0,
          "count_of_user_selections": 7,
          "minutes_in_hmi_background": 123,
          "minutes_in_hmi_full": 123,
          "minutes_in_hmi_limited": 456,
          "minutes_in_hmi_none": 456
        }
    }
}