Alexa Auto SDK  4.3
Public Member Functions | Static Public Member Functions | List of all members
aace::carControl::config::CarControlConfiguration Class Referenceabstract

Public Member Functions

virtual CarControlConfigurationcreateEndpoint (const std::string &endpointId)=0
 
virtual CarControlConfigurationaddAssetId (const std::string &assetId)=0
 
virtual CarControlConfigurationaddPowerController (bool retrievable)=0
 
virtual CarControlConfigurationaddToggleController (const std::string &instanceId, bool retrievable)=0
 
virtual CarControlConfigurationaddActionTurnOn (const std::vector< std::string > &actions)=0
 
virtual CarControlConfigurationaddActionTurnOff (const std::vector< std::string > &actions)=0
 
virtual CarControlConfigurationaddRangeController (const std::string &instanceId, bool retrievable, double minimum, double maximum, double precision, const std::string &unit="")=0
 
virtual CarControlConfigurationaddPreset (double value)=0
 
virtual CarControlConfigurationaddActionSetRange (const std::vector< std::string > &actions, double value)=0
 
virtual CarControlConfigurationaddActionAdjustRange (const std::vector< std::string > &actions, double delta)=0
 
virtual CarControlConfigurationaddModeController (const std::string &instanceId, bool retrievable, bool ordered)=0
 
virtual CarControlConfigurationaddValue (const std::string &value)=0
 
virtual CarControlConfigurationaddActionSetMode (const std::vector< std::string > &actions, const std::string &value)=0
 
virtual CarControlConfigurationaddActionAdjustMode (const std::vector< std::string > &actions, int delta)=0
 
virtual CarControlConfigurationcreateZone (const std::string &zoneId)=0
 
virtual CarControlConfigurationaddMembers (const std::vector< std::string > &endpointIds)=0
 
virtual CarControlConfigurationsetDefaultZone (const std::string &zoneId)=0
 
virtual CarControlConfigurationaddDefaultAssetsPath (const std::string &path)=0
 
virtual CarControlConfigurationaddCustomAssetsPath (const std::string &path)=0
 
- Public Member Functions inherited from aace::core::config::EngineConfiguration
virtual std::shared_ptr< std::istream > getStream ()=0
 

Static Public Member Functions

static std::shared_ptr< CarControlConfigurationcreate ()
 

Detailed Description

The CarControlConfiguration class programmatically generates the "aace.carControl" aace::core::config::EngineConfiguration. "aace.carControl" configuration specifies additional endpoints that are connected and controllable through the root endpoint that maintains the connection to the Alexa service. Each connected endpoint represents a controllable component of the vehicle and should be configured with any of the supported capabilities (i.e. PowerController and primitives ModeController, ToggleController, RangeController ) to model how the endpoint can be controlled with voice.

Using the methods on an instance of this class produces configuration data in the format of the following example:

{
"aace.carControl": {
"endpoints": [
{
"endpointId": "default.ac",
"endpointResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.DeviceName.AirConditioner"
}
}
]
},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": false,
"retrievable": false
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.ModeController",
"version": "3",
"instance": "intensity",
"capabilityResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Setting.Intensity"
}
}
]
},
"properties": {
"supported": [
{
"name": "mode"
}
],
"proactivelyReported": false,
"retrievable": false
},
"configuration": {
"ordered": true,
"supportedModes": [
{
"value": "LOW",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Value.Low"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Value.Minimum"
}
}
]
}
},
{
"value": "MEDIUM",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Value.Medium"
}
}
]
}
},
{
"value": "HIGH",
"modeResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Value.High"
}
},
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Value.Maximum"
}
}
]
}
}
]
},
"semantics" : {
"actionMappings": [
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Raise"],
"directive": {
"name": "AdjustMode",
"payload": {"modeDelta": 1}
}
},
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Lower"],
"directive": {
"name": "AdjustMode",
"payload": {"modeDelta": -1}
}
}
]
}
}
]
}
],
"zones": [
{
"zoneId": "zone.default",
"zoneResources": {
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Automotive.Location.All"
}
}
]
},
"members": [
{
"endpointId": "default.ac"
}
]
}
],
"defaultZoneId" : "zone.default",
"assets" : {
"customAssetsPath" : "/opt/AAC/assets-3P.json"
}
}
}

