[MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon

© 2014 Car Connectivity Consortium. All Rights Reserved.

MirrorLink API OverviewIntroduction to the MirrorLink Common API, Requirements & Tools

Ed Pichon, App CB2015-05-18 ver 1.1

© 2014 Car Connectivity Consortium. All Rights Reserved. 2015/05/18

Info Session Agenda

• What is MirrorLink?

• MirrorLink Common API

• Application Requirements

• App Certificates

• Support Tools


Basic MirrorLink® Concept

Once connected, no need to touch or look at your phone


What is MirrorLink? High Level Overview for Application Developers

• MirrorLink is a Protocol for Using Automotive Head Units (Clients) as Remote Terminals for Phones (Servers)• Uses/extends a number of open standards• Physical layer agnostic

• Services Provided• Framebuffer replication• Control events• Bi-directional audio• Bi-directional data services

• MirrorLink Services Provided Transparently to the Application• Apps don’t have to implement ML protocol• Thin API provides access to info about ML session

and some basic commands• Applications Execute On the Phone, But Are

Viewed and Used on the Head UnitMirrorLink Client(Head Unit)

MirrorLink Server(Phone)

MirrorLink Common API

Application


MirrorLink Common APIQuick Survey of Exposed Capabilities


MirrorLink Common API Modules

Module Obligation Summary

Common API Info Mandatory Module availability and version info.

Device Info Mandatory MirrorLink version, head unit info*

Certification Information Mandatory Certificate status introspection

Connection Information Mandatory Connection status*

Display Information Mandatory Head unit screen size*, orientation status*

Event Information Mandatory Head unit buttons*

Client Virtual Keyboard Optional VKB provided by head unit interface

Key Event Listing Optional VKB provided by head unit interface

Context Information Mandatory Audio/video metadata, blocking*

Device Status Information Mandatory Drive/Park mode*, microphone*

Data Services Optional Data object model interface*

Notifications Optional Head unit notification interface*

* - Callback available


Application MetadataQuick overview

• Provide Information to the ML Client About the Application

• Audio Content Categories• Application categories of audio streams• Set at runtime using Common API• Head unit uses info to mix audio feeds

• Other Metadata (Deprecated)• Video Application Categories

- Deprecated

• Visual Content Categories- Deprecated

• Audio Content Types- System Services- Don’t use!

App CategoryNavigation

Visual Content CategoryVector Graphics

App Category – General UI FrameworkVisual Content Category – Vector Graphics

App CB’s Advice: Set Audio Content Category at run-time

whenever app starts playing audio.(Set other metadata in application certificate, &

don’t modify at run-time.)


Head Unit Display Info

• Information Provided• Size of ML screen in pixels• Size of ML screen in millimeters• Distance to user (if known)• Scaling support info – padding rows/columns for

aspect ratio, etc.• Client pixel format (565, 888, etc.)

• Can Set Orientation Support of App at RunTime• Callback – Info Can Change While in a

MirrorLink Session• Screen windowing• Overlays• Minimizing• Orientation change request (can reject!)

Full Head Unit Screen

ML Window(Reported Screen Size)

Full Head Unit Screen

Initial Window

Temp Window 1Rotate?


Event Configuration Info

Element Description

Knob Support Knob and direction keys available

Device Key Support Dedicated keys available (make call, end call, back, etc.)

Multimedia Key Support Audio keys available (play, pause, rewind, etc.)

Function Key Support F1, F2, etc.

ITU Key Support Phone specific (*, #, 0, 1, 2, 3, 4…)

Touch event support Number of simultaneous touch events

Pressure Mask Pressure levels supported on touch events

Keyboard Language Language & country codes for client VKB

UI Language Language & country codes for client UI language


Event Configuration Discussion

• Different Head Units Have Different Capabilities

• Minimum Set – Rotary Knob OR Single-Touch (1 Pressure Level)• Rotary knob – up/down/left/right, clockwise/counter-clockwise turn, push• If you are going to be CCC certified, have to work with both

• Event Configuration Can Change at Runtime…in Theory• I haven’t seen it yet

• Can Tailor Application UI Based on Head Unit Capabilities• One UI for rotary know and one UI for single-touch• One UI for multi-touch• One UI for park and one UI for drive

• We Test Each UI Layout in Certification Testing

App CB’s Advice: Build One UI That Works With Rotary & Single-Touch


Data Services

• Extensible Data Object Model for Exchanging Data between Head Unit and Phone• Bi-directional• Not always available – some phones/head units don’t support

• Currently Two Services Defined• GPS• Location

• GPS and Location Mapped Directly to Location Services in Android• Typically higher accuracy/reduced latency vs. on-phone capabilities• Your app gets access for free!

• Additional Services Being Defined by CCC• Let us know what you’d like to see!


Application RequirementsQuick Survey


Application Requirements

• Base Requirements “Park Mode” – Ensure Applications Can Be Used• Application supports multiple UI schemes

- Different screen sizes- Different controls

› Rotary knob› Touch screens

• Application doesn’t require use of OS keys that may not be available• Useful for alternate use cases of MirrorLink

• Drive Requirements – Ensure Applications Do Not Excessively Distract Driver• Does not show forbidden content• Does not demand user’s attention• Easy for the user to read and interact with• Does not consume too much of the driver’s attention (driver workload)


Base RequirementsBasic Interoperability

Display Compatibility• Support Reference Client

Display• 800 x 480 pixels (square)• 13.33 cm x 8.00 cm• 90 cm from driver

• Adapt to Client Display [Optional]

• Support Landscape Mode• Control Positioning

• Not entirely within outer 5% of the display

Control Compatibility• Support Rotary Knobs

• May not have a rotary keyboard available, so either implement your own, or don’t require

• Support Single-Touch Events• Cannot require multi-touch

• Voice Commands• May use, but may not be

available• Must notify user if not available

• Cannot Require OS Keys• May not be present on Client

• Provide Application Metadata

Benefit – App Will Work With ML Clients


Drive RequirementsMinimizing Driver Distraction

• Guiding Principals• Nothing that demands the driver’s attention• Quickly comprehensible and accessible

• Restricted Content• No video, incidental animations or flashing• No automatic scrolling text

• Visual Accessibility• Color contrast – brightness & color differences• Text legibility

• Minimum height• Font requirements

• Control Accessibility• No two-handed operations• Should not use the keyboard• Control sizing and spacing

• Pace of Interaction• Input retention and responsiveness• Notification dismissal

Region-Based Certification

• Region Specific• North America (AAM)• European Union (EU)• APAC (JAMA)

• Global Certification• Superset of NA, EU and

APAC guidelines

• Can Get Certified for One or Multiple Regions• E.g. Drive in EU & APAC, but

not NA


Drive Certification RegionsClarification

• EU Requirements are the Minimum Set• Applies to all regions that do not have a requirement set• If your app isn’t targeting NA or Japan, go with EU requirement set

• NA Requirements: EU + Driver Workload• Japan Requirements: EU + Strict(er) Driver Workload• Global Requirements are Superset – Japan Requirements• Working on Defining New Regional Requirements

All Regions (EU Requirements)

North America

Japan


• Primary Text Must Be At Least (≥) 4.2 mm Tall• Secondary, supplemental text must be at least (≥) 3.2 mm tall

• Must Comply With Legibility Requirements• Use a pre-approved font (most of the Android fonts)

• Comply with various spacing/stroke ratio requirements

• Don’t use cursive handwriting fonts or ones with lots of decorative elements

• Map/Icon Content is Exempt

Drive RequirementsText Accessibility Requirements Detail

Make Your Text Big, Use Default Fonts


• Foreground Elements Must Have a W3C Contrast Ratio of At Least 7:1 to their Background• Allows for legibility in high-glare conditions

• Defined Pre-Approved Color Combinations• Can use those color combinations, or ones where RGB values are “wider”• Can add color combination to pre-approved list – CCC will test

- Derived from ISO specs, and we check on multiple head units/lighting conditions

• This Applies to Text, Icons & Controls• If the user needs to be able to see it, it needs to be clearly visible• Map content is exempt• Disabled controls have lower threshold

Drive RequirementsColor Contrast Requirements Detail

Choose Colors Carefully!


Drive RequirementsControl Accessibility Requirements Detail

• Visual Representation of Controls Have to Be At Least 200 mm2, With a Minimum Dimension of 10 mm

• Must Fill up 50% of the Containing Box

• Must be a Border Between Controls


Accessibility & Screen SizeDealing with Multiple Client Screen Sizes

• Client Screens Can Have Multiple Sizes• Reference Client Display used for Driver Testing

• Resolution: 800 x 480 (assuming square pixels)• Physical sizes: 13.33 cm x 8.00 cm (width x height)• Distance to the eye of the driver: 90.00 cm

• Scaling Up & Down Takes Place Automatically• If ML Client is Larger Than Reference Client Display:

• App doesn’t have to do anything – scaling makes text/controls larger• May tailor UI to take advantage of larger size, but don’t have to

• Not Required to Comply with Size Requirements on ML Clients Smaller than Reference Client Display

App CB’s Advice: Build for the Reference Client Display, & Don’t Worry About Scaling


Driver Workload VerificationHuman Subject Testing

• Short Version – No More Distracting Than Tuning a Radio• Required Test For Global, NA or Japan Certification

• Japan is the more stringent requirement• Basic Requirement

• 10 subjects, half male, half female, range of ages• Occlusion goggles or blanking display – 1.5 seconds on, 1 second off• Average time to perform longest task ≤ 7.5 seconds total open time

- 5 “on” cycles- NA – 20 subjects, ≤15 seconds total open time for 85% of

participants• How We Do It

• CCC approved Subject Matter Expert (SME) assesses application• Identifies tasks that need to be evaluated• Test lab screens tasks to find ones that take longest• Test 3 longest tasks (and key tasks identified by SME)

Keep Lists and Tasks Short & Simple


ACMS & App Certificates App Certificate Management System


Two Kinds of Certificates

• Self-Signed Application Certificate• Included with the APK• Application metadata• Indicate to phone if it should check for a “real” certificate from the

ACMS• Optional: Indicate to the phone if it is a developer application

• CCC Application Certificate• Distributed by the CCC’s App Certificate Management System (ACMS)• Indicates to the phone that is a certified app• May be CCC certified – required to be presented to the user

- Tested by the CCC as being compliant with our requirements• May be whitelisted by an OEM – required to be presented to user if

head units is from that OEM• …or both!


Car Connectivity ConsortiumApp Certificate

Management System

Application Certificate Management SystemACMS for App Developers

24

Certificate Distribution

Management Portal

App & Dev Certificates

MirrorLink® Server DevicesPhones & other mobile devices

Apps

Apps

Device Makers

Developers

Test Labs

MirrorLink® Client DevicesHead units

App StoresApps do not contain

Application Certificates.

Application Certificates distributed to server

devices over the Internet.

App Certificate tells Servers & Clients when the app is safe to use, and where.

ACMS Integration Requires No Changes to Application

Certification Body


Application Certificate InformationApplication Metadata

<appIdentifier>ACMSDemo1234abcd</appIdentifier><appListEntry> <name>ACMS Demo 1</name> <providerName>E-Qualus</providerName> <providerURL>www.e-qualus.com</providerURL> <description>A demo app.</description> <iconList> <icon> <mimetype>image/png</mimetype> <width>72</width> <height>72</height> <depth>24</depth> <url>/resources/icon.png</url> </icon> </iconList> <appInfo> <appCategory>0x00080000</appCategory> </appInfo>


Application Certificate InformationCertification Status

<appCertInfoEntry> <appUUID>uuid:abcd1234-abcd-1234-5678-abcdef123456</appUUID> <entity> <name>CCC</name> <restricted>EU</restricted> <nonRestricted>EU, USA,AUS,KOR,CHN,APAC,WORLD</nonRestricted> </entity> <entity> <name>OEM-A</name> <restricted>USA,EU</restricted> <nonRestricted>EU,USA,AUS,KOR,CHN,APAC,WORLD</nonRestricted> </entity> <entity> <name>OEM-B</name> <restricted>USA,EU</restricted> <nonRestricted>EU,USA,AUS,KOR,CHN,APAC,WORLD</nonRestricted> </entity></appCertInfoEntry>


Allowed Certificate Entity NamesWhat is Allowed in the <entity><name> Block

• CCC (CCC Application Certificates ONLY)• Certified by the CCC• All head units will show the app as a certified app• All head units will pay attention to the restricted (drive) and non-restricted

(park) modes

• OEM Name (CCC Application Certificates ONLY)• Head units from that OEM will treat that app as certified• Whitelisting by individual OEMs• Added to certificates at request/approval of OEM

• ACMS (Self-Signed Certificates ONLY)• Indicates that the phone should check with the ACMS for a certificate

• Developer (Self-Signed Certificates ONLY)• Indicates that this is a developer certificate• Reported as “CCC” to head unit if developer certificate validation

successful


Developer Certificates

See the Developer Application Certificate Tutorial for more

information.https://causeway.carconnectivity.org/wg/DevWG/document/3130


Developer Support ToolsAids to Developing ML Applications


Protocol ImplementationConformance Statement

• PICS is a Spreadsheet Filled Out by the App Developer• Identification information about the app• Requirements checklist• Description of application

- What are the screens?- How does application adjust to head-unit capabilities?- What fonts to do you use?

• Used by the CCC and the ATL to Determine Which Tests to Run• If you don’t have any maps in your app, we don’t check that your app complies

with the navigation requirements• If EU-certified only, no need to run driver workload tests

• Used by the ATL to Determine How to Run Tests• What screens to examine for compliance and how to get to them• What client capabilities needed to examine all variations?

• Critical to Certification Program – We Rely On You to Be Honest• Test labs will check that your app matches the PICS


Application Certificate XML Extension

• XML Data for Application Certificates Builder• Presentation information to show user

on head unit: Icon, Name, etc.• Content of application: video and

audio content categories (navigation, music, etc.)

• Certification status information: who has certified for what regions- Multiple certifying entities: CCC,

Car Maker, etc.- Multiple possible regions- Car-maker specific information

• Guides on Structure and Data Fields

31


Application Certificate Generation

• Certificate Builder• Create Self-Signed

Certificates to Include in Application APK

• Automatically generate Android Application IDs

• Build Regular Self-Signed Certificates and Developer Certificates

• Linux and Windows Versions

32


Android Common API Simulator & Controller

• Common API Simulator APK• Can be installed on any Android device (API level >

14)• Provides a “fake” MirrorLink Common API

to other applications on device• Common API Simulator Controller

• Runs on separate PC (Ubuntu & Windows)• Controls behavior of MirrorLink API• Configure simulator MirrorLink session

capabilities• Configure responses API calls• Trigger events

- Change Client screen sizes- Button pushes- Simulate data service objects

• Only Works on Phones That Don’t Have MirrorLink• Doesn’t make a phone a ML phone!

33


ML Client Simulator

• Built by Head of Technical Working Group• Full Featured Simulator of MirrorLink 1.1

Client on an Ubuntu PC• DAP, Simulated Data Source, Receive

Audio• Variable session capabilities

- Screen size- Offered services and controls

• Certification pending

• Used in Certification Testing of Apps• Allows for internal testing of driver

distraction at the developer workstation• Provided by Microsoft (No Cost!)

• Must agree to license terms with Microsoft• [email protected]

34


Rotary Shift Knob

• Some MirrorLink Clients Use a Rotary Shift Knob• Custom hardware device• No common equivalent in PC

space• Applications Are Required to

Support the Rotary Shift Knob

• Instructions for Assembling Your Own• CAN-USB interface dongle• C-Class Control Knob from

Daimler• 12 V DC power supply• 60Ω termination resistor

35


Common API Test Application

• Used for Certification of Server Implementations of Common API• User interfaces for each element of

Common API• Testing support tools

• Great Way for Developers to Learn About Common API• What information is exposed• What commands are available

• Source Code Provided to Developers

36


ML 1.1 Devices

• MirrorLink 1.1 is First Version of MirrorLink that Supports 3rd Party Apps• 1.0 just allowed first-party built-in car-mode apps

• MirrorLink 1.1 Phones (Servers) Now On the Market• HTC One M8• Samsung Galaxy S4 Mini, Note 4, And Others• Sony Xperia Z3• Others pending

- In testing- Certified but not publicly announced

• ML 1.1 Head Units (Clients) • New VW, Honda, Toyota, Peugeot, Skoda• Pioneer AVH-X5700BHS (Aftermarket)• Others pending

• Check the Certified Products Listing on MirrorLink.com


Why Make an App a MirrorLink App?Advantages of implementing MirrorLink in Your Apps

• Open Standard• No one company controls, no one company can change the rules• Not tied to a single OS or platform

• Broad Install Base• Most car manufacturers are adding MirrorLink to their head units

• Clear, Open Requirements• You know what the rules are

• Maximum Flexibility• As long as you comply with the requirements, you can do what you like

• Minimal Technical Burden• No SDK, just a thin API

• You Can Focus on the User Experience


Thanks

• Feel Free to Email Me if You Have Questions• [email protected]

• Register as a Developer at Mirrorlink.com!

• Weekly Test Status Review Call• 9:30am Central Time, Thursdays• Webex posted to Developer Portal• Open to all developers• If you have a problem with a test case, you can

ask here.• Can route questions through CB (me) to keep

identify anonymous

[MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon

Technology

Transcript of [MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon