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.
1.0.0
.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 theAlexaCaptions
interface for control of AlexaCaptions presentation in your IPC client. -
APLClient
– Use theAPLClient
interface to render Alexa Presentation Language (APL) visual content with theAPLClientLibrary
runtime. -
AudioFocusManager
– Use theAudioFocusManager
interface to communicate with the Alexa client about audio activities in your IPC client. -
DoNotDisturb
– Use theDoNotDisturb
interface to communicate with the Alexa client to disable incoming notifications, announcements, and calls. -
InteractionManager
– Use theInteractionManager
interface to initiate interactions with the Alexa client for voice recognition, navigation, and interruptions. -
LiveViewCamera
– Use theLiveViewCamera
interface to enable live feed video stream to your IPC client from a smart home camera. -
Logger
– Use theLogger
interface to write console logs to the Alexa client. -
SessionSetup
– Use theSessionSetup
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 theTemplateRuntime
interface to render display cards created from templates that accompany voice interactions, music playback, and other user experiences. -
WindowManager
– Use theWindowManager
interface to report and control window-based presentations in your IPC client.
Related topics
Last updated: Aug 10, 2022