note This class acts as a configuration builder, so the method calls must be ordered to produce the intended configuration.

Member Function Documentation

◆ create()

static std::shared_ptr<CarControlConfiguration> aace::carControl::config::CarControlConfiguration::create ( )
static

Create a CarControlConfiguration instance.

◆ createEndpoint()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::createEndpoint ( const std::string &  endpointId)
pure virtual

Begin an endpoint definition using the specified endpoint ID. This creates a single entry in the "endpoints" array of 'aace.carControl'.

Note
Do not use the following format for the endpointId: <clientId>::<productId>::<serialNumber>::[-<extEndpoint>]. The Engine internally prepends the 3-part device prefix to your specified endpointId before sending the configuration to the cloud in an AddOrUpdateReport event. Configuring the full ID directly results in duplication and excess characters.
Parameters
[in]endpointIdThe unique identifier for the endpoint.
Returns
CarControlConfiguration to allow chaining.

◆ addAssetId()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addAssetId ( const std::string &  assetId)
pure virtual

Add an asset ID to the enclosing element. This can be called to add an asset ID to the friendly names list for the following elements:

  • The 'endpointResources' of an endpoint definition
  • The 'capabilityResources' of a ToggleController, RangeController, or ModeController definition
  • The 'presetResources' of a RangeController preset definition
  • The 'modeResources' of a ModeController mode definition
Note
Specify only valid asset IDs. See CarControlAssets.h for a full list of the asset IDs supported by default.
Parameters
[in]assetIdThe identifier of the asset.
Returns
CarControlConfiguration to allow chaining.

◆ addPowerController()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addPowerController ( bool  retrievable)
pure virtual

Add a PowerController capability to the enclosing endpoint. Only one instance is allowed per endpoint.

See also
https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/alexa-powercontroller.html.
Parameters
[in]retrievableWhether the state of this instance may be retrieved by the Alexa service. Only false is supported.
Returns
CarControlConfiguration to allow chaining.

◆ addToggleController()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addToggleController ( const std::string &  instanceId,
bool  retrievable 
)
pure virtual

Add a ToggleController capability to the enclosing endpoint. Multiple instances are allowed per endpoint. Call addAsset() to add friendly names to the 'capabilityResources' of this instance.

See also
https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/alexa-togglecontroller.html.
Parameters
[in]instanceIdThe identifier of this ToggleController instance. Must be unique with respect to the enclosing endpoint.
[in]retrievableWhether the state of this instance may be retrieved by the Alexa service. Only false is supported.
Returns
CarControlConfiguration to allow chaining.

◆ addActionTurnOn()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addActionTurnOn ( const std::vector< std::string > &  actions)
pure virtual

Maps the specified action IDs to the TurnOn directive for the enclosing ToggleController. This adds a 'semantics.actionMappings' entry to its definition. aace::carControl::CarControl::turnToggleControllerOn() is invoked when the user says the additional utterances enabled by the specified action ID(s).

Note
Use a specific action ID only once per endpoint.
Only the action IDs defined in the aace::carControl::config::action namespace are supported.
Parameters
[in]actionsThe action IDs to map to the TurnOn directive.

◆ addActionTurnOff()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addActionTurnOff ( const std::vector< std::string > &  actions)
pure virtual

Maps the specified action IDs to the TurnOff directive for the enclosing ToggleController. This adds a 'semantics.actionMappings' entry to its definition. aace::carControl::CarControl::turnToggleControllerOff() is invoked when the user says the additional utterances enabled by the specified action ID(s).

