AVS Device SDK IPC Client Framework API Overview

The AVS Device SDK Inter-Process Communication (IPC) Client Framework API is a collection of IPC interfaces exposed in the AVS Device SDK’s IPCServerSampleApplication, which enables communication with an IPC client to complete customer-facing Alexa interactions. The framework provides namespace-organized inbound and outbound messages for a variety of core Alexa features and functionality that are implemented through the IPC Server Sample App.

Framework version

The framework version refers to the JSON schema of the IPC messages. The version defines the specific namespace and their message structure.

Upon connection to the IPC Server, the IPC client receives the SessionSetup.initializeClient directive, which informs the IPC client of the ipcVersion implemented by the IPC Server. The client responds with the SessionSetup.clientInitialized event to indicate if the Client supports the IPC framework version.

Message schema

The message schema of the IPC API follows a similar pattern to that of the Alexa Voice Service (AVS), leveraging a header and payload paradigm for all outbound (directive) and inbound (event) messages.

Messages

{
  "message": {
    "header": {
      "namespace": "{{STRING}}",
      "name": "{{STRING}}",
      "version": {{NUMBER}},
    },
    "payload": {
      // payload as defined by the IPC interface
    }
  }
}
 

Message parameters

Parameter Description Type
header.namespace The IPC interface to which the message belongs. string
header.name The name of the message, unique within the namespace, which defines the payload type. string
header.version The interface version of the namespace. number
payload The substantive content of the message. object

Interface versioning

Unlike the AVS Interface Version model, which uses a "major.minor" convention, the AVS Device SDK IPC interface versioning is denoted by a single integer version number. Any update to an interface increments the version number.

The following scenarios cause a versioning update:

  • An update removes existing messages from a namespace.
  • An update adds new messages to a namespace.
  • An update removes parameters from the payload of a message for the given namespace.
  • An update adds new parameters to the payload of a message for the given namespace.
  • The data type of an existing parameter changes.

Namespace assertion

The IPC client should assert the namespaces and versions that it supports to the IPC Server Sample App on startup with the SessionSetup.namespaceVersionsReport message.

After the available versions are received from the IPC client, the IPCVersionManager of the IPC Server Sample App compares the version of each namespace asserted by the IPC client against the version supported by each corresponding handler or router IPC component in the IPC Server Sample App. If the versions are the same, the IPC Server Sample App uses the version from the IPC client in all corresponding messages for the respective component. If the versions are incompatible, the IPC Server Sample App produces an error and prints the two incompatible versions.

IPC Client Framework API reference

This section provides an overview and links to reference documentation for the IPC client APIs provided by the AVS Device SDK IPC Client Framework:

  • AlexaCaptions – Use the AlexaCaptions interface for control of AlexaCaptions presentation in your IPC client.

  • APLClient – Use the APLClient interface to render Alexa Presentation Language (APL) visual content with the APLClientLibrary runtime.

  • AudioFocusManager – Use the AudioFocusManager interface to communicate with the Alexa client about audio activities in your IPC client.

  • DoNotDisturb – Use the DoNotDisturb interface to communicate with the Alexa client to disable incoming notifications, announcements, and calls.

  • InteractionManager – Use the InteractionManager interface to initiate interactions with the Alexa client for voice recognition, navigation, and interruptions.

  • LiveViewCamera – Use the LiveViewCamera interface to enable live feed video stream to your IPC client from a smart home camera.

  • Logger – Use the Logger interface to write console logs to the Alexa client.

  • SessionSetup – Use the SessionSetup interface to initialize your IPC client's connection to the Alexa client and handle runtime configurations.

  • System – Use the System interface to handle basic system-level operations of the Alexa client in your IPC client.

  • TemplateRuntime – Use the TemplateRuntime interface to render display cards created from templates that accompany voice interactions, music playback, and other user experiences.

  • WindowManager – Use the WindowManager interface to report and control window-based presentations in your IPC client.