Public Member Functions
virtual CarControlConfiguration &	createEndpoint (const std::string &endpointId)=0

virtual CarControlConfiguration &	addAssetId (const std::string &assetId)=0

virtual CarControlConfiguration &	addPowerController (bool retrievable)=0

virtual CarControlConfiguration &	addToggleController (const std::string &instanceId, bool retrievable)=0

virtual CarControlConfiguration &	addActionTurnOn (const std::vector< std::string > &actions)=0

virtual CarControlConfiguration &	addActionTurnOff (const std::vector< std::string > &actions)=0

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

virtual CarControlConfiguration &	addPreset (double value)=0

virtual CarControlConfiguration &	addActionSetRange (const std::vector< std::string > &actions, double value)=0

virtual CarControlConfiguration &	addActionAdjustRange (const std::vector< std::string > &actions, double delta)=0

virtual CarControlConfiguration &	addModeController (const std::string &instanceId, bool retrievable, bool ordered)=0

virtual CarControlConfiguration &	addValue (const std::string &value)=0

virtual CarControlConfiguration &	addActionSetMode (const std::vector< std::string > &actions, const std::string &value)=0

virtual CarControlConfiguration &	addActionAdjustMode (const std::vector< std::string > &actions, int delta)=0

virtual CarControlConfiguration &	createZone (const std::string &zoneId)=0

virtual CarControlConfiguration &	addMembers (const std::vector< std::string > &endpointIds)=0

virtual CarControlConfiguration &	setDefaultZone (const std::string &zoneId)=0

virtual CarControlConfiguration &	addDefaultAssetsPath (const std::string &path)=0

virtual CarControlConfiguration &	addCustomAssetsPath (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< CarControlConfiguration >	create ()

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] endpointId The 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] assetId The 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] retrievable Whether 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]	instanceId	The identifier of this ToggleController instance. Must be unique with respect to the enclosing endpoint.
[in]	retrievable	Whether 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] actions The 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] actions The 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]	instanceId	The identifier of this RangeController instance. Must be unique with respect to the enclosing endpoint.
[in]	retrievable	Whether the state of this instance may be retrieved by the Alexa service. Only `false` is supported.
[in]	minimum	The minimum value of the range supported by this instance.
[in]	minimum	The maximum value of the range supported by this instance.
[in]	precision	The amount by which the set value changes when iterating through the range.
[in]	unit	The 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] value The 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]	actions	The action IDs to map to the SetRangeValue directive.
[in]	value	The 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]	actions	The action IDs to map to the AdjustRangeValue directive.
[in]	delta	The 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]	instanceId	The identifier of this ModeController instance. Must be unique with respect to the enclosing endpoint.
[in]	retrievable	Whether the state of this instance may be retrieved by the Alexa service. Only `false` is supported.
[in]	Whether	the 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] value The 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]	actions	The action IDs to map to the SetMode directive.
[in]	value	The 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]	actions	The action IDs to map to the AdjustMode directive.
[in]	delta	The 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] zoneId The 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] endpointIds The 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] zoneId The 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] path The 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] path The path to the file defining additional assets.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ create()

◆ createEndpoint()

◆ addAssetId()

◆ addPowerController()

◆ addToggleController()

◆ addActionTurnOn()

◆ addActionTurnOff()

◆ addRangeController()

◆ addPreset()

◆ addActionSetRange()

◆ addActionAdjustRange()

◆ addModeController()

◆ addValue()

◆ addActionSetMode()

◆ addActionAdjustMode()

◆ createZone()

◆ addMembers()

◆ setDefaultZone()

◆ addDefaultAssetsPath()

◆ addCustomAssetsPath()