Note
Use a specific action ID only once per endpoint.
Only the action IDs defined in the aace::carControl::config::action namespace are supported.
Parameters
[in]actionsThe action IDs to map to the TurnOff directive.

◆ addRangeController()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addRangeController ( const std::string &  instanceId,
bool  retrievable,
double  minimum,
double  maximum,
double  precision,
const std::string &  unit = "" 
)
pure virtual

Add a RangeController capability to the enclosing endpoint. Multiple instances are allowed per endpoint. Call addAsset() to add friendly names to the 'capabilityResources' of this instance.

See also
https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/alexa-rangecontroller.html
Parameters
[in]instanceIdThe identifier of this RangeController instance. Must be unique with respect to the enclosing endpoint.
[in]retrievableWhether the state of this instance may be retrieved by the Alexa service. Only false is supported.
[in]minimumThe minimum value of the range supported by this instance.
[in]minimumThe maximum value of the range supported by this instance.
[in]precisionThe amount by which the set value changes when iterating through the range.
[in]unitThe unit of the measure.
Returns
CarControlConfiguration to allow chaining.

◆ addPreset()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addPreset ( double  value)
pure virtual

Add a 'preset' to the enclosing RangeController instance. A preset describes a value that can be invoked by name. Call addAsset() to add friendly names to 'presetResources' of this preset.

Parameters
[in]valueThe value within the range that has an associated named preset.
Returns
CarControlConfiguration to allow chaining.

◆ addActionSetRange()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addActionSetRange ( const std::vector< std::string > &  actions,
double  value 
)
pure virtual

Maps the specified action IDs to the SetRangeValue directive for the enclosing RangeController. This adds a 'semantics.actionMappings' entry to its definition. aace::carControl::CarControl::setRangeControllerValue() is invoked when the user says the additional utterances enabled by the specified action ID(s).

Note
Use a specific action ID only once per endpoint.
Only the action IDs defined in the aace::carControl::config::action namespace are supported.
Parameters
[in]actionsThe action IDs to map to the SetRangeValue directive.
[in]valueThe value argument of setRangeControllerValue(). The value must be within the configured range of this RangeController instance.

◆ addActionAdjustRange()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addActionAdjustRange ( const std::vector< std::string > &  actions,
double  delta 
)
pure virtual

Maps the specified action IDs to AdjustRangeValue directive for the enclosing RangeController. This adds a 'semantics.actionMappings' entry to its definition. aace::carControl::CarControl::adjustRangeControllerValue() will be invoked when the user says the additional utterances enabled by the specified action ID(s).

Note
Use a specific action ID only once per endpoint.
Only the action IDs defined in the aace::carControl::config::action namespace are supported.
Parameters
[in]actionsThe action IDs to map to the AdjustRangeValue directive.
[in]deltaThe delta argument of adjustRangeControllerValue(). The absolute value must be <= (max - min) configured for this RangeController instance.

◆ addModeController()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addModeController ( const std::string &  instanceId,
bool  retrievable,
bool  ordered 
)
pure virtual

Add a ModeController capability to the enclosing endpoint. Multiple instances are allowed per endpoint. Call addAsset() to add friendly names to the 'capabilityResources' of this instance.

See also
https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/alexa-modecontroller.html
Parameters
[in]instanceIdThe identifier of this ModeController instance. Must be unique with respect to the enclosing endpoint.
[in]retrievableWhether the state of this instance may be retrieved by the Alexa service. Only false is supported.
[in]Whetherthe modes are ordered, enabling iteration through them using the AdjustMode directive.
Returns
CarControlConfiguration to allow chaining.

◆ addValue()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addValue ( const std::string &  value)
pure virtual

Add a supported mode 'value' to the enclosing ModeController instance. If ordered is true, the order in which modes are created with calls to this method determines the ordering for iteration by voice. Call addAsset() to add friendly names to 'modeResources' of this mode.

