Table of Contents
- Core module overview
- Understand the Auto SDK API
- Manage the Engine lifecycle in your application
- Configure the Core module
- Understand the key core Engine services
- Provide core device status
The Alexa Auto SDK Core module is the heart of the SDK. The Core module acts as the foundation for all Auto SDK features by contributing the following essential elements to the SDK:
-
Defining the Auto SDK API for your application—
Coredefines theEngineandMessageBrokercomponents. 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 Understand the Auto SDK API. -
Providing an infrastructure to other modules—
Coreprovides the base infrastructure of the Engine, which each Auto SDK module extends to add module-specific features.Corealso defines the common Engine services for logging, audio I/O, authorization, and device settings. Each module uses these Engine services to provide its own module-specific features. To learn about the primary core services, see Understand the key core Engine services. -
Receiving core device statuses from your application—
Coreincludes AASB message interfaces for your application to report essential information such as device location and network connection status. The Engine uses this information to provide a reliable experience to the user. To learn about the core device status interfaces, see Provide core device status.
Important!: If you are an Android developer, your application will use the Alexa Auto Client Service (AACS) as its foundation. AACS implements much of the core Auto SDK setup, abstracting it from your application and exposing only a necessary subset of the Auto SDK API in an Android-specific way. Some of the information presented in this documentation and documentation for other SDK modules might not pertain to your application exactly as written for cases in which AACS provides the implementation or further abstracts it, so keep this in mind while reading. Use the module documentation to understand the underlying layers of Auto SDK, if interested, and to reference the Engine configuration and AASB message definitions for the features you do need to build into your application yourself.
The Engine, MessageBroker, and AASB message interfaces comprise the Auto SDK API. Your application uses these three components to build a complete Alexa client implementation for your vehicle.
The Auto SDK Engine is a system of components that provide the core implementation of all Auto SDK features. With respect to Alexa, your application's Alexa client stack uses the Engine as the layer that sets up the connection to Alexa, publishes device capabilities, sends Alexa events, sequences Alexa directives, and more.
Your application creates an instance of the Engine and uses a simple interface to manage the Engine lifecycle for the duration of the application run time. Aside from setting up the Engine, the primary responsibility of your application is to provide the platform-specific, customizable integration details that make Alexa and other core SDK features work for your vehicle, in particular. Platform-specific integration might include interacting with external libraries or the underlying software frameworks of your operating system to complete the Auto SDK client stack with deep integration into the applications on your system.
The Engine implements as much of the general functionality as possible; for integration details that it can't implement, the Engine delegates responsibility to your application via AASB messages published through the MessageBroker.
The MessageBroker is the bridge in the Alexa Auto Services Bridge (AASB). MessageBroker provides a publish and subscribe API to the Engine and your application for communication with each other. In order to consume a message that the Engine publishes to your application, your application uses MessageBroker to subscribe to the message by specifying the message topic and action as well as a function for MessageBroker to invoke to deliver the message. Similarly, the Engine uses MessageBroker to subscribe to messages published by your application.
A typical Auto SDK module defines one or more AASB message interfaces. An interface groups logically related messages together with a topic. Within the topic, each interface has one or more actions to represent individual messages. I.e., a topic + action combination identifies a single message.
For instance, the Alexa module defines many interfaces related to standard Alexa features. The Alexa module SpeechRecogizer interface defines messages for your application to publish to the Engine when the user invokes Alexa. It also defines messages the Engine publishes to your application to convey key events in the user speech stream.
For example, your application publishes a SpeechRecognizer.StartCapture message when the user taps the Alexa invocation button:
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": "12345",
"messageDescription": {
"topic": "SpeechRecognizer",
"action": "StartCapture"
}
},
"payload": {
"initiator": "TAP_TO_TALK"
}
}The Engine subscribes to this message at startup time, so it is ready to consume the message when published by your application. In response to the message, the Engine sends the user speech audio to Alexa. Alexa processes the speech, and when she detects the user has finished speaking, the Engine publishes a SpeechRecognizer.EndOfSpeechDetected message to your application:
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": "00876",
"messageDescription": {
"topic": "SpeechRecognizer",
"action": "EndOfSpeechDetected"
}
}
}Your application receives this message from MessageBroker if it subscribed to the SpeechRecognizer topic and EndOfSpeechDetected action.
MessageBroker uses AASB messages as serialized JSON strings; however, for convenience, Auto SDK provides C++ wrapper classes for each message that help with the serialization and deserialization. The Auto SDK build system generates these wrapper classes as part of the build.
To use Auto SDK features, your application must instantiate and manage the lifecycle of the Engine.
During the launch sequence of your application, create one instance of the Engine using the static function aace::core::Engine::create():
std::shared_ptr<aace::core::Engine> engine = aace::core::Engine::create();A typical application creates the Engine once when the user turns on the vehicle ignition and uses the instance until the user turns off the vehicle ignition.
After creating the Engine instance, configure it with the required Engine configurations. Engine configuration uses JSON serialized as strings, but you pass the configurations to the Engine in one or more aace::core::config::EngineConfiguration wrapper objects. Auto SDK provides two options to generate EngineConfiguration objects:
- Specify your Engine configuration in a JSON file and construct an
EngineConfigurationfrom a path to the file - Build the configuration programatically using one of the configuration factory functions.
You can choose either option or a combination of both. I.e., you can generate a single EngineConfiguration object that includes all configuration data for the Engine components you use, or you can break up the configuration data into logical sections and generate multiple EngineConfiguration objects. For example, you might generate one EngineConfiguration object for each module.
To configure the Engine, call the Engine's configure() function, passing in the EngineConfiguration object(s):
-
For a single
EngineConfigurationobject:engine->configure( config ); -
For multiple
EngineConfigurationobjects:engine->configure( { xConfig, yConfig, zConfig } );replacing
xConfig, yConfig, zConfigwith logical names to identify theEngineConfigurationobjects you generated.
Note: For one Engine instance, you can call the
configure()function only once, and you must call it before you subscribe to AASB messages withMessageBrokerand before you start the Engine.
Auto SDK provides the ConfigurationFile class that reads the configuration from a specified JSON file path and creates an EngineConfiguration object from that configuration:
aace::core::config::ConfigurationFile::create( “</path/to/filename.json>” )You can include all the configuration data in a single JSON file to create a single EngineConfiguration object. For example,
auto config = aace::core::config::ConfigurationFile::create( “/opt/AAC/config/config.json” );Alternatively, you can break the configuration data into multiple JSON files to create multiple EngineConfiguration objects. For example,
auto coreConfig = aace::core::config::ConfigurationFile::create( “/opt/AAC/data/core-config.json” );
auto alexaConfig = aace::core::config::ConfigurationFile::create( “/opt/AAC/data/alexa-config.json” );
auto navigationConfig = aace::core::config::ConfigurationFile::create( “/opt/AAC/data/navigation-config.json” );See documentation for individual module features to see the format of their respective JSON configuration. For example, Core outlines its required configurations in Configure the Core module.
Each Auto SDK module that defines configuration provides a factory class with functions that return EngineConfiguration objects. The values a function puts in the configuration it creates correspond to the function parameters. For example, you can configure the Alexa module's alertsCapabilityAgent settings by using the AlexaConfiguration::createAlertsConfig() function:
auto alertsConfig = aace::alexa::config::AlexaConfiguration::createAlertsConfig("</some/directory/path/for/databases>" );After you configure the Engine, use MessageBroker to subscribe to any AASB interface messages that your application will handle. For example, the following code uses the AASB message wrapper classes for the SpeechRecognizer interface to subscribe to messages from the Engine with SpeechRecognizer topic:
#include <AASB/Message/Alexa/SpeechRecognizer/StopCaptureMessage.h>
#include <AASB/Message/Alexa/SpeechRecognizer/EndOfSpeechDetectedMessage.h>
#include <AASB/Message/Alexa/SpeechRecognizer/WakewordDetectedMessage.h>
void SpeechRecognizerHandler::subscribeToAASBMessages() {
m_messageBroker->subscribe(
[=](const std::string& message) { handleEndOfSpeechDetectedMessage(message); },
EndOfSpeechDetectedMessage::topic(),
EndOfSpeechDetectedMessage::action());
m_messageBroker->subscribe(
[=](const std::string& message) { handleWakewordDetectedMessage(message); },
WakewordDetectedMessage::topic(),
WakewordDetectedMessage::action());
}
void SpeechRecognizerHandler::handleEndOfSpeechDetectedMessage(const std::string& message) {
// MessageBroker invokes this function when the Engine publishes a SpeechRecognizer.EndOfSpeechDetected message
// Do something here!
// Return quickly to avoid blocking MessageBroker's outgoing thread
}
void SpeechRecognizerHandler::handleWakewordDetectedMessage(const std::string& message) {
// MessageBroker invokes this function when the Engine publishes a SpeechRecognizer.WakewordDetected message
// Do something here!
// Return quickly to avoid blocking MessageBroker's outgoing thread
}
Note: For one Engine instance, you must subscribe to messages after configuring the Engine and before starting the Engine.
After configuring the Engine and subscribing to AASB messages, start the Engine by calling the Engine's start() function:
engine->start();Engine start initializes the internal Engine components for each Engine component your application uses. With respect to Alexa, it starts the connection to Alexa if there is an internet connection and an Alexa access token. Wait to publish messages to the Engine until after start() completes.
Your application can start the Engine more than once in its lifetime, if needed, by stopping the Engine and starting it again. However, you cannot start the Engine again after shutting it down.
When your application needs to halt the operations of the Engine, stop the Engine by calling the Engine's stop() function:
engine->stop();With respect to Alexa, stopping the Engine tears down the Alexa connection.
Typically, Engine stop is a cleanup step before Engine shutdown. However, if you stopped the Engine at runtime and need to start it again, calling start() resumes Engine operations. With respect to Alexa, this includes reestablishing the Alexa connection.
When your application is ready to exit, shut down the Engine by calling the Engine's shutdown() function.
engine->shutdown();Make sure you also stop the Engine prior to shutting it down. After shutdown completes, you can safely dispose of the pointer to your Engine instance. You cannot use this instance of the Engine again.
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 programatically with the relevant configuration factory functions.
Your application must provide the aace.vehicle configuration specified below. The properties of the vehicle configuration are used 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}}
}
}
}
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" |
Auto SDK provides the VehicleConfiguration::createVehicleInfoConfig() factory function to generate the configuration programatically.
Important! To pass the certification process, the
vehicleIdentifiervalue you provide must NOT be the vehicle identification number (VIN).
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 path to a directory for the Engine to create a 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. Components in the
Alexamodule have similar configuration to store feature-specific settings and data. See Configure the Alexa module for details.
By default, the Engine writes logs to the console. 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" |
| 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 logs files. | 5 |
| aace.logger. sinks[i]. config. append |
boolean | Yes | 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 used to filter logs written to the sink. Accepted values:
|
"VERBOSE" |
Click to expand or collapse details— Generate the configuration programatically with the C++ factory function
Auto SDK provides the LoggerConfiguration::createFileSinkConfig() factory function to generate the configuration programatically.
#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",
5242880,
5,
false);
engine->configure(
{
// ...other config objects...,
fileSinkConfig
}
);
The Auto SDK uses cURL for network connections. Your application can provide 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 header with the
PropertyManagerinterface by using theaace.network.httpProxyHeadersproperty name. You can also change the network interface at runtime with theaace.network.networkInterfaceproperty name.
Auto SDK provides the AlexaConfiguration::createCurlConfig() factory function to generate the configuration programatically.
When you use a module, the Engine services of that module enable every interface defined in the module. This means that for every interface, if your application does not subscribe to the AASB messages of the interface, the Engine performs default handling 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 change this enablement on a per-interface basis. The enabled setting tells the Engine service whether to enable the interface. 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:
{
"aasb.<message_handler_engine_service_name>": {
"<interface_name>": {
"enabled": false
}
}
}
For example, the below configuration disables the TemplateRuntime interface from the Alexa module and the LocationProvider interface from Core module.
{
"aasb.alexa": {
"TemplateRuntime": {
"enabled": false
}
},
"aasb.location": {
"LocationProvider": {
"enabled": false
}
}
}
All the messages published by the Engine through MessageBroker 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 MessageBroker cannot dispatch more messages while waiting. The following is an example of the Reply message for the LocationProvider.GetLocation message:
{
"header": {
"id": "4c4d13b6-6a8d-445b-931a-a3feb0878311",
"messageType": "Reply",
"version": "1.0",
"messageDescription": {
"replyToId": "23b578ed-6dc3-460a-998e-1647ba6cde42"
}
},
"payload": {
"location": {
"latitude": 37.410,
"longitude": -122.025
}
}
}
If your application does not publish the reply before the message timeout expires, the relevant Engine operation won't execute properly. The AASB message documentation for each interface specifies whether the interface requires any reply messages.
The default timeout value for these 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. The following example shows how to change the 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.
The Core module defines several Engine services for common functionality used by multiple Auto SDK modules. For example, the Core, Alexa, and Alexa Comms modules all require the application to play audio through platform-specific audio ouput channels. The Core module defines the core audio Engine service and corresponding AudioOutput AASB message interface, and all three modules use AudioOutput messages to request the application to play audio for their respective audio channels.
The following list describes the primary core Engine services provided by the Core module. Each service defines to one or more important AASB message interfaces that your application is required to use.
Note: This is not a list of every Engine service in the
Coremodule. For the most part, every AASB interface defined byCorealso corresponds to aCoremodule Engine service that other modules might care about. The following lists the foundational core services that matter most to your application; the Engine cannot function without these.
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. See Alexa Auto SDK Authorization for more information.
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. See Alexa Auto SDK Audio Channels for more information.
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. See Alexa Auto SDK Property Manager for more information.
The Core module defines interfaces for your application to provide key "core" information about the status of the application or its runtime environment.
Sometimes the user asks Alexa a question that requires she know the location in order to answer properly. For example, a user in San Francisco, California might say "Alexa, what's the weather?". This user probably wants to hear Alexa say something like "The weather in San Francisco is sixty-five degrees and overcast..." rather than something like "I can't find your exact location right now...". Similarly, the user might say "Alexa, take me to the nearest Whole Foods" and wants Alexa to start navigation to a Whole Foods that is actually nearby.
To provide the user with accurate responses to local search commands, weather questions, and more, obtain the user's consent to share their location with Alexa and use the LocationProvider interface.
Note: For Android applications, AACS provides a default implementation of
LocationProvider. See the AACS Default Implementation documentation for more information.
Your application should subscribe to the LocationProvider.GetLocation and LocationProvider.GetCountry messages to provide location data, such as geocoordinates and vehicle operating country, when the Engine requests it. These messages are synchronous-style and require your application to send the corresponding reply messages right away. To avoid blocking the MessageBroker outgoing thread and delaying user requests to Alexa, your application should keep the location data in a cache that you update frequently. Pull the location from the cache when the Engine requests it.
The Engine won't publish the GetLocation message if it knows your application has lost access to the location data. Keep the Engine in sync with the state of your application's location provider availability by proactively publishing the LocationServiceAccessChanged message at startup and each time the state changes. For example, your application might publish this message with access set to DISABLED if the system revokes your application's access to location or if GPS turns off.
Note: The Engine does not persist this state across device reboots. To ensure the Engine always knows the initial state of location availability, publish a
LocationServiceAccessChangedmessage each time you start the Engine. This includes notifying the Engine thataccessisENABLED.
Click to expand or collapse C++ example code
#include <AACE/Core/MessageBroker.h>
#include <AASB/Message/Location/LocationProvider/GetCountryMessage.h>
#include <AASB/Message/Location/LocationProvider/GetLocationMessage.h>
#include <AASB/Message/Location/LocationProvider/LocationServiceAccessChangedMessage.h>
class MyLocationProviderHandler {
// Call before you start the Engine
void MyLocationProviderHandler::subscribeToAASBMessages() {
m_messageBroker->subscribe(
[=](const std::string& message) { handleGetCountryMessage(message); },
GetCountryMessage::topic(),
GetCountryMessage::action());
m_messageBroker->subscribe(
[=](const std::string& message) { handleGetLocationMessage(message); },
GetLocationMessage::topic(),
GetLocationMessage::action());
}
void MyLocationProviderHandler::handleGetCountryMessage(const std::string& message) {
GetCountryMessage msg = json::parse(message);
// Quickly publish the GetCountry reply message
auto country = getCountryFromCache(); // implement this stub
GetCountryMessageReply replyMsg;
replyMsg.header.messageDescription.replyToId = msg.header.id;
replyMsg.payload.country = country;
m_messageBroker->publish(replyMsg.toString());
}
void MyLocationProviderHandler::handleGetLocationMessage(const std::string& message) {
GetLocationMessage msg = json::parse(message);
// Quickly publish the GetCountry reply message
auto location = getLocationFromCache(); // implement this stub
GetLocationMessageReply replyMsg;
replyMsg.header.messageDescription.replyToId = msg.header.id;
// parse "location" and populate the fields of the reply message
aasb::message::location::locationProvider::Location replyLocation;
replyLocation.latitude = ... ; // the latitude from "location";
replyLocation.longitude = ... ; // the longitude from "location";
replyMsg.payload.location = replyLocation;
m_messageBroker->publish(replyMsg.toString());
}
// Call when the application access to location data changes
// and after starting the Engine
void MyLocationProviderHandler::locationServiceAccessChanged(bool hasAccess) {
LocationServiceAccessChangedMessage msg;
if (hasAccess) {
msg.payload.access = aasb::message::location::locationProvider::LocationServiceAccess::ENABLED;
} else {
msg.payload.access = aasb::message::location::locationProvider::LocationServiceAccess::DISABLED;
}
m_messageBroker->publish(msg.toString());
}
}
Your application should monitor the network connection and notify the Engine of changes in the status using the NetworkInfoProvider interface. The Engine uses this information to adjust its behavior, including tearing down the connection to Alexa cloud when your application reports that there is no internet connection. Although using NetworkInfoProvider is optional, you should use it so the Engine can avoid undesirable behavior; for instance, attempting to send events to Alexa when the lack of connectivity means the events are bound to fail.
Note: You must use the
NetworkInfoProviderinterface if your application uses the Local Voice Control (LVC) extension.
Note: For Android applications, AACS provides a default implementation of
NetworkInfoProvider. See the AACS Default Implementation documentation for more information.
Various Engine components want the initial network status at startup so they can adapt their initial behavior accordingly. Your application should subscribe to the NetworkInfoProvider.GetNetworkStatus and NetworkInfoProvider.GetWifiSignalStrength to answer the inital query from the Engine. These messages are synchronous-style and require your application to send the corresponding reply messages right away.
At runtime, publish the NetworkInfoProvider.NetworkStatusChanged message to notify the Engine of any status changes.
Periodically publish the DeviceUsage.ReportNetworkDataUsage message (for example, at five minute intervals) to report network data usage to the Engine. If your application uses the Device Client Metrics (DCM) extension, the Engine tracks metrics with this information.
The usage field in the payload is a JSON object as a string. The format of the JSON is the following:
{
"startTimeStamp" : {{LONG}},
"endTimeStamp" : {{LONG}},
"networkInterfaceType": "{{STRING}}",
"dataPlanType" : "{{STRING}}",
"bytesUsage" :{
"rxBytes" : {{LONG}},
"txBytes" : {{LONG}}
}
}
The following table describes the properties in the JSON:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| startTimeStamp | long | Yes | The starting timestamp in milliseconds for this network usage datapoint | — |
| endTimeStamp | long | Yes | The ending timestamp in milliseconds for this network usage datapoint | — |
| networkInterfaceType | string | Yes | The network interface name over which the data is recorded | "WIFI", "MOBILE" |
| dataPlanType | string | No | The type of data plan the device is subscribed to. This is an optional field and should be provided if your application uses the AlexaConnectivity module. |
See AlexaConnectivity |
| bytesUsage .rxBytes |
long | Yes | The bytes received over the network interface | — |
| bytesUsage .txBytes |
long | Yes | The bytes transmitted over the network interface | — |