Skip to content

Core Module

Overview

The Core module is the heart of the Alexa Auto SDK. The Core module provides the following elements that are the foundation for all Auto SDK features: - Defining core API for your application to access the features of Auto SDK— Core defines the Engine and MessageBroker components. Alongside the Alexa Auto Services Bridge (AASB) messages defined by each Auto SDK module, these components comprise the core API for your application to access the features of Auto SDK. To learn about the API, see Auto SDK Core API Overview.

  • Providing an infrastructure to other modules— Core provides the base infrastructure of the Engine, which each Auto SDK module extends to add module-specific features.

  • Providing core services to other modules— Core defines the common Engine services and corresponding AASB message interfaces for logging, audio I/O, authorization, device settings, network info, and more. Each module uses these Engine services to provide its own module-specific features.

Configure the Core module

The Core module defines required and optional configuration objects that you include in the Engine configuration for your application. You can define the configuration objects in a file or construct them programmatically with the relevant configuration factory functions.

(Required) Vehicle info configuration

Your application must provide the aace.vehicle configuration specified below. Amazon uses the vehicle configuration properties for analytics.

{
  "aace.vehicle": {
     "info": {
         "make": {{STRING}},
         "model": {{STRING}},
         "year": {{STRING}},
         "trim": {{STRING}},
         "geography": {{STRING}},
         "version": {{STRING}},
         "os": {{STRING}},
         "arch": {{STRING}},
         "language": {{STRING}},
         "microphone": {{STRING}},
         "vehicleIdentifier": {{STRING}},
         "engineType": {{STRING}},
         "rseEmbeddedFireTvs": {{STRING}}
     }
  }
}
The following table describes the properties in the configuration:

Property Type Required Description Example
make String Yes The make of the vehicle
model String Yes The model of the vehicle
year Integer as a string Yes The model year of the vehicle. The value must be an integer in the range 1900-2100. "2019"
trim String No The trim package of the vehicle, identifying the vehicle's level of equipment or special features "Sport"
geography String No The location of the vehicle "US",
"US-North",
"WA"
version String No The client software version "4.0"
os String No The operating system used by the head unit "AndroidOreo_8.1"
arch String No The hardware architecture used by the head unit "x86_64"
language String No The language or locale selected for Alexa by the vehicle owner "en-US",
"fr-CA"
microphone String No The type and arrangement of microphone used in the vehicle "7 mic array, centrally mounted"
vehicleIdentifier String Yes An identifier for the vehicle "1234abcd"
engineType String No The engine type of the vehicle.

Accepted values:
  • "GAS"
  • "ELECTRIC"
  • "HYBRID"
"GAS"
rseEmbeddedFireTvs Integer as a string No The number of RSE embedded FireTVs installed in the vehicle "1"

Important! To pass the Amazon certification process, the vehicleIdentifier value you provide must NOT be the vehicle identification number (VIN).

Click to expand or collapse details— Generate the configuration programmatically with the C++ factory function

Auto SDK provides the VehicleConfiguration::createVehicleInfoConfig() factory function to generate the configuration programmatically.

#include <AACE/Vehicle/VehicleConfiguration.h>

std::vector<aace::vehicle::config::VehicleConfiguration::VehicleProperty> vehicleProperties = {
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::MAKE, "SampleMake"},
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::MODEL, "SampleModel" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::YEAR, "2020" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::TRIM, "Sport" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::GEOGRAPHY, "US" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::VERSION, "4.0"},
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::OPERATING_SYSTEM, "AndroidOreo_8.1"},
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::HARDWARE_ARCH, "x86_64" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::MICROPHONE, "7 mic array, centrally mounted" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::LANGUAGE, "en-US" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::VEHICLE_IDENTIFIER, "1234abcd" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::ENGINE_TYPE, "GAS" },
    { aace::vehicle::config::VehicleConfiguration::VehiclePropertyType::RSE_EMBEDDED_FIRETVS, "1" }
};

auto vehicleConfig = aace::vehicle::config::VehicleConfiguration::createVehicleInfoConfig(vehicleProperties);

engine->configure(
    {
        // ...other config objects...,
        vehicleConfig
    }
);

(Required) Storage configuration

Your application must provide the aace.storage configuration specified below. The Engine uses the configured path to create a database to persist data across device reboots.

{
    "aace.storage": {
        "localStoragePath": {{STRING}},
        "storageType": "sqlite"
    }
}

The following table describes the properties in the configuration:

Property Type Required Description Example
localStoragePath String Yes The absolute path where the Engine will create the local storage database, including the database name "/opt/AAC/data/aace-storage.db"
storageType String Yes The type of storage to use "sqlite"

Note: This database is not the only one used by the Engine. For example, components in the Alexa module have similar configuration to store feature-specific data. See Configure the Alexa module for details.

Click to expand or collapse details— Generate the configuration programmatically with the C++ factory function