Parameters
[in]valueThe identifier of the mode.
Returns
CarControlConfiguration to allow chaining.

◆ addActionSetMode()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addActionSetMode ( const std::vector< std::string > &  actions,
const std::string &  value 
)
pure virtual

Maps the specified action IDs to the SetMode directive for the enclosing ModeController. This adds a 'semantics.actionMappings' entry to its definition. aace::carControl::CarControl::setModeControllerValue() is invoked when the user says the additional utterances enabled by the specified action ID(s).

Note
Use a specific action ID only once per endpoint.
Only the action IDs defined in the aace::carControl::config::action namespace are supported.
Parameters
[in]actionsThe action IDs to map to the SetMode directive.
[in]valueThe value argument of setModeControllerValue() specifying the mode to set. The value must be one configured for this ModeController instance.

◆ addActionAdjustMode()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addActionAdjustMode ( const std::vector< std::string > &  actions,
int  delta 
)
pure virtual

Maps the specified action IDs to the AdjustMode directive for the enclosing ModeController. This adds a 'semantics.actionMappings' entry to its definition. aace::carControl::CarControl::adjustModeControllerValue() is invoked when the user says the additional utterances enabled by the specified action ID(s).

Note
This may only be used if ordered is true for this ModeController instance.
Use a specific action ID only once per endpoint.
Only the action IDs defined in the aace::carControl::config::action namespace are supported.
Parameters
[in]actionsThe action IDs to map to the AdjustMode directive.
[in]deltaThe delta argument of adjustModeControllerValue() specifying the number of modes to advance from the current mode setting.

◆ createZone()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::createZone ( const std::string &  zoneId)
pure virtual

Begin a zone definition using the specified zone ID. This creates a single entry in the "zones" array of 'aace.carControl'. Call addMembers() to add endpoint IDs as members of this zone.

Parameters
[in]zoneIdThe unique identifier for the zone.
Returns
CarControlConfiguration to allow chaining.

◆ addMembers()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addMembers ( const std::vector< std::string > &  endpointIds)
pure virtual

Add the specified endpoint IDs to the definition of the enclosing zone.

Note
An endpoint ID added to this zone instance may belong to other zones as well.
Parameters
[in]endpointIdsThe IDs of the endpoints belonging to this zone. Endpoint IDs used must correspond to endpoints created with createEndpoint().
Returns
CarControlConfiguration to allow chaining.

◆ setDefaultZone()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::setDefaultZone ( const std::string &  zoneId)
pure virtual

Set the default zone to the specified zone ID. This allows the endpoints in the specified default zone to take precedence over endpoints not in the default zone when the user does not specify any zone in the utterance.

Note
There can only be one default zone. Multiple calls to this method will override the previously set default.
Parameters
[in]zoneIdThe ID of the default zone.
Returns
CarControlConfiguration to allow chaining.

◆ addDefaultAssetsPath()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addDefaultAssetsPath ( const std::string &  path)
pure virtual
Deprecated:

Specify the path to a file that defines the default assets. This creates an "assets.defaultAssetsPath" entry in 'aace.carControl'.

Note
Using this method is not necessary or recommended. The default assets are already defined internally. including all supported locales and use the asset IDs present in CarControlAssets.h. This method can override the internal asset definitions in online-only use cases (without the LVC extension).
Parameters
[in]pathThe path to the file defining the default assets.

◆ addCustomAssetsPath()

virtual CarControlConfiguration& aace::carControl::config::CarControlConfiguration::addCustomAssetsPath ( const std::string &  path)
pure virtual

Specify the path to a file that defines additional assets. This creates an "assets.customAssetsPath" entry in 'aace.carControl'. Specify a path to additional assets if you have endpoints that cannot be modeled using the default asset IDs present in CarControlAssets.h.

Parameters
[in]pathThe path to the file defining additional assets.

Alexa Auto SDK 4.3 - Copyright 2017-2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0