Version 1.17.0 alexa-client-sdk

Changes in this update:

**Enhancements**

- Added support for [captions for TTS](https://developer.amazon.com/docs/avs-device-sdk/features.html#captions). This enhancement allows you to print onscreen captions for Alexa voice responses.
- Added support for [SpeechSynthesizer Interface 1.3](https://developer.amazon.com/docs/alexa-voice-service/speechsynthesizer.html). This interface supports the new `captions` parameter.
- Added support for [AudioPlayer Interface 1.3](https://developer.amazon.com/docs/alexa-voice-service/audioplayer.html). This interface supports the new `captions` parameter.
- Added support for [Interaction Model 1.2](https://developer.amazon.com/docs/alexa-voice-service/interactionmodel-interface.html).
- Added support for [System 2.0](https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/system.html).
- Added support for Alarm Volume Ramp. This feature lets you to fade in alarms for a more pleasant experience. You enable alarm volume ramp in the sample app through the settings menu.
- Added support for using certified senders for URI path extensions. This change allows you to specify the URI path extension when sending messages with [`CertifiedSender::sendJSONMessage`](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1certified_sender_1_1_certified_sender.html#a4c0706d79717b226ba77d1a9c3280fe6).
- Added new [`Metrics`](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1avs_common_1_1utils_1_1_metrics.html) interfaces and helper classes. These additions help you create and consume [`Metrics`](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1avs_common_1_1utils_1_1_metrics.html) events.
 - **Interfaces** - `MetricRecorderInterface`, `MetricSinkInterface`.
 - **Helper Classes** - `DataPointStringBuilder`, `DataPointCounterBuilder`, `DataPointDurationBuilder`, `MetricEventBuilder`.

- Added support for the following AVS [endpoint](../avs-device-sdk/endpoints.html) controller capabilities:
 - [Alexa.ModeController](https://developer.amazon.com/docs/alexa-voice-service/alexa-modecontroller.html)
 - [Alexa.RangeController](https://developer.amazon.com/docs/alexa-voice-service/alexa-rangecontroller.html)
 - [Alexa.PowerController](https://developer.amazon.com/docs/alexa-voice-service/alexa-powercontroller.html)
 - [Alexa.ToggleController](https://developer.amazon.com/docs/alexa-voice-service/alexa-togglecontroller.html)

- Added `PowerResourceManagerInterface`. This interface allows the SDK to control power resource levels for components such as the `AudioInputProcessor` and `SpeechSynthesizer`.
- Added `AlexaInterfaceCapabilityAgent`. This Capability Agent handles common directives and endpoint controller capabilities support by [`Alexa.AlexaInterface`](../alexa-voice-service/alexa.html).
- Added `AlexaInterfaceMessageSenderInterface`. This interface is required to send common events defined by the `Alexa.AlexaInterface` interface.
- Added `BufferingComplete` to [`MediaPlayerObserverInterface`](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1avs_common_1_1utils_1_1media_player_1_1_media_player_observer_interface.html). This method helps improve performance in poor networking conditions by making sure `MediaPlayer` pre-buffers correctly.
- Added `SendDTMF` to `CallManagerInterface`. This method allows you to send DTMF tones during calls.

**New build options**

- CAPTIONS
 - **ADDED** [`CAPTIONS`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#captions)
 - **ADDED** [`LIBWEBVTT_LIB_PATH`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#captions)
 - **ADDED** [`LIBWEBVTT_INCLUDE_DIR`](https://developer.amazon.com/docs//avs-device-sdk/cmake-parameters.html#captions)
- METRICS
 - **ADDED** [`METRICS`](https://developer.amazon.com/docs//avs-device-sdk/cmake-parameters.html#metrics)
- ENDPONTS
 - **ADDED** [`ENABLE_ALL_ENDPOINT_CONTROLLERS`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#endpoints)
 - **ADDED** [`ENABLE_POWER_CONTROLLER`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#endpoints)
 - **ADDED** [`ENABLE_TOGGLE_CONTROLLER`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#endpoints)
 - **ADDED** [`ENABLE_RANGE_CONTROLLER`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#endpoints)
 - **ADDED** [`ENABLE_MODE_CONTROLLER`](https://developer.amazon.com/docs/avs-device-sdk/cmake-parameters.html#endpoints)

**New dependencies**

- To use captions, you must install a [new dependency](https://developer.amazon.com/docs/avs-device-sdk/dependencies) – the [libwebvtt parsing library](https://github.com/alexa/webvtt). Webvtt is a C/C++ library for interpreting and authoring conformant WebVTT content. WebVTT is a caption and subtitle format designed for use with HTML5 audio and video elements.

**Bug fixes**

- Fixed [`MimeResponseSink::onReceiveNonMimeData`](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1acl_1_1_mime_response_sink.html) [data issue](#1519) that returned invalid data.
- Fixed [data type issue](#1519) that incorrectly used `finalResponseCode` instead of [`FinalResponseCodeId`](https://github.com/alexa/avs-device-sdk/blob/master/AVSCommon/Utils/src/LibcurlUtils/LibCurlHttpContentFetcher.cpp#L370).
- Fixed [`UrlContentToAttachmentConverter`](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1playlist_parser_1_1_url_content_to_attachment_converter.html) issue that used the incorrect range parameter.
- Fixed `FinallyGuard` [linking issue](#1517) that caused problems compiling the SDK on iOS.
- Fixed a [Bluetooth Capability Agent](https://alexa.github.io/avs-device-sdk/classalexa_client_s_d_k_1_1capability_agents_1_1bluetooth_1_1_bluetooth.html) bug that prevented devices from initializing.

**Known Issues**

* The WebVTT dependency required for `captions` isn't supported for Windows/Android.
* Music playback history isn't displayed in the Alexa app for certain account and device types.
* When using Gnu Compiler Collection 8+ (GCC 8+), `-Wclass-memaccess` triggers warnings. You can ignore these, they don't cause the build to fail.
* Android error `libDefaultClient.so not found` might occur. Resolve this by upgrading to ADB version 1.0.40.
* If a device loses a network connection, the lost connection status isn't returned via local TTS.
* ACL encounters issues if it receives audio attachments but doesn't consume them.
* `SpeechSynthesizerState` uses `GAINING_FOCUS` and `LOSING_FOCUS` as a workaround for handling intermediate states.
* Media steamed through Bluetooth might abruptly stop. To restart playback, resume the media in the source application or toggle next/previous.
* If a connected Bluetooth device is inactive, the Alexa app might indicates that audio is playing.
* The Bluetooth agent assumes that the Bluetooth adapter is always connected to a power source. Disconnecting from a power source during operation isn't yet supported.
* When using some products, interrupted Bluetooth playback might not resume if other content is locally streamed.
* `make integration` isn't available for Android. To run Android integration tests, manually upload the test binary and input file and run ADB.
* Alexa might truncate the beginning of speech when responding to text-to-speech (TTS) user events. This only impacts Raspberry Pi devices running Android Things with HDMI output audio.
* A reminder TTS message doesn't play if the sample app restarts and loses a network connection. Instead, the default alarm tone plays twice.
* `ServerDisconnectIntegratonTest` tests are disabled until they are updated to reflect new service behavior.
* Bluetooth initialization must complete before connecting devices, otherwise devices are ignored.
* The `DirectiveSequencerTest.test_handleBlockingThenImmediatelyThenNonBockingOnSameDialogId` test fails intermittently.
* On some devices, Alexa gets stuck in a permanent listening state. Pressing `t` and `h` in the Sample App doesn't exit the listening state.
* Exiting the settings menu doesn't provide a message to indicate that you're back in the main menu.

ACL/include/ACL/AVSConnectionManager.h

@@ -24,7 +24,7 @@
 
 #include <AVSCommon/AVS/AbstractAVSConnectionManager.h>
 #include <AVSCommon/AVS/MessageRequest.h>
-#include <AVSCommon/SDKInterfaces/AVSEndpointAssignerInterface.h>
+#include <AVSCommon/SDKInterfaces/AVSGatewayAssignerInterface.h>
 #include <AVSCommon/SDKInterfaces/ConnectionStatusObserverInterface.h>
 #include <AVSCommon/SDKInterfaces/InternetConnectionMonitorInterface.h>
 #include <AVSCommon/SDKInterfaces/MessageObserverInterface.h>
@@ -70,7 +70,7 @@ namespace acl {
 class AVSConnectionManager
  : public avsCommon::avs::AbstractAVSConnectionManager
  , public avsCommon::sdkInterfaces::MessageSenderInterface
- , public avsCommon::sdkInterfaces::AVSEndpointAssignerInterface
+ , public avsCommon::sdkInterfaces::AVSGatewayAssignerInterface
  , public MessageRouterObserverInterface
  , public avsCommon::sdkInterfaces::InternetConnectionObserverInterface
  , public avsCommon::utils::RequiresShutdown
@@ -112,15 +112,15 @@ class AVSConnectionManager
  void sendMessage(std::shared_ptr<avsCommon::avs::MessageRequest> request) override;
 
  /**
- * @note Set the URL endpoint for the AVS connection. Calling this function with a new value will cause the
- * current active connection to be closed, and a new one opened to the new endpoint.
+ * @note Set the gateway URL for the AVS connection. Calling this function with a new value will cause the
+ * current active connection to be closed, and a new one opened to the new gateway.
  */
- void setAVSEndpoint(const std::string& avsEndpoint) override;
+ void setAVSGateway(const std::string& avsGateway) override;
 
  /**
- * @return The current URL endpoint for AVS connection.
+ * @return The current gateway URL for AVS connection.
  */
- std::string getAVSEndpoint();
+ std::string getAVSGateway();
 
  /// @name InternetConnectionObserverInterface method overrides.
  /// @{

ACL/include/ACL/Transport/ExchangeHandlerContextInterface.h

@@ -101,9 +101,9 @@ class ExchangeHandlerContextInterface {
  const avsCommon::utils::http2::HTTP2RequestConfig& cfg) = 0;
 
  /**
- * Get AVS endpoint to send request to.
+ * Get AVS gateway to send request to.
  */
- virtual std::string getEndpoint() = 0;
+ virtual std::string getAVSGateway() = 0;
 };
 
 } // namespace acl

ACL/include/ACL/Transport/HTTP2Transport.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2016-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License").
  * You may not use this file except in compliance with the License.
@@ -29,12 +29,12 @@
 #include <AVSCommon/AVS/Attachment/AttachmentManager.h>
 #include <AVSCommon/Utils/HTTP2/HTTP2ConnectionInterface.h>
 #include <AVSCommon/SDKInterfaces/AuthDelegateInterface.h>
+#include <AVSCommon/SDKInterfaces/PostConnectSendMessageInterface.h>
 
 #include "ACL/Transport/MessageConsumerInterface.h"
 #include "ACL/Transport/PingHandler.h"
 #include "ACL/Transport/PostConnectFactoryInterface.h"
 #include "ACL/Transport/PostConnectObserverInterface.h"
-#include "ACL/Transport/PostConnectSendMessageInterface.h"
 #include "ACL/Transport/TransportInterface.h"
 #include "ACL/Transport/TransportObserverInterface.h"
 
@@ -48,7 +48,7 @@ class HTTP2Transport
  : public std::enable_shared_from_this<HTTP2Transport>
  , public TransportInterface
  , public PostConnectObserverInterface
- , public PostConnectSendMessageInterface
+ , public avsCommon::sdkInterfaces::PostConnectSendMessageInterface
  , public avsCommon::sdkInterfaces::AuthObserverInterface
  , public ExchangeHandlerContextInterface {
 public:
@@ -69,7 +69,7 @@ class HTTP2Transport
  * A function that creates a HTTP2Transport object.
  *
  * @param authDelegate The AuthDelegate implementation.
- * @param avsEndpoint The URL for the AVS endpoint of this object.
+ * @param avsGateway The URL for the AVS gateway of this object.
  * @param http2Connection Instance of HTTP2ConnectionInterface with which to perform HTTP2 operations.
  * @param messageConsumer The MessageConsumerInterface to pass messages to.
  * @param attachmentManager The attachment manager that manages the attachments.
@@ -80,7 +80,7 @@ class HTTP2Transport
  */
  static std::shared_ptr<HTTP2Transport> create(
  std::shared_ptr<avsCommon::sdkInterfaces::AuthDelegateInterface> authDelegate,
- const std::string& avsEndpoint,
+ const std::string& avsGateway,
  std::shared_ptr<avsCommon::utils::http2::HTTP2ConnectionInterface> http2Connection,
  std::shared_ptr<MessageConsumerInterface> messageConsumer,
  std::shared_ptr<avsCommon::avs::attachment::AttachmentManager> attachmentManager,
@@ -125,6 +125,7 @@ class HTTP2Transport
  /// @name PostConnectObserverInterface methods.
  /// @{
  void onPostConnected() override;
+ void onUnRecoverablePostConnectFailure() override;
  /// @}
 
  /// @name AuthObserverInterface methods
@@ -153,7 +154,7 @@ class HTTP2Transport
  void onForbidden(const std::string& authToken = "") override;
  std::shared_ptr<avsCommon::utils::http2::HTTP2RequestInterface> createAndSendRequest(
  const avsCommon::utils::http2::HTTP2RequestConfig& cfg) override;
- std::string getEndpoint() override;
+ std::string getAVSGateway() override;
  /// @}
 
 private:
@@ -189,7 +190,7 @@ class HTTP2Transport
  * HTTP2Transport Constructor.
  *
  * @param authDelegate The AuthDelegate implementation.
- * @param avsEndpoint The URL for the AVS endpoint of this object.
+ * @param avsGateway The URL for the AVS gateway of this object.
  * @param http2Connection Instance of HTTP2ConnectionInterface with which to perform HTTP2 operations.
  * @param messageConsumer The MessageConsumerInterface to pass messages to.
  * @param attachmentManager The attachment manager that manages the attachments.
@@ -199,7 +200,7 @@ class HTTP2Transport
  */
  HTTP2Transport(
  std::shared_ptr<avsCommon::sdkInterfaces::AuthDelegateInterface> authDelegate,
- const std::string& avsEndpoint,
+ const std::string& avsGateway,
  std::shared_ptr<avsCommon::utils::http2::HTTP2ConnectionInterface> http2Connection,
  std::shared_ptr<MessageConsumerInterface> messageConsumer,
  std::shared_ptr<avsCommon::avs::attachment::AttachmentManager> attachmentManager,
@@ -354,7 +355,7 @@ class HTTP2Transport
  std::shared_ptr<avsCommon::sdkInterfaces::AuthDelegateInterface> m_authDelegate;
 
  /// The URL of the AVS server we will connect to.
- std::string m_avsEndpoint;
+ std::string m_avsGateway;
 
  /// The HTTP2ConnectionInterface with which to perform HTTP2 operations.
  std::shared_ptr<avsCommon::utils::http2::HTTP2ConnectionInterface> m_http2Connection;

ACL/include/ACL/Transport/HTTP2TransportFactory.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License").
  * You may not use this file except in compliance with the License.
@@ -51,7 +51,7 @@ class HTTP2TransportFactory : public TransportFactoryInterface {
  std::shared_ptr<TransportInterface> createTransport(
  std::shared_ptr<avsCommon::sdkInterfaces::AuthDelegateInterface> authDelegate,
  std::shared_ptr<avsCommon::avs::attachment::AttachmentManager> attachmentManager,
- const std::string& avsEndpoint,
+ const std::string& avsGateway,
  std::shared_ptr<MessageConsumerInterface> messageConsumerInterface,
  std::shared_ptr<TransportObserverInterface> transportObserverInterface) override;
  /// @}

ACL/include/ACL/Transport/MessageRouter.h

@@ -54,14 +54,15 @@ class MessageRouter
  * the MessageRouter can authorize the client to AVS.
  * @param attachmentManager The AttachmentManager, which allows ACL to write attachments received from AVS.
  * @param transportFactory Factory used to create new transport objects.
- * @param avsEndpoint The endpoint to connect to AVS. If empty the "endpoint" value of the "acl" configuration
- * will be used. If there no such configuration value a default value will be used instead.
+ * @param avsGateway The gateway to connect to AVS. The value will be set by the @c AVSGatewayManager based on
+ * either the previously verified gateway or a value from the config file. If both are not present, a default value
+ * is used.
  */
  MessageRouter(
  std::shared_ptr<avsCommon::sdkInterfaces::AuthDelegateInterface> authDelegate,
  std::shared_ptr<avsCommon::avs::attachment::AttachmentManager> attachmentManager,
  std::shared_ptr<TransportFactoryInterface> transportFactory,
- const std::string& avsEndpoint = "");
+ const std::string& avsGateway = "");
 
  void enable() override;
 
@@ -71,9 +72,9 @@ class MessageRouter
 
  void sendMessage(std::shared_ptr<avsCommon::avs::MessageRequest> request) override;
 
- void setAVSEndpoint(const std::string& avsEndpoint) override;
+ void setAVSGateway(const std::string& avsGateway) override;
 
- std::string getAVSEndpoint() override;
+ std::string getAVSGateway() override;
 
  void setObserver(std::shared_ptr<MessageRouterObserverInterface> observer) override;
 
@@ -168,8 +169,8 @@ class MessageRouter
  /// The observer object. Access serialized with @c m_connectionMutex.
  std::shared_ptr<MessageRouterObserverInterface> m_observer;
 
- /// The current AVS endpoint. Access serialized with @c m_connectionMutex.
- std::string m_avsEndpoint;
+ /// The current AVS gateway. Access serialized with @c m_connectionMutex.
+ std::string m_avsGateway;
 
  /// The AuthDelegateInterface which provides a valid access token.
  std::shared_ptr<avsCommon::sdkInterfaces::AuthDelegateInterface> m_authDelegate;

ACL/include/ACL/Transport/MessageRouterInterface.h

@@ -74,18 +74,18 @@ class MessageRouterInterface
  virtual ConnectionStatus getConnectionStatus() = 0;
 
  /**
- * Set the URL endpoint for the AVS connection. Calling this function with a new value will cause the
- * current active connection to be closed, and a new one opened to the new endpoint.
- * @param avsEndpoint The URL for the new AVS endpoint.
+ * Set the gateway URL for the AVS connection. Calling this function with a new value will cause the
+ * current active connection to be closed, and a new one opened to the new gateway.
+ * @param avsGateway The URL for the new AVS gateway.
  */
- virtual void setAVSEndpoint(const std::string& avsEndpoint) = 0;
+ virtual void setAVSGateway(const std::string& avsGateway) = 0;
 
  /**
- * Get the URL endpoint for the AVS connection.
+ * Get the gateway URL for the AVS connection.
  *
- * @return The URL for the current AVS endpoint.
+ * @return The URL for the current AVS gateway.
  */
- virtual std::string getAVSEndpoint() = 0;
+ virtual std::string getAVSGateway() = 0;
 
  /**
  * Set the observer to this object.

ACL/include/ACL/Transport/PostConnectInterface.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License").
  * You may not use this file except in compliance with the License.
@@ -19,27 +19,29 @@
 #include <memory>
 
 #include "ACL/Transport/PostConnectObserverInterface.h"
-#include "ACL/Transport/PostConnectSendMessageInterface.h"
+#include <AVSCommon/SDKInterfaces/PostConnectSendMessageInterface.h>
 
 namespace alexaClientSDK {
 namespace acl {
 
-class HTTP2Transport;
-
 /**
  * Interface for post-connect objects which should be used to perform activities after a connection is established.
  */
 class PostConnectInterface {
 public:
  /**
- * The main method which is responsible for doing the PostConnect action
- * of the specific PostConnect object type.
+ * The main method which is responsible for doing the PostConnect action.
  *
- * @param transport The transport to which the post connect is associated..
+ * @note: This method is not expected to be called twice throughout the lifecycle of the object.
  *
- * @return A boolean to indicate that the post connect process has been successfully initiated
+ * @param postConnectSender The @c PostConnectSendMessageInterface to send post connect messages.
+ * @param postConnectObserver The @c PostConnectObserverInterface to get notified on success or failure of the
+ * post connect action.
+ * @return A boolean to indicate that the post connect process has been successfully initiated.
  */
- virtual bool doPostConnect(std::shared_ptr<HTTP2Transport> transport) = 0;
+ virtual bool doPostConnect(
+ std::shared_ptr<avsCommon::sdkInterfaces::PostConnectSendMessageInterface> postConnectSender,
+ std::shared_ptr<PostConnectObserverInterface> postConnectObserver) = 0;
 
  /**
  * Handle notification that the connection has been lost.

ACL/include/ACL/Transport/PostConnectObserverInterface.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2017-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License").
  * You may not use this file except in compliance with the License.
@@ -31,6 +31,11 @@ class PostConnectObserverInterface {
  * post-connect processing.
  */
  virtual void onPostConnected() = 0;
+
+ /**
+ * Called when a PostConnect object failed to complete the post-connect processing.
+ */
+ virtual void onUnRecoverablePostConnectFailure() = 0;
 };
 
 } // namespace acl