Auto SDK provides the StorageConfiguration::createLocalStorageConfig() factory function to generate the configuration programmatically.

#include <AACE/Storage/StorageConfiguration.h>

auto storageConfig = aace::storage::config::StorageConfiguration::createLocalStorageConfig("/opt/AAC/data/storage.db");

engine->configure(
    {
        // ...other config objects...,
        storageConfig
    }
);

(Required) cURL configuration

The Auto SDK uses cURL for network connections. Your application can provide Engine configuration to specify the cURL configuration:

{
    "aace.alexa": {
        "avsDeviceSDK": {
            "libcurlUtils" {
                "CURLOPT_CAPATH": {{STRING}},
                "CURLOPT_INTERFACE": {{STRING}},
                "CURLOPT_PROXY": {{STRING}}

            }
        }
    }
}

The following table describes the properties in the configuration:

Property Type Required Description Example
CURLOPT_CAPATH String Yes The path to the directory containing the CA certificates "/opt/AAC/certs"
CURLOPT_INTERFACE String Yes The outgoing network interface. Can be a network interface name, an IP address, or a host name "wlan0"
CURLOPT_PROXY String No The address of the HTTP proxy "http://127.0.0.1:8888"

Note: If the HTTP proxy requires credentials in HTTP headers to authenticate a user agent, you can specify the headers at runtime with the PropertyManager interface by using the aace.network.httpProxyHeaders property name. You can also change the network interface at runtime with the aace.network.networkInterface property name.

Click to expand or collapse details— Generate the configuration programmatically with the C++ factory function

Auto SDK provides the AlexaConfiguration::createCurlConfig() factory function to generate the configuration programmatically.

#include <AACE/Alexa/AlexaConfiguration.h>

auto curlConfig = aace::alexa::config::AlexaConfiguration::createCurlConfig("/opt/AAC/etc/certs");

engine->configure(
    {
        // ...other config objects...,
        curlConfig
    }
);

(Optional) Logger configuration

By default, the Engine writes Auto SDK logs to the following places:

  • The console, for C++ native applications
  • Logcat, for Android applications

You can configure the Engine to save logs to a file with the aace.logger configuration:

{
  "aace.logger": {
    "sinks": [
        {
            "id": {{STRING}},
            "type": "aace.logger.sink.file",
            "config": {
                "path": {{STRING}},
                "prefix": {{STRING}},
                "maxSize": {{INTEGER}},
                "maxFiles": {{INTEGER}},
                "append": {{BOOLEAN}}
            },
            "rules": [
                {
                    "level": {{STRING}}
                }
            ]
        }
    ]
}

The following table describes the properties in the configuration:

Property Type Required Description Example
aace.logger.
sinks[i].
id
String Yes A unique identifier for the log sink. "debug-logs"
aace.logger.
sinks[i].
type
String Yes The type of the log sink. Use "aace.logger.sink.file" to write logs to a file. "aace.logger.sink.file"
aace.logger.
sinks[i].
config.
path
String Yes An absolute path to a directory where the Engine creates the log file. "/opt/AAC/data"
aace.logger.
sinks[i].
config.
prefix
String Yes The prefix for the log file. "auto-sdk-logs"
aace.logger.
sinks[i].
config.
maxSize
Integer Yes The maximum size of the log file in bytes. 5242880
aace.logger.
sinks[i].
config.
maxFiles
Integer Yes The maximum number of log files. 5
aace.logger.
sinks[i].
config.
append
Boolean Yes Whether the Engine should overwrite log files.
Use true to append logs to the existing file. Use false to overwrite the log files.
false
aace.logger.
sinks[i].
rules[j].
level
Enum string Yes The log level filter the Engine uses when writing logs to the sink.

Accepted values:
  • "VERBOSE"
  • "INFO"
  • "WARN"
  • "ERROR"
  • "CRITICAL"
  • "METRIC"
"VERBOSE"
Click to expand or collapse details— Generate the configuration programmatically with the C++ factory function

Auto SDK provides the LoggerConfiguration::createFileSinkConfig() factory function to generate the configuration programmatically.

#include "AACE/Logger/Logger.h"
#include "AACE/Logger/LoggerConfiguration.h"


auto fileSinkConfig = aace::logger::config::LoggerConfiguration::createFileSinkConfig(
    "debug-logs",
    aace::logger::LoggerEngineInterface::Level::VERBOSE,
    "opt/AAC/data",
    "auto-sdk-logs",
    5242880,
    5,
    false);

engine->configure(
    {
        // ...other config objects...,
        fileSinkConfig
    }
);

(Optional) AASB and MessageBroker configuration

Configure enabled interfaces

When you use a module, the Engine services of that module enable every interface the module defines. This means that for every interface in a module you use, if your application does not subscribe to the AASB messages of the interface, the Engine performs default handling (typically no-op) for the messages you do not handle.

To disable this setting, provide the following aace.messageBroker configuration object in your Engine configuration:

{
    "aace.messageBroker": {
        "autoEnableInterfaces": false
    }
}

You can also configure the enablement on a per-interface basis. If you don't want the Engine to provide a default handler for a particular interface, you can disable the interface using the following configuration that specifies the name of the interface and the Engine service that owns it:

{
    "aasb.<engine_service_ID>": {
        "<interface_name>": {
            "enabled": {{BOOLEAN}}
        }
    }
}

For example, the following configuration disables the TemplateRuntime interface from the Alexa module's alexa Engine service and the LocationProvider interface from Core module's location Engine service:

{
    "aasb.alexa": {
        "TemplateRuntime": {
            "enabled": false
        }
    },
   "aasb.location": {
      "LocationProvider": {
         "enabled": false
      }
   }
}

Configure the synchronous message timeout

All the messages published by the Engine through the Message Broker are asynchronous; however, certain messages require your application to respond with a special synchronous-style Reply message. Your application must publish the reply quickly because the Engine blocks its execution thread while waiting for the response, and the Message Broker cannot dispatch more messages while waiting. The following messages are examples of the LocationProvider.GetLocation message and its reply message:

LocationProvider.GetLocation message:

{
  "header": {
    "id": "23b578ed-6dc3-460a-998e-1647ba6cde42",
    "messageType": "Publish",
    "version": "4.0",
    "messageDescription": {
        "topic": "LocationProvider",
        "action": "GetLocation"
    }
  }
}
LocationProvider.GetLocation reply message:
{
  "header": {
    "id": "4c4d13b6-6a8d-445b-931a-a3feb0878311",
    "messageType": "Reply",
    "version": "4.0",
    "messageDescription": {
      "topic": "LocationProvider",
      "action": "GetLocation",
      "replyToId": "23b578ed-6dc3-460a-998e-1647ba6cde42"
    }
  },
  "payload": {
    "location": {
      "latitude": 37.410,
      "longitude": -122.025
    }
  }
}
The AASB message documentation for each interface specifies whether the interface requires any Reply messages. However, not every Reply message is synchronous-style.

To avoid waiting indefinitely for "synchronous" replies, the Engine uses a timeout when waiting for these reply messages. If your application does not publish a reply before the timeout elapses, the Message Broker proceeds to avoid waiting, but the relevant Engine operation won't execute properly. The default timeout value for reply messages is 500 milliseconds. In a busy system, the default timeout might not be long enough. You can configure this value by adding the optional field defaultMessageTimeout to the aace.messageBroker JSON object in your Engine configuration. The following example configuration sets the reply timeout to 1000 ms:

{
    "aace.messageBroker": {
        "defaultMessageTimeout": 1000
    }
}

Important! Since increasing the timeout increases the Engine's message processing time, use this configuration carefully. Consult with your Amazon Solutions Architect (SA) as needed.

Use the Core module interfaces

The following list describes the AASB message interfaces provided by the Core module:

(Required) Provide access tokens with Authorization

The Authorization interface specifies messages for your application to initiate device authorization, terminate device authorization, or provide authorization data, such as Alexa access tokens, to the Engine.

>> Authorization interface

(Required) Provide audio channels with AudioInput and AudioOutput

The core audio Engine service provides a mechanism for Engine components of any module to open audio input and output channels in your application. Each component that requests an audio channel specifies its audio channel type so your application can provide different microphone and media player implementations for each channel.

>> AudioInput interface

>> AudioOutput interface

(Required) Manage runtime properties with PropertyManager

Different Auto SDK modules define properties based on their supported features. For example, the Alexa module requires a locale setting to notify Alexa which language to use when interacting with the user. The Core module provides a mechanism for Engine services to register properties they manage and listen to changes in properties managed by other modules. The PropertyManager interface specifies messages for your application and the Engine to query and update these properties.

>> PropertyManager interface

(Optional) Report location with LocationProvider

For an accurate and personalized user experience, the Engine uses the vehicle's location from LocationProvider.

>> LocationProvider interface

(Optional) Report network status changes with NetworkInfoProvider

To adapt the Engine behavior dynamically based on the state of the head unit's network connection, provide network connection reporting through NetworkInfoProvider.

>> NetworkInfoProvider interface

(Optional) Report data usage with DeviceUsage

Report metrics about the head unit's data usage with DeviceUsage.

>> DeviceUsage interface

(Optional) Manage multiple voice assistants dialog requests and status

The Arbitrator interface manages the voice assistant agents for both Alexa and 3rd parties. You can control how arbitration is handled for multiple voice assistant requests based on the rules you configure at the system level or at agent registration.

>> Arbitrator interface

(Optional) Provide 3rd Party Wakeword Support

The Wakeword interface manages the voice assistant agents for both Alexa and 3rd party assistants. Using the Wakeword module, OEM partners can simultaneously support multiple voice assistant wake words like Siri on the same in-vehicle infotainment system.

>> Wakeword interface

Back to top